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.)

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 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.

StringIO.close()

Free the memory buffer.

Example usage:

import StringIO

output = StringIO.StringIO()
output.write('First line.\n')
print('Second line.', file=output)

# 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()

cStringIO — Faster version of StringIO

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.

Since this module provides a factory function which returns objects of built-in types, there’s no way to build your own version using subclassing. Use the original StringIO module in that case.

Unlike the memory files implemented by the StringIO module, those provided by this module are not able to accept strings that cannot be encoded in plain ASCII.

Calling StringIO() with a string parameter populates the object with the buffer representation of the string, instead of encoding the string.

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('Second line.', file=output)

# 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()