1
2:mod:`StringIO` --- Read and write strings as files
3===================================================
4
5.. module:: StringIO
6   :synopsis: Read and write strings as if they were files.
7
8
9This module implements a file-like class, :class:`~StringIO.StringIO`, that reads and
10writes a string buffer (also known as *memory files*).  See the description of
11file objects for operations (section :ref:`bltin-file-objects`). (For
12standard strings, see :class:`str` and :class:`unicode`.)
13
14
15.. class:: StringIO([buffer])
16
17   When a :class:`~StringIO.StringIO` object is created, it can be initialized to an existing
18   string by passing the string to the constructor. If no string is given, the
19   :class:`~StringIO.StringIO` will start empty. In both cases, the initial file position
20   starts at zero.
21
22   The :class:`~StringIO.StringIO` object can accept either Unicode or 8-bit strings, but
23   mixing the two may take some care.  If both are used, 8-bit strings that cannot
24   be interpreted as 7-bit ASCII (that use the 8th bit) will cause a
25   :exc:`UnicodeError` to be raised when :meth:`getvalue` is called.
26
27The following methods of :class:`~StringIO.StringIO` objects require special mention:
28
29
30.. method:: StringIO.getvalue()
31
32   Retrieve the entire contents of the "file" at any time before the
33   :class:`~StringIO.StringIO` object's :meth:`close` method is called.  See the note above
34   for information about mixing Unicode and 8-bit strings; such mixing can cause
35   this method to raise :exc:`UnicodeError`.
36
37
38.. method:: StringIO.close()
39
40   Free the memory buffer.  Attempting to do further operations with a closed
41   :class:`~StringIO.StringIO` object will raise a :exc:`ValueError`.
42
43Example usage::
44
45   import StringIO
46
47   output = StringIO.StringIO()
48   output.write('First line.\n')
49   print >>output, 'Second line.'
50
51   # Retrieve file contents -- this will be
52   # 'First line.\nSecond line.\n'
53   contents = output.getvalue()
54
55   # Close object and discard memory buffer --
56   # .getvalue() will now raise an exception.
57   output.close()
58
59
60:mod:`cStringIO` --- Faster version of :mod:`StringIO`
61======================================================
62
63.. module:: cStringIO
64   :synopsis: Faster version of StringIO, but not subclassable.
65.. moduleauthor:: Jim Fulton <jim@zope.com>
66.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
67
68
69The module :mod:`cStringIO` provides an interface similar to that of the
70:mod:`StringIO` module.  Heavy use of :class:`StringIO.StringIO` objects can be
71made more efficient by using the function :func:`StringIO` from this module
72instead.
73
74
75.. function:: StringIO([s])
76
77   Return a StringIO-like stream for reading or writing.
78
79   Since this is a factory function which returns objects of built-in types,
80   there's no way to build your own version using subclassing.  It's not
81   possible to set attributes on it.  Use the original :mod:`StringIO` module in
82   those cases.
83
84   Unlike the :mod:`StringIO` module, this module is not able to accept Unicode
85   strings that cannot be encoded as plain ASCII strings.
86
87   Another difference from the :mod:`StringIO` module is that calling
88   :func:`StringIO` with a string parameter creates a read-only object. Unlike an
89   object created without a string parameter, it does not have write methods.
90   These objects are not generally visible.  They turn up in tracebacks as
91   :class:`StringI` and :class:`StringO`.
92
93
94
95The following data objects are provided as well:
96
97
98.. data:: InputType
99
100   The type object of the objects created by calling :func:`StringIO` with a string
101   parameter.
102
103
104.. data:: OutputType
105
106   The type object of the objects returned by calling :func:`StringIO` with no
107   parameters.
108
109There is a C API to the module as well; refer to the module source for  more
110information.
111
112Example usage::
113
114   import cStringIO
115
116   output = cStringIO.StringIO()
117   output.write('First line.\n')
118   print >>output, 'Second line.'
119
120   # Retrieve file contents -- this will be
121   # 'First line.\nSecond line.\n'
122   contents = output.getvalue()
123
124   # Close object and discard memory buffer --
125   # .getvalue() will now raise an exception.
126   output.close()
127
128