Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{StringIO} --- |
Fred Drake | 543e19d | 1999-04-21 18:15:22 +0000 | [diff] [blame] | 2 | Read and write strings as files} |
| 3 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{StringIO} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{Read and write strings as if they were files.} |
| 6 | |
Guido van Rossum | cda3d7d | 1997-03-03 16:01:21 +0000 | [diff] [blame] | 7 | |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 8 | This module implements a file-like class, \class{StringIO}, |
Fred Drake | af8a015 | 1998-01-14 14:51:31 +0000 | [diff] [blame] | 9 | that reads and writes a string buffer (also known as \emph{memory |
Fred Drake | 83ff4af | 2000-11-28 16:24:28 +0000 | [diff] [blame] | 10 | files}). See the description of file objects for operations (section |
Fred Drake | 543e19d | 1999-04-21 18:15:22 +0000 | [diff] [blame] | 11 | \ref{bltin-file-objects}). |
Guido van Rossum | cda3d7d | 1997-03-03 16:01:21 +0000 | [diff] [blame] | 12 | |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 13 | \begin{classdesc}{StringIO}{\optional{buffer}} |
| 14 | When a \class{StringIO} object is created, it can be initialized |
Guido van Rossum | cda3d7d | 1997-03-03 16:01:21 +0000 | [diff] [blame] | 15 | to an existing string by passing the string to the constructor. |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 16 | If no string is given, the \class{StringIO} will start empty. |
Fred Drake | 83ff4af | 2000-11-28 16:24:28 +0000 | [diff] [blame] | 17 | |
| 18 | The \class{StringIO} object can accept either Unicode or 8-bit |
| 19 | strings, but mixing the two may take some care. If both are used, |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 20 | 8-bit strings that cannot be interpreted as 7-bit \ASCII{} (that |
Fred Drake | 83ff4af | 2000-11-28 16:24:28 +0000 | [diff] [blame] | 21 | use the 8th bit) will cause a \exception{UnicodeError} to be raised |
| 22 | when \method{getvalue()} is called. |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 23 | \end{classdesc} |
Guido van Rossum | cda3d7d | 1997-03-03 16:01:21 +0000 | [diff] [blame] | 24 | |
Fred Drake | 7e9383a | 1998-04-11 18:05:24 +0000 | [diff] [blame] | 25 | The following methods of \class{StringIO} objects require special |
| 26 | mention: |
| 27 | |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 28 | \begin{methoddesc}{getvalue}{} |
| 29 | Retrieve the entire contents of the ``file'' at any time before the |
Fred Drake | 83ff4af | 2000-11-28 16:24:28 +0000 | [diff] [blame] | 30 | \class{StringIO} object's \method{close()} method is called. See the |
| 31 | note above for information about mixing Unicode and 8-bit strings; |
| 32 | such mixing can cause this method to raise \exception{UnicodeError}. |
Fred Drake | 8fe533e | 1998-03-27 05:27:08 +0000 | [diff] [blame] | 33 | \end{methoddesc} |
| 34 | |
| 35 | \begin{methoddesc}{close}{} |
| 36 | Free the memory buffer. |
| 37 | \end{methoddesc} |
Fred Drake | 9463de2 | 1998-04-11 20:05:43 +0000 | [diff] [blame] | 38 | |
| 39 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 40 | \section{\module{cStringIO} --- |
Fred Drake | 543e19d | 1999-04-21 18:15:22 +0000 | [diff] [blame] | 41 | Faster version of \module{StringIO}} |
Fred Drake | cd71aa2 | 1999-02-18 21:13:03 +0000 | [diff] [blame] | 42 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 43 | \declaremodule{builtin}{cStringIO} |
Fred Drake | 543e19d | 1999-04-21 18:15:22 +0000 | [diff] [blame] | 44 | \modulesynopsis{Faster version of \module{StringIO}, but not |
| 45 | subclassable.} |
Andrew M. Kuchling | c62af02 | 2004-01-08 15:01:08 +0000 | [diff] [blame] | 46 | \moduleauthor{Jim Fulton}{jim@zope.com} |
Fred Drake | cd71aa2 | 1999-02-18 21:13:03 +0000 | [diff] [blame] | 47 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
Fred Drake | 9463de2 | 1998-04-11 20:05:43 +0000 | [diff] [blame] | 48 | |
| 49 | The module \module{cStringIO} provides an interface similar to that of |
Fred Drake | 543e19d | 1999-04-21 18:15:22 +0000 | [diff] [blame] | 50 | the \refmodule{StringIO} module. Heavy use of \class{StringIO.StringIO} |
Fred Drake | 9463de2 | 1998-04-11 20:05:43 +0000 | [diff] [blame] | 51 | objects can be made more efficient by using the function |
| 52 | \function{StringIO()} from this module instead. |
| 53 | |
| 54 | Since this module provides a factory function which returns objects of |
| 55 | built-in types, there's no way to build your own version using |
Fred Drake | 543e19d | 1999-04-21 18:15:22 +0000 | [diff] [blame] | 56 | subclassing. Use the original \refmodule{StringIO} module in that case. |
| 57 | |
Fred Drake | 83ff4af | 2000-11-28 16:24:28 +0000 | [diff] [blame] | 58 | Unlike the memory files implemented by the \refmodule{StringIO} |
| 59 | module, those provided by this module are not able to accept Unicode |
| 60 | strings that cannot be encoded as plain \ASCII{} strings. |
| 61 | |
Raymond Hettinger | 2adbb83 | 2003-01-31 05:17:33 +0000 | [diff] [blame] | 62 | Another difference from the \refmodule{StringIO} module is that calling |
| 63 | \function{StringIO()} with a string parameter creates a read-only object. |
| 64 | Unlike an object created without a string parameter, it does not have |
Skip Montanaro | bc961e5 | 2003-08-11 15:06:07 +0000 | [diff] [blame] | 65 | write methods. These objects are not generally visible. They turn up in |
| 66 | tracebacks as \class{StringI} and \class{StringO}. |
Raymond Hettinger | 2adbb83 | 2003-01-31 05:17:33 +0000 | [diff] [blame] | 67 | |
Fred Drake | 543e19d | 1999-04-21 18:15:22 +0000 | [diff] [blame] | 68 | The following data objects are provided as well: |
| 69 | |
| 70 | |
| 71 | \begin{datadesc}{InputType} |
| 72 | The type object of the objects created by calling |
| 73 | \function{StringIO} with a string parameter. |
| 74 | \end{datadesc} |
| 75 | |
| 76 | \begin{datadesc}{OutputType} |
| 77 | The type object of the objects returned by calling |
| 78 | \function{StringIO} with no parameters. |
| 79 | \end{datadesc} |
| 80 | |
| 81 | |
| 82 | There is a C API to the module as well; refer to the module source for |
| 83 | more information. |