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

# 7.6. `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.

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