/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
  9This module implements a file-like class, :class:`StringIO`, that reads and
 10writes a string buffer (also known as *memory files*).  See the description of
 11file objects for operations (section :ref:`bltin-file-objects`). (For
 12standard 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
 27The 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
 43Example 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
 69The module :mod:`cStringIO` provides an interface similar to that of the
 70:mod:`StringIO` module.  Heavy use of :class:`StringIO.StringIO` objects can be
 71made more efficient by using the function :func:`StringIO` from this module
 72instead.
 73
 74Since this module provides a factory function which returns objects of built-in
 75types, there's no way to build your own version using subclassing.  It's not
 76possible to set attributes on it.  Use the original :mod:`StringIO` module in
 77those cases.
 78
 79Unlike the memory files implemented by the :mod:`StringIO` module, those
 80provided by this module are not able to accept Unicode strings that cannot be
 81encoded as plain ASCII strings.
 82
 83Calling :func:`StringIO` with a Unicode string parameter populates
 84the object with the buffer representation of the Unicode string, instead of
 85encoding the string.
 86
 87Another difference from the :mod:`StringIO` module is that calling
 88:func:`StringIO` with a string parameter creates a read-only object. Unlike an
 89object created without a string parameter, it does not have write methods.
 90These objects are not generally visible.  They turn up in tracebacks as
 91:class:`StringI` and :class:`StringO`.
 92
 93The 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
107There is a C API to the module as well; refer to the module source for  more
108information.
109
110Example 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