\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{memoryfiles}).  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 initializedto 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-bitstrings, but mixing the two may take some care.  If both are used,8-bit strings that cannot be interpreted as 7-bit \ASCII{} (thatuse the 8th bit) will cause a \exception{UnicodeError} to be raisedwhen \method{getvalue()} is called.\end{classdesc} The following methods of \class{StringIO} objects require specialmention: \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 thenote 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}{jim@zope.com}\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} The module \module{cStringIO} provides an interface similar to that ofthe \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 ofbuilt-in types, there's no way to build your own version usingsubclassing.  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 Unicodestrings 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 havewrite methods.  These objects are not generally visible.  They turn up intracebacks 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}