2 Python implementation of the io module.
9 # Import _thread instead of threading to reduce startup cost
11 from _thread
import allocate_lock
as Lock
13 from _dummy_thread
import allocate_lock
as Lock
16 from io
import __all__
17 from io
import SEEK_SET
, SEEK_CUR
, SEEK_END
19 # open() uses st_blksize whenever we can
20 DEFAULT_BUFFER_SIZE
= 8 * 1024 # bytes
22 # NOTE: Base classes defined here are registered with the "official" ABCs
23 # defined in io.py. We don't use real inheritance though, because we don't
24 # want to inherit the C implementations.
27 class BlockingIOError(IOError):
29 """Exception raised when I/O would block on a non-blocking I/O stream."""
31 def __init__(self
, errno
, strerror
, characters_written
=0):
32 super().__init
__(errno
, strerror
)
33 if not isinstance(characters_written
, int):
34 raise TypeError("characters_written must be a integer")
35 self
.characters_written
= characters_written
38 def open(file: (str, bytes
), mode
: str = "r", buffering
: int = None,
39 encoding
: str = None, errors
: str = None,
40 newline
: str = None, closefd
: bool = True) -> "IOBase":
42 r
"""Open file and return a stream. Raise IOError upon failure.
44 file is either a text or byte string giving the name (and the path
45 if the file isn't in the current working directory) of the file to
46 be opened or an integer file descriptor of the file to be
47 wrapped. (If a file descriptor is given, it is closed when the
48 returned I/O object is closed, unless closefd is set to False.)
50 mode is an optional string that specifies the mode in which the file
51 is opened. It defaults to 'r' which means open for reading in text
52 mode. Other common values are 'w' for writing (truncating the file if
53 it already exists), and 'a' for appending (which on some Unix systems,
54 means that all writes append to the end of the file regardless of the
55 current seek position). In text mode, if encoding is not specified the
56 encoding used is platform dependent. (For reading and writing raw
57 bytes use binary mode and leave encoding unspecified.) The available
60 ========= ===============================================================
62 --------- ---------------------------------------------------------------
63 'r' open for reading (default)
64 'w' open for writing, truncating the file first
65 'a' open for writing, appending to the end of the file if it exists
67 't' text mode (default)
68 '+' open a disk file for updating (reading and writing)
69 'U' universal newline mode (for backwards compatibility; unneeded
71 ========= ===============================================================
73 The default mode is 'rt' (open for reading text). For binary random
74 access, the mode 'w+b' opens and truncates the file to 0 bytes, while
75 'r+b' opens the file without truncation.
77 Python distinguishes between files opened in binary and text modes,
78 even when the underlying operating system doesn't. Files opened in
79 binary mode (appending 'b' to the mode argument) return contents as
80 bytes objects without any decoding. In text mode (the default, or when
81 't' is appended to the mode argument), the contents of the file are
82 returned as strings, the bytes having been first decoded using a
83 platform-dependent encoding or using the specified encoding if given.
85 buffering is an optional integer used to set the buffering policy.
86 Pass 0 to switch buffering off (only allowed in binary mode), 1 to select
87 line buffering (only usable in text mode), and an integer > 1 to indicate
88 the size of a fixed-size chunk buffer. When no buffering argument is
89 given, the default buffering policy works as follows:
91 * Binary files are buffered in fixed-size chunks; the size of the buffer
92 is chosen using a heuristic trying to determine the underlying device's
93 "block size" and falling back on `io.DEFAULT_BUFFER_SIZE`.
94 On many systems, the buffer will typically be 4096 or 8192 bytes long.
96 * "Interactive" text files (files for which isatty() returns True)
97 use line buffering. Other text files use the policy described above
100 encoding is the name of the encoding used to decode or encode the
101 file. This should only be used in text mode. The default encoding is
102 platform dependent, but any encoding supported by Python can be
103 passed. See the codecs module for the list of supported encodings.
105 errors is an optional string that specifies how encoding errors are to
106 be handled---this argument should not be used in binary mode. Pass
107 'strict' to raise a ValueError exception if there is an encoding error
108 (the default of None has the same effect), or pass 'ignore' to ignore
109 errors. (Note that ignoring encoding errors can lead to data loss.)
110 See the documentation for codecs.register for a list of the permitted
111 encoding error strings.
113 newline controls how universal newlines works (it only applies to text
114 mode). It can be None, '', '\n', '\r', and '\r\n'. It works as
117 * On input, if newline is None, universal newlines mode is
118 enabled. Lines in the input can end in '\n', '\r', or '\r\n', and
119 these are translated into '\n' before being returned to the
120 caller. If it is '', universal newline mode is enabled, but line
121 endings are returned to the caller untranslated. If it has any of
122 the other legal values, input lines are only terminated by the given
123 string, and the line ending is returned to the caller untranslated.
125 * On output, if newline is None, any '\n' characters written are
126 translated to the system default line separator, os.linesep. If
127 newline is '', no translation takes place. If newline is any of the
128 other legal values, any '\n' characters written are translated to
131 If closefd is False, the underlying file descriptor will be kept open
132 when the file is closed. This does not work when a file name is given
133 and must be True in that case.
135 open() returns a file object whose type depends on the mode, and
136 through which the standard file operations such as reading and writing
137 are performed. When open() is used to open a file in a text mode ('w',
138 'r', 'wt', 'rt', etc.), it returns a TextIOWrapper. When used to open
139 a file in a binary mode, the returned class varies: in read binary
140 mode, it returns a BufferedReader; in write binary and append binary
141 modes, it returns a BufferedWriter, and in read/write mode, it returns
144 It is also possible to use a string or bytearray as a file for both
145 reading and writing. For strings StringIO can be used like a file
146 opened in a text mode, and for bytes a BytesIO can be used like a file
147 opened in a binary mode.
149 if not isinstance(file, (str, bytes
, int)):
150 raise TypeError("invalid file: %r" % file)
151 if not isinstance(mode
, str):
152 raise TypeError("invalid mode: %r" % mode
)
153 if buffering
is not None and not isinstance(buffering
, int):
154 raise TypeError("invalid buffering: %r" % buffering
)
155 if encoding
is not None and not isinstance(encoding
, str):
156 raise TypeError("invalid encoding: %r" % encoding
)
157 if errors
is not None and not isinstance(errors
, str):
158 raise TypeError("invalid errors: %r" % errors
)
160 if modes
- set("arwb+tU") or len(mode
) > len(modes
):
161 raise ValueError("invalid mode: %r" % mode
)
162 reading
= "r" in modes
163 writing
= "w" in modes
164 appending
= "a" in modes
165 updating
= "+" in modes
167 binary
= "b" in modes
169 if writing
or appending
:
170 raise ValueError("can't use U and writing mode at once")
173 raise ValueError("can't have text and binary mode at once")
174 if reading
+ writing
+ appending
> 1:
175 raise ValueError("can't have read/write/append mode at once")
176 if not (reading
or writing
or appending
):
177 raise ValueError("must have exactly one of read/write/append mode")
178 if binary
and encoding
is not None:
179 raise ValueError("binary mode doesn't take an encoding argument")
180 if binary
and errors
is not None:
181 raise ValueError("binary mode doesn't take an errors argument")
182 if binary
and newline
is not None:
183 raise ValueError("binary mode doesn't take a newline argument")
185 (reading
and "r" or "") +
186 (writing
and "w" or "") +
187 (appending
and "a" or "") +
188 (updating
and "+" or ""),
190 if buffering
is None:
192 line_buffering
= False
193 if buffering
== 1 or buffering
< 0 and raw
.isatty():
195 line_buffering
= True
197 buffering
= DEFAULT_BUFFER_SIZE
199 bs
= os
.fstat(raw
.fileno()).st_blksize
200 except (os
.error
, AttributeError):
206 raise ValueError("invalid buffering size")
210 raise ValueError("can't have unbuffered text I/O")
212 buffer = BufferedRandom(raw
, buffering
)
213 elif writing
or appending
:
214 buffer = BufferedWriter(raw
, buffering
)
216 buffer = BufferedReader(raw
, buffering
)
218 raise ValueError("unknown mode: %r" % mode
)
221 text
= TextIOWrapper(buffer, encoding
, errors
, newline
, line_buffering
)
227 """Helper for builtins.open.__doc__
229 def __get__(self
, obj
, typ
):
231 "open(file, mode='r', buffering=None, encoding=None, "
232 "errors=None, newline=None, closefd=True)\n\n" +
236 """Wrapper for builtins.open
238 Trick so that open won't become a bound method when stored
239 as a class variable (as dbm.dumb does).
241 See initstdio() in Python/pythonrun.c.
243 __doc__
= DocDescriptor()
245 def __new__(cls
, *args
, **kwargs
):
246 return open(*args
, **kwargs
)
249 class UnsupportedOperation(ValueError, IOError):
253 class IOBase(metaclass
=abc
.ABCMeta
):
255 """The abstract base class for all I/O classes, acting on streams of
256 bytes. There is no public constructor.
258 This class provides dummy implementations for many methods that
259 derived classes can override selectively; the default implementations
260 represent a file that cannot be read, written or seeked.
262 Even though IOBase does not declare read, readinto, or write because
263 their signatures will vary, implementations and clients should
264 consider those methods part of the interface. Also, implementations
265 may raise a IOError when operations they do not support are called.
267 The basic type used for binary data read from or written to a file is
268 bytes. bytearrays are accepted too, and in some cases (such as
269 readinto) needed. Text I/O classes work with str data.
271 Note that calling any method (even inquiries) on a closed stream is
272 undefined. Implementations may raise IOError in this case.
274 IOBase (and its subclasses) support the iterator protocol, meaning
275 that an IOBase object can be iterated over yielding the lines in a
278 IOBase also supports the :keyword:`with` statement. In this example,
279 fp is closed after the suite of the with statement is complete:
281 with open('spam.txt', 'r') as fp:
282 fp.write('Spam and eggs!')
287 def _unsupported(self
, name
: str) -> IOError:
288 """Internal: raise an exception for unsupported operations."""
289 raise UnsupportedOperation("%s.%s() not supported" %
290 (self
.__class
__.__name
__, name
))
294 def seek(self
, pos
: int, whence
: int = 0) -> int:
295 """Change stream position.
297 Change the stream position to byte offset offset. offset is
298 interpreted relative to the position indicated by whence. Values
301 * 0 -- start of stream (the default); offset should be zero or positive
302 * 1 -- current stream position; offset may be negative
303 * 2 -- end of stream; offset is usually negative
305 Return the new absolute position.
307 self
._unsupported
("seek")
309 def tell(self
) -> int:
310 """Return current stream position."""
311 return self
.seek(0, 1)
313 def truncate(self
, pos
: int = None) -> int:
314 """Truncate file to size bytes.
316 Size defaults to the current IO position as reported by tell(). Return
319 self
._unsupported
("truncate")
321 ### Flush and close ###
323 def flush(self
) -> None:
324 """Flush write buffers, if applicable.
326 This is not implemented for read-only and non-blocking streams.
329 # XXX Should this return the number of bytes written???
333 def close(self
) -> None:
334 """Flush and close the IO object.
336 This method has no effect if the file is already closed.
338 if not self
.__closed
:
342 def __del__(self
) -> None:
343 """Destructor. Calls close()."""
344 # The try/except block is in case this is called at program
345 # exit time, when it's possible that globals have already been
346 # deleted, and then the close() call might fail. Since
347 # there's nothing we can do about such failures and they annoy
348 # the end users, we suppress the traceback.
356 def seekable(self
) -> bool:
357 """Return whether object supports random access.
359 If False, seek(), tell() and truncate() will raise IOError.
360 This method may need to do a test seek().
364 def _checkSeekable(self
, msg
=None):
365 """Internal: raise an IOError if file is not seekable
367 if not self
.seekable():
368 raise IOError("File or stream is not seekable."
369 if msg
is None else msg
)
372 def readable(self
) -> bool:
373 """Return whether object was opened for reading.
375 If False, read() will raise IOError.
379 def _checkReadable(self
, msg
=None):
380 """Internal: raise an IOError if file is not readable
382 if not self
.readable():
383 raise IOError("File or stream is not readable."
384 if msg
is None else msg
)
386 def writable(self
) -> bool:
387 """Return whether object was opened for writing.
389 If False, write() and truncate() will raise IOError.
393 def _checkWritable(self
, msg
=None):
394 """Internal: raise an IOError if file is not writable
396 if not self
.writable():
397 raise IOError("File or stream is not writable."
398 if msg
is None else msg
)
402 """closed: bool. True iff the file has been closed.
404 For backwards compatibility, this is a property, not a predicate.
408 def _checkClosed(self
, msg
=None):
409 """Internal: raise an ValueError if file is closed
412 raise ValueError("I/O operation on closed file."
413 if msg
is None else msg
)
415 ### Context manager ###
417 def __enter__(self
) -> "IOBase": # That's a forward reference
418 """Context management protocol. Returns self."""
422 def __exit__(self
, *args
) -> None:
423 """Context management protocol. Calls close()"""
426 ### Lower-level APIs ###
428 # XXX Should these be present even if unimplemented?
430 def fileno(self
) -> int:
431 """Returns underlying file descriptor if one exists.
433 An IOError is raised if the IO object does not use a file descriptor.
435 self
._unsupported
("fileno")
437 def isatty(self
) -> bool:
438 """Return whether this is an 'interactive' stream.
440 Return False if it can't be determined.
445 ### Readline[s] and writelines ###
447 def readline(self
, limit
: int = -1) -> bytes
:
448 r
"""Read and return a line from the stream.
450 If limit is specified, at most limit bytes will be read.
452 The line terminator is always b'\n' for binary files; for text
453 files, the newlines argument to open can be used to select the line
454 terminator(s) recognized.
456 # For backwards compatibility, a (slowish) readline().
457 if hasattr(self
, "peek"):
459 readahead
= self
.peek(1)
462 n
= (readahead
.find(b
"\n") + 1) or len(readahead
)
471 elif not isinstance(limit
, int):
472 raise TypeError("limit must be an integer")
474 while limit
< 0 or len(res
) < limit
:
475 b
= self
.read(nreadahead())
479 if res
.endswith(b
"\n"):
488 line
= self
.readline()
493 def readlines(self
, hint
=None):
494 """Return a list of lines from the stream.
496 hint can be specified to control the number of lines read: no more
497 lines will be read if the total size (in bytes/characters) of all
498 lines so far exceeds hint.
500 if hint
is None or hint
<= 0:
511 def writelines(self
, lines
):
516 io
.IOBase
.register(IOBase
)
519 class RawIOBase(IOBase
):
521 """Base class for raw binary I/O."""
523 # The read() method is implemented by calling readinto(); derived
524 # classes that want to support read() only need to implement
525 # readinto() as a primitive operation. In general, readinto() can be
526 # more efficient than read().
528 # (It would be tempting to also provide an implementation of
529 # readinto() in terms of read(), in case the latter is a more suitable
530 # primitive operation, but that would lead to nasty recursion in case
531 # a subclass doesn't implement either.)
533 def read(self
, n
: int = -1) -> bytes
:
534 """Read and return up to n bytes.
536 Returns an empty bytes object on EOF, or None if the object is
537 set not to block and has no data to read.
542 return self
.readall()
543 b
= bytearray(n
.__index
__())
549 """Read until EOF, using multiple read() call."""
552 data
= self
.read(DEFAULT_BUFFER_SIZE
)
558 def readinto(self
, b
: bytearray
) -> int:
559 """Read up to len(b) bytes into b.
561 Returns number of bytes read (0 for EOF), or None if the object
562 is set not to block as has no data to read.
564 self
._unsupported
("readinto")
566 def write(self
, b
: bytes
) -> int:
567 """Write the given buffer to the IO stream.
569 Returns the number of bytes written, which may be less than len(b).
571 self
._unsupported
("write")
573 io
.RawIOBase
.register(RawIOBase
)
574 from _io
import FileIO
575 RawIOBase
.register(FileIO
)
578 class BufferedIOBase(IOBase
):
580 """Base class for buffered IO objects.
582 The main difference with RawIOBase is that the read() method
583 supports omitting the size argument, and does not have a default
584 implementation that defers to readinto().
586 In addition, read(), readinto() and write() may raise
587 BlockingIOError if the underlying raw stream is in non-blocking
588 mode and not ready; unlike their raw counterparts, they will never
591 A typical implementation should not inherit from a RawIOBase
592 implementation, but wrap one.
595 def read(self
, n
: int = None) -> bytes
:
596 """Read and return up to n bytes.
598 If the argument is omitted, None, or negative, reads and
599 returns all data until EOF.
601 If the argument is positive, and the underlying raw stream is
602 not 'interactive', multiple raw reads may be issued to satisfy
603 the byte count (unless EOF is reached first). But for
604 interactive raw streams (XXX and for pipes?), at most one raw
605 read will be issued, and a short result does not imply that
608 Returns an empty bytes array on EOF.
610 Raises BlockingIOError if the underlying raw stream has no
613 self
._unsupported
("read")
615 def read1(self
, n
: int=None) -> bytes
:
616 """Read up to n bytes with at most one read() system call."""
617 self
._unsupported
("read1")
619 def readinto(self
, b
: bytearray
) -> int:
620 """Read up to len(b) bytes into b.
622 Like read(), this may issue multiple reads to the underlying raw
623 stream, unless the latter is 'interactive'.
625 Returns the number of bytes read (0 for EOF).
627 Raises BlockingIOError if the underlying raw stream has no
630 # XXX This ought to work with anything that supports the buffer API
631 data
= self
.read(len(b
))
635 except TypeError as err
:
637 if not isinstance(b
, array
.array
):
639 b
[:n
] = array
.array('b', data
)
642 def write(self
, b
: bytes
) -> int:
643 """Write the given buffer to the IO stream.
645 Return the number of bytes written, which is never less than
648 Raises BlockingIOError if the buffer is full and the
649 underlying raw stream cannot accept more data at the moment.
651 self
._unsupported
("write")
653 def detach(self
) -> None:
655 Separate the underlying raw stream from the buffer and return it.
657 After the raw stream has been detached, the buffer is in an unusable
660 self
._unsupported
("detach")
662 io
.BufferedIOBase
.register(BufferedIOBase
)
665 class _BufferedIOMixin(BufferedIOBase
):
667 """A mixin implementation of BufferedIOBase with an underlying raw stream.
669 This passes most requests on to the underlying raw stream. It
670 does *not* provide implementations of read(), readinto() or
674 def __init__(self
, raw
):
679 def seek(self
, pos
, whence
=0):
680 new_position
= self
.raw
.seek(pos
, whence
)
682 raise IOError("seek() returned an invalid position")
686 pos
= self
.raw
.tell()
688 raise IOError("tell() returned an invalid position")
691 def truncate(self
, pos
=None):
692 # Flush the stream. We're mixing buffered I/O with lower-level I/O,
693 # and a flush may be necessary to synch both views of the current
699 # XXX: Should seek() be used, instead of passing the position
700 # XXX directly to truncate?
701 return self
.raw
.truncate(pos
)
703 ### Flush and close ###
707 raise ValueError("flush of closed file")
711 if self
.raw
is not None and not self
.closed
:
717 raise ValueError("raw stream already detached")
726 return self
.raw
.seekable()
729 return self
.raw
.readable()
732 return self
.raw
.writable()
736 return self
.raw
.closed
747 clsname
= self
.__class
__.__name
__
750 except AttributeError:
751 return "<_pyio.{0}>".format(clsname
)
753 return "<_pyio.{0} name={1!r}>".format(clsname
, name
)
755 ### Lower-level APIs ###
758 return self
.raw
.fileno()
761 return self
.raw
.isatty()
764 class BytesIO(BufferedIOBase
):
766 """Buffered I/O implementation using an in-memory bytes buffer."""
768 def __init__(self
, initial_bytes
=None):
770 if initial_bytes
is not None:
776 """Return the bytes value (contents) of the buffer
779 raise ValueError("getvalue on closed file")
780 return bytes(self
._buffer
)
782 def read(self
, n
=None):
784 raise ValueError("read from closed file")
788 n
= len(self
._buffer
)
789 if len(self
._buffer
) <= self
._pos
:
791 newpos
= min(len(self
._buffer
), self
._pos
+ n
)
792 b
= self
._buffer
[self
._pos
: newpos
]
797 """This is the same as read.
803 raise ValueError("write to closed file")
804 if isinstance(b
, str):
805 raise TypeError("can't write str to binary stream")
810 if pos
> len(self
._buffer
):
811 # Inserts null bytes between the current end of the file
812 # and the new write position.
813 padding
= b
'\x00' * (pos
- len(self
._buffer
))
814 self
._buffer
+= padding
815 self
._buffer
[pos
:pos
+ n
] = b
819 def seek(self
, pos
, whence
=0):
821 raise ValueError("seek on closed file")
823 pos
= pos
.__index
__()
824 except AttributeError as err
:
825 raise TypeError("an integer is required") from err
828 raise ValueError("negative seek position %r" % (pos
,))
831 self
._pos
= max(0, self
._pos
+ pos
)
833 self
._pos
= max(0, len(self
._buffer
) + pos
)
835 raise ValueError("invalid whence value")
840 raise ValueError("tell on closed file")
843 def truncate(self
, pos
=None):
845 raise ValueError("truncate on closed file")
849 raise ValueError("negative truncate position %r" % (pos
,))
850 del self
._buffer
[pos
:]
863 class BufferedReader(_BufferedIOMixin
):
865 """BufferedReader(raw[, buffer_size])
867 A buffer for a readable, sequential BaseRawIO object.
869 The constructor creates a BufferedReader for the given readable raw
870 stream and buffer_size. If buffer_size is omitted, DEFAULT_BUFFER_SIZE
874 def __init__(self
, raw
, buffer_size
=DEFAULT_BUFFER_SIZE
):
875 """Create a new buffered reader using the given readable raw IO object.
877 if not raw
.readable():
878 raise IOError('"raw" argument must be readable.')
880 _BufferedIOMixin
.__init
__(self
, raw
)
882 raise ValueError("invalid buffer size")
883 self
.buffer_size
= buffer_size
884 self
._reset
_read
_buf
()
885 self
._read
_lock
= Lock()
887 def _reset_read_buf(self
):
891 def read(self
, n
=None):
894 Returns exactly n bytes of data unless the underlying raw IO
895 stream reaches EOF or if the call would block in non-blocking
896 mode. If n is negative, read until EOF or until read() would
899 if n
is not None and n
< -1:
900 raise ValueError("invalid number of bytes to read")
901 with self
._read
_lock
:
902 return self
._read
_unlocked
(n
)
904 def _read_unlocked(self
, n
=None):
906 empty_values
= (b
"", None)
910 # Special case for when the number of bytes to read is unspecified.
911 if n
is None or n
== -1:
912 self
._reset
_read
_buf
()
913 chunks
= [buf
[pos
:]] # Strip the consumed bytes.
916 # Read until EOF or until read() would block.
917 chunk
= self
.raw
.read()
918 if chunk
in empty_values
:
921 current_size
+= len(chunk
)
923 return b
"".join(chunks
) or nodata_val
925 # The number of bytes to read is specified, return at most n bytes.
926 avail
= len(buf
) - pos
# Length of the available buffered data.
928 # Fast path: the data to read is fully buffered.
930 return buf
[pos
:pos
+n
]
931 # Slow path: read from the stream until enough bytes are read,
932 # or until an EOF occurs or until read() would block.
934 wanted
= max(self
.buffer_size
, n
)
936 chunk
= self
.raw
.read(wanted
)
937 if chunk
in empty_values
:
942 # n is more then avail only when an EOF occurred or when
943 # read() would have blocked.
945 out
= b
"".join(chunks
)
946 self
._read
_buf
= out
[n
:] # Save the extra data in the buffer.
948 return out
[:n
] if out
else nodata_val
951 """Returns buffered bytes without advancing the position.
953 The argument indicates a desired minimal number of bytes; we
954 do at most one raw read to satisfy it. We never return more
955 than self.buffer_size.
957 with self
._read
_lock
:
958 return self
._peek
_unlocked
(n
)
960 def _peek_unlocked(self
, n
=0):
961 want
= min(n
, self
.buffer_size
)
962 have
= len(self
._read
_buf
) - self
._read
_pos
963 if have
< want
or have
<= 0:
964 to_read
= self
.buffer_size
- have
965 current
= self
.raw
.read(to_read
)
967 self
._read
_buf
= self
._read
_buf
[self
._read
_pos
:] + current
969 return self
._read
_buf
[self
._read
_pos
:]
972 """Reads up to n bytes, with at most one read() system call."""
973 # Returns up to n bytes. If at least one byte is buffered, we
974 # only return buffered bytes. Otherwise, we do one raw read.
976 raise ValueError("number of bytes to read must be positive")
979 with self
._read
_lock
:
980 self
._peek
_unlocked
(1)
981 return self
._read
_unlocked
(
982 min(n
, len(self
._read
_buf
) - self
._read
_pos
))
985 return _BufferedIOMixin
.tell(self
) - len(self
._read
_buf
) + self
._read
_pos
987 def seek(self
, pos
, whence
=0):
988 if not (0 <= whence
<= 2):
989 raise ValueError("invalid whence value")
990 with self
._read
_lock
:
992 pos
-= len(self
._read
_buf
) - self
._read
_pos
993 pos
= _BufferedIOMixin
.seek(self
, pos
, whence
)
994 self
._reset
_read
_buf
()
997 class BufferedWriter(_BufferedIOMixin
):
999 """A buffer for a writeable sequential RawIO object.
1001 The constructor creates a BufferedWriter for the given writeable raw
1002 stream. If the buffer_size is not given, it defaults to
1003 DEFAULT_BUFFER_SIZE.
1006 _warning_stack_offset
= 2
1008 def __init__(self
, raw
,
1009 buffer_size
=DEFAULT_BUFFER_SIZE
, max_buffer_size
=None):
1010 if not raw
.writable():
1011 raise IOError('"raw" argument must be writable.')
1013 _BufferedIOMixin
.__init
__(self
, raw
)
1014 if buffer_size
<= 0:
1015 raise ValueError("invalid buffer size")
1016 if max_buffer_size
is not None:
1017 warnings
.warn("max_buffer_size is deprecated", DeprecationWarning,
1018 self
._warning
_stack
_offset
)
1019 self
.buffer_size
= buffer_size
1020 self
._write
_buf
= bytearray()
1021 self
._write
_lock
= Lock()
1025 raise ValueError("write to closed file")
1026 if isinstance(b
, str):
1027 raise TypeError("can't write str to binary stream")
1028 with self
._write
_lock
:
1029 # XXX we can implement some more tricks to try and avoid
1031 if len(self
._write
_buf
) > self
.buffer_size
:
1032 # We're full, so let's pre-flush the buffer
1034 self
._flush
_unlocked
()
1035 except BlockingIOError
as e
:
1036 # We can't accept anything else.
1037 # XXX Why not just let the exception pass through?
1038 raise BlockingIOError(e
.errno
, e
.strerror
, 0)
1039 before
= len(self
._write
_buf
)
1040 self
._write
_buf
.extend(b
)
1041 written
= len(self
._write
_buf
) - before
1042 if len(self
._write
_buf
) > self
.buffer_size
:
1044 self
._flush
_unlocked
()
1045 except BlockingIOError
as e
:
1046 if len(self
._write
_buf
) > self
.buffer_size
:
1047 # We've hit the buffer_size. We have to accept a partial
1048 # write and cut back our buffer.
1049 overage
= len(self
._write
_buf
) - self
.buffer_size
1051 self
._write
_buf
= self
._write
_buf
[:self
.buffer_size
]
1052 raise BlockingIOError(e
.errno
, e
.strerror
, written
)
1055 def truncate(self
, pos
=None):
1056 with self
._write
_lock
:
1057 self
._flush
_unlocked
()
1059 pos
= self
.raw
.tell()
1060 return self
.raw
.truncate(pos
)
1063 with self
._write
_lock
:
1064 self
._flush
_unlocked
()
1066 def _flush_unlocked(self
):
1068 raise ValueError("flush of closed file")
1071 while self
._write
_buf
:
1072 n
= self
.raw
.write(self
._write
_buf
)
1073 if n
> len(self
._write
_buf
) or n
< 0:
1074 raise IOError("write() returned incorrect number of bytes")
1075 del self
._write
_buf
[:n
]
1077 except BlockingIOError
as e
:
1078 n
= e
.characters_written
1079 del self
._write
_buf
[:n
]
1081 raise BlockingIOError(e
.errno
, e
.strerror
, written
)
1084 return _BufferedIOMixin
.tell(self
) + len(self
._write
_buf
)
1086 def seek(self
, pos
, whence
=0):
1087 if not (0 <= whence
<= 2):
1088 raise ValueError("invalid whence")
1089 with self
._write
_lock
:
1090 self
._flush
_unlocked
()
1091 return _BufferedIOMixin
.seek(self
, pos
, whence
)
1094 class BufferedRWPair(BufferedIOBase
):
1096 """A buffered reader and writer object together.
1098 A buffered reader object and buffered writer object put together to
1099 form a sequential IO object that can read and write. This is typically
1100 used with a socket or two-way pipe.
1102 reader and writer are RawIOBase objects that are readable and
1103 writeable respectively. If the buffer_size is omitted it defaults to
1104 DEFAULT_BUFFER_SIZE.
1107 # XXX The usefulness of this (compared to having two separate IO
1108 # objects) is questionable.
1110 def __init__(self
, reader
, writer
,
1111 buffer_size
=DEFAULT_BUFFER_SIZE
, max_buffer_size
=None):
1114 The arguments are two RawIO instances.
1116 if max_buffer_size
is not None:
1117 warnings
.warn("max_buffer_size is deprecated", DeprecationWarning, 2)
1119 if not reader
.readable():
1120 raise IOError('"reader" argument must be readable.')
1122 if not writer
.writable():
1123 raise IOError('"writer" argument must be writable.')
1125 self
.reader
= BufferedReader(reader
, buffer_size
)
1126 self
.writer
= BufferedWriter(writer
, buffer_size
)
1128 def read(self
, n
=None):
1131 return self
.reader
.read(n
)
1133 def readinto(self
, b
):
1134 return self
.reader
.readinto(b
)
1137 return self
.writer
.write(b
)
1139 def peek(self
, n
=0):
1140 return self
.reader
.peek(n
)
1143 return self
.reader
.read1(n
)
1146 return self
.reader
.readable()
1149 return self
.writer
.writable()
1152 return self
.writer
.flush()
1159 return self
.reader
.isatty() or self
.writer
.isatty()
1163 return self
.writer
.closed
1166 class BufferedRandom(BufferedWriter
, BufferedReader
):
1168 """A buffered interface to random access streams.
1170 The constructor creates a reader and writer for a seekable stream,
1171 raw, given in the first argument. If the buffer_size is omitted it
1172 defaults to DEFAULT_BUFFER_SIZE.
1175 _warning_stack_offset
= 3
1177 def __init__(self
, raw
,
1178 buffer_size
=DEFAULT_BUFFER_SIZE
, max_buffer_size
=None):
1179 raw
._checkSeekable
()
1180 BufferedReader
.__init
__(self
, raw
, buffer_size
)
1181 BufferedWriter
.__init
__(self
, raw
, buffer_size
, max_buffer_size
)
1183 def seek(self
, pos
, whence
=0):
1184 if not (0 <= whence
<= 2):
1185 raise ValueError("invalid whence")
1189 with self
._read
_lock
:
1190 self
.raw
.seek(self
._read
_pos
- len(self
._read
_buf
), 1)
1191 # First do the raw seek, then empty the read buffer, so that
1192 # if the raw seek fails, we don't lose buffered data forever.
1193 pos
= self
.raw
.seek(pos
, whence
)
1194 with self
._read
_lock
:
1195 self
._reset
_read
_buf
()
1197 raise IOError("seek() returned invalid position")
1202 return BufferedWriter
.tell(self
)
1204 return BufferedReader
.tell(self
)
1206 def truncate(self
, pos
=None):
1209 # Use seek to flush the read buffer.
1210 return BufferedWriter
.truncate(self
, pos
)
1212 def read(self
, n
=None):
1216 return BufferedReader
.read(self
, n
)
1218 def readinto(self
, b
):
1220 return BufferedReader
.readinto(self
, b
)
1222 def peek(self
, n
=0):
1224 return BufferedReader
.peek(self
, n
)
1228 return BufferedReader
.read1(self
, n
)
1233 with self
._read
_lock
:
1234 self
.raw
.seek(self
._read
_pos
- len(self
._read
_buf
), 1)
1235 self
._reset
_read
_buf
()
1236 return BufferedWriter
.write(self
, b
)
1239 class TextIOBase(IOBase
):
1241 """Base class for text I/O.
1243 This class provides a character and line based interface to stream
1244 I/O. There is no readinto method because Python's character strings
1245 are immutable. There is no public constructor.
1248 def read(self
, n
: int = -1) -> str:
1249 """Read at most n characters from stream.
1251 Read from underlying buffer until we have n characters or we hit EOF.
1252 If n is negative or omitted, read until EOF.
1254 self
._unsupported
("read")
1256 def write(self
, s
: str) -> int:
1257 """Write string s to stream."""
1258 self
._unsupported
("write")
1260 def truncate(self
, pos
: int = None) -> int:
1261 """Truncate size to pos."""
1262 self
._unsupported
("truncate")
1264 def readline(self
) -> str:
1265 """Read until newline or EOF.
1267 Returns an empty string if EOF is hit immediately.
1269 self
._unsupported
("readline")
1271 def detach(self
) -> None:
1273 Separate the underlying buffer from the TextIOBase and return it.
1275 After the underlying buffer has been detached, the TextIO is in an
1278 self
._unsupported
("detach")
1282 """Subclasses should override."""
1287 """Line endings translated so far.
1289 Only line endings translated during reading are considered.
1291 Subclasses should override.
1297 """Error setting of the decoder or encoder.
1299 Subclasses should override."""
1302 io
.TextIOBase
.register(TextIOBase
)
1305 class IncrementalNewlineDecoder(codecs
.IncrementalDecoder
):
1306 r
"""Codec used when reading a file in universal newlines mode. It wraps
1307 another incremental decoder, translating \r\n and \r into \n. It also
1308 records the types of newlines encountered. When used with
1309 translate=False, it ensures that the newline sequence is returned in
1312 def __init__(self
, decoder
, translate
, errors
='strict'):
1313 codecs
.IncrementalDecoder
.__init
__(self
, errors
=errors
)
1314 self
.translate
= translate
1315 self
.decoder
= decoder
1317 self
.pendingcr
= False
1319 def decode(self
, input, final
=False):
1320 # decode input (with the eventual \r from a previous pass)
1321 if self
.decoder
is None:
1324 output
= self
.decoder
.decode(input, final
=final
)
1325 if self
.pendingcr
and (output
or final
):
1326 output
= "\r" + output
1327 self
.pendingcr
= False
1329 # retain last \r even when not translating data:
1330 # then readline() is sure to get \r\n in one pass
1331 if output
.endswith("\r") and not final
:
1332 output
= output
[:-1]
1333 self
.pendingcr
= True
1335 # Record which newlines are read
1336 crlf
= output
.count('\r\n')
1337 cr
= output
.count('\r') - crlf
1338 lf
= output
.count('\n') - crlf
1339 self
.seennl |
= (lf
and self
._LF
) |
(cr
and self
._CR
) \
1340 |
(crlf
and self
._CRLF
)
1344 output
= output
.replace("\r\n", "\n")
1346 output
= output
.replace("\r", "\n")
1351 if self
.decoder
is None:
1355 buf
, flag
= self
.decoder
.getstate()
1361 def setstate(self
, state
):
1363 self
.pendingcr
= bool(flag
& 1)
1364 if self
.decoder
is not None:
1365 self
.decoder
.setstate((buf
, flag
>> 1))
1369 self
.pendingcr
= False
1370 if self
.decoder
is not None:
1371 self
.decoder
.reset()
1386 ("\r", "\n", "\r\n")
1390 class TextIOWrapper(TextIOBase
):
1392 r
"""Character and line based layer over a BufferedIOBase object, buffer.
1394 encoding gives the name of the encoding that the stream will be
1395 decoded or encoded with. It defaults to locale.getpreferredencoding.
1397 errors determines the strictness of encoding and decoding (see the
1398 codecs.register) and defaults to "strict".
1400 newline can be None, '', '\n', '\r', or '\r\n'. It controls the
1401 handling of line endings. If it is None, universal newlines is
1402 enabled. With this enabled, on input, the lines endings '\n', '\r',
1403 or '\r\n' are translated to '\n' before being returned to the
1404 caller. Conversely, on output, '\n' is translated to the system
1405 default line seperator, os.linesep. If newline is any other of its
1406 legal values, that newline becomes the newline when the file is read
1407 and it is returned untranslated. On output, '\n' is converted to the
1410 If line_buffering is True, a call to flush is implied when a call to
1411 write contains a newline character.
1416 def __init__(self
, buffer, encoding
=None, errors
=None, newline
=None,
1417 line_buffering
=False):
1418 if newline
is not None and not isinstance(newline
, str):
1419 raise TypeError("illegal newline type: %r" % (type(newline
),))
1420 if newline
not in (None, "", "\n", "\r", "\r\n"):
1421 raise ValueError("illegal newline value: %r" % (newline
,))
1422 if encoding
is None:
1424 encoding
= os
.device_encoding(buffer.fileno())
1425 except (AttributeError, UnsupportedOperation
):
1427 if encoding
is None:
1431 # Importing locale may fail if Python is being built
1434 encoding
= locale
.getpreferredencoding()
1436 if not isinstance(encoding
, str):
1437 raise ValueError("invalid encoding: %r" % encoding
)
1442 if not isinstance(errors
, str):
1443 raise ValueError("invalid errors: %r" % errors
)
1445 self
.buffer = buffer
1446 self
._line
_buffering
= line_buffering
1447 self
._encoding
= encoding
1448 self
._errors
= errors
1449 self
._readuniversal
= not newline
1450 self
._readtranslate
= newline
is None
1451 self
._readnl
= newline
1452 self
._writetranslate
= newline
!= ''
1453 self
._writenl
= newline
or os
.linesep
1454 self
._encoder
= None
1455 self
._decoder
= None
1456 self
._decoded
_chars
= '' # buffer for text returned from decoder
1457 self
._decoded
_chars
_used
= 0 # offset into _decoded_chars for read()
1458 self
._snapshot
= None # info for reconstructing decoder state
1459 self
._seekable
= self
._telling
= self
.buffer.seekable()
1461 if self
._seekable
and self
.writable():
1462 position
= self
.buffer.tell()
1465 self
._get
_encoder
().setstate(0)
1467 # Sometimes the encoder doesn't exist
1470 # self._snapshot is either None, or a tuple (dec_flags, next_input)
1471 # where dec_flags is the second (integer) item of the decoder state
1472 # and next_input is the chunk of input bytes that comes next after the
1473 # snapshot point. We use this to reconstruct decoder states in tell().
1475 # Naming convention:
1476 # - "bytes_..." for integer variables that count input bytes
1477 # - "chars_..." for integer variables that count decoded characters
1482 except AttributeError:
1483 return "<_pyio.TextIOWrapper encoding={0!r}>".format(self
.encoding
)
1485 return "<_pyio.TextIOWrapper name={0!r} encoding={1!r}>".format(
1486 name
, self
.encoding
)
1490 return self
._encoding
1497 def line_buffering(self
):
1498 return self
._line
_buffering
1501 return self
._seekable
1504 return self
.buffer.readable()
1507 return self
.buffer.writable()
1511 self
._telling
= self
._seekable
1514 if self
.buffer is not None and not self
.closed
:
1520 return self
.buffer.closed
1524 return self
.buffer.name
1527 return self
.buffer.fileno()
1530 return self
.buffer.isatty()
1532 def write(self
, s
: str):
1534 raise ValueError("write to closed file")
1535 if not isinstance(s
, str):
1536 raise TypeError("can't write %s to text stream" %
1537 s
.__class
__.__name
__)
1539 haslf
= (self
._writetranslate
or self
._line
_buffering
) and "\n" in s
1540 if haslf
and self
._writetranslate
and self
._writenl
!= "\n":
1541 s
= s
.replace("\n", self
._writenl
)
1542 encoder
= self
._encoder
or self
._get
_encoder
()
1543 # XXX What if we were just reading?
1544 b
= encoder
.encode(s
)
1545 self
.buffer.write(b
)
1546 if self
._line
_buffering
and (haslf
or "\r" in s
):
1548 self
._snapshot
= None
1550 self
._decoder
.reset()
1553 def _get_encoder(self
):
1554 make_encoder
= codecs
.getincrementalencoder(self
._encoding
)
1555 self
._encoder
= make_encoder(self
._errors
)
1556 return self
._encoder
1558 def _get_decoder(self
):
1559 make_decoder
= codecs
.getincrementaldecoder(self
._encoding
)
1560 decoder
= make_decoder(self
._errors
)
1561 if self
._readuniversal
:
1562 decoder
= IncrementalNewlineDecoder(decoder
, self
._readtranslate
)
1563 self
._decoder
= decoder
1566 # The following three methods implement an ADT for _decoded_chars.
1567 # Text returned from the decoder is buffered here until the client
1568 # requests it by calling our read() or readline() method.
1569 def _set_decoded_chars(self
, chars
):
1570 """Set the _decoded_chars buffer."""
1571 self
._decoded
_chars
= chars
1572 self
._decoded
_chars
_used
= 0
1574 def _get_decoded_chars(self
, n
=None):
1575 """Advance into the _decoded_chars buffer."""
1576 offset
= self
._decoded
_chars
_used
1578 chars
= self
._decoded
_chars
[offset
:]
1580 chars
= self
._decoded
_chars
[offset
:offset
+ n
]
1581 self
._decoded
_chars
_used
+= len(chars
)
1584 def _rewind_decoded_chars(self
, n
):
1585 """Rewind the _decoded_chars buffer."""
1586 if self
._decoded
_chars
_used
< n
:
1587 raise AssertionError("rewind decoded_chars out of bounds")
1588 self
._decoded
_chars
_used
-= n
1590 def _read_chunk(self
):
1592 Read and decode the next chunk of data from the BufferedReader.
1595 # The return value is True unless EOF was reached. The decoded
1596 # string is placed in self._decoded_chars (replacing its previous
1597 # value). The entire input chunk is sent to the decoder, though
1598 # some of it may remain buffered in the decoder, yet to be
1601 if self
._decoder
is None:
1602 raise ValueError("no decoder")
1605 # To prepare for tell(), we need to snapshot a point in the
1606 # file where the decoder's input buffer is empty.
1608 dec_buffer
, dec_flags
= self
._decoder
.getstate()
1609 # Given this, we know there was a valid snapshot point
1610 # len(dec_buffer) bytes ago with decoder state (b'', dec_flags).
1612 # Read a chunk, decode it, and put the result in self._decoded_chars.
1613 input_chunk
= self
.buffer.read1(self
._CHUNK
_SIZE
)
1614 eof
= not input_chunk
1615 self
._set
_decoded
_chars
(self
._decoder
.decode(input_chunk
, eof
))
1618 # At the snapshot point, len(dec_buffer) bytes before the read,
1619 # the next input to be decoded is dec_buffer + input_chunk.
1620 self
._snapshot
= (dec_flags
, dec_buffer
+ input_chunk
)
1624 def _pack_cookie(self
, position
, dec_flags
=0,
1625 bytes_to_feed
=0, need_eof
=0, chars_to_skip
=0):
1626 # The meaning of a tell() cookie is: seek to position, set the
1627 # decoder flags to dec_flags, read bytes_to_feed bytes, feed them
1628 # into the decoder with need_eof as the EOF flag, then skip
1629 # chars_to_skip characters of the decoded result. For most simple
1630 # decoders, tell() will often just give a byte offset in the file.
1631 return (position |
(dec_flags
<<64) |
(bytes_to_feed
<<128) |
1632 (chars_to_skip
<<192) |
bool(need_eof
)<<256)
1634 def _unpack_cookie(self
, bigint
):
1635 rest
, position
= divmod(bigint
, 1<<64)
1636 rest
, dec_flags
= divmod(rest
, 1<<64)
1637 rest
, bytes_to_feed
= divmod(rest
, 1<<64)
1638 need_eof
, chars_to_skip
= divmod(rest
, 1<<64)
1639 return position
, dec_flags
, bytes_to_feed
, need_eof
, chars_to_skip
1642 if not self
._seekable
:
1643 raise IOError("underlying stream is not seekable")
1644 if not self
._telling
:
1645 raise IOError("telling position disabled by next() call")
1647 position
= self
.buffer.tell()
1648 decoder
= self
._decoder
1649 if decoder
is None or self
._snapshot
is None:
1650 if self
._decoded
_chars
:
1651 # This should never happen.
1652 raise AssertionError("pending decoded text")
1655 # Skip backward to the snapshot point (see _read_chunk).
1656 dec_flags
, next_input
= self
._snapshot
1657 position
-= len(next_input
)
1659 # How many decoded characters have been used up since the snapshot?
1660 chars_to_skip
= self
._decoded
_chars
_used
1661 if chars_to_skip
== 0:
1662 # We haven't moved from the snapshot point.
1663 return self
._pack
_cookie
(position
, dec_flags
)
1665 # Starting from the snapshot position, we will walk the decoder
1666 # forward until it gives us enough decoded characters.
1667 saved_state
= decoder
.getstate()
1669 # Note our initial start point.
1670 decoder
.setstate((b
'', dec_flags
))
1671 start_pos
= position
1672 start_flags
, bytes_fed
, chars_decoded
= dec_flags
, 0, 0
1675 # Feed the decoder one byte at a time. As we go, note the
1676 # nearest "safe start point" before the current location
1677 # (a point where the decoder has nothing buffered, so seek()
1678 # can safely start from there and advance to this location).
1679 next_byte
= bytearray(1)
1680 for next_byte
[0] in next_input
:
1682 chars_decoded
+= len(decoder
.decode(next_byte
))
1683 dec_buffer
, dec_flags
= decoder
.getstate()
1684 if not dec_buffer
and chars_decoded
<= chars_to_skip
:
1685 # Decoder buffer is empty, so this is a safe start point.
1686 start_pos
+= bytes_fed
1687 chars_to_skip
-= chars_decoded
1688 start_flags
, bytes_fed
, chars_decoded
= dec_flags
, 0, 0
1689 if chars_decoded
>= chars_to_skip
:
1692 # We didn't get enough decoded data; signal EOF to get more.
1693 chars_decoded
+= len(decoder
.decode(b
'', final
=True))
1695 if chars_decoded
< chars_to_skip
:
1696 raise IOError("can't reconstruct logical file position")
1698 # The returned cookie corresponds to the last safe start point.
1699 return self
._pack
_cookie
(
1700 start_pos
, start_flags
, bytes_fed
, need_eof
, chars_to_skip
)
1702 decoder
.setstate(saved_state
)
1704 def truncate(self
, pos
=None):
1708 return self
.buffer.truncate(pos
)
1711 if self
.buffer is None:
1712 raise ValueError("buffer is already detached")
1714 buffer = self
.buffer
1718 def seek(self
, cookie
, whence
=0):
1720 raise ValueError("tell on closed file")
1721 if not self
._seekable
:
1722 raise IOError("underlying stream is not seekable")
1723 if whence
== 1: # seek relative to current position
1725 raise IOError("can't do nonzero cur-relative seeks")
1726 # Seeking to the current position should attempt to
1727 # sync the underlying buffer with the current position.
1729 cookie
= self
.tell()
1730 if whence
== 2: # seek relative to end of file
1732 raise IOError("can't do nonzero end-relative seeks")
1734 position
= self
.buffer.seek(0, 2)
1735 self
._set
_decoded
_chars
('')
1736 self
._snapshot
= None
1738 self
._decoder
.reset()
1741 raise ValueError("invalid whence (%r, should be 0, 1 or 2)" %
1744 raise ValueError("negative seek position %r" % (cookie
,))
1747 # The strategy of seek() is to go back to the safe start point
1748 # and replay the effect of read(chars_to_skip) from there.
1749 start_pos
, dec_flags
, bytes_to_feed
, need_eof
, chars_to_skip
= \
1750 self
._unpack
_cookie
(cookie
)
1752 # Seek back to the safe start point.
1753 self
.buffer.seek(start_pos
)
1754 self
._set
_decoded
_chars
('')
1755 self
._snapshot
= None
1757 # Restore the decoder to its state from the safe start point.
1758 if cookie
== 0 and self
._decoder
:
1759 self
._decoder
.reset()
1760 elif self
._decoder
or dec_flags
or chars_to_skip
:
1761 self
._decoder
= self
._decoder
or self
._get
_decoder
()
1762 self
._decoder
.setstate((b
'', dec_flags
))
1763 self
._snapshot
= (dec_flags
, b
'')
1766 # Just like _read_chunk, feed the decoder and save a snapshot.
1767 input_chunk
= self
.buffer.read(bytes_to_feed
)
1768 self
._set
_decoded
_chars
(
1769 self
._decoder
.decode(input_chunk
, need_eof
))
1770 self
._snapshot
= (dec_flags
, input_chunk
)
1772 # Skip chars_to_skip of the decoded characters.
1773 if len(self
._decoded
_chars
) < chars_to_skip
:
1774 raise IOError("can't restore logical file position")
1775 self
._decoded
_chars
_used
= chars_to_skip
1777 # Finally, reset the encoder (merely useful for proper BOM handling)
1779 encoder
= self
._encoder
or self
._get
_encoder
()
1781 # Sometimes the encoder doesn't exist
1790 def read(self
, n
=None):
1791 self
._checkReadable
()
1794 decoder
= self
._decoder
or self
._get
_decoder
()
1797 result
= (self
._get
_decoded
_chars
() +
1798 decoder
.decode(self
.buffer.read(), final
=True))
1799 self
._set
_decoded
_chars
('')
1800 self
._snapshot
= None
1803 # Keep reading chunks until we have n characters to return.
1805 result
= self
._get
_decoded
_chars
(n
)
1806 while len(result
) < n
and not eof
:
1807 eof
= not self
._read
_chunk
()
1808 result
+= self
._get
_decoded
_chars
(n
- len(result
))
1812 self
._telling
= False
1813 line
= self
.readline()
1815 self
._snapshot
= None
1816 self
._telling
= self
._seekable
1820 def readline(self
, limit
=None):
1822 raise ValueError("read from closed file")
1825 elif not isinstance(limit
, int):
1826 raise TypeError("limit must be an integer")
1828 # Grab all the decoded text (we will rewind any extra bits later).
1829 line
= self
._get
_decoded
_chars
()
1832 # Make the decoder if it doesn't already exist.
1833 if not self
._decoder
:
1838 if self
._readtranslate
:
1839 # Newlines are already translated, only search for \n
1840 pos
= line
.find('\n', start
)
1847 elif self
._readuniversal
:
1848 # Universal newline search. Find any of \r, \r\n, \n
1849 # The decoder ensures that \r\n are not split in two pieces
1851 # In C we'd look for these in parallel of course.
1852 nlpos
= line
.find("\n", start
)
1853 crpos
= line
.find("\r", start
)
1870 elif nlpos
== crpos
+ 1:
1880 pos
= line
.find(self
._readnl
)
1882 endpos
= pos
+ len(self
._readnl
)
1885 if limit
>= 0 and len(line
) >= limit
:
1886 endpos
= limit
# reached length limit
1889 # No line ending seen yet - get more data'
1890 while self
._read
_chunk
():
1891 if self
._decoded
_chars
:
1893 if self
._decoded
_chars
:
1894 line
+= self
._get
_decoded
_chars
()
1897 self
._set
_decoded
_chars
('')
1898 self
._snapshot
= None
1901 if limit
>= 0 and endpos
> limit
:
1902 endpos
= limit
# don't exceed limit
1904 # Rewind _decoded_chars to just after the line ending we found.
1905 self
._rewind
_decoded
_chars
(len(line
) - endpos
)
1906 return line
[:endpos
]
1910 return self
._decoder
.newlines
if self
._decoder
else None
1913 class StringIO(TextIOWrapper
):
1914 """Text I/O implementation using an in-memory buffer.
1916 The initial_value argument sets the value of object. The newline
1917 argument is like the one of TextIOWrapper's constructor.
1920 def __init__(self
, initial_value
="", newline
="\n"):
1921 super(StringIO
, self
).__init
__(BytesIO(),
1925 # Issue #5645: make universal newlines semantics the same as in the
1926 # C version, even under Windows.
1928 self
._writetranslate
= False
1929 if initial_value
is not None:
1930 if not isinstance(initial_value
, str):
1931 raise TypeError("initial_value must be str or None, not {0}"
1932 .format(type(initial_value
).__name
__))
1933 initial_value
= str(initial_value
)
1934 self
.write(initial_value
)
1939 return self
.buffer.getvalue().decode(self
._encoding
, self
._errors
)
1942 # TextIOWrapper tells the encoding in its repr. In StringIO,
1943 # that's a implementation detail.
1944 return object.__repr
__(self
)
1955 # This doesn't make sense on StringIO.
1956 self
._unsupported
("detach")