:mod:`StringIO` --- Read and write strings as files

===================================================

.. module:: StringIO

   :synopsis: Read and write strings as if they were files.

This module implements a file-like class, :class:`StringIO`, that reads and

writes a string buffer (also known as *memory files*).  See the description of

file objects for operations (section :ref:`bltin-file-objects`). (For

standard strings, see :class:`str` and :class:`unicode`.)

.. class:: StringIO([buffer])

   When a :class:`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

   :class:`StringIO` will start empty. In both cases, the initial file position

   starts at zero.

   The :class:`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

   :exc:`UnicodeError` to be raised when :meth:`getvalue` is called.

The following methods of :class:`StringIO` objects require special mention:

.. method:: StringIO.getvalue()

   Retrieve the entire contents of the "file" at any time before the

   :class:`StringIO` object's :meth:`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 :exc:`UnicodeError`.

.. method:: StringIO.close()

   Free the memory buffer.

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

:mod:`cStringIO` --- Faster version of :mod:`StringIO`

======================================================

.. module:: cStringIO

   :synopsis: Faster version of StringIO, but not subclassable.

.. moduleauthor:: Jim Fulton <jim@zope.com>

.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

The module :mod:`cStringIO` provides an interface similar to that of the

:mod:`StringIO` module.  Heavy use of :class:`StringIO.StringIO` objects can be

made more efficient by using the function :func:`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 :mod:`StringIO` module in that case.

Unlike the memory files implemented by the :mod:`StringIO` module, those

provided by this module are not able to accept Unicode strings that cannot be

encoded as plain ASCII strings.

Calling :func:`StringIO` with a Unicode string parameter populates

the object with the buffer representation of the Unicode string, instead of

encoding the string. 

Another difference from the :mod:`StringIO` module is that calling

:func:`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

:class:`StringI` and :class:`StringO`.

The following data objects are provided as well:

.. data:: InputType

   The type object of the objects created by calling :func:`StringIO` with a string

   parameter.

.. data:: OutputType

   The type object of the objects returned by calling :func:`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()