7.5. StringIO — Read and write strings as files¶
This module implements a file-like class, StringIO, that reads and
writes a string buffer (also known as memory files). See the description of
file objects for operations (section File Objects). (For
standard strings, see str and unicode.)
-
class
StringIO.StringIO([buffer])¶
When a StringIO object is created, it can be initialized to an existing
string by passing the string to the constructor. If no string is given, the
StringIO will start empty. In both cases, the initial file position
starts at zero.
The StringIO object can accept either Unicode or 8-bit strings, but
mixing the two may take some care. If both are used, 8-bit strings that cannot
be interpreted as 7-bit ASCII (that use the 8th bit) will cause a
UnicodeError to be raised when getvalue() is called.
The following methods of StringIO objects require special mention:
-
StringIO.getvalue()¶
Retrieve the entire contents of the “file” at any time before the
StringIO object’s close() method is called. See the note above
for information about mixing Unicode and 8-bit strings; such mixing can cause
this method to raise UnicodeError.
-
StringIO.close()¶
Free the memory buffer. Attempting to do further operations with a closed
StringIO object will raise a ValueError.
Example usage:
import StringIO
output = StringIO.StringIO()
output.write('First line.\n')
print >>output, 'Second line.'
# Retrieve file contents -- this will be
# 'First line.\nSecond line.\n'
contents = output.getvalue()
# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()
The module cStringIO provides an interface similar to that of the
StringIO module. Heavy use of StringIO.StringIO objects can be
made more efficient by using the function StringIO() from this module
instead.
-
cStringIO.StringIO([s])¶
Return a StringIO-like stream for reading or writing.
Since this is a factory function which returns objects of built-in types,
there’s no way to build your own version using subclassing. It’s not
possible to set attributes on it. Use the original StringIO module in
those cases.
Unlike the StringIO module, this module is not able to accept Unicode
strings that cannot be encoded as plain ASCII strings.
Another difference from the StringIO module is that calling
StringIO() with a string parameter creates a read-only object. Unlike an
object created without a string parameter, it does not have write methods.
These objects are not generally visible. They turn up in tracebacks as
StringI and StringO.
The following data objects are provided as well:
-
cStringIO.InputType¶
The type object of the objects created by calling StringIO() with a string
parameter.
-
cStringIO.OutputType¶
The type object of the objects returned by calling StringIO() with no
parameters.
There is a C API to the module as well; refer to the module source for more
information.
Example usage:
import cStringIO
output = cStringIO.StringIO()
output.write('First line.\n')
print >>output, 'Second line.'
# Retrieve file contents -- this will be
# 'First line.\nSecond line.\n'
contents = output.getvalue()
# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()