Doc/library/stringio.rst

   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.  Attempting to do further operations with a closed
  41    :class:`StringIO` object will raise a :exc:`ValueError`.
  42
  43 Example usage::
  44
  45    import StringIO
  46
  47    output = StringIO.StringIO()
  48    output.write('First line.\n')
  49    print >>output, 'Second line.'
  50
  51    # Retrieve file contents -- this will be
  52    # 'First line.\nSecond line.\n'
  53    contents = output.getvalue()
  54
  55    # Close object and discard memory buffer --
  56    # .getvalue() will now raise an exception.
  57    output.close()
  58
  59
  60 :mod:`cStringIO` --- Faster version of :mod:`StringIO`
  61 ======================================================
  62
  63 .. module:: cStringIO
  64    :synopsis: Faster version of StringIO, but not subclassable.
  65 .. moduleauthor:: Jim Fulton <jim@zope.com>
  66 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
  67
  68
  69 The module :mod:`cStringIO` provides an interface similar to that of the
  70 :mod:`StringIO` module.  Heavy use of :class:`StringIO.StringIO` objects can be
  71 made more efficient by using the function :func:`StringIO` from this module
  72 instead.
  73
  74 Since this module provides a factory function which returns objects of built-in
  75 types, there's no way to build your own version using subclassing.  It's not
  76 possible to set attributes on it.  Use the original :mod:`StringIO` module in
  77 those cases.
  78
  79 Unlike the memory files implemented by the :mod:`StringIO` module, those
  80 provided by this module are not able to accept Unicode strings that cannot be
  81 encoded as plain ASCII strings.
  82
  83 Calling :func:`StringIO` with a Unicode string parameter populates
  84 the object with the buffer representation of the Unicode string, instead of
  85 encoding the string.
  86
  87 Another difference from the :mod:`StringIO` module is that calling
  88 :func:`StringIO` with a string parameter creates a read-only object. Unlike an
  89 object created without a string parameter, it does not have write methods.
  90 These objects are not generally visible.  They turn up in tracebacks as
  91 :class:`StringI` and :class:`StringO`.
  92
  93 The following data objects are provided as well:
  94
  95
  96 .. data:: InputType
  97
  98    The type object of the objects created by calling :func:`StringIO` with a string
  99    parameter.
 100
 101
 102 .. data:: OutputType
 103
 104    The type object of the objects returned by calling :func:`StringIO` with no
 105    parameters.
 106
 107 There is a C API to the module as well; refer to the module source for  more
 108 information.
 109
 110 Example usage::
 111
 112    import cStringIO
 113
 114    output = cStringIO.StringIO()
 115    output.write('First line.\n')
 116    print >>output, 'Second line.'
 117
 118    # Retrieve file contents -- this will be
 119    # 'First line.\nSecond line.\n'
 120    contents = output.getvalue()
 121
 122    # Close object and discard memory buffer --
 123    # .getvalue() will now raise an exception.
 124    output.close()
 125