1 

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

     3 ===================================================

     4 

     5 .. module:: StringIO

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

     7 

     8 

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

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

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

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

    13 

    14 

    15 .. class:: StringIO([buffer])

    16 

    17    When a :class:`StringIO` object is created, it can be initialized to an existing

    18    string by passing the string to the constructor. If no string is given, the

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

    20    starts at zero.

    21 

    22    The :class:`StringIO` object can accept either Unicode or 8-bit strings, but

    23    mixing the two may take some care.  If both are used, 8-bit strings that cannot

    24    be interpreted as 7-bit ASCII (that use the 8th bit) will cause a

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

    26 

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

    28 

    29 

    30 .. method:: StringIO.getvalue()

    31 

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

    33    :class:`StringIO` object's :meth:`close` method is called.  See the note above

    34    for information about mixing Unicode and 8-bit strings; such mixing can cause

    35    this method to raise :exc:`UnicodeError`.

    36 

    37 

    38 .. method:: StringIO.close()

    39 

    40    Free the memory buffer.

    41 

    42 Example usage::

    43 

    44    import StringIO

    45 

    46    output = StringIO.StringIO()

    47    output.write('First line.\n')

    48    print >>output, 'Second line.'

    49 

    50    # Retrieve file contents -- this will be

    51    # 'First line.\nSecond line.\n'

    52    contents = output.getvalue()

    53 

    54    # Close object and discard memory buffer -- 

    55    # .getvalue() will now raise an exception.

    56    output.close()

    57 

    58 

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

    60 ======================================================

    61 

    62 .. module:: cStringIO

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

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

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

    66 

    67 

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

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

    70 made more efficient by using the function :func:`StringIO` from this module

    71 instead.

    72 

    73 Since this module provides a factory function which returns objects of built-in

    74 types, there's no way to build your own version using subclassing.  Use the

    75 original :mod:`StringIO` module in that case.

    76 

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

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

    79 encoded as plain ASCII strings.

    80 

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

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

    83 encoding the string. 

    84 

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

    86 :func:`StringIO` with a string parameter creates a read-only object. Unlike an

    87 object created without a string parameter, it does not have write methods.

    88 These objects are not generally visible.  They turn up in tracebacks as

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

    90 

    91 The following data objects are provided as well:

    92 

    93 

    94 .. data:: InputType

    95 

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

    97    parameter.

    98 

    99 

   100 .. data:: OutputType

   101 

   102    The type object of the objects returned by calling :func:`StringIO` with no

   103    parameters.

   104 

   105 There is a C API to the module as well; refer to the module source for  more

   106 information.

   107 

   108 Example usage::

   109 

   110    import cStringIO

   111 

   112    output = cStringIO.StringIO()

   113    output.write('First line.\n')

   114    print >>output, 'Second line.'

   115 

   116    # Retrieve file contents -- this will be

   117    # 'First line.\nSecond line.\n'

   118    contents = output.getvalue()

   119 

   120    # Close object and discard memory buffer -- 

   121    # .getvalue() will now raise an exception.

   122    output.close()

   123