2 Python implementation of the io module.
5 from __future__
import (print_function
, unicode_literals
)
11 # Import thread instead of threading to reduce startup cost
13 from thread
import allocate_lock
as Lock
15 from dummy_thread
import allocate_lock
as Lock
18 from io
import (__all__
, SEEK_SET
, SEEK_CUR
, SEEK_END
)
22 # open() uses st_blksize whenever we can
23 DEFAULT_BUFFER_SIZE
= 8 * 1024 # bytes
25 # NOTE: Base classes defined here are registered with the "official" ABCs
26 # defined in io.py. We don't use real inheritance though, because we don't
27 # want to inherit the C implementations.
30 class BlockingIOError(IOError):
32 """Exception raised when I/O would block on a non-blocking I/O stream."""
34 def __init__(self
, errno
, strerror
, characters_written
=0):
35 super(IOError, self
).__init
__(errno
, strerror
)
36 if not isinstance(characters_written
, (int, long)):
37 raise TypeError("characters_written must be a integer")
38 self
.characters_written
= characters_written
41 def open(file, mode
="r", buffering
=-1,
42 encoding
=None, errors
=None,
43 newline
=None, closefd
=True):
45 r
"""Open file and return a stream. Raise IOError upon failure.
47 file is either a text or byte string giving the name (and the path
48 if the file isn't in the current working directory) of the file to
49 be opened or an integer file descriptor of the file to be
50 wrapped. (If a file descriptor is given, it is closed when the
51 returned I/O object is closed, unless closefd is set to False.)
53 mode is an optional string that specifies the mode in which the file
54 is opened. It defaults to 'r' which means open for reading in text
55 mode. Other common values are 'w' for writing (truncating the file if
56 it already exists), and 'a' for appending (which on some Unix systems,
57 means that all writes append to the end of the file regardless of the
58 current seek position). In text mode, if encoding is not specified the
59 encoding used is platform dependent. (For reading and writing raw
60 bytes use binary mode and leave encoding unspecified.) The available
63 ========= ===============================================================
65 --------- ---------------------------------------------------------------
66 'r' open for reading (default)
67 'w' open for writing, truncating the file first
68 'a' open for writing, appending to the end of the file if it exists
70 't' text mode (default)
71 '+' open a disk file for updating (reading and writing)
72 'U' universal newline mode (for backwards compatibility; unneeded
74 ========= ===============================================================
76 The default mode is 'rt' (open for reading text). For binary random
77 access, the mode 'w+b' opens and truncates the file to 0 bytes, while
78 'r+b' opens the file without truncation.
80 Python distinguishes between files opened in binary and text modes,
81 even when the underlying operating system doesn't. Files opened in
82 binary mode (appending 'b' to the mode argument) return contents as
83 bytes objects without any decoding. In text mode (the default, or when
84 't' is appended to the mode argument), the contents of the file are
85 returned as strings, the bytes having been first decoded using a
86 platform-dependent encoding or using the specified encoding if given.
88 buffering is an optional integer used to set the buffering policy.
89 Pass 0 to switch buffering off (only allowed in binary mode), 1 to select
90 line buffering (only usable in text mode), and an integer > 1 to indicate
91 the size of a fixed-size chunk buffer. When no buffering argument is
92 given, the default buffering policy works as follows:
94 * Binary files are buffered in fixed-size chunks; the size of the buffer
95 is chosen using a heuristic trying to determine the underlying device's
96 "block size" and falling back on `io.DEFAULT_BUFFER_SIZE`.
97 On many systems, the buffer will typically be 4096 or 8192 bytes long.
99 * "Interactive" text files (files for which isatty() returns True)
100 use line buffering. Other text files use the policy described above
103 encoding is the name of the encoding used to decode or encode the
104 file. This should only be used in text mode. The default encoding is
105 platform dependent, but any encoding supported by Python can be
106 passed. See the codecs module for the list of supported encodings.
108 errors is an optional string that specifies how encoding errors are to
109 be handled---this argument should not be used in binary mode. Pass
110 'strict' to raise a ValueError exception if there is an encoding error
111 (the default of None has the same effect), or pass 'ignore' to ignore
112 errors. (Note that ignoring encoding errors can lead to data loss.)
113 See the documentation for codecs.register for a list of the permitted
114 encoding error strings.
116 newline controls how universal newlines works (it only applies to text
117 mode). It can be None, '', '\n', '\r', and '\r\n'. It works as
120 * On input, if newline is None, universal newlines mode is
121 enabled. Lines in the input can end in '\n', '\r', or '\r\n', and
122 these are translated into '\n' before being returned to the
123 caller. If it is '', universal newline mode is enabled, but line
124 endings are returned to the caller untranslated. If it has any of
125 the other legal values, input lines are only terminated by the given
126 string, and the line ending is returned to the caller untranslated.
128 * On output, if newline is None, any '\n' characters written are
129 translated to the system default line separator, os.linesep. If
130 newline is '', no translation takes place. If newline is any of the
131 other legal values, any '\n' characters written are translated to
134 If closefd is False, the underlying file descriptor will be kept open
135 when the file is closed. This does not work when a file name is given
136 and must be True in that case.
138 open() returns a file object whose type depends on the mode, and
139 through which the standard file operations such as reading and writing
140 are performed. When open() is used to open a file in a text mode ('w',
141 'r', 'wt', 'rt', etc.), it returns a TextIOWrapper. When used to open
142 a file in a binary mode, the returned class varies: in read binary
143 mode, it returns a BufferedReader; in write binary and append binary
144 modes, it returns a BufferedWriter, and in read/write mode, it returns
147 It is also possible to use a string or bytearray as a file for both
148 reading and writing. For strings StringIO can be used like a file
149 opened in a text mode, and for bytes a BytesIO can be used like a file
150 opened in a binary mode.
152 if not isinstance(file, (basestring
, int, long)):
153 raise TypeError("invalid file: %r" % file)
154 if not isinstance(mode
, basestring
):
155 raise TypeError("invalid mode: %r" % mode
)
156 if not isinstance(buffering
, (int, long)):
157 raise TypeError("invalid buffering: %r" % buffering
)
158 if encoding
is not None and not isinstance(encoding
, basestring
):
159 raise TypeError("invalid encoding: %r" % encoding
)
160 if errors
is not None and not isinstance(errors
, basestring
):
161 raise TypeError("invalid errors: %r" % errors
)
163 if modes
- set("arwb+tU") or len(mode
) > len(modes
):
164 raise ValueError("invalid mode: %r" % mode
)
165 reading
= "r" in modes
166 writing
= "w" in modes
167 appending
= "a" in modes
168 updating
= "+" in modes
170 binary
= "b" in modes
172 if writing
or appending
:
173 raise ValueError("can't use U and writing mode at once")
176 raise ValueError("can't have text and binary mode at once")
177 if reading
+ writing
+ appending
> 1:
178 raise ValueError("can't have read/write/append mode at once")
179 if not (reading
or writing
or appending
):
180 raise ValueError("must have exactly one of read/write/append mode")
181 if binary
and encoding
is not None:
182 raise ValueError("binary mode doesn't take an encoding argument")
183 if binary
and errors
is not None:
184 raise ValueError("binary mode doesn't take an errors argument")
185 if binary
and newline
is not None:
186 raise ValueError("binary mode doesn't take a newline argument")
188 (reading
and "r" or "") +
189 (writing
and "w" or "") +
190 (appending
and "a" or "") +
191 (updating
and "+" or ""),
193 line_buffering
= False
194 if buffering
== 1 or buffering
< 0 and raw
.isatty():
196 line_buffering
= True
198 buffering
= DEFAULT_BUFFER_SIZE
200 bs
= os
.fstat(raw
.fileno()).st_blksize
201 except (os
.error
, AttributeError):
207 raise ValueError("invalid buffering size")
211 raise ValueError("can't have unbuffered text I/O")
213 buffer = BufferedRandom(raw
, buffering
)
214 elif writing
or appending
:
215 buffer = BufferedWriter(raw
, buffering
)
217 buffer = BufferedReader(raw
, buffering
)
219 raise ValueError("unknown mode: %r" % mode
)
222 text
= TextIOWrapper(buffer, encoding
, errors
, newline
, line_buffering
)
228 """Helper for builtins.open.__doc__
230 def __get__(self
, obj
, typ
):
232 "open(file, mode='r', buffering=-1, encoding=None, "
233 "errors=None, newline=None, closefd=True)\n\n" +
237 """Wrapper for builtins.open
239 Trick so that open won't become a bound method when stored
240 as a class variable (as dbm.dumb does).
242 See initstdio() in Python/pythonrun.c.
244 __doc__
= DocDescriptor()
246 def __new__(cls
, *args
, **kwargs
):
247 return open(*args
, **kwargs
)
250 class UnsupportedOperation(ValueError, IOError):
255 __metaclass__
= abc
.ABCMeta
257 """The abstract base class for all I/O classes, acting on streams of
258 bytes. There is no public constructor.
260 This class provides dummy implementations for many methods that
261 derived classes can override selectively; the default implementations
262 represent a file that cannot be read, written or seeked.
264 Even though IOBase does not declare read, readinto, or write because
265 their signatures will vary, implementations and clients should
266 consider those methods part of the interface. Also, implementations
267 may raise a IOError when operations they do not support are called.
269 The basic type used for binary data read from or written to a file is
270 bytes. bytearrays are accepted too, and in some cases (such as
271 readinto) needed. Text I/O classes work with str data.
273 Note that calling any method (even inquiries) on a closed stream is
274 undefined. Implementations may raise IOError in this case.
276 IOBase (and its subclasses) support the iterator protocol, meaning
277 that an IOBase object can be iterated over yielding the lines in a
280 IOBase also supports the :keyword:`with` statement. In this example,
281 fp is closed after the suite of the with statement is complete:
283 with open('spam.txt', 'r') as fp:
284 fp.write('Spam and eggs!')
289 def _unsupported(self
, name
):
290 """Internal: raise an exception for unsupported operations."""
291 raise UnsupportedOperation("%s.%s() not supported" %
292 (self
.__class
__.__name
__, name
))
296 def seek(self
, pos
, whence
=0):
297 """Change stream position.
299 Change the stream position to byte offset offset. offset is
300 interpreted relative to the position indicated by whence. Values
303 * 0 -- start of stream (the default); offset should be zero or positive
304 * 1 -- current stream position; offset may be negative
305 * 2 -- end of stream; offset is usually negative
307 Return the new absolute position.
309 self
._unsupported
("seek")
312 """Return current stream position."""
313 return self
.seek(0, 1)
315 def truncate(self
, pos
=None):
316 """Truncate file to size bytes.
318 Size defaults to the current IO position as reported by tell(). Return
321 self
._unsupported
("truncate")
323 ### Flush and close ###
326 """Flush write buffers, if applicable.
328 This is not implemented for read-only and non-blocking streams.
331 # XXX Should this return the number of bytes written???
336 """Flush and close the IO object.
338 This method has no effect if the file is already closed.
340 if not self
.__closed
:
345 """Destructor. Calls close()."""
346 # The try/except block is in case this is called at program
347 # exit time, when it's possible that globals have already been
348 # deleted, and then the close() call might fail. Since
349 # there's nothing we can do about such failures and they annoy
350 # the end users, we suppress the traceback.
359 """Return whether object supports random access.
361 If False, seek(), tell() and truncate() will raise IOError.
362 This method may need to do a test seek().
366 def _checkSeekable(self
, msg
=None):
367 """Internal: raise an IOError if file is not seekable
369 if not self
.seekable():
370 raise IOError("File or stream is not seekable."
371 if msg
is None else msg
)
375 """Return whether object was opened for reading.
377 If False, read() will raise IOError.
381 def _checkReadable(self
, msg
=None):
382 """Internal: raise an IOError if file is not readable
384 if not self
.readable():
385 raise IOError("File or stream is not readable."
386 if msg
is None else msg
)
389 """Return whether object was opened for writing.
391 If False, write() and truncate() will raise IOError.
395 def _checkWritable(self
, msg
=None):
396 """Internal: raise an IOError if file is not writable
398 if not self
.writable():
399 raise IOError("File or stream is not writable."
400 if msg
is None else msg
)
404 """closed: bool. True iff the file has been closed.
406 For backwards compatibility, this is a property, not a predicate.
410 def _checkClosed(self
, msg
=None):
411 """Internal: raise an ValueError if file is closed
414 raise ValueError("I/O operation on closed file."
415 if msg
is None else msg
)
417 ### Context manager ###
420 """Context management protocol. Returns self."""
424 def __exit__(self
, *args
):
425 """Context management protocol. Calls close()"""
428 ### Lower-level APIs ###
430 # XXX Should these be present even if unimplemented?
433 """Returns underlying file descriptor if one exists.
435 An IOError is raised if the IO object does not use a file descriptor.
437 self
._unsupported
("fileno")
440 """Return whether this is an 'interactive' stream.
442 Return False if it can't be determined.
447 ### Readline[s] and writelines ###
449 def readline(self
, limit
=-1):
450 r
"""Read and return a line from the stream.
452 If limit is specified, at most limit bytes will be read.
454 The line terminator is always b'\n' for binary files; for text
455 files, the newlines argument to open can be used to select the line
456 terminator(s) recognized.
458 # For backwards compatibility, a (slowish) readline().
459 if hasattr(self
, "peek"):
461 readahead
= self
.peek(1)
464 n
= (readahead
.find(b
"\n") + 1) or len(readahead
)
473 elif not isinstance(limit
, (int, long)):
474 raise TypeError("limit must be an integer")
476 while limit
< 0 or len(res
) < limit
:
477 b
= self
.read(nreadahead())
481 if res
.endswith(b
"\n"):
490 line
= self
.readline()
495 def readlines(self
, hint
=None):
496 """Return a list of lines from the stream.
498 hint can be specified to control the number of lines read: no more
499 lines will be read if the total size (in bytes/characters) of all
500 lines so far exceeds hint.
502 if hint
is not None and not isinstance(hint
, (int, long)):
503 raise TypeError("integer or None expected")
504 if hint
is None or hint
<= 0:
515 def writelines(self
, lines
):
520 io
.IOBase
.register(IOBase
)
523 class RawIOBase(IOBase
):
525 """Base class for raw binary I/O."""
527 # The read() method is implemented by calling readinto(); derived
528 # classes that want to support read() only need to implement
529 # readinto() as a primitive operation. In general, readinto() can be
530 # more efficient than read().
532 # (It would be tempting to also provide an implementation of
533 # readinto() in terms of read(), in case the latter is a more suitable
534 # primitive operation, but that would lead to nasty recursion in case
535 # a subclass doesn't implement either.)
537 def read(self
, n
=-1):
538 """Read and return up to n bytes.
540 Returns an empty bytes object on EOF, or None if the object is
541 set not to block and has no data to read.
546 return self
.readall()
547 b
= bytearray(n
.__index
__())
553 """Read until EOF, using multiple read() call."""
556 data
= self
.read(DEFAULT_BUFFER_SIZE
)
562 def readinto(self
, b
):
563 """Read up to len(b) bytes into b.
565 Returns number of bytes read (0 for EOF), or None if the object
566 is set not to block as has no data to read.
568 self
._unsupported
("readinto")
571 """Write the given buffer to the IO stream.
573 Returns the number of bytes written, which may be less than len(b).
575 self
._unsupported
("write")
577 io
.RawIOBase
.register(RawIOBase
)
578 from _io
import FileIO
579 RawIOBase
.register(FileIO
)
582 class BufferedIOBase(IOBase
):
584 """Base class for buffered IO objects.
586 The main difference with RawIOBase is that the read() method
587 supports omitting the size argument, and does not have a default
588 implementation that defers to readinto().
590 In addition, read(), readinto() and write() may raise
591 BlockingIOError if the underlying raw stream is in non-blocking
592 mode and not ready; unlike their raw counterparts, they will never
595 A typical implementation should not inherit from a RawIOBase
596 implementation, but wrap one.
599 def read(self
, n
=None):
600 """Read and return up to n bytes.
602 If the argument is omitted, None, or negative, reads and
603 returns all data until EOF.
605 If the argument is positive, and the underlying raw stream is
606 not 'interactive', multiple raw reads may be issued to satisfy
607 the byte count (unless EOF is reached first). But for
608 interactive raw streams (XXX and for pipes?), at most one raw
609 read will be issued, and a short result does not imply that
612 Returns an empty bytes array on EOF.
614 Raises BlockingIOError if the underlying raw stream has no
617 self
._unsupported
("read")
619 def read1(self
, n
=None):
620 """Read up to n bytes with at most one read() system call."""
621 self
._unsupported
("read1")
623 def readinto(self
, b
):
624 """Read up to len(b) bytes into b.
626 Like read(), this may issue multiple reads to the underlying raw
627 stream, unless the latter is 'interactive'.
629 Returns the number of bytes read (0 for EOF).
631 Raises BlockingIOError if the underlying raw stream has no
634 # XXX This ought to work with anything that supports the buffer API
635 data
= self
.read(len(b
))
639 except TypeError as err
:
641 if not isinstance(b
, array
.array
):
643 b
[:n
] = array
.array(b
'b', data
)
647 """Write the given buffer to the IO stream.
649 Return the number of bytes written, which is never less than
652 Raises BlockingIOError if the buffer is full and the
653 underlying raw stream cannot accept more data at the moment.
655 self
._unsupported
("write")
659 Separate the underlying raw stream from the buffer and return it.
661 After the raw stream has been detached, the buffer is in an unusable
664 self
._unsupported
("detach")
666 io
.BufferedIOBase
.register(BufferedIOBase
)
669 class _BufferedIOMixin(BufferedIOBase
):
671 """A mixin implementation of BufferedIOBase with an underlying raw stream.
673 This passes most requests on to the underlying raw stream. It
674 does *not* provide implementations of read(), readinto() or
678 def __init__(self
, raw
):
683 def seek(self
, pos
, whence
=0):
684 new_position
= self
.raw
.seek(pos
, whence
)
686 raise IOError("seek() returned an invalid position")
690 pos
= self
.raw
.tell()
692 raise IOError("tell() returned an invalid position")
695 def truncate(self
, pos
=None):
696 # Flush the stream. We're mixing buffered I/O with lower-level I/O,
697 # and a flush may be necessary to synch both views of the current
703 # XXX: Should seek() be used, instead of passing the position
704 # XXX directly to truncate?
705 return self
.raw
.truncate(pos
)
707 ### Flush and close ###
711 raise ValueError("flush of closed file")
715 if self
.raw
is not None and not self
.closed
:
721 raise ValueError("raw stream already detached")
730 return self
.raw
.seekable()
733 return self
.raw
.readable()
736 return self
.raw
.writable()
740 return self
.raw
.closed
751 clsname
= self
.__class
__.__name
__
754 except AttributeError:
755 return "<_pyio.{0}>".format(clsname
)
757 return "<_pyio.{0} name={1!r}>".format(clsname
, name
)
759 ### Lower-level APIs ###
762 return self
.raw
.fileno()
765 return self
.raw
.isatty()
768 class BytesIO(BufferedIOBase
):
770 """Buffered I/O implementation using an in-memory bytes buffer."""
772 def __init__(self
, initial_bytes
=None):
774 if initial_bytes
is not None:
775 buf
.extend(initial_bytes
)
779 def __getstate__(self
):
781 raise ValueError("__getstate__ on closed file")
782 return self
.__dict
__.copy()
785 """Return the bytes value (contents) of the buffer
788 raise ValueError("getvalue on closed file")
789 return bytes(self
._buffer
)
791 def read(self
, n
=None):
793 raise ValueError("read from closed file")
796 if not isinstance(n
, (int, long)):
797 raise TypeError("integer argument expected, got {0!r}".format(
800 n
= len(self
._buffer
)
801 if len(self
._buffer
) <= self
._pos
:
803 newpos
= min(len(self
._buffer
), self
._pos
+ n
)
804 b
= self
._buffer
[self
._pos
: newpos
]
809 """This is the same as read.
815 raise ValueError("write to closed file")
816 if isinstance(b
, unicode):
817 raise TypeError("can't write unicode to binary stream")
822 if pos
> len(self
._buffer
):
823 # Inserts null bytes between the current end of the file
824 # and the new write position.
825 padding
= b
'\x00' * (pos
- len(self
._buffer
))
826 self
._buffer
+= padding
827 self
._buffer
[pos
:pos
+ n
] = b
831 def seek(self
, pos
, whence
=0):
833 raise ValueError("seek on closed file")
836 except AttributeError:
837 raise TypeError("an integer is required")
840 raise ValueError("negative seek position %r" % (pos
,))
843 self
._pos
= max(0, self
._pos
+ pos
)
845 self
._pos
= max(0, len(self
._buffer
) + pos
)
847 raise ValueError("invalid whence value")
852 raise ValueError("tell on closed file")
855 def truncate(self
, pos
=None):
857 raise ValueError("truncate on closed file")
863 except AttributeError:
864 raise TypeError("an integer is required")
866 raise ValueError("negative truncate position %r" % (pos
,))
867 del self
._buffer
[pos
:]
880 class BufferedReader(_BufferedIOMixin
):
882 """BufferedReader(raw[, buffer_size])
884 A buffer for a readable, sequential BaseRawIO object.
886 The constructor creates a BufferedReader for the given readable raw
887 stream and buffer_size. If buffer_size is omitted, DEFAULT_BUFFER_SIZE
891 def __init__(self
, raw
, buffer_size
=DEFAULT_BUFFER_SIZE
):
892 """Create a new buffered reader using the given readable raw IO object.
894 if not raw
.readable():
895 raise IOError('"raw" argument must be readable.')
897 _BufferedIOMixin
.__init
__(self
, raw
)
899 raise ValueError("invalid buffer size")
900 self
.buffer_size
= buffer_size
901 self
._reset
_read
_buf
()
902 self
._read
_lock
= Lock()
904 def _reset_read_buf(self
):
908 def read(self
, n
=None):
911 Returns exactly n bytes of data unless the underlying raw IO
912 stream reaches EOF or if the call would block in non-blocking
913 mode. If n is negative, read until EOF or until read() would
916 if n
is not None and n
< -1:
917 raise ValueError("invalid number of bytes to read")
918 with self
._read
_lock
:
919 return self
._read
_unlocked
(n
)
921 def _read_unlocked(self
, n
=None):
923 empty_values
= (b
"", None)
927 # Special case for when the number of bytes to read is unspecified.
928 if n
is None or n
== -1:
929 self
._reset
_read
_buf
()
930 chunks
= [buf
[pos
:]] # Strip the consumed bytes.
933 # Read until EOF or until read() would block.
934 chunk
= self
.raw
.read()
935 if chunk
in empty_values
:
938 current_size
+= len(chunk
)
940 return b
"".join(chunks
) or nodata_val
942 # The number of bytes to read is specified, return at most n bytes.
943 avail
= len(buf
) - pos
# Length of the available buffered data.
945 # Fast path: the data to read is fully buffered.
947 return buf
[pos
:pos
+n
]
948 # Slow path: read from the stream until enough bytes are read,
949 # or until an EOF occurs or until read() would block.
951 wanted
= max(self
.buffer_size
, n
)
953 chunk
= self
.raw
.read(wanted
)
954 if chunk
in empty_values
:
959 # n is more then avail only when an EOF occurred or when
960 # read() would have blocked.
962 out
= b
"".join(chunks
)
963 self
._read
_buf
= out
[n
:] # Save the extra data in the buffer.
965 return out
[:n
] if out
else nodata_val
968 """Returns buffered bytes without advancing the position.
970 The argument indicates a desired minimal number of bytes; we
971 do at most one raw read to satisfy it. We never return more
972 than self.buffer_size.
974 with self
._read
_lock
:
975 return self
._peek
_unlocked
(n
)
977 def _peek_unlocked(self
, n
=0):
978 want
= min(n
, self
.buffer_size
)
979 have
= len(self
._read
_buf
) - self
._read
_pos
980 if have
< want
or have
<= 0:
981 to_read
= self
.buffer_size
- have
982 current
= self
.raw
.read(to_read
)
984 self
._read
_buf
= self
._read
_buf
[self
._read
_pos
:] + current
986 return self
._read
_buf
[self
._read
_pos
:]
989 """Reads up to n bytes, with at most one read() system call."""
990 # Returns up to n bytes. If at least one byte is buffered, we
991 # only return buffered bytes. Otherwise, we do one raw read.
993 raise ValueError("number of bytes to read must be positive")
996 with self
._read
_lock
:
997 self
._peek
_unlocked
(1)
998 return self
._read
_unlocked
(
999 min(n
, len(self
._read
_buf
) - self
._read
_pos
))
1002 return _BufferedIOMixin
.tell(self
) - len(self
._read
_buf
) + self
._read
_pos
1004 def seek(self
, pos
, whence
=0):
1005 if not (0 <= whence
<= 2):
1006 raise ValueError("invalid whence value")
1007 with self
._read
_lock
:
1009 pos
-= len(self
._read
_buf
) - self
._read
_pos
1010 pos
= _BufferedIOMixin
.seek(self
, pos
, whence
)
1011 self
._reset
_read
_buf
()
1014 class BufferedWriter(_BufferedIOMixin
):
1016 """A buffer for a writeable sequential RawIO object.
1018 The constructor creates a BufferedWriter for the given writeable raw
1019 stream. If the buffer_size is not given, it defaults to
1020 DEFAULT_BUFFER_SIZE.
1023 _warning_stack_offset
= 2
1025 def __init__(self
, raw
,
1026 buffer_size
=DEFAULT_BUFFER_SIZE
, max_buffer_size
=None):
1027 if not raw
.writable():
1028 raise IOError('"raw" argument must be writable.')
1030 _BufferedIOMixin
.__init
__(self
, raw
)
1031 if buffer_size
<= 0:
1032 raise ValueError("invalid buffer size")
1033 if max_buffer_size
is not None:
1034 warnings
.warn("max_buffer_size is deprecated", DeprecationWarning,
1035 self
._warning
_stack
_offset
)
1036 self
.buffer_size
= buffer_size
1037 self
._write
_buf
= bytearray()
1038 self
._write
_lock
= Lock()
1042 raise ValueError("write to closed file")
1043 if isinstance(b
, unicode):
1044 raise TypeError("can't write unicode to binary stream")
1045 with self
._write
_lock
:
1046 # XXX we can implement some more tricks to try and avoid
1048 if len(self
._write
_buf
) > self
.buffer_size
:
1049 # We're full, so let's pre-flush the buffer
1051 self
._flush
_unlocked
()
1052 except BlockingIOError
as e
:
1053 # We can't accept anything else.
1054 # XXX Why not just let the exception pass through?
1055 raise BlockingIOError(e
.errno
, e
.strerror
, 0)
1056 before
= len(self
._write
_buf
)
1057 self
._write
_buf
.extend(b
)
1058 written
= len(self
._write
_buf
) - before
1059 if len(self
._write
_buf
) > self
.buffer_size
:
1061 self
._flush
_unlocked
()
1062 except BlockingIOError
as e
:
1063 if len(self
._write
_buf
) > self
.buffer_size
:
1064 # We've hit the buffer_size. We have to accept a partial
1065 # write and cut back our buffer.
1066 overage
= len(self
._write
_buf
) - self
.buffer_size
1068 self
._write
_buf
= self
._write
_buf
[:self
.buffer_size
]
1069 raise BlockingIOError(e
.errno
, e
.strerror
, written
)
1072 def truncate(self
, pos
=None):
1073 with self
._write
_lock
:
1074 self
._flush
_unlocked
()
1076 pos
= self
.raw
.tell()
1077 return self
.raw
.truncate(pos
)
1080 with self
._write
_lock
:
1081 self
._flush
_unlocked
()
1083 def _flush_unlocked(self
):
1085 raise ValueError("flush of closed file")
1088 while self
._write
_buf
:
1089 n
= self
.raw
.write(self
._write
_buf
)
1090 if n
> len(self
._write
_buf
) or n
< 0:
1091 raise IOError("write() returned incorrect number of bytes")
1092 del self
._write
_buf
[:n
]
1094 except BlockingIOError
as e
:
1095 n
= e
.characters_written
1096 del self
._write
_buf
[:n
]
1098 raise BlockingIOError(e
.errno
, e
.strerror
, written
)
1101 return _BufferedIOMixin
.tell(self
) + len(self
._write
_buf
)
1103 def seek(self
, pos
, whence
=0):
1104 if not (0 <= whence
<= 2):
1105 raise ValueError("invalid whence")
1106 with self
._write
_lock
:
1107 self
._flush
_unlocked
()
1108 return _BufferedIOMixin
.seek(self
, pos
, whence
)
1111 class BufferedRWPair(BufferedIOBase
):
1113 """A buffered reader and writer object together.
1115 A buffered reader object and buffered writer object put together to
1116 form a sequential IO object that can read and write. This is typically
1117 used with a socket or two-way pipe.
1119 reader and writer are RawIOBase objects that are readable and
1120 writeable respectively. If the buffer_size is omitted it defaults to
1121 DEFAULT_BUFFER_SIZE.
1124 # XXX The usefulness of this (compared to having two separate IO
1125 # objects) is questionable.
1127 def __init__(self
, reader
, writer
,
1128 buffer_size
=DEFAULT_BUFFER_SIZE
, max_buffer_size
=None):
1131 The arguments are two RawIO instances.
1133 if max_buffer_size
is not None:
1134 warnings
.warn("max_buffer_size is deprecated", DeprecationWarning, 2)
1136 if not reader
.readable():
1137 raise IOError('"reader" argument must be readable.')
1139 if not writer
.writable():
1140 raise IOError('"writer" argument must be writable.')
1142 self
.reader
= BufferedReader(reader
, buffer_size
)
1143 self
.writer
= BufferedWriter(writer
, buffer_size
)
1145 def read(self
, n
=None):
1148 return self
.reader
.read(n
)
1150 def readinto(self
, b
):
1151 return self
.reader
.readinto(b
)
1154 return self
.writer
.write(b
)
1156 def peek(self
, n
=0):
1157 return self
.reader
.peek(n
)
1160 return self
.reader
.read1(n
)
1163 return self
.reader
.readable()
1166 return self
.writer
.writable()
1169 return self
.writer
.flush()
1176 return self
.reader
.isatty() or self
.writer
.isatty()
1180 return self
.writer
.closed
1183 class BufferedRandom(BufferedWriter
, BufferedReader
):
1185 """A buffered interface to random access streams.
1187 The constructor creates a reader and writer for a seekable stream,
1188 raw, given in the first argument. If the buffer_size is omitted it
1189 defaults to DEFAULT_BUFFER_SIZE.
1192 _warning_stack_offset
= 3
1194 def __init__(self
, raw
,
1195 buffer_size
=DEFAULT_BUFFER_SIZE
, max_buffer_size
=None):
1196 raw
._checkSeekable
()
1197 BufferedReader
.__init
__(self
, raw
, buffer_size
)
1198 BufferedWriter
.__init
__(self
, raw
, buffer_size
, max_buffer_size
)
1200 def seek(self
, pos
, whence
=0):
1201 if not (0 <= whence
<= 2):
1202 raise ValueError("invalid whence")
1206 with self
._read
_lock
:
1207 self
.raw
.seek(self
._read
_pos
- len(self
._read
_buf
), 1)
1208 # First do the raw seek, then empty the read buffer, so that
1209 # if the raw seek fails, we don't lose buffered data forever.
1210 pos
= self
.raw
.seek(pos
, whence
)
1211 with self
._read
_lock
:
1212 self
._reset
_read
_buf
()
1214 raise IOError("seek() returned invalid position")
1219 return BufferedWriter
.tell(self
)
1221 return BufferedReader
.tell(self
)
1223 def truncate(self
, pos
=None):
1226 # Use seek to flush the read buffer.
1227 return BufferedWriter
.truncate(self
, pos
)
1229 def read(self
, n
=None):
1233 return BufferedReader
.read(self
, n
)
1235 def readinto(self
, b
):
1237 return BufferedReader
.readinto(self
, b
)
1239 def peek(self
, n
=0):
1241 return BufferedReader
.peek(self
, n
)
1245 return BufferedReader
.read1(self
, n
)
1250 with self
._read
_lock
:
1251 self
.raw
.seek(self
._read
_pos
- len(self
._read
_buf
), 1)
1252 self
._reset
_read
_buf
()
1253 return BufferedWriter
.write(self
, b
)
1256 class TextIOBase(IOBase
):
1258 """Base class for text I/O.
1260 This class provides a character and line based interface to stream
1261 I/O. There is no readinto method because Python's character strings
1262 are immutable. There is no public constructor.
1265 def read(self
, n
=-1):
1266 """Read at most n characters from stream.
1268 Read from underlying buffer until we have n characters or we hit EOF.
1269 If n is negative or omitted, read until EOF.
1271 self
._unsupported
("read")
1274 """Write string s to stream."""
1275 self
._unsupported
("write")
1277 def truncate(self
, pos
=None):
1278 """Truncate size to pos."""
1279 self
._unsupported
("truncate")
1282 """Read until newline or EOF.
1284 Returns an empty string if EOF is hit immediately.
1286 self
._unsupported
("readline")
1290 Separate the underlying buffer from the TextIOBase and return it.
1292 After the underlying buffer has been detached, the TextIO is in an
1295 self
._unsupported
("detach")
1299 """Subclasses should override."""
1304 """Line endings translated so far.
1306 Only line endings translated during reading are considered.
1308 Subclasses should override.
1314 """Error setting of the decoder or encoder.
1316 Subclasses should override."""
1319 io
.TextIOBase
.register(TextIOBase
)
1322 class IncrementalNewlineDecoder(codecs
.IncrementalDecoder
):
1323 r
"""Codec used when reading a file in universal newlines mode. It wraps
1324 another incremental decoder, translating \r\n and \r into \n. It also
1325 records the types of newlines encountered. When used with
1326 translate=False, it ensures that the newline sequence is returned in
1329 def __init__(self
, decoder
, translate
, errors
='strict'):
1330 codecs
.IncrementalDecoder
.__init
__(self
, errors
=errors
)
1331 self
.translate
= translate
1332 self
.decoder
= decoder
1334 self
.pendingcr
= False
1336 def decode(self
, input, final
=False):
1337 # decode input (with the eventual \r from a previous pass)
1338 if self
.decoder
is None:
1341 output
= self
.decoder
.decode(input, final
=final
)
1342 if self
.pendingcr
and (output
or final
):
1343 output
= "\r" + output
1344 self
.pendingcr
= False
1346 # retain last \r even when not translating data:
1347 # then readline() is sure to get \r\n in one pass
1348 if output
.endswith("\r") and not final
:
1349 output
= output
[:-1]
1350 self
.pendingcr
= True
1352 # Record which newlines are read
1353 crlf
= output
.count('\r\n')
1354 cr
= output
.count('\r') - crlf
1355 lf
= output
.count('\n') - crlf
1356 self
.seennl |
= (lf
and self
._LF
) |
(cr
and self
._CR
) \
1357 |
(crlf
and self
._CRLF
)
1361 output
= output
.replace("\r\n", "\n")
1363 output
= output
.replace("\r", "\n")
1368 if self
.decoder
is None:
1372 buf
, flag
= self
.decoder
.getstate()
1378 def setstate(self
, state
):
1380 self
.pendingcr
= bool(flag
& 1)
1381 if self
.decoder
is not None:
1382 self
.decoder
.setstate((buf
, flag
>> 1))
1386 self
.pendingcr
= False
1387 if self
.decoder
is not None:
1388 self
.decoder
.reset()
1403 ("\r", "\n", "\r\n")
1407 class TextIOWrapper(TextIOBase
):
1409 r
"""Character and line based layer over a BufferedIOBase object, buffer.
1411 encoding gives the name of the encoding that the stream will be
1412 decoded or encoded with. It defaults to locale.getpreferredencoding.
1414 errors determines the strictness of encoding and decoding (see the
1415 codecs.register) and defaults to "strict".
1417 newline can be None, '', '\n', '\r', or '\r\n'. It controls the
1418 handling of line endings. If it is None, universal newlines is
1419 enabled. With this enabled, on input, the lines endings '\n', '\r',
1420 or '\r\n' are translated to '\n' before being returned to the
1421 caller. Conversely, on output, '\n' is translated to the system
1422 default line seperator, os.linesep. If newline is any other of its
1423 legal values, that newline becomes the newline when the file is read
1424 and it is returned untranslated. On output, '\n' is converted to the
1427 If line_buffering is True, a call to flush is implied when a call to
1428 write contains a newline character.
1433 def __init__(self
, buffer, encoding
=None, errors
=None, newline
=None,
1434 line_buffering
=False):
1435 if newline
is not None and not isinstance(newline
, basestring
):
1436 raise TypeError("illegal newline type: %r" % (type(newline
),))
1437 if newline
not in (None, "", "\n", "\r", "\r\n"):
1438 raise ValueError("illegal newline value: %r" % (newline
,))
1439 if encoding
is None:
1443 # Importing locale may fail if Python is being built
1446 encoding
= locale
.getpreferredencoding()
1448 if not isinstance(encoding
, basestring
):
1449 raise ValueError("invalid encoding: %r" % encoding
)
1454 if not isinstance(errors
, basestring
):
1455 raise ValueError("invalid errors: %r" % errors
)
1457 self
.buffer = buffer
1458 self
._line
_buffering
= line_buffering
1459 self
._encoding
= encoding
1460 self
._errors
= errors
1461 self
._readuniversal
= not newline
1462 self
._readtranslate
= newline
is None
1463 self
._readnl
= newline
1464 self
._writetranslate
= newline
!= ''
1465 self
._writenl
= newline
or os
.linesep
1466 self
._encoder
= None
1467 self
._decoder
= None
1468 self
._decoded
_chars
= '' # buffer for text returned from decoder
1469 self
._decoded
_chars
_used
= 0 # offset into _decoded_chars for read()
1470 self
._snapshot
= None # info for reconstructing decoder state
1471 self
._seekable
= self
._telling
= self
.buffer.seekable()
1473 if self
._seekable
and self
.writable():
1474 position
= self
.buffer.tell()
1477 self
._get
_encoder
().setstate(0)
1479 # Sometimes the encoder doesn't exist
1482 # self._snapshot is either None, or a tuple (dec_flags, next_input)
1483 # where dec_flags is the second (integer) item of the decoder state
1484 # and next_input is the chunk of input bytes that comes next after the
1485 # snapshot point. We use this to reconstruct decoder states in tell().
1487 # Naming convention:
1488 # - "bytes_..." for integer variables that count input bytes
1489 # - "chars_..." for integer variables that count decoded characters
1494 except AttributeError:
1495 return "<_pyio.TextIOWrapper encoding='{0}'>".format(self
.encoding
)
1497 return "<_pyio.TextIOWrapper name={0!r} encoding='{1}'>".format(
1498 name
, self
.encoding
)
1502 return self
._encoding
1509 def line_buffering(self
):
1510 return self
._line
_buffering
1513 return self
._seekable
1516 return self
.buffer.readable()
1519 return self
.buffer.writable()
1523 self
._telling
= self
._seekable
1526 if self
.buffer is not None and not self
.closed
:
1532 return self
.buffer.closed
1536 return self
.buffer.name
1539 return self
.buffer.fileno()
1542 return self
.buffer.isatty()
1546 raise ValueError("write to closed file")
1547 if not isinstance(s
, unicode):
1548 raise TypeError("can't write %s to text stream" %
1549 s
.__class
__.__name
__)
1551 haslf
= (self
._writetranslate
or self
._line
_buffering
) and "\n" in s
1552 if haslf
and self
._writetranslate
and self
._writenl
!= "\n":
1553 s
= s
.replace("\n", self
._writenl
)
1554 encoder
= self
._encoder
or self
._get
_encoder
()
1555 # XXX What if we were just reading?
1556 b
= encoder
.encode(s
)
1557 self
.buffer.write(b
)
1558 if self
._line
_buffering
and (haslf
or "\r" in s
):
1560 self
._snapshot
= None
1562 self
._decoder
.reset()
1565 def _get_encoder(self
):
1566 make_encoder
= codecs
.getincrementalencoder(self
._encoding
)
1567 self
._encoder
= make_encoder(self
._errors
)
1568 return self
._encoder
1570 def _get_decoder(self
):
1571 make_decoder
= codecs
.getincrementaldecoder(self
._encoding
)
1572 decoder
= make_decoder(self
._errors
)
1573 if self
._readuniversal
:
1574 decoder
= IncrementalNewlineDecoder(decoder
, self
._readtranslate
)
1575 self
._decoder
= decoder
1578 # The following three methods implement an ADT for _decoded_chars.
1579 # Text returned from the decoder is buffered here until the client
1580 # requests it by calling our read() or readline() method.
1581 def _set_decoded_chars(self
, chars
):
1582 """Set the _decoded_chars buffer."""
1583 self
._decoded
_chars
= chars
1584 self
._decoded
_chars
_used
= 0
1586 def _get_decoded_chars(self
, n
=None):
1587 """Advance into the _decoded_chars buffer."""
1588 offset
= self
._decoded
_chars
_used
1590 chars
= self
._decoded
_chars
[offset
:]
1592 chars
= self
._decoded
_chars
[offset
:offset
+ n
]
1593 self
._decoded
_chars
_used
+= len(chars
)
1596 def _rewind_decoded_chars(self
, n
):
1597 """Rewind the _decoded_chars buffer."""
1598 if self
._decoded
_chars
_used
< n
:
1599 raise AssertionError("rewind decoded_chars out of bounds")
1600 self
._decoded
_chars
_used
-= n
1602 def _read_chunk(self
):
1604 Read and decode the next chunk of data from the BufferedReader.
1607 # The return value is True unless EOF was reached. The decoded
1608 # string is placed in self._decoded_chars (replacing its previous
1609 # value). The entire input chunk is sent to the decoder, though
1610 # some of it may remain buffered in the decoder, yet to be
1613 if self
._decoder
is None:
1614 raise ValueError("no decoder")
1617 # To prepare for tell(), we need to snapshot a point in the
1618 # file where the decoder's input buffer is empty.
1620 dec_buffer
, dec_flags
= self
._decoder
.getstate()
1621 # Given this, we know there was a valid snapshot point
1622 # len(dec_buffer) bytes ago with decoder state (b'', dec_flags).
1624 # Read a chunk, decode it, and put the result in self._decoded_chars.
1625 input_chunk
= self
.buffer.read1(self
._CHUNK
_SIZE
)
1626 eof
= not input_chunk
1627 self
._set
_decoded
_chars
(self
._decoder
.decode(input_chunk
, eof
))
1630 # At the snapshot point, len(dec_buffer) bytes before the read,
1631 # the next input to be decoded is dec_buffer + input_chunk.
1632 self
._snapshot
= (dec_flags
, dec_buffer
+ input_chunk
)
1636 def _pack_cookie(self
, position
, dec_flags
=0,
1637 bytes_to_feed
=0, need_eof
=0, chars_to_skip
=0):
1638 # The meaning of a tell() cookie is: seek to position, set the
1639 # decoder flags to dec_flags, read bytes_to_feed bytes, feed them
1640 # into the decoder with need_eof as the EOF flag, then skip
1641 # chars_to_skip characters of the decoded result. For most simple
1642 # decoders, tell() will often just give a byte offset in the file.
1643 return (position |
(dec_flags
<<64) |
(bytes_to_feed
<<128) |
1644 (chars_to_skip
<<192) |
bool(need_eof
)<<256)
1646 def _unpack_cookie(self
, bigint
):
1647 rest
, position
= divmod(bigint
, 1<<64)
1648 rest
, dec_flags
= divmod(rest
, 1<<64)
1649 rest
, bytes_to_feed
= divmod(rest
, 1<<64)
1650 need_eof
, chars_to_skip
= divmod(rest
, 1<<64)
1651 return position
, dec_flags
, bytes_to_feed
, need_eof
, chars_to_skip
1654 if not self
._seekable
:
1655 raise IOError("underlying stream is not seekable")
1656 if not self
._telling
:
1657 raise IOError("telling position disabled by next() call")
1659 position
= self
.buffer.tell()
1660 decoder
= self
._decoder
1661 if decoder
is None or self
._snapshot
is None:
1662 if self
._decoded
_chars
:
1663 # This should never happen.
1664 raise AssertionError("pending decoded text")
1667 # Skip backward to the snapshot point (see _read_chunk).
1668 dec_flags
, next_input
= self
._snapshot
1669 position
-= len(next_input
)
1671 # How many decoded characters have been used up since the snapshot?
1672 chars_to_skip
= self
._decoded
_chars
_used
1673 if chars_to_skip
== 0:
1674 # We haven't moved from the snapshot point.
1675 return self
._pack
_cookie
(position
, dec_flags
)
1677 # Starting from the snapshot position, we will walk the decoder
1678 # forward until it gives us enough decoded characters.
1679 saved_state
= decoder
.getstate()
1681 # Note our initial start point.
1682 decoder
.setstate((b
'', dec_flags
))
1683 start_pos
= position
1684 start_flags
, bytes_fed
, chars_decoded
= dec_flags
, 0, 0
1687 # Feed the decoder one byte at a time. As we go, note the
1688 # nearest "safe start point" before the current location
1689 # (a point where the decoder has nothing buffered, so seek()
1690 # can safely start from there and advance to this location).
1691 for next_byte
in next_input
:
1693 chars_decoded
+= len(decoder
.decode(next_byte
))
1694 dec_buffer
, dec_flags
= decoder
.getstate()
1695 if not dec_buffer
and chars_decoded
<= chars_to_skip
:
1696 # Decoder buffer is empty, so this is a safe start point.
1697 start_pos
+= bytes_fed
1698 chars_to_skip
-= chars_decoded
1699 start_flags
, bytes_fed
, chars_decoded
= dec_flags
, 0, 0
1700 if chars_decoded
>= chars_to_skip
:
1703 # We didn't get enough decoded data; signal EOF to get more.
1704 chars_decoded
+= len(decoder
.decode(b
'', final
=True))
1706 if chars_decoded
< chars_to_skip
:
1707 raise IOError("can't reconstruct logical file position")
1709 # The returned cookie corresponds to the last safe start point.
1710 return self
._pack
_cookie
(
1711 start_pos
, start_flags
, bytes_fed
, need_eof
, chars_to_skip
)
1713 decoder
.setstate(saved_state
)
1715 def truncate(self
, pos
=None):
1719 return self
.buffer.truncate(pos
)
1722 if self
.buffer is None:
1723 raise ValueError("buffer is already detached")
1725 buffer = self
.buffer
1729 def seek(self
, cookie
, whence
=0):
1731 raise ValueError("tell on closed file")
1732 if not self
._seekable
:
1733 raise IOError("underlying stream is not seekable")
1734 if whence
== 1: # seek relative to current position
1736 raise IOError("can't do nonzero cur-relative seeks")
1737 # Seeking to the current position should attempt to
1738 # sync the underlying buffer with the current position.
1740 cookie
= self
.tell()
1741 if whence
== 2: # seek relative to end of file
1743 raise IOError("can't do nonzero end-relative seeks")
1745 position
= self
.buffer.seek(0, 2)
1746 self
._set
_decoded
_chars
('')
1747 self
._snapshot
= None
1749 self
._decoder
.reset()
1752 raise ValueError("invalid whence (%r, should be 0, 1 or 2)" %
1755 raise ValueError("negative seek position %r" % (cookie
,))
1758 # The strategy of seek() is to go back to the safe start point
1759 # and replay the effect of read(chars_to_skip) from there.
1760 start_pos
, dec_flags
, bytes_to_feed
, need_eof
, chars_to_skip
= \
1761 self
._unpack
_cookie
(cookie
)
1763 # Seek back to the safe start point.
1764 self
.buffer.seek(start_pos
)
1765 self
._set
_decoded
_chars
('')
1766 self
._snapshot
= None
1768 # Restore the decoder to its state from the safe start point.
1769 if cookie
== 0 and self
._decoder
:
1770 self
._decoder
.reset()
1771 elif self
._decoder
or dec_flags
or chars_to_skip
:
1772 self
._decoder
= self
._decoder
or self
._get
_decoder
()
1773 self
._decoder
.setstate((b
'', dec_flags
))
1774 self
._snapshot
= (dec_flags
, b
'')
1777 # Just like _read_chunk, feed the decoder and save a snapshot.
1778 input_chunk
= self
.buffer.read(bytes_to_feed
)
1779 self
._set
_decoded
_chars
(
1780 self
._decoder
.decode(input_chunk
, need_eof
))
1781 self
._snapshot
= (dec_flags
, input_chunk
)
1783 # Skip chars_to_skip of the decoded characters.
1784 if len(self
._decoded
_chars
) < chars_to_skip
:
1785 raise IOError("can't restore logical file position")
1786 self
._decoded
_chars
_used
= chars_to_skip
1788 # Finally, reset the encoder (merely useful for proper BOM handling)
1790 encoder
= self
._encoder
or self
._get
_encoder
()
1792 # Sometimes the encoder doesn't exist
1801 def read(self
, n
=None):
1802 self
._checkReadable
()
1805 decoder
= self
._decoder
or self
._get
_decoder
()
1808 except AttributeError:
1809 raise TypeError("an integer is required")
1812 result
= (self
._get
_decoded
_chars
() +
1813 decoder
.decode(self
.buffer.read(), final
=True))
1814 self
._set
_decoded
_chars
('')
1815 self
._snapshot
= None
1818 # Keep reading chunks until we have n characters to return.
1820 result
= self
._get
_decoded
_chars
(n
)
1821 while len(result
) < n
and not eof
:
1822 eof
= not self
._read
_chunk
()
1823 result
+= self
._get
_decoded
_chars
(n
- len(result
))
1827 self
._telling
= False
1828 line
= self
.readline()
1830 self
._snapshot
= None
1831 self
._telling
= self
._seekable
1835 def readline(self
, limit
=None):
1837 raise ValueError("read from closed file")
1840 elif not isinstance(limit
, (int, long)):
1841 raise TypeError("limit must be an integer")
1843 # Grab all the decoded text (we will rewind any extra bits later).
1844 line
= self
._get
_decoded
_chars
()
1847 # Make the decoder if it doesn't already exist.
1848 if not self
._decoder
:
1853 if self
._readtranslate
:
1854 # Newlines are already translated, only search for \n
1855 pos
= line
.find('\n', start
)
1862 elif self
._readuniversal
:
1863 # Universal newline search. Find any of \r, \r\n, \n
1864 # The decoder ensures that \r\n are not split in two pieces
1866 # In C we'd look for these in parallel of course.
1867 nlpos
= line
.find("\n", start
)
1868 crpos
= line
.find("\r", start
)
1885 elif nlpos
== crpos
+ 1:
1895 pos
= line
.find(self
._readnl
)
1897 endpos
= pos
+ len(self
._readnl
)
1900 if limit
>= 0 and len(line
) >= limit
:
1901 endpos
= limit
# reached length limit
1904 # No line ending seen yet - get more data'
1905 while self
._read
_chunk
():
1906 if self
._decoded
_chars
:
1908 if self
._decoded
_chars
:
1909 line
+= self
._get
_decoded
_chars
()
1912 self
._set
_decoded
_chars
('')
1913 self
._snapshot
= None
1916 if limit
>= 0 and endpos
> limit
:
1917 endpos
= limit
# don't exceed limit
1919 # Rewind _decoded_chars to just after the line ending we found.
1920 self
._rewind
_decoded
_chars
(len(line
) - endpos
)
1921 return line
[:endpos
]
1925 return self
._decoder
.newlines
if self
._decoder
else None
1928 class StringIO(TextIOWrapper
):
1929 """Text I/O implementation using an in-memory buffer.
1931 The initial_value argument sets the value of object. The newline
1932 argument is like the one of TextIOWrapper's constructor.
1935 def __init__(self
, initial_value
="", newline
="\n"):
1936 super(StringIO
, self
).__init
__(BytesIO(),
1940 # Issue #5645: make universal newlines semantics the same as in the
1941 # C version, even under Windows.
1943 self
._writetranslate
= False
1945 if not isinstance(initial_value
, unicode):
1946 initial_value
= unicode(initial_value
)
1947 self
.write(initial_value
)
1952 return self
.buffer.getvalue().decode(self
._encoding
, self
._errors
)
1955 # TextIOWrapper tells the encoding in its repr. In StringIO,
1956 # that's a implementation detail.
1957 return object.__repr
__(self
)
1968 # This doesn't make sense on StringIO.
1969 self
._unsupported
("detach")