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