2 The io module provides the Python interfaces to stream handling. The
3 builtin open function is defined in this module.
5 At the top of the I/O hierarchy is the abstract base class IOBase. It
6 defines the basic interface to a stream. Note, however, that there is no
7 seperation between reading and writing to streams; implementations are
8 allowed to throw an IOError if they do not support a given operation.
10 Extending IOBase is RawIOBase which deals simply with the reading and
11 writing of raw bytes to a stream. FileIO subclasses RawIOBase to provide
12 an interface to OS files.
14 BufferedIOBase deals with buffering on a raw byte stream (RawIOBase). Its
15 subclasses, BufferedWriter, BufferedReader, and BufferedRWPair buffer
16 streams that are readable, writable, and both respectively.
17 BufferedRandom provides a buffered interface to random access
18 streams. BytesIO is a simple stream of in-memory bytes.
20 Another IOBase subclass, TextIOBase, deals with the encoding and decoding
21 of streams into text. TextIOWrapper, which extends it, is a buffered text
22 interface to a buffered raw stream (`BufferedIOBase`). Finally, StringIO
23 is a in-memory stream for text.
25 Argument names are not part of the specification, and only the arguments
26 of open() are intended to be used as keyword arguments.
32 An int containing the default buffer size used by the module's buffered
33 I/O classes. open() uses the file's blksize (as obtained by os.stat) if
36 # New I/O library conforming to PEP 3116.
38 # This is a prototype; hopefully eventually some of this will be
41 # XXX edge cases when switching between reading/writing
42 # XXX need to support 1 meaning line-buffered
43 # XXX whenever an argument is None, use the default value
44 # XXX read/write ops should check readable/writable
45 # XXX buffered readinto should work with arbitrary buffer objects
46 # XXX use incremental encoder for text output, at least for UTF-16 and UTF-8-SIG
47 # XXX check writable, readable and seekable in appropriate places
48 from __future__
import print_function
49 from __future__
import unicode_literals
51 __author__
= ("Guido van Rossum <guido@python.org>, "
52 "Mike Verdone <mike.verdone@gmail.com>, "
53 "Mark Russell <mark.russell@zen.co.uk>")
55 __all__
= ["BlockingIOError", "open", "IOBase", "RawIOBase", "FileIO",
56 "BytesIO", "StringIO", "BufferedIOBase",
57 "BufferedReader", "BufferedWriter", "BufferedRWPair",
58 "BufferedRandom", "TextIOBase", "TextIOWrapper"]
66 # open() uses st_blksize whenever we can
67 DEFAULT_BUFFER_SIZE
= 8 * 1024 # bytes
69 # py3k has only new style classes
72 class BlockingIOError(IOError):
74 """Exception raised when I/O would block on a non-blocking I/O stream."""
76 def __init__(self
, errno
, strerror
, characters_written
=0):
77 IOError.__init
__(self
, errno
, strerror
)
78 self
.characters_written
= characters_written
81 def open(file, mode
="r", buffering
=None, encoding
=None, errors
=None,
82 newline
=None, closefd
=True):
83 r
"""Open file and return a stream. If the file cannot be opened, an IOError is
86 file is either a string giving the name (and the path if the file
87 isn't in the current working directory) of the file to be opened or an
88 integer file descriptor of the file to be wrapped. (If a file
89 descriptor is given, it is closed when the returned I/O object is
90 closed, unless closefd is set to False.)
92 mode is an optional string that specifies the mode in which the file
93 is opened. It defaults to 'r' which means open for reading in text
94 mode. Other common values are 'w' for writing (truncating the file if
95 it already exists), and 'a' for appending (which on some Unix systems,
96 means that all writes append to the end of the file regardless of the
97 current seek position). In text mode, if encoding is not specified the
98 encoding used is platform dependent. (For reading and writing raw
99 bytes use binary mode and leave encoding unspecified.) The available
102 ========= ===============================================================
104 --------- ---------------------------------------------------------------
105 'r' open for reading (default)
106 'w' open for writing, truncating the file first
107 'a' open for writing, appending to the end of the file if it exists
109 't' text mode (default)
110 '+' open a disk file for updating (reading and writing)
111 'U' universal newline mode (for backwards compatibility; unneeded
113 ========= ===============================================================
115 The default mode is 'rt' (open for reading text). For binary random
116 access, the mode 'w+b' opens and truncates the file to 0 bytes, while
117 'r+b' opens the file without truncation.
119 Python distinguishes between files opened in binary and text modes,
120 even when the underlying operating system doesn't. Files opened in
121 binary mode (appending 'b' to the mode argument) return contents as
122 bytes objects without any decoding. In text mode (the default, or when
123 't' is appended to the mode argument), the contents of the file are
124 returned as strings, the bytes having been first decoded using a
125 platform-dependent encoding or using the specified encoding if given.
127 buffering is an optional integer used to set the buffering policy. By
128 default full buffering is on. Pass 0 to switch buffering off (only
129 allowed in binary mode), 1 to set line buffering, and an integer > 1
132 encoding is the name of the encoding used to decode or encode the
133 file. This should only be used in text mode. The default encoding is
134 platform dependent, but any encoding supported by Python can be
135 passed. See the codecs module for the list of supported encodings.
137 errors is an optional string that specifies how encoding errors are to
138 be handled---this argument should not be used in binary mode. Pass
139 'strict' to raise a ValueError exception if there is an encoding error
140 (the default of None has the same effect), or pass 'ignore' to ignore
141 errors. (Note that ignoring encoding errors can lead to data loss.)
142 See the documentation for codecs.register for a list of the permitted
143 encoding error strings.
145 newline controls how universal newlines works (it only applies to text
146 mode). It can be None, '', '\n', '\r', and '\r\n'. It works as
149 * On input, if newline is None, universal newlines mode is
150 enabled. Lines in the input can end in '\n', '\r', or '\r\n', and
151 these are translated into '\n' before being returned to the
152 caller. If it is '', universal newline mode is enabled, but line
153 endings are returned to the caller untranslated. If it has any of
154 the other legal values, input lines are only terminated by the given
155 string, and the line ending is returned to the caller untranslated.
157 * On output, if newline is None, any '\n' characters written are
158 translated to the system default line separator, os.linesep. If
159 newline is '', no translation takes place. If newline is any of the
160 other legal values, any '\n' characters written are translated to
163 If closefd is False, the underlying file descriptor will be kept open
164 when the file is closed. This does not work when a file name is given
165 and must be True in that case.
167 open() returns a file object whose type depends on the mode, and
168 through which the standard file operations such as reading and writing
169 are performed. When open() is used to open a file in a text mode ('w',
170 'r', 'wt', 'rt', etc.), it returns a TextIOWrapper. When used to open
171 a file in a binary mode, the returned class varies: in read binary
172 mode, it returns a BufferedReader; in write binary and append binary
173 modes, it returns a BufferedWriter, and in read/write mode, it returns
176 It is also possible to use a string or bytearray as a file for both
177 reading and writing. For strings StringIO can be used like a file
178 opened in a text mode, and for bytes a BytesIO can be used like a file
179 opened in a binary mode.
181 if not isinstance(file, (basestring
, int)):
182 raise TypeError("invalid file: %r" % file)
183 if not isinstance(mode
, basestring
):
184 raise TypeError("invalid mode: %r" % mode
)
185 if buffering
is not None and not isinstance(buffering
, int):
186 raise TypeError("invalid buffering: %r" % buffering
)
187 if encoding
is not None and not isinstance(encoding
, basestring
):
188 raise TypeError("invalid encoding: %r" % encoding
)
189 if errors
is not None and not isinstance(errors
, basestring
):
190 raise TypeError("invalid errors: %r" % errors
)
192 if modes
- set("arwb+tU") or len(mode
) > len(modes
):
193 raise ValueError("invalid mode: %r" % mode
)
194 reading
= "r" in modes
195 writing
= "w" in modes
196 appending
= "a" in modes
197 updating
= "+" in modes
199 binary
= "b" in modes
201 if writing
or appending
:
202 raise ValueError("can't use U and writing mode at once")
205 raise ValueError("can't have text and binary mode at once")
206 if reading
+ writing
+ appending
> 1:
207 raise ValueError("can't have read/write/append mode at once")
208 if not (reading
or writing
or appending
):
209 raise ValueError("must have exactly one of read/write/append mode")
210 if binary
and encoding
is not None:
211 raise ValueError("binary mode doesn't take an encoding argument")
212 if binary
and errors
is not None:
213 raise ValueError("binary mode doesn't take an errors argument")
214 if binary
and newline
is not None:
215 raise ValueError("binary mode doesn't take a newline argument")
217 (reading
and "r" or "") +
218 (writing
and "w" or "") +
219 (appending
and "a" or "") +
220 (updating
and "+" or ""),
222 if buffering
is None:
224 line_buffering
= False
225 if buffering
== 1 or buffering
< 0 and raw
.isatty():
227 line_buffering
= True
229 buffering
= DEFAULT_BUFFER_SIZE
231 bs
= os
.fstat(raw
.fileno()).st_blksize
232 except (os
.error
, AttributeError):
238 raise ValueError("invalid buffering size")
244 raise ValueError("can't have unbuffered text I/O")
246 buffer = BufferedRandom(raw
, buffering
)
247 elif writing
or appending
:
248 buffer = BufferedWriter(raw
, buffering
)
250 buffer = BufferedReader(raw
, buffering
)
252 raise ValueError("unknown mode: %r" % mode
)
257 text
= TextIOWrapper(buffer, encoding
, errors
, newline
, line_buffering
)
262 class _DocDescriptor
:
263 """Helper for builtins.open.__doc__
265 def __get__(self
, obj
, typ
):
267 "open(file, mode='r', buffering=None, encoding=None, "
268 "errors=None, newline=None, closefd=True)\n\n" +
272 """Wrapper for builtins.open
274 Trick so that open won't become a bound method when stored
275 as a class variable (as dumbdbm does).
277 See initstdio() in Python/pythonrun.c.
279 __doc__
= _DocDescriptor()
281 def __new__(cls
, *args
, **kwargs
):
282 return open(*args
, **kwargs
)
285 class UnsupportedOperation(ValueError, IOError):
289 class IOBase(object):
291 """The abstract base class for all I/O classes, acting on streams of
292 bytes. There is no public constructor.
294 This class provides dummy implementations for many methods that
295 derived classes can override selectively; the default implementations
296 represent a file that cannot be read, written or seeked.
298 Even though IOBase does not declare read, readinto, or write because
299 their signatures will vary, implementations and clients should
300 consider those methods part of the interface. Also, implementations
301 may raise a IOError when operations they do not support are called.
303 The basic type used for binary data read from or written to a file is
304 bytes. bytearrays are accepted too, and in some cases (such as
305 readinto) needed. Text I/O classes work with str data.
307 Note that calling any method (even inquiries) on a closed stream is
308 undefined. Implementations may raise IOError in this case.
310 IOBase (and its subclasses) support the iterator protocol, meaning
311 that an IOBase object can be iterated over yielding the lines in a
314 IOBase also supports the :keyword:`with` statement. In this example,
315 fp is closed after the suite of the with statment is complete:
317 with open('spam.txt', 'r') as fp:
318 fp.write('Spam and eggs!')
321 __metaclass__
= abc
.ABCMeta
325 def _unsupported(self
, name
):
326 """Internal: raise an exception for unsupported operations."""
327 raise UnsupportedOperation("%s.%s() not supported" %
328 (self
.__class
__.__name
__, name
))
332 def seek(self
, pos
, whence
= 0):
333 """Change stream position.
335 Change the stream position to byte offset offset. offset is
336 interpreted relative to the position indicated by whence. Values
339 * 0 -- start of stream (the default); offset should be zero or positive
340 * 1 -- current stream position; offset may be negative
341 * 2 -- end of stream; offset is usually negative
343 Return the new absolute position.
345 self
._unsupported
("seek")
348 """Return current stream position."""
349 return self
.seek(0, 1)
351 def truncate(self
, pos
= None):
352 """Truncate file to size bytes.
354 Size defaults to the current IO position as reported by tell(). Return
357 self
._unsupported
("truncate")
359 ### Flush and close ###
362 """Flush write buffers, if applicable.
364 This is not implemented for read-only and non-blocking streams.
366 # XXX Should this return the number of bytes written???
371 """Flush and close the IO object.
373 This method has no effect if the file is already closed.
375 if not self
.__closed
:
379 pass # If flush() fails, just give up
383 """Destructor. Calls close()."""
384 # The try/except block is in case this is called at program
385 # exit time, when it's possible that globals have already been
386 # deleted, and then the close() call might fail. Since
387 # there's nothing we can do about such failures and they annoy
388 # the end users, we suppress the traceback.
397 """Return whether object supports random access.
399 If False, seek(), tell() and truncate() will raise IOError.
400 This method may need to do a test seek().
404 def _checkSeekable(self
, msg
=None):
405 """Internal: raise an IOError if file is not seekable
407 if not self
.seekable():
408 raise IOError("File or stream is not seekable."
409 if msg
is None else msg
)
413 """Return whether object was opened for reading.
415 If False, read() will raise IOError.
419 def _checkReadable(self
, msg
=None):
420 """Internal: raise an IOError if file is not readable
422 if not self
.readable():
423 raise IOError("File or stream is not readable."
424 if msg
is None else msg
)
427 """Return whether object was opened for writing.
429 If False, write() and truncate() will raise IOError.
433 def _checkWritable(self
, msg
=None):
434 """Internal: raise an IOError if file is not writable
436 if not self
.writable():
437 raise IOError("File or stream is not writable."
438 if msg
is None else msg
)
442 """closed: bool. True iff the file has been closed.
444 For backwards compatibility, this is a property, not a predicate.
448 def _checkClosed(self
, msg
=None):
449 """Internal: raise an ValueError if file is closed
452 raise ValueError("I/O operation on closed file."
453 if msg
is None else msg
)
455 ### Context manager ###
458 """Context management protocol. Returns self."""
462 def __exit__(self
, *args
):
463 """Context management protocol. Calls close()"""
466 ### Lower-level APIs ###
468 # XXX Should these be present even if unimplemented?
471 """Returns underlying file descriptor if one exists.
473 An IOError is raised if the IO object does not use a file descriptor.
475 self
._unsupported
("fileno")
478 """Return whether this is an 'interactive' stream.
480 Return False if it can't be determined.
485 ### Readline[s] and writelines ###
487 def readline(self
, limit
= -1):
488 r
"""Read and return a line from the stream.
490 If limit is specified, at most limit bytes will be read.
492 The line terminator is always b'\n' for binary files; for text
493 files, the newlines argument to open can be used to select the line
494 terminator(s) recognized.
497 if hasattr(self
, "peek"):
499 readahead
= self
.peek(1)
502 n
= (readahead
.find(b
"\n") + 1) or len(readahead
)
511 if not isinstance(limit
, (int, long)):
512 raise TypeError("limit must be an integer")
514 while limit
< 0 or len(res
) < limit
:
515 b
= self
.read(nreadahead())
519 if res
.endswith(b
"\n"):
528 line
= self
.readline()
533 def readlines(self
, hint
=None):
534 """Return a list of lines from the stream.
536 hint can be specified to control the number of lines read: no more
537 lines will be read if the total size (in bytes/characters) of all
538 lines so far exceeds hint.
542 if not isinstance(hint
, (int, long)):
543 raise TypeError("hint must be an integer")
555 def writelines(self
, lines
):
561 class RawIOBase(IOBase
):
563 """Base class for raw binary I/O."""
565 # The read() method is implemented by calling readinto(); derived
566 # classes that want to support read() only need to implement
567 # readinto() as a primitive operation. In general, readinto() can be
568 # more efficient than read().
570 # (It would be tempting to also provide an implementation of
571 # readinto() in terms of read(), in case the latter is a more suitable
572 # primitive operation, but that would lead to nasty recursion in case
573 # a subclass doesn't implement either.)
575 def read(self
, n
= -1):
576 """Read and return up to n bytes.
578 Returns an empty bytes array on EOF, or None if the object is
579 set not to block and has no data to read.
584 return self
.readall()
585 b
= bytearray(n
.__index
__())
591 """Read until EOF, using multiple read() call."""
594 data
= self
.read(DEFAULT_BUFFER_SIZE
)
600 def readinto(self
, b
):
601 """Read up to len(b) bytes into b.
603 Returns number of bytes read (0 for EOF), or None if the object
604 is set not to block as has no data to read.
606 self
._unsupported
("readinto")
609 """Write the given buffer to the IO stream.
611 Returns the number of bytes written, which may be less than len(b).
613 self
._unsupported
("write")
616 class FileIO(_fileio
._FileIO
, RawIOBase
):
618 """Raw I/O implementation for OS files."""
620 # This multiply inherits from _FileIO and RawIOBase to make
621 # isinstance(io.FileIO(), io.RawIOBase) return True without requiring
622 # that _fileio._FileIO inherits from io.RawIOBase (which would be hard
623 # to do since _fileio.c is written in C).
626 _fileio
._FileIO
.close(self
)
627 RawIOBase
.close(self
)
638 class BufferedIOBase(IOBase
):
640 """Base class for buffered IO objects.
642 The main difference with RawIOBase is that the read() method
643 supports omitting the size argument, and does not have a default
644 implementation that defers to readinto().
646 In addition, read(), readinto() and write() may raise
647 BlockingIOError if the underlying raw stream is in non-blocking
648 mode and not ready; unlike their raw counterparts, they will never
651 A typical implementation should not inherit from a RawIOBase
652 implementation, but wrap one.
655 def read(self
, n
= None):
656 """Read and return up to n bytes.
658 If the argument is omitted, None, or negative, reads and
659 returns all data until EOF.
661 If the argument is positive, and the underlying raw stream is
662 not 'interactive', multiple raw reads may be issued to satisfy
663 the byte count (unless EOF is reached first). But for
664 interactive raw streams (XXX and for pipes?), at most one raw
665 read will be issued, and a short result does not imply that
668 Returns an empty bytes array on EOF.
670 Raises BlockingIOError if the underlying raw stream has no
673 self
._unsupported
("read")
675 def readinto(self
, b
):
676 """Read up to len(b) bytes into b.
678 Like read(), this may issue multiple reads to the underlying raw
679 stream, unless the latter is 'interactive'.
681 Returns the number of bytes read (0 for EOF).
683 Raises BlockingIOError if the underlying raw stream has no
686 # XXX This ought to work with anything that supports the buffer API
687 data
= self
.read(len(b
))
691 except TypeError as err
:
693 if not isinstance(b
, array
.array
):
695 b
[:n
] = array
.array(b
'b', data
)
699 """Write the given buffer to the IO stream.
701 Return the number of bytes written, which is never less than
704 Raises BlockingIOError if the buffer is full and the
705 underlying raw stream cannot accept more data at the moment.
707 self
._unsupported
("write")
710 class _BufferedIOMixin(BufferedIOBase
):
712 """A mixin implementation of BufferedIOBase with an underlying raw stream.
714 This passes most requests on to the underlying raw stream. It
715 does *not* provide implementations of read(), readinto() or
719 def __init__(self
, raw
):
724 def seek(self
, pos
, whence
=0):
725 return self
.raw
.seek(pos
, whence
)
728 return self
.raw
.tell()
730 def truncate(self
, pos
=None):
731 # Flush the stream. We're mixing buffered I/O with lower-level I/O,
732 # and a flush may be necessary to synch both views of the current
738 # XXX: Should seek() be used, instead of passing the position
739 # XXX directly to truncate?
740 return self
.raw
.truncate(pos
)
742 ### Flush and close ###
752 pass # If flush() fails, just give up
758 return self
.raw
.seekable()
761 return self
.raw
.readable()
764 return self
.raw
.writable()
768 return self
.raw
.closed
770 ### Lower-level APIs ###
773 return self
.raw
.fileno()
776 return self
.raw
.isatty()
779 class _BytesIO(BufferedIOBase
):
781 """Buffered I/O implementation using an in-memory bytes buffer."""
785 def __init__(self
, initial_bytes
=None):
787 if initial_bytes
is not None:
788 buf
+= bytearray(initial_bytes
)
793 """Return the bytes value (contents) of the buffer
796 raise ValueError("getvalue on closed file")
797 return bytes(self
._buffer
)
799 def read(self
, n
=None):
801 raise ValueError("read from closed file")
804 if not isinstance(n
, (int, long)):
805 raise TypeError("argument must be an integer")
807 n
= len(self
._buffer
)
808 if len(self
._buffer
) <= self
._pos
:
810 newpos
= min(len(self
._buffer
), self
._pos
+ n
)
811 b
= self
._buffer
[self
._pos
: newpos
]
816 """this is the same as read.
822 raise ValueError("write to closed file")
823 if isinstance(b
, unicode):
824 raise TypeError("can't write unicode to binary stream")
829 if pos
> len(self
._buffer
):
830 # Inserts null bytes between the current end of the file
831 # and the new write position.
832 padding
= b
'\x00' * (pos
- len(self
._buffer
))
833 self
._buffer
+= padding
834 self
._buffer
[pos
:pos
+ n
] = b
838 def seek(self
, pos
, whence
=0):
840 raise ValueError("seek on closed file")
842 pos
= pos
.__index
__()
843 except AttributeError as err
:
844 raise TypeError("an integer is required") # from err
847 raise ValueError("negative seek position %r" % (pos
,))
850 self
._pos
= max(0, self
._pos
+ pos
)
852 self
._pos
= max(0, len(self
._buffer
) + pos
)
854 raise ValueError("invalid whence value")
859 raise ValueError("tell on closed file")
862 def truncate(self
, pos
=None):
864 raise ValueError("truncate on closed file")
868 raise ValueError("negative truncate position %r" % (pos
,))
869 del self
._buffer
[pos
:]
870 return self
.seek(pos
)
881 # Use the faster implementation of BytesIO if available
885 class BytesIO(_bytesio
._BytesIO
, BufferedIOBase
):
886 __doc__
= _bytesio
._BytesIO
.__doc
__
892 class BufferedReader(_BufferedIOMixin
):
894 """BufferedReader(raw[, buffer_size])
896 A buffer for a readable, sequential BaseRawIO object.
898 The constructor creates a BufferedReader for the given readable raw
899 stream and buffer_size. If buffer_size is omitted, DEFAULT_BUFFER_SIZE
903 def __init__(self
, raw
, buffer_size
=DEFAULT_BUFFER_SIZE
):
904 """Create a new buffered reader using the given readable raw IO object.
907 _BufferedIOMixin
.__init
__(self
, raw
)
908 self
.buffer_size
= buffer_size
909 self
._reset
_read
_buf
()
910 self
._read
_lock
= threading
.Lock()
912 def _reset_read_buf(self
):
916 def read(self
, n
=None):
919 Returns exactly n bytes of data unless the underlying raw IO
920 stream reaches EOF or if the call would block in non-blocking
921 mode. If n is negative, read until EOF or until read() would
924 with self
._read
_lock
:
925 return self
._read
_unlocked
(n
)
927 def _read_unlocked(self
, n
=None):
929 empty_values
= (b
"", None)
933 # Special case for when the number of bytes to read is unspecified.
934 if n
is None or n
== -1:
935 self
._reset
_read
_buf
()
936 chunks
= [buf
[pos
:]] # Strip the consumed bytes.
939 # Read until EOF or until read() would block.
940 chunk
= self
.raw
.read()
941 if chunk
in empty_values
:
944 current_size
+= len(chunk
)
946 return b
"".join(chunks
) or nodata_val
948 # The number of bytes to read is specified, return at most n bytes.
949 avail
= len(buf
) - pos
# Length of the available buffered data.
951 # Fast path: the data to read is fully buffered.
953 return buf
[pos
:pos
+n
]
954 # Slow path: read from the stream until enough bytes are read,
955 # or until an EOF occurs or until read() would block.
957 wanted
= max(self
.buffer_size
, n
)
959 chunk
= self
.raw
.read(wanted
)
960 if chunk
in empty_values
:
965 # n is more then avail only when an EOF occurred or when
966 # read() would have blocked.
968 out
= b
"".join(chunks
)
969 self
._read
_buf
= out
[n
:] # Save the extra data in the buffer.
971 return out
[:n
] if out
else nodata_val
974 """Returns buffered bytes without advancing the position.
976 The argument indicates a desired minimal number of bytes; we
977 do at most one raw read to satisfy it. We never return more
978 than self.buffer_size.
980 with self
._read
_lock
:
981 return self
._peek
_unlocked
(n
)
983 def _peek_unlocked(self
, n
=0):
984 want
= min(n
, self
.buffer_size
)
985 have
= len(self
._read
_buf
) - self
._read
_pos
987 to_read
= self
.buffer_size
- have
988 current
= self
.raw
.read(to_read
)
990 self
._read
_buf
= self
._read
_buf
[self
._read
_pos
:] + current
992 return self
._read
_buf
[self
._read
_pos
:]
995 """Reads up to n bytes, with at most one read() system call."""
996 # Returns up to n bytes. If at least one byte is buffered, we
997 # only return buffered bytes. Otherwise, we do one raw read.
1000 with self
._read
_lock
:
1001 self
._peek
_unlocked
(1)
1002 return self
._read
_unlocked
(
1003 min(n
, len(self
._read
_buf
) - self
._read
_pos
))
1006 return self
.raw
.tell() - len(self
._read
_buf
) + self
._read
_pos
1008 def seek(self
, pos
, whence
=0):
1009 with self
._read
_lock
:
1011 pos
-= len(self
._read
_buf
) - self
._read
_pos
1012 pos
= self
.raw
.seek(pos
, whence
)
1013 self
._reset
_read
_buf
()
1017 class BufferedWriter(_BufferedIOMixin
):
1019 """A buffer for a writeable sequential RawIO object.
1021 The constructor creates a BufferedWriter for the given writeable raw
1022 stream. If the buffer_size is not given, it defaults to
1023 DEAFULT_BUFFER_SIZE. If max_buffer_size is omitted, it defaults to
1024 twice the buffer size.
1027 def __init__(self
, raw
,
1028 buffer_size
=DEFAULT_BUFFER_SIZE
, max_buffer_size
=None):
1029 raw
._checkWritable
()
1030 _BufferedIOMixin
.__init
__(self
, raw
)
1031 self
.buffer_size
= buffer_size
1032 self
.max_buffer_size
= (2*buffer_size
1033 if max_buffer_size
is None
1034 else max_buffer_size
)
1035 self
._write
_buf
= bytearray()
1036 self
._write
_lock
= threading
.Lock()
1040 raise ValueError("write to closed file")
1041 if isinstance(b
, unicode):
1042 raise TypeError("can't write unicode to binary stream")
1043 with self
._write
_lock
:
1044 # XXX we can implement some more tricks to try and avoid
1046 if len(self
._write
_buf
) > self
.buffer_size
:
1047 # We're full, so let's pre-flush the buffer
1049 self
._flush
_unlocked
()
1050 except BlockingIOError
as e
:
1051 # We can't accept anything else.
1052 # XXX Why not just let the exception pass through?
1053 raise BlockingIOError(e
.errno
, e
.strerror
, 0)
1054 before
= len(self
._write
_buf
)
1055 self
._write
_buf
.extend(b
)
1056 written
= len(self
._write
_buf
) - before
1057 if len(self
._write
_buf
) > self
.buffer_size
:
1059 self
._flush
_unlocked
()
1060 except BlockingIOError
as e
:
1061 if len(self
._write
_buf
) > self
.max_buffer_size
:
1062 # We've hit max_buffer_size. We have to accept a
1063 # partial write and cut back our buffer.
1064 overage
= len(self
._write
_buf
) - self
.max_buffer_size
1065 self
._write
_buf
= self
._write
_buf
[:self
.max_buffer_size
]
1066 raise BlockingIOError(e
.errno
, e
.strerror
, overage
)
1069 def truncate(self
, pos
=None):
1070 with self
._write
_lock
:
1071 self
._flush
_unlocked
()
1073 pos
= self
.raw
.tell()
1074 return self
.raw
.truncate(pos
)
1077 with self
._write
_lock
:
1078 self
._flush
_unlocked
()
1080 def _flush_unlocked(self
):
1082 raise ValueError("flush of closed file")
1085 while self
._write
_buf
:
1086 n
= self
.raw
.write(self
._write
_buf
)
1087 del self
._write
_buf
[:n
]
1089 except BlockingIOError
as e
:
1090 n
= e
.characters_written
1091 del self
._write
_buf
[:n
]
1093 raise BlockingIOError(e
.errno
, e
.strerror
, written
)
1096 return self
.raw
.tell() + len(self
._write
_buf
)
1098 def seek(self
, pos
, whence
=0):
1099 with self
._write
_lock
:
1100 self
._flush
_unlocked
()
1101 return self
.raw
.seek(pos
, whence
)
1104 class BufferedRWPair(BufferedIOBase
):
1106 """A buffered reader and writer object together.
1108 A buffered reader object and buffered writer object put together to
1109 form a sequential IO object that can read and write. This is typically
1110 used with a socket or two-way pipe.
1112 reader and writer are RawIOBase objects that are readable and
1113 writeable respectively. If the buffer_size is omitted it defaults to
1114 DEFAULT_BUFFER_SIZE. The max_buffer_size (for the buffered writer)
1115 defaults to twice the buffer size.
1118 # XXX The usefulness of this (compared to having two separate IO
1119 # objects) is questionable.
1121 def __init__(self
, reader
, writer
,
1122 buffer_size
=DEFAULT_BUFFER_SIZE
, max_buffer_size
=None):
1125 The arguments are two RawIO instances.
1127 reader
._checkReadable
()
1128 writer
._checkWritable
()
1129 self
.reader
= BufferedReader(reader
, buffer_size
)
1130 self
.writer
= BufferedWriter(writer
, buffer_size
, max_buffer_size
)
1132 def read(self
, n
=None):
1135 return self
.reader
.read(n
)
1137 def readinto(self
, b
):
1138 return self
.reader
.readinto(b
)
1141 return self
.writer
.write(b
)
1143 def peek(self
, n
=0):
1144 return self
.reader
.peek(n
)
1147 return self
.reader
.read1(n
)
1150 return self
.reader
.readable()
1153 return self
.writer
.writable()
1156 return self
.writer
.flush()
1163 return self
.reader
.isatty() or self
.writer
.isatty()
1167 return self
.writer
.closed()
1170 class BufferedRandom(BufferedWriter
, BufferedReader
):
1172 """A buffered interface to random access streams.
1174 The constructor creates a reader and writer for a seekable stream,
1175 raw, given in the first argument. If the buffer_size is omitted it
1176 defaults to DEFAULT_BUFFER_SIZE. The max_buffer_size (for the buffered
1177 writer) defaults to twice the buffer size.
1180 def __init__(self
, raw
,
1181 buffer_size
=DEFAULT_BUFFER_SIZE
, max_buffer_size
=None):
1182 raw
._checkSeekable
()
1183 BufferedReader
.__init
__(self
, raw
, buffer_size
)
1184 BufferedWriter
.__init
__(self
, raw
, buffer_size
, max_buffer_size
)
1186 def seek(self
, pos
, whence
=0):
1188 # First do the raw seek, then empty the read buffer, so that
1189 # if the raw seek fails, we don't lose buffered data forever.
1190 pos
= self
.raw
.seek(pos
, whence
)
1191 with self
._read
_lock
:
1192 self
._reset
_read
_buf
()
1197 return self
.raw
.tell() + len(self
._write
_buf
)
1199 return BufferedReader
.tell(self
)
1201 def truncate(self
, pos
=None):
1204 # Use seek to flush the read buffer.
1206 return BufferedWriter
.truncate(self
)
1208 def read(self
, n
=None):
1212 return BufferedReader
.read(self
, n
)
1214 def readinto(self
, b
):
1216 return BufferedReader
.readinto(self
, b
)
1218 def peek(self
, n
=0):
1220 return BufferedReader
.peek(self
, n
)
1224 return BufferedReader
.read1(self
, n
)
1229 with self
._read
_lock
:
1230 self
.raw
.seek(self
._read
_pos
- len(self
._read
_buf
), 1)
1231 self
._reset
_read
_buf
()
1232 return BufferedWriter
.write(self
, b
)
1235 class TextIOBase(IOBase
):
1237 """Base class for text I/O.
1239 This class provides a character and line based interface to stream
1240 I/O. There is no readinto method because Python's character strings
1241 are immutable. There is no public constructor.
1244 def read(self
, n
= -1):
1245 """Read at most n characters from stream.
1247 Read from underlying buffer until we have n characters or we hit EOF.
1248 If n is negative or omitted, read until EOF.
1250 self
._unsupported
("read")
1253 """Write string s to stream."""
1254 self
._unsupported
("write")
1256 def truncate(self
, pos
= None):
1257 """Truncate size to pos."""
1258 self
._unsupported
("truncate")
1261 """Read until newline or EOF.
1263 Returns an empty string if EOF is hit immediately.
1265 self
._unsupported
("readline")
1269 """Subclasses should override."""
1274 """Line endings translated so far.
1276 Only line endings translated during reading are considered.
1278 Subclasses should override.
1283 class IncrementalNewlineDecoder(codecs
.IncrementalDecoder
):
1284 """Codec used when reading a file in universal newlines mode.
1285 It wraps another incremental decoder, translating \\r\\n and \\r into \\n.
1286 It also records the types of newlines encountered.
1287 When used with translate=False, it ensures that the newline sequence is
1288 returned in one piece.
1290 def __init__(self
, decoder
, translate
, errors
='strict'):
1291 codecs
.IncrementalDecoder
.__init
__(self
, errors
=errors
)
1293 self
.translate
= translate
1294 self
.decoder
= decoder
1297 def decode(self
, input, final
=False):
1298 # decode input (with the eventual \r from a previous pass)
1300 input = self
.buffer + input
1302 output
= self
.decoder
.decode(input, final
=final
)
1304 # retain last \r even when not translating data:
1305 # then readline() is sure to get \r\n in one pass
1306 if output
.endswith("\r") and not final
:
1307 output
= output
[:-1]
1312 # Record which newlines are read
1313 crlf
= output
.count('\r\n')
1314 cr
= output
.count('\r') - crlf
1315 lf
= output
.count('\n') - crlf
1316 self
.seennl |
= (lf
and self
._LF
) |
(cr
and self
._CR
) \
1317 |
(crlf
and self
._CRLF
)
1321 output
= output
.replace("\r\n", "\n")
1323 output
= output
.replace("\r", "\n")
1328 buf
, flag
= self
.decoder
.getstate()
1329 return buf
+ self
.buffer, flag
1331 def setstate(self
, state
):
1333 if buf
.endswith(b
'\r'):
1338 self
.decoder
.setstate((buf
, flag
))
1343 self
.decoder
.reset()
1358 ("\r", "\n", "\r\n")
1362 class TextIOWrapper(TextIOBase
):
1364 r
"""Character and line based layer over a BufferedIOBase object, buffer.
1366 encoding gives the name of the encoding that the stream will be
1367 decoded or encoded with. It defaults to locale.getpreferredencoding.
1369 errors determines the strictness of encoding and decoding (see the
1370 codecs.register) and defaults to "strict".
1372 newline can be None, '', '\n', '\r', or '\r\n'. It controls the
1373 handling of line endings. If it is None, universal newlines is
1374 enabled. With this enabled, on input, the lines endings '\n', '\r',
1375 or '\r\n' are translated to '\n' before being returned to the
1376 caller. Conversely, on output, '\n' is translated to the system
1377 default line seperator, os.linesep. If newline is any other of its
1378 legal values, that newline becomes the newline when the file is read
1379 and it is returned untranslated. On output, '\n' is converted to the
1382 If line_buffering is True, a call to flush is implied when a call to
1383 write contains a newline character.
1388 def __init__(self
, buffer, encoding
=None, errors
=None, newline
=None,
1389 line_buffering
=False):
1390 if newline
not in (None, "", "\n", "\r", "\r\n"):
1391 raise ValueError("illegal newline value: %r" % (newline
,))
1392 if encoding
is None:
1394 encoding
= os
.device_encoding(buffer.fileno())
1395 except (AttributeError, UnsupportedOperation
):
1397 if encoding
is None:
1401 # Importing locale may fail if Python is being built
1404 encoding
= locale
.getpreferredencoding()
1406 if not isinstance(encoding
, basestring
):
1407 raise ValueError("invalid encoding: %r" % encoding
)
1412 if not isinstance(errors
, basestring
):
1413 raise ValueError("invalid errors: %r" % errors
)
1415 self
.buffer = buffer
1416 self
._line
_buffering
= line_buffering
1417 self
._encoding
= encoding
1418 self
._errors
= errors
1419 self
._readuniversal
= not newline
1420 self
._readtranslate
= newline
is None
1421 self
._readnl
= newline
1422 self
._writetranslate
= newline
!= ''
1423 self
._writenl
= newline
or os
.linesep
1424 self
._encoder
= None
1425 self
._decoder
= None
1426 self
._decoded
_chars
= '' # buffer for text returned from decoder
1427 self
._decoded
_chars
_used
= 0 # offset into _decoded_chars for read()
1428 self
._snapshot
= None # info for reconstructing decoder state
1429 self
._seekable
= self
._telling
= self
.buffer.seekable()
1431 # self._snapshot is either None, or a tuple (dec_flags, next_input)
1432 # where dec_flags is the second (integer) item of the decoder state
1433 # and next_input is the chunk of input bytes that comes next after the
1434 # snapshot point. We use this to reconstruct decoder states in tell().
1436 # Naming convention:
1437 # - "bytes_..." for integer variables that count input bytes
1438 # - "chars_..." for integer variables that count decoded characters
1442 return self
._encoding
1449 def line_buffering(self
):
1450 return self
._line
_buffering
1453 return self
._seekable
1456 return self
.buffer.readable()
1459 return self
.buffer.writable()
1463 self
._telling
= self
._seekable
1469 pass # If flush() fails, just give up
1474 return self
.buffer.closed
1477 return self
.buffer.fileno()
1480 return self
.buffer.isatty()
1484 raise ValueError("write to closed file")
1485 if not isinstance(s
, unicode):
1486 raise TypeError("can't write %s to text stream" %
1487 s
.__class
__.__name
__)
1489 haslf
= (self
._writetranslate
or self
._line
_buffering
) and "\n" in s
1490 if haslf
and self
._writetranslate
and self
._writenl
!= "\n":
1491 s
= s
.replace("\n", self
._writenl
)
1492 encoder
= self
._encoder
or self
._get
_encoder
()
1493 # XXX What if we were just reading?
1494 b
= encoder
.encode(s
)
1495 self
.buffer.write(b
)
1496 if self
._line
_buffering
and (haslf
or "\r" in s
):
1498 self
._snapshot
= None
1500 self
._decoder
.reset()
1503 def _get_encoder(self
):
1504 make_encoder
= codecs
.getincrementalencoder(self
._encoding
)
1505 self
._encoder
= make_encoder(self
._errors
)
1506 return self
._encoder
1508 def _get_decoder(self
):
1509 make_decoder
= codecs
.getincrementaldecoder(self
._encoding
)
1510 decoder
= make_decoder(self
._errors
)
1511 if self
._readuniversal
:
1512 decoder
= IncrementalNewlineDecoder(decoder
, self
._readtranslate
)
1513 self
._decoder
= decoder
1516 # The following three methods implement an ADT for _decoded_chars.
1517 # Text returned from the decoder is buffered here until the client
1518 # requests it by calling our read() or readline() method.
1519 def _set_decoded_chars(self
, chars
):
1520 """Set the _decoded_chars buffer."""
1521 self
._decoded
_chars
= chars
1522 self
._decoded
_chars
_used
= 0
1524 def _get_decoded_chars(self
, n
=None):
1525 """Advance into the _decoded_chars buffer."""
1526 offset
= self
._decoded
_chars
_used
1528 chars
= self
._decoded
_chars
[offset
:]
1530 chars
= self
._decoded
_chars
[offset
:offset
+ n
]
1531 self
._decoded
_chars
_used
+= len(chars
)
1534 def _rewind_decoded_chars(self
, n
):
1535 """Rewind the _decoded_chars buffer."""
1536 if self
._decoded
_chars
_used
< n
:
1537 raise AssertionError("rewind decoded_chars out of bounds")
1538 self
._decoded
_chars
_used
-= n
1540 def _read_chunk(self
):
1542 Read and decode the next chunk of data from the BufferedReader.
1544 The return value is True unless EOF was reached. The decoded string
1545 is placed in self._decoded_chars (replacing its previous value).
1546 The entire input chunk is sent to the decoder, though some of it
1547 may remain buffered in the decoder, yet to be converted.
1550 if self
._decoder
is None:
1551 raise ValueError("no decoder")
1554 # To prepare for tell(), we need to snapshot a point in the
1555 # file where the decoder's input buffer is empty.
1557 dec_buffer
, dec_flags
= self
._decoder
.getstate()
1558 # Given this, we know there was a valid snapshot point
1559 # len(dec_buffer) bytes ago with decoder state (b'', dec_flags).
1561 # Read a chunk, decode it, and put the result in self._decoded_chars.
1562 input_chunk
= self
.buffer.read1(self
._CHUNK
_SIZE
)
1563 eof
= not input_chunk
1564 self
._set
_decoded
_chars
(self
._decoder
.decode(input_chunk
, eof
))
1567 # At the snapshot point, len(dec_buffer) bytes before the read,
1568 # the next input to be decoded is dec_buffer + input_chunk.
1569 self
._snapshot
= (dec_flags
, dec_buffer
+ input_chunk
)
1573 def _pack_cookie(self
, position
, dec_flags
=0,
1574 bytes_to_feed
=0, need_eof
=0, chars_to_skip
=0):
1575 # The meaning of a tell() cookie is: seek to position, set the
1576 # decoder flags to dec_flags, read bytes_to_feed bytes, feed them
1577 # into the decoder with need_eof as the EOF flag, then skip
1578 # chars_to_skip characters of the decoded result. For most simple
1579 # decoders, tell() will often just give a byte offset in the file.
1580 return (position |
(dec_flags
<<64) |
(bytes_to_feed
<<128) |
1581 (chars_to_skip
<<192) |
bool(need_eof
)<<256)
1583 def _unpack_cookie(self
, bigint
):
1584 rest
, position
= divmod(bigint
, 1<<64)
1585 rest
, dec_flags
= divmod(rest
, 1<<64)
1586 rest
, bytes_to_feed
= divmod(rest
, 1<<64)
1587 need_eof
, chars_to_skip
= divmod(rest
, 1<<64)
1588 return position
, dec_flags
, bytes_to_feed
, need_eof
, chars_to_skip
1591 if not self
._seekable
:
1592 raise IOError("underlying stream is not seekable")
1593 if not self
._telling
:
1594 raise IOError("telling position disabled by next() call")
1596 position
= self
.buffer.tell()
1597 decoder
= self
._decoder
1598 if decoder
is None or self
._snapshot
is None:
1599 if self
._decoded
_chars
:
1600 # This should never happen.
1601 raise AssertionError("pending decoded text")
1604 # Skip backward to the snapshot point (see _read_chunk).
1605 dec_flags
, next_input
= self
._snapshot
1606 position
-= len(next_input
)
1608 # How many decoded characters have been used up since the snapshot?
1609 chars_to_skip
= self
._decoded
_chars
_used
1610 if chars_to_skip
== 0:
1611 # We haven't moved from the snapshot point.
1612 return self
._pack
_cookie
(position
, dec_flags
)
1614 # Starting from the snapshot position, we will walk the decoder
1615 # forward until it gives us enough decoded characters.
1616 saved_state
= decoder
.getstate()
1618 # Note our initial start point.
1619 decoder
.setstate((b
'', dec_flags
))
1620 start_pos
= position
1621 start_flags
, bytes_fed
, chars_decoded
= dec_flags
, 0, 0
1624 # Feed the decoder one byte at a time. As we go, note the
1625 # nearest "safe start point" before the current location
1626 # (a point where the decoder has nothing buffered, so seek()
1627 # can safely start from there and advance to this location).
1628 for next_byte
in next_input
:
1630 chars_decoded
+= len(decoder
.decode(next_byte
))
1631 dec_buffer
, dec_flags
= decoder
.getstate()
1632 if not dec_buffer
and chars_decoded
<= chars_to_skip
:
1633 # Decoder buffer is empty, so this is a safe start point.
1634 start_pos
+= bytes_fed
1635 chars_to_skip
-= chars_decoded
1636 start_flags
, bytes_fed
, chars_decoded
= dec_flags
, 0, 0
1637 if chars_decoded
>= chars_to_skip
:
1640 # We didn't get enough decoded data; signal EOF to get more.
1641 chars_decoded
+= len(decoder
.decode(b
'', final
=True))
1643 if chars_decoded
< chars_to_skip
:
1644 raise IOError("can't reconstruct logical file position")
1646 # The returned cookie corresponds to the last safe start point.
1647 return self
._pack
_cookie
(
1648 start_pos
, start_flags
, bytes_fed
, need_eof
, chars_to_skip
)
1650 decoder
.setstate(saved_state
)
1652 def truncate(self
, pos
=None):
1657 return self
.buffer.truncate()
1659 def seek(self
, cookie
, whence
=0):
1661 raise ValueError("tell on closed file")
1662 if not self
._seekable
:
1663 raise IOError("underlying stream is not seekable")
1664 if whence
== 1: # seek relative to current position
1666 raise IOError("can't do nonzero cur-relative seeks")
1667 # Seeking to the current position should attempt to
1668 # sync the underlying buffer with the current position.
1670 cookie
= self
.tell()
1671 if whence
== 2: # seek relative to end of file
1673 raise IOError("can't do nonzero end-relative seeks")
1675 position
= self
.buffer.seek(0, 2)
1676 self
._set
_decoded
_chars
('')
1677 self
._snapshot
= None
1679 self
._decoder
.reset()
1682 raise ValueError("invalid whence (%r, should be 0, 1 or 2)" %
1685 raise ValueError("negative seek position %r" % (cookie
,))
1688 # The strategy of seek() is to go back to the safe start point
1689 # and replay the effect of read(chars_to_skip) from there.
1690 start_pos
, dec_flags
, bytes_to_feed
, need_eof
, chars_to_skip
= \
1691 self
._unpack
_cookie
(cookie
)
1693 # Seek back to the safe start point.
1694 self
.buffer.seek(start_pos
)
1695 self
._set
_decoded
_chars
('')
1696 self
._snapshot
= None
1698 # Restore the decoder to its state from the safe start point.
1699 if self
._decoder
or dec_flags
or chars_to_skip
:
1700 self
._decoder
= self
._decoder
or self
._get
_decoder
()
1701 self
._decoder
.setstate((b
'', dec_flags
))
1702 self
._snapshot
= (dec_flags
, b
'')
1705 # Just like _read_chunk, feed the decoder and save a snapshot.
1706 input_chunk
= self
.buffer.read(bytes_to_feed
)
1707 self
._set
_decoded
_chars
(
1708 self
._decoder
.decode(input_chunk
, need_eof
))
1709 self
._snapshot
= (dec_flags
, input_chunk
)
1711 # Skip chars_to_skip of the decoded characters.
1712 if len(self
._decoded
_chars
) < chars_to_skip
:
1713 raise IOError("can't restore logical file position")
1714 self
._decoded
_chars
_used
= chars_to_skip
1718 def read(self
, n
=None):
1721 decoder
= self
._decoder
or self
._get
_decoder
()
1724 result
= (self
._get
_decoded
_chars
() +
1725 decoder
.decode(self
.buffer.read(), final
=True))
1726 self
._set
_decoded
_chars
('')
1727 self
._snapshot
= None
1730 # Keep reading chunks until we have n characters to return.
1732 result
= self
._get
_decoded
_chars
(n
)
1733 while len(result
) < n
and not eof
:
1734 eof
= not self
._read
_chunk
()
1735 result
+= self
._get
_decoded
_chars
(n
- len(result
))
1739 self
._telling
= False
1740 line
= self
.readline()
1742 self
._snapshot
= None
1743 self
._telling
= self
._seekable
1747 def readline(self
, limit
=None):
1749 raise ValueError("read from closed file")
1752 if not isinstance(limit
, (int, long)):
1753 raise TypeError("limit must be an integer")
1755 # Grab all the decoded text (we will rewind any extra bits later).
1756 line
= self
._get
_decoded
_chars
()
1759 decoder
= self
._decoder
or self
._get
_decoder
()
1763 if self
._readtranslate
:
1764 # Newlines are already translated, only search for \n
1765 pos
= line
.find('\n', start
)
1772 elif self
._readuniversal
:
1773 # Universal newline search. Find any of \r, \r\n, \n
1774 # The decoder ensures that \r\n are not split in two pieces
1776 # In C we'd look for these in parallel of course.
1777 nlpos
= line
.find("\n", start
)
1778 crpos
= line
.find("\r", start
)
1795 elif nlpos
== crpos
+ 1:
1805 pos
= line
.find(self
._readnl
)
1807 endpos
= pos
+ len(self
._readnl
)
1810 if limit
>= 0 and len(line
) >= limit
:
1811 endpos
= limit
# reached length limit
1814 # No line ending seen yet - get more data
1816 while self
._read
_chunk
():
1817 if self
._decoded
_chars
:
1819 if self
._decoded
_chars
:
1820 line
+= self
._get
_decoded
_chars
()
1823 self
._set
_decoded
_chars
('')
1824 self
._snapshot
= None
1827 if limit
>= 0 and endpos
> limit
:
1828 endpos
= limit
# don't exceed limit
1830 # Rewind _decoded_chars to just after the line ending we found.
1831 self
._rewind
_decoded
_chars
(len(line
) - endpos
)
1832 return line
[:endpos
]
1836 return self
._decoder
.newlines
if self
._decoder
else None
1838 class StringIO(TextIOWrapper
):
1840 """An in-memory stream for text. The initial_value argument sets the
1841 value of object. The other arguments are like those of TextIOWrapper's
1845 def __init__(self
, initial_value
="", encoding
="utf-8",
1846 errors
="strict", newline
="\n"):
1847 super(StringIO
, self
).__init
__(BytesIO(),
1852 if not isinstance(initial_value
, unicode):
1853 initial_value
= unicode(initial_value
)
1854 self
.write(initial_value
)
1859 return self
.buffer.getvalue().decode(self
._encoding
, self
._errors
)