7.5.StringIO — Read and write strings as files

This module implements a file-like class,StringIO, that reads andwrites a string buffer (also known asmemory files). See the description offile objects for operations (sectionFile Objects). (Forstandard strings, seestr andunicode.)

classStringIO.StringIO([buffer])

When aStringIO object is created, it can be initialized to an existingstring by passing the string to the constructor. If no string is given, theStringIO will start empty. In both cases, the initial file positionstarts at zero.

TheStringIO object can accept either Unicode or 8-bit strings, butmixing the two may take some care. If both are used, 8-bit strings that cannotbe interpreted as 7-bit ASCII (that use the 8th bit) will cause aUnicodeError to be raised whengetvalue() is called.

The following methods ofStringIO objects require special mention:

StringIO.getvalue()

Retrieve the entire contents of the “file” at any time before theStringIO object’sclose() method is called. See the note abovefor information about mixing Unicode and 8-bit strings; such mixing can causethis method to raiseUnicodeError.

StringIO.close()

Free the memory buffer. Attempting to do further operations with a closedStringIO object will raise aValueError.

Example usage:

importStringIOoutput=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()

7.6.cStringIO — Faster version ofStringIO

The modulecStringIO provides an interface similar to that of theStringIO module. Heavy use ofStringIO.StringIO objects can bemade more efficient by using the functionStringIO() from this moduleinstead.

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 notpossible to set attributes on it. Use the originalStringIO module inthose cases.

Unlike theStringIO module, this module is not able to accept Unicodestrings that cannot be encoded as plain ASCII strings.

Another difference from theStringIO module is that callingStringIO() with a string parameter creates a read-only object. Unlike anobject created without a string parameter, it does not have write methods.These objects are not generally visible. They turn up in tracebacks asStringI andStringO.

The following data objects are provided as well:

cStringIO.InputType

The type object of the objects created by callingStringIO() with a stringparameter.

cStringIO.OutputType

The type object of the objects returned by callingStringIO() with noparameters.

There is a C API to the module as well; refer to the module source for moreinformation.

Example usage:

importcStringIOoutput=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()