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.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.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.StringIO` will start empty. In both cases, the initial file position 20 starts at zero. 21 22 The :class:`~StringIO.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.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.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.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 (a] zope.com> 66 .. sectionauthor:: Fred L. Drake, Jr. <fdrake (a] 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 75 .. function:: StringIO([s]) 76 77 Return a StringIO-like stream for reading or writing. 78 79 Since this is a factory function which returns objects of built-in types, 80 there's no way to build your own version using subclassing. It's not 81 possible to set attributes on it. Use the original :mod:`StringIO` module in 82 those cases. 83 84 Unlike the :mod:`StringIO` module, this module is not able to accept Unicode 85 strings that cannot be encoded as plain ASCII strings. 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 94 95 The following data objects are provided as well: 96 97 98 .. data:: InputType 99 100 The type object of the objects created by calling :func:`StringIO` with a string 101 parameter. 102 103 104 .. data:: OutputType 105 106 The type object of the objects returned by calling :func:`StringIO` with no 107 parameters. 108 109 There is a C API to the module as well; refer to the module source for more 110 information. 111 112 Example usage:: 113 114 import cStringIO 115 116 output = cStringIO.StringIO() 117 output.write('First line.\n') 118 print >>output, 'Second line.' 119 120 # Retrieve file contents -- this will be 121 # 'First line.\nSecond line.\n' 122 contents = output.getvalue() 123 124 # Close object and discard memory buffer -- 125 # .getvalue() will now raise an exception. 126 output.close() 127 128
