ref: 68f15d65942da7e30cf9cbae7362f778fe5da1d2
dir: /sys/src/cmd/python/Doc/lib/libstringio.tex/
\section{\module{StringIO} --- Read and write strings as files} \declaremodule{standard}{StringIO} \modulesynopsis{Read and write strings as if they were files.} This module implements a file-like class, \class{StringIO}, that reads and writes a string buffer (also known as \emph{memory files}). See the description of file objects for operations (section \ref{bltin-file-objects}). \begin{classdesc}{StringIO}{\optional{buffer}} When a \class{StringIO} object is created, it can be initialized to an existing string by passing the string to the constructor. If no string is given, the \class{StringIO} will start empty. In both cases, the initial file position starts at zero. The \class{StringIO} object can accept either Unicode or 8-bit strings, but mixing the two may take some care. If both are used, 8-bit strings that cannot be interpreted as 7-bit \ASCII{} (that use the 8th bit) will cause a \exception{UnicodeError} to be raised when \method{getvalue()} is called. \end{classdesc} The following methods of \class{StringIO} objects require special mention: \begin{methoddesc}{getvalue}{} Retrieve the entire contents of the ``file'' at any time before the \class{StringIO} object's \method{close()} method is called. See the note above for information about mixing Unicode and 8-bit strings; such mixing can cause this method to raise \exception{UnicodeError}. \end{methoddesc} \begin{methoddesc}{close}{} Free the memory buffer. \end{methoddesc} Example usage: \begin{verbatim} import StringIO output = StringIO.StringIO() output.write('First line.\n') print >>output, 'Second line.' # Retrieve file contents -- this will be # 'First line.\nSecond line.\n' contents = output.getvalue() # Close object and discard memory buffer -- # .getvalue() will now raise an exception. output.close() \end{verbatim} \section{\module{cStringIO} --- Faster version of \module{StringIO}} \declaremodule{builtin}{cStringIO} \modulesynopsis{Faster version of \module{StringIO}, but not subclassable.} \moduleauthor{Jim Fulton}{[email protected]} \sectionauthor{Fred L. Drake, Jr.}{[email protected]} The module \module{cStringIO} provides an interface similar to that of the \refmodule{StringIO} module. Heavy use of \class{StringIO.StringIO} objects can be made more efficient by using the function \function{StringIO()} from this module instead. Since this module provides a factory function which returns objects of built-in types, there's no way to build your own version using subclassing. Use the original \refmodule{StringIO} module in that case. Unlike the memory files implemented by the \refmodule{StringIO} module, those provided by this module are not able to accept Unicode strings that cannot be encoded as plain \ASCII{} strings. Another difference from the \refmodule{StringIO} module is that calling \function{StringIO()} with a string parameter creates a read-only object. Unlike an object created without a string parameter, it does not have write methods. These objects are not generally visible. They turn up in tracebacks as \class{StringI} and \class{StringO}. The following data objects are provided as well: \begin{datadesc}{InputType} The type object of the objects created by calling \function{StringIO} with a string parameter. \end{datadesc} \begin{datadesc}{OutputType} The type object of the objects returned by calling \function{StringIO} with no parameters. \end{datadesc} There is a C API to the module as well; refer to the module source for more information. Example usage: \begin{verbatim} import cStringIO output = cStringIO.StringIO() output.write('First line.\n') print >>output, 'Second line.' # Retrieve file contents -- this will be # 'First line.\nSecond line.\n' contents = output.getvalue() # Close object and discard memory buffer -- # .getvalue() will now raise an exception. output.close() \end{verbatim}