/Doc/library/stringio.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 125 lines · 82 code · 43 blank · 0 comment · 0 complexity · 65ec0b86b76e683ffcead132aa43f8ae MD5 · raw file

  1. :mod:`StringIO` --- Read and write strings as files
  2. ===================================================
  3. .. module:: StringIO
  4. :synopsis: Read and write strings as if they were files.
  5. This module implements a file-like class, :class:`StringIO`, that reads and
  6. writes a string buffer (also known as *memory files*). See the description of
  7. file objects for operations (section :ref:`bltin-file-objects`). (For
  8. standard strings, see :class:`str` and :class:`unicode`.)
  9. .. class:: StringIO([buffer])
  10. When a :class:`StringIO` object is created, it can be initialized to an existing
  11. string by passing the string to the constructor. If no string is given, the
  12. :class:`StringIO` will start empty. In both cases, the initial file position
  13. starts at zero.
  14. The :class:`StringIO` object can accept either Unicode or 8-bit strings, but
  15. mixing the two may take some care. If both are used, 8-bit strings that cannot
  16. be interpreted as 7-bit ASCII (that use the 8th bit) will cause a
  17. :exc:`UnicodeError` to be raised when :meth:`getvalue` is called.
  18. The following methods of :class:`StringIO` objects require special mention:
  19. .. method:: StringIO.getvalue()
  20. Retrieve the entire contents of the "file" at any time before the
  21. :class:`StringIO` object's :meth:`close` method is called. See the note above
  22. for information about mixing Unicode and 8-bit strings; such mixing can cause
  23. this method to raise :exc:`UnicodeError`.
  24. .. method:: StringIO.close()
  25. Free the memory buffer. Attempting to do further operations with a closed
  26. :class:`StringIO` object will raise a :exc:`ValueError`.
  27. Example usage::
  28. import StringIO
  29. output = StringIO.StringIO()
  30. output.write('First line.\n')
  31. print >>output, 'Second line.'
  32. # Retrieve file contents -- this will be
  33. # 'First line.\nSecond line.\n'
  34. contents = output.getvalue()
  35. # Close object and discard memory buffer --
  36. # .getvalue() will now raise an exception.
  37. output.close()
  38. :mod:`cStringIO` --- Faster version of :mod:`StringIO`
  39. ======================================================
  40. .. module:: cStringIO
  41. :synopsis: Faster version of StringIO, but not subclassable.
  42. .. moduleauthor:: Jim Fulton <jim@zope.com>
  43. .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
  44. The module :mod:`cStringIO` provides an interface similar to that of the
  45. :mod:`StringIO` module. Heavy use of :class:`StringIO.StringIO` objects can be
  46. made more efficient by using the function :func:`StringIO` from this module
  47. instead.
  48. Since this module provides a factory function which returns objects of built-in
  49. types, there's no way to build your own version using subclassing. It's not
  50. possible to set attributes on it. Use the original :mod:`StringIO` module in
  51. those cases.
  52. Unlike the memory files implemented by the :mod:`StringIO` module, those
  53. provided by this module are not able to accept Unicode strings that cannot be
  54. encoded as plain ASCII strings.
  55. Calling :func:`StringIO` with a Unicode string parameter populates
  56. the object with the buffer representation of the Unicode string, instead of
  57. encoding the string.
  58. Another difference from the :mod:`StringIO` module is that calling
  59. :func:`StringIO` with a string parameter creates a read-only object. Unlike an
  60. object created without a string parameter, it does not have write methods.
  61. These objects are not generally visible. They turn up in tracebacks as
  62. :class:`StringI` and :class:`StringO`.
  63. The following data objects are provided as well:
  64. .. data:: InputType
  65. The type object of the objects created by calling :func:`StringIO` with a string
  66. parameter.
  67. .. data:: OutputType
  68. The type object of the objects returned by calling :func:`StringIO` with no
  69. parameters.
  70. There is a C API to the module as well; refer to the module source for more
  71. information.
  72. Example usage::
  73. import cStringIO
  74. output = cStringIO.StringIO()
  75. output.write('First line.\n')
  76. print >>output, 'Second line.'
  77. # Retrieve file contents -- this will be
  78. # 'First line.\nSecond line.\n'
  79. contents = output.getvalue()
  80. # Close object and discard memory buffer --
  81. # .getvalue() will now raise an exception.
  82. output.close()