ยปCore Development>Code coverage>Lib/_pyio.py

Python code coverage for Lib/_pyio.py

#countcontent
1n/a"""
2n/aPython implementation of the io module.
3n/a"""
4n/a
5n/aimport os
6n/aimport abc
7n/aimport codecs
8n/aimport errno
9n/aimport stat
10n/aimport sys
11n/a# Import _thread instead of threading to reduce startup cost
12n/atry:
13n/a from _thread import allocate_lock as Lock
14n/aexcept ImportError:
15n/a from _dummy_thread import allocate_lock as Lock
16n/aif sys.platform in {'win32', 'cygwin'}:
17n/a from msvcrt import setmode as _setmode
18n/aelse:
19n/a _setmode = None
20n/a
21n/aimport io
22n/afrom io import (__all__, SEEK_SET, SEEK_CUR, SEEK_END)
23n/a
24n/avalid_seek_flags = {0, 1, 2} # Hardwired values
25n/aif hasattr(os, 'SEEK_HOLE') :
26n/a valid_seek_flags.add(os.SEEK_HOLE)
27n/a valid_seek_flags.add(os.SEEK_DATA)
28n/a
29n/a# open() uses st_blksize whenever we can
30n/aDEFAULT_BUFFER_SIZE = 8 * 1024 # bytes
31n/a
32n/a# NOTE: Base classes defined here are registered with the "official" ABCs
33n/a# defined in io.py. We don't use real inheritance though, because we don't want
34n/a# to inherit the C implementations.
35n/a
36n/a# Rebind for compatibility
37n/aBlockingIOError = BlockingIOError
38n/a
39n/a
40n/adef open(file, mode="r", buffering=-1, encoding=None, errors=None,
41n/a newline=None, closefd=True, opener=None):
42n/a
43n/a r"""Open file and return a stream. Raise OSError upon failure.
44n/a
45n/a file is either a text or byte string giving the name (and the path
46n/a if the file isn't in the current working directory) of the file to
47n/a be opened or an integer file descriptor of the file to be
48n/a wrapped. (If a file descriptor is given, it is closed when the
49n/a returned I/O object is closed, unless closefd is set to False.)
50n/a
51n/a mode is an optional string that specifies the mode in which the file is
52n/a opened. It defaults to 'r' which means open for reading in text mode. Other
53n/a common values are 'w' for writing (truncating the file if it already
54n/a exists), 'x' for exclusive creation of a new file, and 'a' for appending
55n/a (which on some Unix systems, means that all writes append to the end of the
56n/a file regardless of the current seek position). In text mode, if encoding is
57n/a not specified the encoding used is platform dependent. (For reading and
58n/a writing raw bytes use binary mode and leave encoding unspecified.) The
59n/a available modes are:
60n/a
61n/a ========= ===============================================================
62n/a Character Meaning
63n/a --------- ---------------------------------------------------------------
64n/a 'r' open for reading (default)
65n/a 'w' open for writing, truncating the file first
66n/a 'x' create a new file and open it for writing
67n/a 'a' open for writing, appending to the end of the file if it exists
68n/a 'b' binary mode
69n/a 't' text mode (default)
70n/a '+' open a disk file for updating (reading and writing)
71n/a 'U' universal newline mode (deprecated)
72n/a ========= ===============================================================
73n/a
74n/a The default mode is 'rt' (open for reading text). For binary random
75n/a access, the mode 'w+b' opens and truncates the file to 0 bytes, while
76n/a 'r+b' opens the file without truncation. The 'x' mode implies 'w' and
77n/a raises an `FileExistsError` if the file already exists.
78n/a
79n/a Python distinguishes between files opened in binary and text modes,
80n/a even when the underlying operating system doesn't. Files opened in
81n/a binary mode (appending 'b' to the mode argument) return contents as
82n/a bytes objects without any decoding. In text mode (the default, or when
83n/a 't' is appended to the mode argument), the contents of the file are
84n/a returned as strings, the bytes having been first decoded using a
85n/a platform-dependent encoding or using the specified encoding if given.
86n/a
87n/a 'U' mode is deprecated and will raise an exception in future versions
88n/a of Python. It has no effect in Python 3. Use newline to control
89n/a universal newlines mode.
90n/a
91n/a buffering is an optional integer used to set the buffering policy.
92n/a Pass 0 to switch buffering off (only allowed in binary mode), 1 to select
93n/a line buffering (only usable in text mode), and an integer > 1 to indicate
94n/a the size of a fixed-size chunk buffer. When no buffering argument is
95n/a given, the default buffering policy works as follows:
96n/a
97n/a * Binary files are buffered in fixed-size chunks; the size of the buffer
98n/a is chosen using a heuristic trying to determine the underlying device's
99n/a "block size" and falling back on `io.DEFAULT_BUFFER_SIZE`.
100n/a On many systems, the buffer will typically be 4096 or 8192 bytes long.
101n/a
102n/a * "Interactive" text files (files for which isatty() returns True)
103n/a use line buffering. Other text files use the policy described above
104n/a for binary files.
105n/a
106n/a encoding is the str name of the encoding used to decode or encode the
107n/a file. This should only be used in text mode. The default encoding is
108n/a platform dependent, but any encoding supported by Python can be
109n/a passed. See the codecs module for the list of supported encodings.
110n/a
111n/a errors is an optional string that specifies how encoding errors are to
112n/a be handled---this argument should not be used in binary mode. Pass
113n/a 'strict' to raise a ValueError exception if there is an encoding error
114n/a (the default of None has the same effect), or pass 'ignore' to ignore
115n/a errors. (Note that ignoring encoding errors can lead to data loss.)
116n/a See the documentation for codecs.register for a list of the permitted
117n/a encoding error strings.
118n/a
119n/a newline is a string controlling how universal newlines works (it only
120n/a applies to text mode). It can be None, '', '\n', '\r', and '\r\n'. It works
121n/a as follows:
122n/a
123n/a * On input, if newline is None, universal newlines mode is
124n/a enabled. Lines in the input can end in '\n', '\r', or '\r\n', and
125n/a these are translated into '\n' before being returned to the
126n/a caller. If it is '', universal newline mode is enabled, but line
127n/a endings are returned to the caller untranslated. If it has any of
128n/a the other legal values, input lines are only terminated by the given
129n/a string, and the line ending is returned to the caller untranslated.
130n/a
131n/a * On output, if newline is None, any '\n' characters written are
132n/a translated to the system default line separator, os.linesep. If
133n/a newline is '', no translation takes place. If newline is any of the
134n/a other legal values, any '\n' characters written are translated to
135n/a the given string.
136n/a
137n/a closedfd is a bool. If closefd is False, the underlying file descriptor will
138n/a be kept open when the file is closed. This does not work when a file name is
139n/a given and must be True in that case.
140n/a
141n/a The newly created file is non-inheritable.
142n/a
143n/a A custom opener can be used by passing a callable as *opener*. The
144n/a underlying file descriptor for the file object is then obtained by calling
145n/a *opener* with (*file*, *flags*). *opener* must return an open file
146n/a descriptor (passing os.open as *opener* results in functionality similar to
147n/a passing None).
148n/a
149n/a open() returns a file object whose type depends on the mode, and
150n/a through which the standard file operations such as reading and writing
151n/a are performed. When open() is used to open a file in a text mode ('w',
152n/a 'r', 'wt', 'rt', etc.), it returns a TextIOWrapper. When used to open
153n/a a file in a binary mode, the returned class varies: in read binary
154n/a mode, it returns a BufferedReader; in write binary and append binary
155n/a modes, it returns a BufferedWriter, and in read/write mode, it returns
156n/a a BufferedRandom.
157n/a
158n/a It is also possible to use a string or bytearray as a file for both
159n/a reading and writing. For strings StringIO can be used like a file
160n/a opened in a text mode, and for bytes a BytesIO can be used like a file
161n/a opened in a binary mode.
162n/a """
163n/a if not isinstance(file, int):
164n/a file = os.fspath(file)
165n/a if not isinstance(file, (str, bytes, int)):
166n/a raise TypeError("invalid file: %r" % file)
167n/a if not isinstance(mode, str):
168n/a raise TypeError("invalid mode: %r" % mode)
169n/a if not isinstance(buffering, int):
170n/a raise TypeError("invalid buffering: %r" % buffering)
171n/a if encoding is not None and not isinstance(encoding, str):
172n/a raise TypeError("invalid encoding: %r" % encoding)
173n/a if errors is not None and not isinstance(errors, str):
174n/a raise TypeError("invalid errors: %r" % errors)
175n/a modes = set(mode)
176n/a if modes - set("axrwb+tU") or len(mode) > len(modes):
177n/a raise ValueError("invalid mode: %r" % mode)
178n/a creating = "x" in modes
179n/a reading = "r" in modes
180n/a writing = "w" in modes
181n/a appending = "a" in modes
182n/a updating = "+" in modes
183n/a text = "t" in modes
184n/a binary = "b" in modes
185n/a if "U" in modes:
186n/a if creating or writing or appending or updating:
187n/a raise ValueError("mode U cannot be combined with 'x', 'w', 'a', or '+'")
188n/a import warnings
189n/a warnings.warn("'U' mode is deprecated",
190n/a DeprecationWarning, 2)
191n/a reading = True
192n/a if text and binary:
193n/a raise ValueError("can't have text and binary mode at once")
194n/a if creating + reading + writing + appending > 1:
195n/a raise ValueError("can't have read/write/append mode at once")
196n/a if not (creating or reading or writing or appending):
197n/a raise ValueError("must have exactly one of read/write/append mode")
198n/a if binary and encoding is not None:
199n/a raise ValueError("binary mode doesn't take an encoding argument")
200n/a if binary and errors is not None:
201n/a raise ValueError("binary mode doesn't take an errors argument")
202n/a if binary and newline is not None:
203n/a raise ValueError("binary mode doesn't take a newline argument")
204n/a raw = FileIO(file,
205n/a (creating and "x" or "") +
206n/a (reading and "r" or "") +
207n/a (writing and "w" or "") +
208n/a (appending and "a" or "") +
209n/a (updating and "+" or ""),
210n/a closefd, opener=opener)
211n/a result = raw
212n/a try:
213n/a line_buffering = False
214n/a if buffering == 1 or buffering < 0 and raw.isatty():
215n/a buffering = -1
216n/a line_buffering = True
217n/a if buffering < 0:
218n/a buffering = DEFAULT_BUFFER_SIZE
219n/a try:
220n/a bs = os.fstat(raw.fileno()).st_blksize
221n/a except (OSError, AttributeError):
222n/a pass
223n/a else:
224n/a if bs > 1:
225n/a buffering = bs
226n/a if buffering < 0:
227n/a raise ValueError("invalid buffering size")
228n/a if buffering == 0:
229n/a if binary:
230n/a return result
231n/a raise ValueError("can't have unbuffered text I/O")
232n/a if updating:
233n/a buffer = BufferedRandom(raw, buffering)
234n/a elif creating or writing or appending:
235n/a buffer = BufferedWriter(raw, buffering)
236n/a elif reading:
237n/a buffer = BufferedReader(raw, buffering)
238n/a else:
239n/a raise ValueError("unknown mode: %r" % mode)
240n/a result = buffer
241n/a if binary:
242n/a return result
243n/a text = TextIOWrapper(buffer, encoding, errors, newline, line_buffering)
244n/a result = text
245n/a text.mode = mode
246n/a return result
247n/a except:
248n/a result.close()
249n/a raise
250n/a
251n/a
252n/aclass DocDescriptor:
253n/a """Helper for builtins.open.__doc__
254n/a """
255n/a def __get__(self, obj, typ):
256n/a return (
257n/a "open(file, mode='r', buffering=-1, encoding=None, "
258n/a "errors=None, newline=None, closefd=True)\n\n" +
259n/a open.__doc__)
260n/a
261n/aclass OpenWrapper:
262n/a """Wrapper for builtins.open
263n/a
264n/a Trick so that open won't become a bound method when stored
265n/a as a class variable (as dbm.dumb does).
266n/a
267n/a See initstdio() in Python/pylifecycle.c.
268n/a """
269n/a __doc__ = DocDescriptor()
270n/a
271n/a def __new__(cls, *args, **kwargs):
272n/a return open(*args, **kwargs)
273n/a
274n/a
275n/a# In normal operation, both `UnsupportedOperation`s should be bound to the
276n/a# same object.
277n/atry:
278n/a UnsupportedOperation = io.UnsupportedOperation
279n/aexcept AttributeError:
280n/a class UnsupportedOperation(OSError, ValueError):
281n/a pass
282n/a
283n/a
284n/aclass IOBase(metaclass=abc.ABCMeta):
285n/a
286n/a """The abstract base class for all I/O classes, acting on streams of
287n/a bytes. There is no public constructor.
288n/a
289n/a This class provides dummy implementations for many methods that
290n/a derived classes can override selectively; the default implementations
291n/a represent a file that cannot be read, written or seeked.
292n/a
293n/a Even though IOBase does not declare read, readinto, or write because
294n/a their signatures will vary, implementations and clients should
295n/a consider those methods part of the interface. Also, implementations
296n/a may raise UnsupportedOperation when operations they do not support are
297n/a called.
298n/a
299n/a The basic type used for binary data read from or written to a file is
300n/a bytes. Other bytes-like objects are accepted as method arguments too. In
301n/a some cases (such as readinto), a writable object is required. Text I/O
302n/a classes work with str data.
303n/a
304n/a Note that calling any method (even inquiries) on a closed stream is
305n/a undefined. Implementations may raise OSError in this case.
306n/a
307n/a IOBase (and its subclasses) support the iterator protocol, meaning
308n/a that an IOBase object can be iterated over yielding the lines in a
309n/a stream.
310n/a
311n/a IOBase also supports the :keyword:`with` statement. In this example,
312n/a fp is closed after the suite of the with statement is complete:
313n/a
314n/a with open('spam.txt', 'r') as fp:
315n/a fp.write('Spam and eggs!')
316n/a """
317n/a
318n/a ### Internal ###
319n/a
320n/a def _unsupported(self, name):
321n/a """Internal: raise an OSError exception for unsupported operations."""
322n/a raise UnsupportedOperation("%s.%s() not supported" %
323n/a (self.__class__.__name__, name))
324n/a
325n/a ### Positioning ###
326n/a
327n/a def seek(self, pos, whence=0):
328n/a """Change stream position.
329n/a
330n/a Change the stream position to byte offset pos. Argument pos is
331n/a interpreted relative to the position indicated by whence. Values
332n/a for whence are ints:
333n/a
334n/a * 0 -- start of stream (the default); offset should be zero or positive
335n/a * 1 -- current stream position; offset may be negative
336n/a * 2 -- end of stream; offset is usually negative
337n/a Some operating systems / file systems could provide additional values.
338n/a
339n/a Return an int indicating the new absolute position.
340n/a """
341n/a self._unsupported("seek")
342n/a
343n/a def tell(self):
344n/a """Return an int indicating the current stream position."""
345n/a return self.seek(0, 1)
346n/a
347n/a def truncate(self, pos=None):
348n/a """Truncate file to size bytes.
349n/a
350n/a Size defaults to the current IO position as reported by tell(). Return
351n/a the new size.
352n/a """
353n/a self._unsupported("truncate")
354n/a
355n/a ### Flush and close ###
356n/a
357n/a def flush(self):
358n/a """Flush write buffers, if applicable.
359n/a
360n/a This is not implemented for read-only and non-blocking streams.
361n/a """
362n/a self._checkClosed()
363n/a # XXX Should this return the number of bytes written???
364n/a
365n/a __closed = False
366n/a
367n/a def close(self):
368n/a """Flush and close the IO object.
369n/a
370n/a This method has no effect if the file is already closed.
371n/a """
372n/a if not self.__closed:
373n/a try:
374n/a self.flush()
375n/a finally:
376n/a self.__closed = True
377n/a
378n/a def __del__(self):
379n/a """Destructor. Calls close()."""
380n/a # The try/except block is in case this is called at program
381n/a # exit time, when it's possible that globals have already been
382n/a # deleted, and then the close() call might fail. Since
383n/a # there's nothing we can do about such failures and they annoy
384n/a # the end users, we suppress the traceback.
385n/a try:
386n/a self.close()
387n/a except:
388n/a pass
389n/a
390n/a ### Inquiries ###
391n/a
392n/a def seekable(self):
393n/a """Return a bool indicating whether object supports random access.
394n/a
395n/a If False, seek(), tell() and truncate() will raise OSError.
396n/a This method may need to do a test seek().
397n/a """
398n/a return False
399n/a
400n/a def _checkSeekable(self, msg=None):
401n/a """Internal: raise UnsupportedOperation if file is not seekable
402n/a """
403n/a if not self.seekable():
404n/a raise UnsupportedOperation("File or stream is not seekable."
405n/a if msg is None else msg)
406n/a
407n/a def readable(self):
408n/a """Return a bool indicating whether object was opened for reading.
409n/a
410n/a If False, read() will raise OSError.
411n/a """
412n/a return False
413n/a
414n/a def _checkReadable(self, msg=None):
415n/a """Internal: raise UnsupportedOperation if file is not readable
416n/a """
417n/a if not self.readable():
418n/a raise UnsupportedOperation("File or stream is not readable."
419n/a if msg is None else msg)
420n/a
421n/a def writable(self):
422n/a """Return a bool indicating whether object was opened for writing.
423n/a
424n/a If False, write() and truncate() will raise OSError.
425n/a """
426n/a return False
427n/a
428n/a def _checkWritable(self, msg=None):
429n/a """Internal: raise UnsupportedOperation if file is not writable
430n/a """
431n/a if not self.writable():
432n/a raise UnsupportedOperation("File or stream is not writable."
433n/a if msg is None else msg)
434n/a
435n/a @property
436n/a def closed(self):
437n/a """closed: bool. True iff the file has been closed.
438n/a
439n/a For backwards compatibility, this is a property, not a predicate.
440n/a """
441n/a return self.__closed
442n/a
443n/a def _checkClosed(self, msg=None):
444n/a """Internal: raise a ValueError if file is closed
445n/a """
446n/a if self.closed:
447n/a raise ValueError("I/O operation on closed file."
448n/a if msg is None else msg)
449n/a
450n/a ### Context manager ###
451n/a
452n/a def __enter__(self): # That's a forward reference
453n/a """Context management protocol. Returns self (an instance of IOBase)."""
454n/a self._checkClosed()
455n/a return self
456n/a
457n/a def __exit__(self, *args):
458n/a """Context management protocol. Calls close()"""
459n/a self.close()
460n/a
461n/a ### Lower-level APIs ###
462n/a
463n/a # XXX Should these be present even if unimplemented?
464n/a
465n/a def fileno(self):
466n/a """Returns underlying file descriptor (an int) if one exists.
467n/a
468n/a An OSError is raised if the IO object does not use a file descriptor.
469n/a """
470n/a self._unsupported("fileno")
471n/a
472n/a def isatty(self):
473n/a """Return a bool indicating whether this is an 'interactive' stream.
474n/a
475n/a Return False if it can't be determined.
476n/a """
477n/a self._checkClosed()
478n/a return False
479n/a
480n/a ### Readline[s] and writelines ###
481n/a
482n/a def readline(self, size=-1):
483n/a r"""Read and return a line of bytes from the stream.
484n/a
485n/a If size is specified, at most size bytes will be read.
486n/a Size should be an int.
487n/a
488n/a The line terminator is always b'\n' for binary files; for text
489n/a files, the newlines argument to open can be used to select the line
490n/a terminator(s) recognized.
491n/a """
492n/a # For backwards compatibility, a (slowish) readline().
493n/a if hasattr(self, "peek"):
494n/a def nreadahead():
495n/a readahead = self.peek(1)
496n/a if not readahead:
497n/a return 1
498n/a n = (readahead.find(b"\n") + 1) or len(readahead)
499n/a if size >= 0:
500n/a n = min(n, size)
501n/a return n
502n/a else:
503n/a def nreadahead():
504n/a return 1
505n/a if size is None:
506n/a size = -1
507n/a elif not isinstance(size, int):
508n/a raise TypeError("size must be an integer")
509n/a res = bytearray()
510n/a while size < 0 or len(res) < size:
511n/a b = self.read(nreadahead())
512n/a if not b:
513n/a break
514n/a res += b
515n/a if res.endswith(b"\n"):
516n/a break
517n/a return bytes(res)
518n/a
519n/a def __iter__(self):
520n/a self._checkClosed()
521n/a return self
522n/a
523n/a def __next__(self):
524n/a line = self.readline()
525n/a if not line:
526n/a raise StopIteration
527n/a return line
528n/a
529n/a def readlines(self, hint=None):
530n/a """Return a list of lines from the stream.
531n/a
532n/a hint can be specified to control the number of lines read: no more
533n/a lines will be read if the total size (in bytes/characters) of all
534n/a lines so far exceeds hint.
535n/a """
536n/a if hint is None or hint <= 0:
537n/a return list(self)
538n/a n = 0
539n/a lines = []
540n/a for line in self:
541n/a lines.append(line)
542n/a n += len(line)
543n/a if n >= hint:
544n/a break
545n/a return lines
546n/a
547n/a def writelines(self, lines):
548n/a self._checkClosed()
549n/a for line in lines:
550n/a self.write(line)
551n/a
552n/aio.IOBase.register(IOBase)
553n/a
554n/a
555n/aclass RawIOBase(IOBase):
556n/a
557n/a """Base class for raw binary I/O."""
558n/a
559n/a # The read() method is implemented by calling readinto(); derived
560n/a # classes that want to support read() only need to implement
561n/a # readinto() as a primitive operation. In general, readinto() can be
562n/a # more efficient than read().
563n/a
564n/a # (It would be tempting to also provide an implementation of
565n/a # readinto() in terms of read(), in case the latter is a more suitable
566n/a # primitive operation, but that would lead to nasty recursion in case
567n/a # a subclass doesn't implement either.)
568n/a
569n/a def read(self, size=-1):
570n/a """Read and return up to size bytes, where size is an int.
571n/a
572n/a Returns an empty bytes object on EOF, or None if the object is
573n/a set not to block and has no data to read.
574n/a """
575n/a if size is None:
576n/a size = -1
577n/a if size < 0:
578n/a return self.readall()
579n/a b = bytearray(size.__index__())
580n/a n = self.readinto(b)
581n/a if n is None:
582n/a return None
583n/a del b[n:]
584n/a return bytes(b)
585n/a
586n/a def readall(self):
587n/a """Read until EOF, using multiple read() call."""
588n/a res = bytearray()
589n/a while True:
590n/a data = self.read(DEFAULT_BUFFER_SIZE)
591n/a if not data:
592n/a break
593n/a res += data
594n/a if res:
595n/a return bytes(res)
596n/a else:
597n/a # b'' or None
598n/a return data
599n/a
600n/a def readinto(self, b):
601n/a """Read bytes into a pre-allocated bytes-like object b.
602n/a
603n/a Returns an int representing the number of bytes read (0 for EOF), or
604n/a None if the object is set not to block and has no data to read.
605n/a """
606n/a self._unsupported("readinto")
607n/a
608n/a def write(self, b):
609n/a """Write the given buffer to the IO stream.
610n/a
611n/a Returns the number of bytes written, which may be less than the
612n/a length of b in bytes.
613n/a """
614n/a self._unsupported("write")
615n/a
616n/aio.RawIOBase.register(RawIOBase)
617n/afrom _io import FileIO
618n/aRawIOBase.register(FileIO)
619n/a
620n/a
621n/aclass BufferedIOBase(IOBase):
622n/a
623n/a """Base class for buffered IO objects.
624n/a
625n/a The main difference with RawIOBase is that the read() method
626n/a supports omitting the size argument, and does not have a default
627n/a implementation that defers to readinto().
628n/a
629n/a In addition, read(), readinto() and write() may raise
630n/a BlockingIOError if the underlying raw stream is in non-blocking
631n/a mode and not ready; unlike their raw counterparts, they will never
632n/a return None.
633n/a
634n/a A typical implementation should not inherit from a RawIOBase
635n/a implementation, but wrap one.
636n/a """
637n/a
638n/a def read(self, size=-1):
639n/a """Read and return up to size bytes, where size is an int.
640n/a
641n/a If the argument is omitted, None, or negative, reads and
642n/a returns all data until EOF.
643n/a
644n/a If the argument is positive, and the underlying raw stream is
645n/a not 'interactive', multiple raw reads may be issued to satisfy
646n/a the byte count (unless EOF is reached first). But for
647n/a interactive raw streams (XXX and for pipes?), at most one raw
648n/a read will be issued, and a short result does not imply that
649n/a EOF is imminent.
650n/a
651n/a Returns an empty bytes array on EOF.
652n/a
653n/a Raises BlockingIOError if the underlying raw stream has no
654n/a data at the moment.
655n/a """
656n/a self._unsupported("read")
657n/a
658n/a def read1(self, size=-1):
659n/a """Read up to size bytes with at most one read() system call,
660n/a where size is an int.
661n/a """
662n/a self._unsupported("read1")
663n/a
664n/a def readinto(self, b):
665n/a """Read bytes into a pre-allocated bytes-like object b.
666n/a
667n/a Like read(), this may issue multiple reads to the underlying raw
668n/a stream, unless the latter is 'interactive'.
669n/a
670n/a Returns an int representing the number of bytes read (0 for EOF).
671n/a
672n/a Raises BlockingIOError if the underlying raw stream has no
673n/a data at the moment.
674n/a """
675n/a
676n/a return self._readinto(b, read1=False)
677n/a
678n/a def readinto1(self, b):
679n/a """Read bytes into buffer *b*, using at most one system call
680n/a
681n/a Returns an int representing the number of bytes read (0 for EOF).
682n/a
683n/a Raises BlockingIOError if the underlying raw stream has no
684n/a data at the moment.
685n/a """
686n/a
687n/a return self._readinto(b, read1=True)
688n/a
689n/a def _readinto(self, b, read1):
690n/a if not isinstance(b, memoryview):
691n/a b = memoryview(b)
692n/a b = b.cast('B')
693n/a
694n/a if read1:
695n/a data = self.read1(len(b))
696n/a else:
697n/a data = self.read(len(b))
698n/a n = len(data)
699n/a
700n/a b[:n] = data
701n/a
702n/a return n
703n/a
704n/a def write(self, b):
705n/a """Write the given bytes buffer to the IO stream.
706n/a
707n/a Return the number of bytes written, which is always the length of b
708n/a in bytes.
709n/a
710n/a Raises BlockingIOError if the buffer is full and the
711n/a underlying raw stream cannot accept more data at the moment.
712n/a """
713n/a self._unsupported("write")
714n/a
715n/a def detach(self):
716n/a """
717n/a Separate the underlying raw stream from the buffer and return it.
718n/a
719n/a After the raw stream has been detached, the buffer is in an unusable
720n/a state.
721n/a """
722n/a self._unsupported("detach")
723n/a
724n/aio.BufferedIOBase.register(BufferedIOBase)
725n/a
726n/a
727n/aclass _BufferedIOMixin(BufferedIOBase):
728n/a
729n/a """A mixin implementation of BufferedIOBase with an underlying raw stream.
730n/a
731n/a This passes most requests on to the underlying raw stream. It
732n/a does *not* provide implementations of read(), readinto() or
733n/a write().
734n/a """
735n/a
736n/a def __init__(self, raw):
737n/a self._raw = raw
738n/a
739n/a ### Positioning ###
740n/a
741n/a def seek(self, pos, whence=0):
742n/a new_position = self.raw.seek(pos, whence)
743n/a if new_position < 0:
744n/a raise OSError("seek() returned an invalid position")
745n/a return new_position
746n/a
747n/a def tell(self):
748n/a pos = self.raw.tell()
749n/a if pos < 0:
750n/a raise OSError("tell() returned an invalid position")
751n/a return pos
752n/a
753n/a def truncate(self, pos=None):
754n/a # Flush the stream. We're mixing buffered I/O with lower-level I/O,
755n/a # and a flush may be necessary to synch both views of the current
756n/a # file state.
757n/a self.flush()
758n/a
759n/a if pos is None:
760n/a pos = self.tell()
761n/a # XXX: Should seek() be used, instead of passing the position
762n/a # XXX directly to truncate?
763n/a return self.raw.truncate(pos)
764n/a
765n/a ### Flush and close ###
766n/a
767n/a def flush(self):
768n/a if self.closed:
769n/a raise ValueError("flush of closed file")
770n/a self.raw.flush()
771n/a
772n/a def close(self):
773n/a if self.raw is not None and not self.closed:
774n/a try:
775n/a # may raise BlockingIOError or BrokenPipeError etc
776n/a self.flush()
777n/a finally:
778n/a self.raw.close()
779n/a
780n/a def detach(self):
781n/a if self.raw is None:
782n/a raise ValueError("raw stream already detached")
783n/a self.flush()
784n/a raw = self._raw
785n/a self._raw = None
786n/a return raw
787n/a
788n/a ### Inquiries ###
789n/a
790n/a def seekable(self):
791n/a return self.raw.seekable()
792n/a
793n/a @property
794n/a def raw(self):
795n/a return self._raw
796n/a
797n/a @property
798n/a def closed(self):
799n/a return self.raw.closed
800n/a
801n/a @property
802n/a def name(self):
803n/a return self.raw.name
804n/a
805n/a @property
806n/a def mode(self):
807n/a return self.raw.mode
808n/a
809n/a def __getstate__(self):
810n/a raise TypeError("can not serialize a '{0}' object"
811n/a .format(self.__class__.__name__))
812n/a
813n/a def __repr__(self):
814n/a modname = self.__class__.__module__
815n/a clsname = self.__class__.__qualname__
816n/a try:
817n/a name = self.name
818n/a except Exception:
819n/a return "<{}.{}>".format(modname, clsname)
820n/a else:
821n/a return "<{}.{} name={!r}>".format(modname, clsname, name)
822n/a
823n/a ### Lower-level APIs ###
824n/a
825n/a def fileno(self):
826n/a return self.raw.fileno()
827n/a
828n/a def isatty(self):
829n/a return self.raw.isatty()
830n/a
831n/a
832n/aclass BytesIO(BufferedIOBase):
833n/a
834n/a """Buffered I/O implementation using an in-memory bytes buffer."""
835n/a
836n/a def __init__(self, initial_bytes=None):
837n/a buf = bytearray()
838n/a if initial_bytes is not None:
839n/a buf += initial_bytes
840n/a self._buffer = buf
841n/a self._pos = 0
842n/a
843n/a def __getstate__(self):
844n/a if self.closed:
845n/a raise ValueError("__getstate__ on closed file")
846n/a return self.__dict__.copy()
847n/a
848n/a def getvalue(self):
849n/a """Return the bytes value (contents) of the buffer
850n/a """
851n/a if self.closed:
852n/a raise ValueError("getvalue on closed file")
853n/a return bytes(self._buffer)
854n/a
855n/a def getbuffer(self):
856n/a """Return a readable and writable view of the buffer.
857n/a """
858n/a if self.closed:
859n/a raise ValueError("getbuffer on closed file")
860n/a return memoryview(self._buffer)
861n/a
862n/a def close(self):
863n/a self._buffer.clear()
864n/a super().close()
865n/a
866n/a def read(self, size=-1):
867n/a if self.closed:
868n/a raise ValueError("read from closed file")
869n/a if size is None:
870n/a size = -1
871n/a if size < 0:
872n/a size = len(self._buffer)
873n/a if len(self._buffer) <= self._pos:
874n/a return b""
875n/a newpos = min(len(self._buffer), self._pos + size)
876n/a b = self._buffer[self._pos : newpos]
877n/a self._pos = newpos
878n/a return bytes(b)
879n/a
880n/a def read1(self, size=-1):
881n/a """This is the same as read.
882n/a """
883n/a return self.read(size)
884n/a
885n/a def write(self, b):
886n/a if self.closed:
887n/a raise ValueError("write to closed file")
888n/a if isinstance(b, str):
889n/a raise TypeError("can't write str to binary stream")
890n/a with memoryview(b) as view:
891n/a n = view.nbytes # Size of any bytes-like object
892n/a if n == 0:
893n/a return 0
894n/a pos = self._pos
895n/a if pos > len(self._buffer):
896n/a # Inserts null bytes between the current end of the file
897n/a # and the new write position.
898n/a padding = b'\x00' * (pos - len(self._buffer))
899n/a self._buffer += padding
900n/a self._buffer[pos:pos + n] = b
901n/a self._pos += n
902n/a return n
903n/a
904n/a def seek(self, pos, whence=0):
905n/a if self.closed:
906n/a raise ValueError("seek on closed file")
907n/a try:
908n/a pos.__index__
909n/a except AttributeError as err:
910n/a raise TypeError("an integer is required") from err
911n/a if whence == 0:
912n/a if pos < 0:
913n/a raise ValueError("negative seek position %r" % (pos,))
914n/a self._pos = pos
915n/a elif whence == 1:
916n/a self._pos = max(0, self._pos + pos)
917n/a elif whence == 2:
918n/a self._pos = max(0, len(self._buffer) + pos)
919n/a else:
920n/a raise ValueError("unsupported whence value")
921n/a return self._pos
922n/a
923n/a def tell(self):
924n/a if self.closed:
925n/a raise ValueError("tell on closed file")
926n/a return self._pos
927n/a
928n/a def truncate(self, pos=None):
929n/a if self.closed:
930n/a raise ValueError("truncate on closed file")
931n/a if pos is None:
932n/a pos = self._pos
933n/a else:
934n/a try:
935n/a pos.__index__
936n/a except AttributeError as err:
937n/a raise TypeError("an integer is required") from err
938n/a if pos < 0:
939n/a raise ValueError("negative truncate position %r" % (pos,))
940n/a del self._buffer[pos:]
941n/a return pos
942n/a
943n/a def readable(self):
944n/a if self.closed:
945n/a raise ValueError("I/O operation on closed file.")
946n/a return True
947n/a
948n/a def writable(self):
949n/a if self.closed:
950n/a raise ValueError("I/O operation on closed file.")
951n/a return True
952n/a
953n/a def seekable(self):
954n/a if self.closed:
955n/a raise ValueError("I/O operation on closed file.")
956n/a return True
957n/a
958n/a
959n/aclass BufferedReader(_BufferedIOMixin):
960n/a
961n/a """BufferedReader(raw[, buffer_size])
962n/a
963n/a A buffer for a readable, sequential BaseRawIO object.
964n/a
965n/a The constructor creates a BufferedReader for the given readable raw
966n/a stream and buffer_size. If buffer_size is omitted, DEFAULT_BUFFER_SIZE
967n/a is used.
968n/a """
969n/a
970n/a def __init__(self, raw, buffer_size=DEFAULT_BUFFER_SIZE):
971n/a """Create a new buffered reader using the given readable raw IO object.
972n/a """
973n/a if not raw.readable():
974n/a raise OSError('"raw" argument must be readable.')
975n/a
976n/a _BufferedIOMixin.__init__(self, raw)
977n/a if buffer_size <= 0:
978n/a raise ValueError("invalid buffer size")
979n/a self.buffer_size = buffer_size
980n/a self._reset_read_buf()
981n/a self._read_lock = Lock()
982n/a
983n/a def readable(self):
984n/a return self.raw.readable()
985n/a
986n/a def _reset_read_buf(self):
987n/a self._read_buf = b""
988n/a self._read_pos = 0
989n/a
990n/a def read(self, size=None):
991n/a """Read size bytes.
992n/a
993n/a Returns exactly size bytes of data unless the underlying raw IO
994n/a stream reaches EOF or if the call would block in non-blocking
995n/a mode. If size is negative, read until EOF or until read() would
996n/a block.
997n/a """
998n/a if size is not None and size < -1:
999n/a raise ValueError("invalid number of bytes to read")
1000n/a with self._read_lock:
1001n/a return self._read_unlocked(size)
1002n/a
1003n/a def _read_unlocked(self, n=None):
1004n/a nodata_val = b""
1005n/a empty_values = (b"", None)
1006n/a buf = self._read_buf
1007n/a pos = self._read_pos
1008n/a
1009n/a # Special case for when the number of bytes to read is unspecified.
1010n/a if n is None or n == -1:
1011n/a self._reset_read_buf()
1012n/a if hasattr(self.raw, 'readall'):
1013n/a chunk = self.raw.readall()
1014n/a if chunk is None:
1015n/a return buf[pos:] or None
1016n/a else:
1017n/a return buf[pos:] + chunk
1018n/a chunks = [buf[pos:]] # Strip the consumed bytes.
1019n/a current_size = 0
1020n/a while True:
1021n/a # Read until EOF or until read() would block.
1022n/a chunk = self.raw.read()
1023n/a if chunk in empty_values:
1024n/a nodata_val = chunk
1025n/a break
1026n/a current_size += len(chunk)
1027n/a chunks.append(chunk)
1028n/a return b"".join(chunks) or nodata_val
1029n/a
1030n/a # The number of bytes to read is specified, return at most n bytes.
1031n/a avail = len(buf) - pos # Length of the available buffered data.
1032n/a if n <= avail:
1033n/a # Fast path: the data to read is fully buffered.
1034n/a self._read_pos += n
1035n/a return buf[pos:pos+n]
1036n/a # Slow path: read from the stream until enough bytes are read,
1037n/a # or until an EOF occurs or until read() would block.
1038n/a chunks = [buf[pos:]]
1039n/a wanted = max(self.buffer_size, n)
1040n/a while avail < n:
1041n/a chunk = self.raw.read(wanted)
1042n/a if chunk in empty_values:
1043n/a nodata_val = chunk
1044n/a break
1045n/a avail += len(chunk)
1046n/a chunks.append(chunk)
1047n/a # n is more than avail only when an EOF occurred or when
1048n/a # read() would have blocked.
1049n/a n = min(n, avail)
1050n/a out = b"".join(chunks)
1051n/a self._read_buf = out[n:] # Save the extra data in the buffer.
1052n/a self._read_pos = 0
1053n/a return out[:n] if out else nodata_val
1054n/a
1055n/a def peek(self, size=0):
1056n/a """Returns buffered bytes without advancing the position.
1057n/a
1058n/a The argument indicates a desired minimal number of bytes; we
1059n/a do at most one raw read to satisfy it. We never return more
1060n/a than self.buffer_size.
1061n/a """
1062n/a with self._read_lock:
1063n/a return self._peek_unlocked(size)
1064n/a
1065n/a def _peek_unlocked(self, n=0):
1066n/a want = min(n, self.buffer_size)
1067n/a have = len(self._read_buf) - self._read_pos
1068n/a if have < want or have <= 0:
1069n/a to_read = self.buffer_size - have
1070n/a current = self.raw.read(to_read)
1071n/a if current:
1072n/a self._read_buf = self._read_buf[self._read_pos:] + current
1073n/a self._read_pos = 0
1074n/a return self._read_buf[self._read_pos:]
1075n/a
1076n/a def read1(self, size=-1):
1077n/a """Reads up to size bytes, with at most one read() system call."""
1078n/a # Returns up to size bytes. If at least one byte is buffered, we
1079n/a # only return buffered bytes. Otherwise, we do one raw read.
1080n/a if size < 0:
1081n/a size = self.buffer_size
1082n/a if size == 0:
1083n/a return b""
1084n/a with self._read_lock:
1085n/a self._peek_unlocked(1)
1086n/a return self._read_unlocked(
1087n/a min(size, len(self._read_buf) - self._read_pos))
1088n/a
1089n/a # Implementing readinto() and readinto1() is not strictly necessary (we
1090n/a # could rely on the base class that provides an implementation in terms of
1091n/a # read() and read1()). We do it anyway to keep the _pyio implementation
1092n/a # similar to the io implementation (which implements the methods for
1093n/a # performance reasons).
1094n/a def _readinto(self, buf, read1):
1095n/a """Read data into *buf* with at most one system call."""
1096n/a
1097n/a # Need to create a memoryview object of type 'b', otherwise
1098n/a # we may not be able to assign bytes to it, and slicing it
1099n/a # would create a new object.
1100n/a if not isinstance(buf, memoryview):
1101n/a buf = memoryview(buf)
1102n/a if buf.nbytes == 0:
1103n/a return 0
1104n/a buf = buf.cast('B')
1105n/a
1106n/a written = 0
1107n/a with self._read_lock:
1108n/a while written < len(buf):
1109n/a
1110n/a # First try to read from internal buffer
1111n/a avail = min(len(self._read_buf) - self._read_pos, len(buf))
1112n/a if avail:
1113n/a buf[written:written+avail] = \
1114n/a self._read_buf[self._read_pos:self._read_pos+avail]
1115n/a self._read_pos += avail
1116n/a written += avail
1117n/a if written == len(buf):
1118n/a break
1119n/a
1120n/a # If remaining space in callers buffer is larger than
1121n/a # internal buffer, read directly into callers buffer
1122n/a if len(buf) - written > self.buffer_size:
1123n/a n = self.raw.readinto(buf[written:])
1124n/a if not n:
1125n/a break # eof
1126n/a written += n
1127n/a
1128n/a # Otherwise refill internal buffer - unless we're
1129n/a # in read1 mode and already got some data
1130n/a elif not (read1 and written):
1131n/a if not self._peek_unlocked(1):
1132n/a break # eof
1133n/a
1134n/a # In readinto1 mode, return as soon as we have some data
1135n/a if read1 and written:
1136n/a break
1137n/a
1138n/a return written
1139n/a
1140n/a def tell(self):
1141n/a return _BufferedIOMixin.tell(self) - len(self._read_buf) + self._read_pos
1142n/a
1143n/a def seek(self, pos, whence=0):
1144n/a if whence not in valid_seek_flags:
1145n/a raise ValueError("invalid whence value")
1146n/a with self._read_lock:
1147n/a if whence == 1:
1148n/a pos -= len(self._read_buf) - self._read_pos
1149n/a pos = _BufferedIOMixin.seek(self, pos, whence)
1150n/a self._reset_read_buf()
1151n/a return pos
1152n/a
1153n/aclass BufferedWriter(_BufferedIOMixin):
1154n/a
1155n/a """A buffer for a writeable sequential RawIO object.
1156n/a
1157n/a The constructor creates a BufferedWriter for the given writeable raw
1158n/a stream. If the buffer_size is not given, it defaults to
1159n/a DEFAULT_BUFFER_SIZE.
1160n/a """
1161n/a
1162n/a def __init__(self, raw, buffer_size=DEFAULT_BUFFER_SIZE):
1163n/a if not raw.writable():
1164n/a raise OSError('"raw" argument must be writable.')
1165n/a
1166n/a _BufferedIOMixin.__init__(self, raw)
1167n/a if buffer_size <= 0:
1168n/a raise ValueError("invalid buffer size")
1169n/a self.buffer_size = buffer_size
1170n/a self._write_buf = bytearray()
1171n/a self._write_lock = Lock()
1172n/a
1173n/a def writable(self):
1174n/a return self.raw.writable()
1175n/a
1176n/a def write(self, b):
1177n/a if self.closed:
1178n/a raise ValueError("write to closed file")
1179n/a if isinstance(b, str):
1180n/a raise TypeError("can't write str to binary stream")
1181n/a with self._write_lock:
1182n/a # XXX we can implement some more tricks to try and avoid
1183n/a # partial writes
1184n/a if len(self._write_buf) > self.buffer_size:
1185n/a # We're full, so let's pre-flush the buffer. (This may
1186n/a # raise BlockingIOError with characters_written == 0.)
1187n/a self._flush_unlocked()
1188n/a before = len(self._write_buf)
1189n/a self._write_buf.extend(b)
1190n/a written = len(self._write_buf) - before
1191n/a if len(self._write_buf) > self.buffer_size:
1192n/a try:
1193n/a self._flush_unlocked()
1194n/a except BlockingIOError as e:
1195n/a if len(self._write_buf) > self.buffer_size:
1196n/a # We've hit the buffer_size. We have to accept a partial
1197n/a # write and cut back our buffer.
1198n/a overage = len(self._write_buf) - self.buffer_size
1199n/a written -= overage
1200n/a self._write_buf = self._write_buf[:self.buffer_size]
1201n/a raise BlockingIOError(e.errno, e.strerror, written)
1202n/a return written
1203n/a
1204n/a def truncate(self, pos=None):
1205n/a with self._write_lock:
1206n/a self._flush_unlocked()
1207n/a if pos is None:
1208n/a pos = self.raw.tell()
1209n/a return self.raw.truncate(pos)
1210n/a
1211n/a def flush(self):
1212n/a with self._write_lock:
1213n/a self._flush_unlocked()
1214n/a
1215n/a def _flush_unlocked(self):
1216n/a if self.closed:
1217n/a raise ValueError("flush of closed file")
1218n/a while self._write_buf:
1219n/a try:
1220n/a n = self.raw.write(self._write_buf)
1221n/a except BlockingIOError:
1222n/a raise RuntimeError("self.raw should implement RawIOBase: it "
1223n/a "should not raise BlockingIOError")
1224n/a if n is None:
1225n/a raise BlockingIOError(
1226n/a errno.EAGAIN,
1227n/a "write could not complete without blocking", 0)
1228n/a if n > len(self._write_buf) or n < 0:
1229n/a raise OSError("write() returned incorrect number of bytes")
1230n/a del self._write_buf[:n]
1231n/a
1232n/a def tell(self):
1233n/a return _BufferedIOMixin.tell(self) + len(self._write_buf)
1234n/a
1235n/a def seek(self, pos, whence=0):
1236n/a if whence not in valid_seek_flags:
1237n/a raise ValueError("invalid whence value")
1238n/a with self._write_lock:
1239n/a self._flush_unlocked()
1240n/a return _BufferedIOMixin.seek(self, pos, whence)
1241n/a
1242n/a
1243n/aclass BufferedRWPair(BufferedIOBase):
1244n/a
1245n/a """A buffered reader and writer object together.
1246n/a
1247n/a A buffered reader object and buffered writer object put together to
1248n/a form a sequential IO object that can read and write. This is typically
1249n/a used with a socket or two-way pipe.
1250n/a
1251n/a reader and writer are RawIOBase objects that are readable and
1252n/a writeable respectively. If the buffer_size is omitted it defaults to
1253n/a DEFAULT_BUFFER_SIZE.
1254n/a """
1255n/a
1256n/a # XXX The usefulness of this (compared to having two separate IO
1257n/a # objects) is questionable.
1258n/a
1259n/a def __init__(self, reader, writer, buffer_size=DEFAULT_BUFFER_SIZE):
1260n/a """Constructor.
1261n/a
1262n/a The arguments are two RawIO instances.
1263n/a """
1264n/a if not reader.readable():
1265n/a raise OSError('"reader" argument must be readable.')
1266n/a
1267n/a if not writer.writable():
1268n/a raise OSError('"writer" argument must be writable.')
1269n/a
1270n/a self.reader = BufferedReader(reader, buffer_size)
1271n/a self.writer = BufferedWriter(writer, buffer_size)
1272n/a
1273n/a def read(self, size=-1):
1274n/a if size is None:
1275n/a size = -1
1276n/a return self.reader.read(size)
1277n/a
1278n/a def readinto(self, b):
1279n/a return self.reader.readinto(b)
1280n/a
1281n/a def write(self, b):
1282n/a return self.writer.write(b)
1283n/a
1284n/a def peek(self, size=0):
1285n/a return self.reader.peek(size)
1286n/a
1287n/a def read1(self, size=-1):
1288n/a return self.reader.read1(size)
1289n/a
1290n/a def readinto1(self, b):
1291n/a return self.reader.readinto1(b)
1292n/a
1293n/a def readable(self):
1294n/a return self.reader.readable()
1295n/a
1296n/a def writable(self):
1297n/a return self.writer.writable()
1298n/a
1299n/a def flush(self):
1300n/a return self.writer.flush()
1301n/a
1302n/a def close(self):
1303n/a try:
1304n/a self.writer.close()
1305n/a finally:
1306n/a self.reader.close()
1307n/a
1308n/a def isatty(self):
1309n/a return self.reader.isatty() or self.writer.isatty()
1310n/a
1311n/a @property
1312n/a def closed(self):
1313n/a return self.writer.closed
1314n/a
1315n/a
1316n/aclass BufferedRandom(BufferedWriter, BufferedReader):
1317n/a
1318n/a """A buffered interface to random access streams.
1319n/a
1320n/a The constructor creates a reader and writer for a seekable stream,
1321n/a raw, given in the first argument. If the buffer_size is omitted it
1322n/a defaults to DEFAULT_BUFFER_SIZE.
1323n/a """
1324n/a
1325n/a def __init__(self, raw, buffer_size=DEFAULT_BUFFER_SIZE):
1326n/a raw._checkSeekable()
1327n/a BufferedReader.__init__(self, raw, buffer_size)
1328n/a BufferedWriter.__init__(self, raw, buffer_size)
1329n/a
1330n/a def seek(self, pos, whence=0):
1331n/a if whence not in valid_seek_flags:
1332n/a raise ValueError("invalid whence value")
1333n/a self.flush()
1334n/a if self._read_buf:
1335n/a # Undo read ahead.
1336n/a with self._read_lock:
1337n/a self.raw.seek(self._read_pos - len(self._read_buf), 1)
1338n/a # First do the raw seek, then empty the read buffer, so that
1339n/a # if the raw seek fails, we don't lose buffered data forever.
1340n/a pos = self.raw.seek(pos, whence)
1341n/a with self._read_lock:
1342n/a self._reset_read_buf()
1343n/a if pos < 0:
1344n/a raise OSError("seek() returned invalid position")
1345n/a return pos
1346n/a
1347n/a def tell(self):
1348n/a if self._write_buf:
1349n/a return BufferedWriter.tell(self)
1350n/a else:
1351n/a return BufferedReader.tell(self)
1352n/a
1353n/a def truncate(self, pos=None):
1354n/a if pos is None:
1355n/a pos = self.tell()
1356n/a # Use seek to flush the read buffer.
1357n/a return BufferedWriter.truncate(self, pos)
1358n/a
1359n/a def read(self, size=None):
1360n/a if size is None:
1361n/a size = -1
1362n/a self.flush()
1363n/a return BufferedReader.read(self, size)
1364n/a
1365n/a def readinto(self, b):
1366n/a self.flush()
1367n/a return BufferedReader.readinto(self, b)
1368n/a
1369n/a def peek(self, size=0):
1370n/a self.flush()
1371n/a return BufferedReader.peek(self, size)
1372n/a
1373n/a def read1(self, size=-1):
1374n/a self.flush()
1375n/a return BufferedReader.read1(self, size)
1376n/a
1377n/a def readinto1(self, b):
1378n/a self.flush()
1379n/a return BufferedReader.readinto1(self, b)
1380n/a
1381n/a def write(self, b):
1382n/a if self._read_buf:
1383n/a # Undo readahead
1384n/a with self._read_lock:
1385n/a self.raw.seek(self._read_pos - len(self._read_buf), 1)
1386n/a self._reset_read_buf()
1387n/a return BufferedWriter.write(self, b)
1388n/a
1389n/a
1390n/aclass FileIO(RawIOBase):
1391n/a _fd = -1
1392n/a _created = False
1393n/a _readable = False
1394n/a _writable = False
1395n/a _appending = False
1396n/a _seekable = None
1397n/a _closefd = True
1398n/a
1399n/a def __init__(self, file, mode='r', closefd=True, opener=None):
1400n/a """Open a file. The mode can be 'r' (default), 'w', 'x' or 'a' for reading,
1401n/a writing, exclusive creation or appending. The file will be created if it
1402n/a doesn't exist when opened for writing or appending; it will be truncated
1403n/a when opened for writing. A FileExistsError will be raised if it already
1404n/a exists when opened for creating. Opening a file for creating implies
1405n/a writing so this mode behaves in a similar way to 'w'. Add a '+' to the mode
1406n/a to allow simultaneous reading and writing. A custom opener can be used by
1407n/a passing a callable as *opener*. The underlying file descriptor for the file
1408n/a object is then obtained by calling opener with (*name*, *flags*).
1409n/a *opener* must return an open file descriptor (passing os.open as *opener*
1410n/a results in functionality similar to passing None).
1411n/a """
1412n/a if self._fd >= 0:
1413n/a # Have to close the existing file first.
1414n/a try:
1415n/a if self._closefd:
1416n/a os.close(self._fd)
1417n/a finally:
1418n/a self._fd = -1
1419n/a
1420n/a if isinstance(file, float):
1421n/a raise TypeError('integer argument expected, got float')
1422n/a if isinstance(file, int):
1423n/a fd = file
1424n/a if fd < 0:
1425n/a raise ValueError('negative file descriptor')
1426n/a else:
1427n/a fd = -1
1428n/a
1429n/a if not isinstance(mode, str):
1430n/a raise TypeError('invalid mode: %s' % (mode,))
1431n/a if not set(mode) <= set('xrwab+'):
1432n/a raise ValueError('invalid mode: %s' % (mode,))
1433n/a if sum(c in 'rwax' for c in mode) != 1 or mode.count('+') > 1:
1434n/a raise ValueError('Must have exactly one of create/read/write/append '
1435n/a 'mode and at most one plus')
1436n/a
1437n/a if 'x' in mode:
1438n/a self._created = True
1439n/a self._writable = True
1440n/a flags = os.O_EXCL | os.O_CREAT
1441n/a elif 'r' in mode:
1442n/a self._readable = True
1443n/a flags = 0
1444n/a elif 'w' in mode:
1445n/a self._writable = True
1446n/a flags = os.O_CREAT | os.O_TRUNC
1447n/a elif 'a' in mode:
1448n/a self._writable = True
1449n/a self._appending = True
1450n/a flags = os.O_APPEND | os.O_CREAT
1451n/a
1452n/a if '+' in mode:
1453n/a self._readable = True
1454n/a self._writable = True
1455n/a
1456n/a if self._readable and self._writable:
1457n/a flags |= os.O_RDWR
1458n/a elif self._readable:
1459n/a flags |= os.O_RDONLY
1460n/a else:
1461n/a flags |= os.O_WRONLY
1462n/a
1463n/a flags |= getattr(os, 'O_BINARY', 0)
1464n/a
1465n/a noinherit_flag = (getattr(os, 'O_NOINHERIT', 0) or
1466n/a getattr(os, 'O_CLOEXEC', 0))
1467n/a flags |= noinherit_flag
1468n/a
1469n/a owned_fd = None
1470n/a try:
1471n/a if fd < 0:
1472n/a if not closefd:
1473n/a raise ValueError('Cannot use closefd=False with file name')
1474n/a if opener is None:
1475n/a fd = os.open(file, flags, 0o666)
1476n/a else:
1477n/a fd = opener(file, flags)
1478n/a if not isinstance(fd, int):
1479n/a raise TypeError('expected integer from opener')
1480n/a if fd < 0:
1481n/a raise OSError('Negative file descriptor')
1482n/a owned_fd = fd
1483n/a if not noinherit_flag:
1484n/a os.set_inheritable(fd, False)
1485n/a
1486n/a self._closefd = closefd
1487n/a fdfstat = os.fstat(fd)
1488n/a try:
1489n/a if stat.S_ISDIR(fdfstat.st_mode):
1490n/a raise IsADirectoryError(errno.EISDIR,
1491n/a os.strerror(errno.EISDIR), file)
1492n/a except AttributeError:
1493n/a # Ignore the AttribueError if stat.S_ISDIR or errno.EISDIR
1494n/a # don't exist.
1495n/a pass
1496n/a self._blksize = getattr(fdfstat, 'st_blksize', 0)
1497n/a if self._blksize <= 1:
1498n/a self._blksize = DEFAULT_BUFFER_SIZE
1499n/a
1500n/a if _setmode:
1501n/a # don't translate newlines (\r\n <=> \n)
1502n/a _setmode(fd, os.O_BINARY)
1503n/a
1504n/a self.name = file
1505n/a if self._appending:
1506n/a # For consistent behaviour, we explicitly seek to the
1507n/a # end of file (otherwise, it might be done only on the
1508n/a # first write()).
1509n/a os.lseek(fd, 0, SEEK_END)
1510n/a except:
1511n/a if owned_fd is not None:
1512n/a os.close(owned_fd)
1513n/a raise
1514n/a self._fd = fd
1515n/a
1516n/a def __del__(self):
1517n/a if self._fd >= 0 and self._closefd and not self.closed:
1518n/a import warnings
1519n/a warnings.warn('unclosed file %r' % (self,), ResourceWarning,
1520n/a stacklevel=2, source=self)
1521n/a self.close()
1522n/a
1523n/a def __getstate__(self):
1524n/a raise TypeError("cannot serialize '%s' object", self.__class__.__name__)
1525n/a
1526n/a def __repr__(self):
1527n/a class_name = '%s.%s' % (self.__class__.__module__,
1528n/a self.__class__.__qualname__)
1529n/a if self.closed:
1530n/a return '<%s [closed]>' % class_name
1531n/a try:
1532n/a name = self.name
1533n/a except AttributeError:
1534n/a return ('<%s fd=%d mode=%r closefd=%r>' %
1535n/a (class_name, self._fd, self.mode, self._closefd))
1536n/a else:
1537n/a return ('<%s name=%r mode=%r closefd=%r>' %
1538n/a (class_name, name, self.mode, self._closefd))
1539n/a
1540n/a def _checkReadable(self):
1541n/a if not self._readable:
1542n/a raise UnsupportedOperation('File not open for reading')
1543n/a
1544n/a def _checkWritable(self, msg=None):
1545n/a if not self._writable:
1546n/a raise UnsupportedOperation('File not open for writing')
1547n/a
1548n/a def read(self, size=None):
1549n/a """Read at most size bytes, returned as bytes.
1550n/a
1551n/a Only makes one system call, so less data may be returned than requested
1552n/a In non-blocking mode, returns None if no data is available.
1553n/a Return an empty bytes object at EOF.
1554n/a """
1555n/a self._checkClosed()
1556n/a self._checkReadable()
1557n/a if size is None or size < 0:
1558n/a return self.readall()
1559n/a try:
1560n/a return os.read(self._fd, size)
1561n/a except BlockingIOError:
1562n/a return None
1563n/a
1564n/a def readall(self):
1565n/a """Read all data from the file, returned as bytes.
1566n/a
1567n/a In non-blocking mode, returns as much as is immediately available,
1568n/a or None if no data is available. Return an empty bytes object at EOF.
1569n/a """
1570n/a self._checkClosed()
1571n/a self._checkReadable()
1572n/a bufsize = DEFAULT_BUFFER_SIZE
1573n/a try:
1574n/a pos = os.lseek(self._fd, 0, SEEK_CUR)
1575n/a end = os.fstat(self._fd).st_size
1576n/a if end >= pos:
1577n/a bufsize = end - pos + 1
1578n/a except OSError:
1579n/a pass
1580n/a
1581n/a result = bytearray()
1582n/a while True:
1583n/a if len(result) >= bufsize:
1584n/a bufsize = len(result)
1585n/a bufsize += max(bufsize, DEFAULT_BUFFER_SIZE)
1586n/a n = bufsize - len(result)
1587n/a try:
1588n/a chunk = os.read(self._fd, n)
1589n/a except BlockingIOError:
1590n/a if result:
1591n/a break
1592n/a return None
1593n/a if not chunk: # reached the end of the file
1594n/a break
1595n/a result += chunk
1596n/a
1597n/a return bytes(result)
1598n/a
1599n/a def readinto(self, b):
1600n/a """Same as RawIOBase.readinto()."""
1601n/a m = memoryview(b).cast('B')
1602n/a data = self.read(len(m))
1603n/a n = len(data)
1604n/a m[:n] = data
1605n/a return n
1606n/a
1607n/a def write(self, b):
1608n/a """Write bytes b to file, return number written.
1609n/a
1610n/a Only makes one system call, so not all of the data may be written.
1611n/a The number of bytes actually written is returned. In non-blocking mode,
1612n/a returns None if the write would block.
1613n/a """
1614n/a self._checkClosed()
1615n/a self._checkWritable()
1616n/a try:
1617n/a return os.write(self._fd, b)
1618n/a except BlockingIOError:
1619n/a return None
1620n/a
1621n/a def seek(self, pos, whence=SEEK_SET):
1622n/a """Move to new file position.
1623n/a
1624n/a Argument offset is a byte count. Optional argument whence defaults to
1625n/a SEEK_SET or 0 (offset from start of file, offset should be >= 0); other values
1626n/a are SEEK_CUR or 1 (move relative to current position, positive or negative),
1627n/a and SEEK_END or 2 (move relative to end of file, usually negative, although
1628n/a many platforms allow seeking beyond the end of a file).
1629n/a
1630n/a Note that not all file objects are seekable.
1631n/a """
1632n/a if isinstance(pos, float):
1633n/a raise TypeError('an integer is required')
1634n/a self._checkClosed()
1635n/a return os.lseek(self._fd, pos, whence)
1636n/a
1637n/a def tell(self):
1638n/a """tell() -> int. Current file position.
1639n/a
1640n/a Can raise OSError for non seekable files."""
1641n/a self._checkClosed()
1642n/a return os.lseek(self._fd, 0, SEEK_CUR)
1643n/a
1644n/a def truncate(self, size=None):
1645n/a """Truncate the file to at most size bytes.
1646n/a
1647n/a Size defaults to the current file position, as returned by tell().
1648n/a The current file position is changed to the value of size.
1649n/a """
1650n/a self._checkClosed()
1651n/a self._checkWritable()
1652n/a if size is None:
1653n/a size = self.tell()
1654n/a os.ftruncate(self._fd, size)
1655n/a return size
1656n/a
1657n/a def close(self):
1658n/a """Close the file.
1659n/a
1660n/a A closed file cannot be used for further I/O operations. close() may be
1661n/a called more than once without error.
1662n/a """
1663n/a if not self.closed:
1664n/a try:
1665n/a if self._closefd:
1666n/a os.close(self._fd)
1667n/a finally:
1668n/a super().close()
1669n/a
1670n/a def seekable(self):
1671n/a """True if file supports random-access."""
1672n/a self._checkClosed()
1673n/a if self._seekable is None:
1674n/a try:
1675n/a self.tell()
1676n/a except OSError:
1677n/a self._seekable = False
1678n/a else:
1679n/a self._seekable = True
1680n/a return self._seekable
1681n/a
1682n/a def readable(self):
1683n/a """True if file was opened in a read mode."""
1684n/a self._checkClosed()
1685n/a return self._readable
1686n/a
1687n/a def writable(self):
1688n/a """True if file was opened in a write mode."""
1689n/a self._checkClosed()
1690n/a return self._writable
1691n/a
1692n/a def fileno(self):
1693n/a """Return the underlying file descriptor (an integer)."""
1694n/a self._checkClosed()
1695n/a return self._fd
1696n/a
1697n/a def isatty(self):
1698n/a """True if the file is connected to a TTY device."""
1699n/a self._checkClosed()
1700n/a return os.isatty(self._fd)
1701n/a
1702n/a @property
1703n/a def closefd(self):
1704n/a """True if the file descriptor will be closed by close()."""
1705n/a return self._closefd
1706n/a
1707n/a @property
1708n/a def mode(self):
1709n/a """String giving the file mode"""
1710n/a if self._created:
1711n/a if self._readable:
1712n/a return 'xb+'
1713n/a else:
1714n/a return 'xb'
1715n/a elif self._appending:
1716n/a if self._readable:
1717n/a return 'ab+'
1718n/a else:
1719n/a return 'ab'
1720n/a elif self._readable:
1721n/a if self._writable:
1722n/a return 'rb+'
1723n/a else:
1724n/a return 'rb'
1725n/a else:
1726n/a return 'wb'
1727n/a
1728n/a
1729n/aclass TextIOBase(IOBase):
1730n/a
1731n/a """Base class for text I/O.
1732n/a
1733n/a This class provides a character and line based interface to stream
1734n/a I/O. There is no readinto method because Python's character strings
1735n/a are immutable. There is no public constructor.
1736n/a """
1737n/a
1738n/a def read(self, size=-1):
1739n/a """Read at most size characters from stream, where size is an int.
1740n/a
1741n/a Read from underlying buffer until we have size characters or we hit EOF.
1742n/a If size is negative or omitted, read until EOF.
1743n/a
1744n/a Returns a string.
1745n/a """
1746n/a self._unsupported("read")
1747n/a
1748n/a def write(self, s):
1749n/a """Write string s to stream and returning an int."""
1750n/a self._unsupported("write")
1751n/a
1752n/a def truncate(self, pos=None):
1753n/a """Truncate size to pos, where pos is an int."""
1754n/a self._unsupported("truncate")
1755n/a
1756n/a def readline(self):
1757n/a """Read until newline or EOF.
1758n/a
1759n/a Returns an empty string if EOF is hit immediately.
1760n/a """
1761n/a self._unsupported("readline")
1762n/a
1763n/a def detach(self):
1764n/a """
1765n/a Separate the underlying buffer from the TextIOBase and return it.
1766n/a
1767n/a After the underlying buffer has been detached, the TextIO is in an
1768n/a unusable state.
1769n/a """
1770n/a self._unsupported("detach")
1771n/a
1772n/a @property
1773n/a def encoding(self):
1774n/a """Subclasses should override."""
1775n/a return None
1776n/a
1777n/a @property
1778n/a def newlines(self):
1779n/a """Line endings translated so far.
1780n/a
1781n/a Only line endings translated during reading are considered.
1782n/a
1783n/a Subclasses should override.
1784n/a """
1785n/a return None
1786n/a
1787n/a @property
1788n/a def errors(self):
1789n/a """Error setting of the decoder or encoder.
1790n/a
1791n/a Subclasses should override."""
1792n/a return None
1793n/a
1794n/aio.TextIOBase.register(TextIOBase)
1795n/a
1796n/a
1797n/aclass IncrementalNewlineDecoder(codecs.IncrementalDecoder):
1798n/a r"""Codec used when reading a file in universal newlines mode. It wraps
1799n/a another incremental decoder, translating \r\n and \r into \n. It also
1800n/a records the types of newlines encountered. When used with
1801n/a translate=False, it ensures that the newline sequence is returned in
1802n/a one piece.
1803n/a """
1804n/a def __init__(self, decoder, translate, errors='strict'):
1805n/a codecs.IncrementalDecoder.__init__(self, errors=errors)
1806n/a self.translate = translate
1807n/a self.decoder = decoder
1808n/a self.seennl = 0
1809n/a self.pendingcr = False
1810n/a
1811n/a def decode(self, input, final=False):
1812n/a # decode input (with the eventual \r from a previous pass)
1813n/a if self.decoder is None:
1814n/a output = input
1815n/a else:
1816n/a output = self.decoder.decode(input, final=final)
1817n/a if self.pendingcr and (output or final):
1818n/a output = "\r" + output
1819n/a self.pendingcr = False
1820n/a
1821n/a # retain last \r even when not translating data:
1822n/a # then readline() is sure to get \r\n in one pass
1823n/a if output.endswith("\r") and not final:
1824n/a output = output[:-1]
1825n/a self.pendingcr = True
1826n/a
1827n/a # Record which newlines are read
1828n/a crlf = output.count('\r\n')
1829n/a cr = output.count('\r') - crlf
1830n/a lf = output.count('\n') - crlf
1831n/a self.seennl |= (lf and self._LF) | (cr and self._CR) \
1832n/a | (crlf and self._CRLF)
1833n/a
1834n/a if self.translate:
1835n/a if crlf:
1836n/a output = output.replace("\r\n", "\n")
1837n/a if cr:
1838n/a output = output.replace("\r", "\n")
1839n/a
1840n/a return output
1841n/a
1842n/a def getstate(self):
1843n/a if self.decoder is None:
1844n/a buf = b""
1845n/a flag = 0
1846n/a else:
1847n/a buf, flag = self.decoder.getstate()
1848n/a flag <<= 1
1849n/a if self.pendingcr:
1850n/a flag |= 1
1851n/a return buf, flag
1852n/a
1853n/a def setstate(self, state):
1854n/a buf, flag = state
1855n/a self.pendingcr = bool(flag & 1)
1856n/a if self.decoder is not None:
1857n/a self.decoder.setstate((buf, flag >> 1))
1858n/a
1859n/a def reset(self):
1860n/a self.seennl = 0
1861n/a self.pendingcr = False
1862n/a if self.decoder is not None:
1863n/a self.decoder.reset()
1864n/a
1865n/a _LF = 1
1866n/a _CR = 2
1867n/a _CRLF = 4
1868n/a
1869n/a @property
1870n/a def newlines(self):
1871n/a return (None,
1872n/a "\n",
1873n/a "\r",
1874n/a ("\r", "\n"),
1875n/a "\r\n",
1876n/a ("\n", "\r\n"),
1877n/a ("\r", "\r\n"),
1878n/a ("\r", "\n", "\r\n")
1879n/a )[self.seennl]
1880n/a
1881n/a
1882n/aclass TextIOWrapper(TextIOBase):
1883n/a
1884n/a r"""Character and line based layer over a BufferedIOBase object, buffer.
1885n/a
1886n/a encoding gives the name of the encoding that the stream will be
1887n/a decoded or encoded with. It defaults to locale.getpreferredencoding(False).
1888n/a
1889n/a errors determines the strictness of encoding and decoding (see the
1890n/a codecs.register) and defaults to "strict".
1891n/a
1892n/a newline can be None, '', '\n', '\r', or '\r\n'. It controls the
1893n/a handling of line endings. If it is None, universal newlines is
1894n/a enabled. With this enabled, on input, the lines endings '\n', '\r',
1895n/a or '\r\n' are translated to '\n' before being returned to the
1896n/a caller. Conversely, on output, '\n' is translated to the system
1897n/a default line separator, os.linesep. If newline is any other of its
1898n/a legal values, that newline becomes the newline when the file is read
1899n/a and it is returned untranslated. On output, '\n' is converted to the
1900n/a newline.
1901n/a
1902n/a If line_buffering is True, a call to flush is implied when a call to
1903n/a write contains a newline character.
1904n/a """
1905n/a
1906n/a _CHUNK_SIZE = 2048
1907n/a
1908n/a # The write_through argument has no effect here since this
1909n/a # implementation always writes through. The argument is present only
1910n/a # so that the signature can match the signature of the C version.
1911n/a def __init__(self, buffer, encoding=None, errors=None, newline=None,
1912n/a line_buffering=False, write_through=False):
1913n/a if newline is not None and not isinstance(newline, str):
1914n/a raise TypeError("illegal newline type: %r" % (type(newline),))
1915n/a if newline not in (None, "", "\n", "\r", "\r\n"):
1916n/a raise ValueError("illegal newline value: %r" % (newline,))
1917n/a if encoding is None:
1918n/a try:
1919n/a encoding = os.device_encoding(buffer.fileno())
1920n/a except (AttributeError, UnsupportedOperation):
1921n/a pass
1922n/a if encoding is None:
1923n/a try:
1924n/a import locale
1925n/a except ImportError:
1926n/a # Importing locale may fail if Python is being built
1927n/a encoding = "ascii"
1928n/a else:
1929n/a encoding = locale.getpreferredencoding(False)
1930n/a
1931n/a if not isinstance(encoding, str):
1932n/a raise ValueError("invalid encoding: %r" % encoding)
1933n/a
1934n/a if not codecs.lookup(encoding)._is_text_encoding:
1935n/a msg = ("%r is not a text encoding; "
1936n/a "use codecs.open() to handle arbitrary codecs")
1937n/a raise LookupError(msg % encoding)
1938n/a
1939n/a if errors is None:
1940n/a errors = "strict"
1941n/a else:
1942n/a if not isinstance(errors, str):
1943n/a raise ValueError("invalid errors: %r" % errors)
1944n/a
1945n/a self._buffer = buffer
1946n/a self._line_buffering = line_buffering
1947n/a self._encoding = encoding
1948n/a self._errors = errors
1949n/a self._readuniversal = not newline
1950n/a self._readtranslate = newline is None
1951n/a self._readnl = newline
1952n/a self._writetranslate = newline != ''
1953n/a self._writenl = newline or os.linesep
1954n/a self._encoder = None
1955n/a self._decoder = None
1956n/a self._decoded_chars = '' # buffer for text returned from decoder
1957n/a self._decoded_chars_used = 0 # offset into _decoded_chars for read()
1958n/a self._snapshot = None # info for reconstructing decoder state
1959n/a self._seekable = self._telling = self.buffer.seekable()
1960n/a self._has_read1 = hasattr(self.buffer, 'read1')
1961n/a self._b2cratio = 0.0
1962n/a
1963n/a if self._seekable and self.writable():
1964n/a position = self.buffer.tell()
1965n/a if position != 0:
1966n/a try:
1967n/a self._get_encoder().setstate(0)
1968n/a except LookupError:
1969n/a # Sometimes the encoder doesn't exist
1970n/a pass
1971n/a
1972n/a # self._snapshot is either None, or a tuple (dec_flags, next_input)
1973n/a # where dec_flags is the second (integer) item of the decoder state
1974n/a # and next_input is the chunk of input bytes that comes next after the
1975n/a # snapshot point. We use this to reconstruct decoder states in tell().
1976n/a
1977n/a # Naming convention:
1978n/a # - "bytes_..." for integer variables that count input bytes
1979n/a # - "chars_..." for integer variables that count decoded characters
1980n/a
1981n/a def __repr__(self):
1982n/a result = "<{}.{}".format(self.__class__.__module__,
1983n/a self.__class__.__qualname__)
1984n/a try:
1985n/a name = self.name
1986n/a except Exception:
1987n/a pass
1988n/a else:
1989n/a result += " name={0!r}".format(name)
1990n/a try:
1991n/a mode = self.mode
1992n/a except Exception:
1993n/a pass
1994n/a else:
1995n/a result += " mode={0!r}".format(mode)
1996n/a return result + " encoding={0!r}>".format(self.encoding)
1997n/a
1998n/a @property
1999n/a def encoding(self):
2000n/a return self._encoding
2001n/a
2002n/a @property
2003n/a def errors(self):
2004n/a return self._errors
2005n/a
2006n/a @property
2007n/a def line_buffering(self):
2008n/a return self._line_buffering
2009n/a
2010n/a @property
2011n/a def buffer(self):
2012n/a return self._buffer
2013n/a
2014n/a def seekable(self):
2015n/a if self.closed:
2016n/a raise ValueError("I/O operation on closed file.")
2017n/a return self._seekable
2018n/a
2019n/a def readable(self):
2020n/a return self.buffer.readable()
2021n/a
2022n/a def writable(self):
2023n/a return self.buffer.writable()
2024n/a
2025n/a def flush(self):
2026n/a self.buffer.flush()
2027n/a self._telling = self._seekable
2028n/a
2029n/a def close(self):
2030n/a if self.buffer is not None and not self.closed:
2031n/a try:
2032n/a self.flush()
2033n/a finally:
2034n/a self.buffer.close()
2035n/a
2036n/a @property
2037n/a def closed(self):
2038n/a return self.buffer.closed
2039n/a
2040n/a @property
2041n/a def name(self):
2042n/a return self.buffer.name
2043n/a
2044n/a def fileno(self):
2045n/a return self.buffer.fileno()
2046n/a
2047n/a def isatty(self):
2048n/a return self.buffer.isatty()
2049n/a
2050n/a def write(self, s):
2051n/a 'Write data, where s is a str'
2052n/a if self.closed:
2053n/a raise ValueError("write to closed file")
2054n/a if not isinstance(s, str):
2055n/a raise TypeError("can't write %s to text stream" %
2056n/a s.__class__.__name__)
2057n/a length = len(s)
2058n/a haslf = (self._writetranslate or self._line_buffering) and "\n" in s
2059n/a if haslf and self._writetranslate and self._writenl != "\n":
2060n/a s = s.replace("\n", self._writenl)
2061n/a encoder = self._encoder or self._get_encoder()
2062n/a # XXX What if we were just reading?
2063n/a b = encoder.encode(s)
2064n/a self.buffer.write(b)
2065n/a if self._line_buffering and (haslf or "\r" in s):
2066n/a self.flush()
2067n/a self._snapshot = None
2068n/a if self._decoder:
2069n/a self._decoder.reset()
2070n/a return length
2071n/a
2072n/a def _get_encoder(self):
2073n/a make_encoder = codecs.getincrementalencoder(self._encoding)
2074n/a self._encoder = make_encoder(self._errors)
2075n/a return self._encoder
2076n/a
2077n/a def _get_decoder(self):
2078n/a make_decoder = codecs.getincrementaldecoder(self._encoding)
2079n/a decoder = make_decoder(self._errors)
2080n/a if self._readuniversal:
2081n/a decoder = IncrementalNewlineDecoder(decoder, self._readtranslate)
2082n/a self._decoder = decoder
2083n/a return decoder
2084n/a
2085n/a # The following three methods implement an ADT for _decoded_chars.
2086n/a # Text returned from the decoder is buffered here until the client
2087n/a # requests it by calling our read() or readline() method.
2088n/a def _set_decoded_chars(self, chars):
2089n/a """Set the _decoded_chars buffer."""
2090n/a self._decoded_chars = chars
2091n/a self._decoded_chars_used = 0
2092n/a
2093n/a def _get_decoded_chars(self, n=None):
2094n/a """Advance into the _decoded_chars buffer."""
2095n/a offset = self._decoded_chars_used
2096n/a if n is None:
2097n/a chars = self._decoded_chars[offset:]
2098n/a else:
2099n/a chars = self._decoded_chars[offset:offset + n]
2100n/a self._decoded_chars_used += len(chars)
2101n/a return chars
2102n/a
2103n/a def _rewind_decoded_chars(self, n):
2104n/a """Rewind the _decoded_chars buffer."""
2105n/a if self._decoded_chars_used < n:
2106n/a raise AssertionError("rewind decoded_chars out of bounds")
2107n/a self._decoded_chars_used -= n
2108n/a
2109n/a def _read_chunk(self):
2110n/a """
2111n/a Read and decode the next chunk of data from the BufferedReader.
2112n/a """
2113n/a
2114n/a # The return value is True unless EOF was reached. The decoded
2115n/a # string is placed in self._decoded_chars (replacing its previous
2116n/a # value). The entire input chunk is sent to the decoder, though
2117n/a # some of it may remain buffered in the decoder, yet to be
2118n/a # converted.
2119n/a
2120n/a if self._decoder is None:
2121n/a raise ValueError("no decoder")
2122n/a
2123n/a if self._telling:
2124n/a # To prepare for tell(), we need to snapshot a point in the
2125n/a # file where the decoder's input buffer is empty.
2126n/a
2127n/a dec_buffer, dec_flags = self._decoder.getstate()
2128n/a # Given this, we know there was a valid snapshot point
2129n/a # len(dec_buffer) bytes ago with decoder state (b'', dec_flags).
2130n/a
2131n/a # Read a chunk, decode it, and put the result in self._decoded_chars.
2132n/a if self._has_read1:
2133n/a input_chunk = self.buffer.read1(self._CHUNK_SIZE)
2134n/a else:
2135n/a input_chunk = self.buffer.read(self._CHUNK_SIZE)
2136n/a eof = not input_chunk
2137n/a decoded_chars = self._decoder.decode(input_chunk, eof)
2138n/a self._set_decoded_chars(decoded_chars)
2139n/a if decoded_chars:
2140n/a self._b2cratio = len(input_chunk) / len(self._decoded_chars)
2141n/a else:
2142n/a self._b2cratio = 0.0
2143n/a
2144n/a if self._telling:
2145n/a # At the snapshot point, len(dec_buffer) bytes before the read,
2146n/a # the next input to be decoded is dec_buffer + input_chunk.
2147n/a self._snapshot = (dec_flags, dec_buffer + input_chunk)
2148n/a
2149n/a return not eof
2150n/a
2151n/a def _pack_cookie(self, position, dec_flags=0,
2152n/a bytes_to_feed=0, need_eof=0, chars_to_skip=0):
2153n/a # The meaning of a tell() cookie is: seek to position, set the
2154n/a # decoder flags to dec_flags, read bytes_to_feed bytes, feed them
2155n/a # into the decoder with need_eof as the EOF flag, then skip
2156n/a # chars_to_skip characters of the decoded result. For most simple
2157n/a # decoders, tell() will often just give a byte offset in the file.
2158n/a return (position | (dec_flags<<64) | (bytes_to_feed<<128) |
2159n/a (chars_to_skip<<192) | bool(need_eof)<<256)
2160n/a
2161n/a def _unpack_cookie(self, bigint):
2162n/a rest, position = divmod(bigint, 1<<64)
2163n/a rest, dec_flags = divmod(rest, 1<<64)
2164n/a rest, bytes_to_feed = divmod(rest, 1<<64)
2165n/a need_eof, chars_to_skip = divmod(rest, 1<<64)
2166n/a return position, dec_flags, bytes_to_feed, need_eof, chars_to_skip
2167n/a
2168n/a def tell(self):
2169n/a if not self._seekable:
2170n/a raise UnsupportedOperation("underlying stream is not seekable")
2171n/a if not self._telling:
2172n/a raise OSError("telling position disabled by next() call")
2173n/a self.flush()
2174n/a position = self.buffer.tell()
2175n/a decoder = self._decoder
2176n/a if decoder is None or self._snapshot is None:
2177n/a if self._decoded_chars:
2178n/a # This should never happen.
2179n/a raise AssertionError("pending decoded text")
2180n/a return position
2181n/a
2182n/a # Skip backward to the snapshot point (see _read_chunk).
2183n/a dec_flags, next_input = self._snapshot
2184n/a position -= len(next_input)
2185n/a
2186n/a # How many decoded characters have been used up since the snapshot?
2187n/a chars_to_skip = self._decoded_chars_used
2188n/a if chars_to_skip == 0:
2189n/a # We haven't moved from the snapshot point.
2190n/a return self._pack_cookie(position, dec_flags)
2191n/a
2192n/a # Starting from the snapshot position, we will walk the decoder
2193n/a # forward until it gives us enough decoded characters.
2194n/a saved_state = decoder.getstate()
2195n/a try:
2196n/a # Fast search for an acceptable start point, close to our
2197n/a # current pos.
2198n/a # Rationale: calling decoder.decode() has a large overhead
2199n/a # regardless of chunk size; we want the number of such calls to
2200n/a # be O(1) in most situations (common decoders, non-crazy input).
2201n/a # Actually, it will be exactly 1 for fixed-size codecs (all
2202n/a # 8-bit codecs, also UTF-16 and UTF-32).
2203n/a skip_bytes = int(self._b2cratio * chars_to_skip)
2204n/a skip_back = 1
2205n/a assert skip_bytes <= len(next_input)
2206n/a while skip_bytes > 0:
2207n/a decoder.setstate((b'', dec_flags))
2208n/a # Decode up to temptative start point
2209n/a n = len(decoder.decode(next_input[:skip_bytes]))
2210n/a if n <= chars_to_skip:
2211n/a b, d = decoder.getstate()
2212n/a if not b:
2213n/a # Before pos and no bytes buffered in decoder => OK
2214n/a dec_flags = d
2215n/a chars_to_skip -= n
2216n/a break
2217n/a # Skip back by buffered amount and reset heuristic
2218n/a skip_bytes -= len(b)
2219n/a skip_back = 1
2220n/a else:
2221n/a # We're too far ahead, skip back a bit
2222n/a skip_bytes -= skip_back
2223n/a skip_back = skip_back * 2
2224n/a else:
2225n/a skip_bytes = 0
2226n/a decoder.setstate((b'', dec_flags))
2227n/a
2228n/a # Note our initial start point.
2229n/a start_pos = position + skip_bytes
2230n/a start_flags = dec_flags
2231n/a if chars_to_skip == 0:
2232n/a # We haven't moved from the start point.
2233n/a return self._pack_cookie(start_pos, start_flags)
2234n/a
2235n/a # Feed the decoder one byte at a time. As we go, note the
2236n/a # nearest "safe start point" before the current location
2237n/a # (a point where the decoder has nothing buffered, so seek()
2238n/a # can safely start from there and advance to this location).
2239n/a bytes_fed = 0
2240n/a need_eof = 0
2241n/a # Chars decoded since `start_pos`
2242n/a chars_decoded = 0
2243n/a for i in range(skip_bytes, len(next_input)):
2244n/a bytes_fed += 1
2245n/a chars_decoded += len(decoder.decode(next_input[i:i+1]))
2246n/a dec_buffer, dec_flags = decoder.getstate()
2247n/a if not dec_buffer and chars_decoded <= chars_to_skip:
2248n/a # Decoder buffer is empty, so this is a safe start point.
2249n/a start_pos += bytes_fed
2250n/a chars_to_skip -= chars_decoded
2251n/a start_flags, bytes_fed, chars_decoded = dec_flags, 0, 0
2252n/a if chars_decoded >= chars_to_skip:
2253n/a break
2254n/a else:
2255n/a # We didn't get enough decoded data; signal EOF to get more.
2256n/a chars_decoded += len(decoder.decode(b'', final=True))
2257n/a need_eof = 1
2258n/a if chars_decoded < chars_to_skip:
2259n/a raise OSError("can't reconstruct logical file position")
2260n/a
2261n/a # The returned cookie corresponds to the last safe start point.
2262n/a return self._pack_cookie(
2263n/a start_pos, start_flags, bytes_fed, need_eof, chars_to_skip)
2264n/a finally:
2265n/a decoder.setstate(saved_state)
2266n/a
2267n/a def truncate(self, pos=None):
2268n/a self.flush()
2269n/a if pos is None:
2270n/a pos = self.tell()
2271n/a return self.buffer.truncate(pos)
2272n/a
2273n/a def detach(self):
2274n/a if self.buffer is None:
2275n/a raise ValueError("buffer is already detached")
2276n/a self.flush()
2277n/a buffer = self._buffer
2278n/a self._buffer = None
2279n/a return buffer
2280n/a
2281n/a def seek(self, cookie, whence=0):
2282n/a def _reset_encoder(position):
2283n/a """Reset the encoder (merely useful for proper BOM handling)"""
2284n/a try:
2285n/a encoder = self._encoder or self._get_encoder()
2286n/a except LookupError:
2287n/a # Sometimes the encoder doesn't exist
2288n/a pass
2289n/a else:
2290n/a if position != 0:
2291n/a encoder.setstate(0)
2292n/a else:
2293n/a encoder.reset()
2294n/a
2295n/a if self.closed:
2296n/a raise ValueError("tell on closed file")
2297n/a if not self._seekable:
2298n/a raise UnsupportedOperation("underlying stream is not seekable")
2299n/a if whence == 1: # seek relative to current position
2300n/a if cookie != 0:
2301n/a raise UnsupportedOperation("can't do nonzero cur-relative seeks")
2302n/a # Seeking to the current position should attempt to
2303n/a # sync the underlying buffer with the current position.
2304n/a whence = 0
2305n/a cookie = self.tell()
2306n/a if whence == 2: # seek relative to end of file
2307n/a if cookie != 0:
2308n/a raise UnsupportedOperation("can't do nonzero end-relative seeks")
2309n/a self.flush()
2310n/a position = self.buffer.seek(0, 2)
2311n/a self._set_decoded_chars('')
2312n/a self._snapshot = None
2313n/a if self._decoder:
2314n/a self._decoder.reset()
2315n/a _reset_encoder(position)
2316n/a return position
2317n/a if whence != 0:
2318n/a raise ValueError("unsupported whence (%r)" % (whence,))
2319n/a if cookie < 0:
2320n/a raise ValueError("negative seek position %r" % (cookie,))
2321n/a self.flush()
2322n/a
2323n/a # The strategy of seek() is to go back to the safe start point
2324n/a # and replay the effect of read(chars_to_skip) from there.
2325n/a start_pos, dec_flags, bytes_to_feed, need_eof, chars_to_skip = \
2326n/a self._unpack_cookie(cookie)
2327n/a
2328n/a # Seek back to the safe start point.
2329n/a self.buffer.seek(start_pos)
2330n/a self._set_decoded_chars('')
2331n/a self._snapshot = None
2332n/a
2333n/a # Restore the decoder to its state from the safe start point.
2334n/a if cookie == 0 and self._decoder:
2335n/a self._decoder.reset()
2336n/a elif self._decoder or dec_flags or chars_to_skip:
2337n/a self._decoder = self._decoder or self._get_decoder()
2338n/a self._decoder.setstate((b'', dec_flags))
2339n/a self._snapshot = (dec_flags, b'')
2340n/a
2341n/a if chars_to_skip:
2342n/a # Just like _read_chunk, feed the decoder and save a snapshot.
2343n/a input_chunk = self.buffer.read(bytes_to_feed)
2344n/a self._set_decoded_chars(
2345n/a self._decoder.decode(input_chunk, need_eof))
2346n/a self._snapshot = (dec_flags, input_chunk)
2347n/a
2348n/a # Skip chars_to_skip of the decoded characters.
2349n/a if len(self._decoded_chars) < chars_to_skip:
2350n/a raise OSError("can't restore logical file position")
2351n/a self._decoded_chars_used = chars_to_skip
2352n/a
2353n/a _reset_encoder(cookie)
2354n/a return cookie
2355n/a
2356n/a def read(self, size=None):
2357n/a self._checkReadable()
2358n/a if size is None:
2359n/a size = -1
2360n/a decoder = self._decoder or self._get_decoder()
2361n/a try:
2362n/a size.__index__
2363n/a except AttributeError as err:
2364n/a raise TypeError("an integer is required") from err
2365n/a if size < 0:
2366n/a # Read everything.
2367n/a result = (self._get_decoded_chars() +
2368n/a decoder.decode(self.buffer.read(), final=True))
2369n/a self._set_decoded_chars('')
2370n/a self._snapshot = None
2371n/a return result
2372n/a else:
2373n/a # Keep reading chunks until we have size characters to return.
2374n/a eof = False
2375n/a result = self._get_decoded_chars(size)
2376n/a while len(result) < size and not eof:
2377n/a eof = not self._read_chunk()
2378n/a result += self._get_decoded_chars(size - len(result))
2379n/a return result
2380n/a
2381n/a def __next__(self):
2382n/a self._telling = False
2383n/a line = self.readline()
2384n/a if not line:
2385n/a self._snapshot = None
2386n/a self._telling = self._seekable
2387n/a raise StopIteration
2388n/a return line
2389n/a
2390n/a def readline(self, size=None):
2391n/a if self.closed:
2392n/a raise ValueError("read from closed file")
2393n/a if size is None:
2394n/a size = -1
2395n/a elif not isinstance(size, int):
2396n/a raise TypeError("size must be an integer")
2397n/a
2398n/a # Grab all the decoded text (we will rewind any extra bits later).
2399n/a line = self._get_decoded_chars()
2400n/a
2401n/a start = 0
2402n/a # Make the decoder if it doesn't already exist.
2403n/a if not self._decoder:
2404n/a self._get_decoder()
2405n/a
2406n/a pos = endpos = None
2407n/a while True:
2408n/a if self._readtranslate:
2409n/a # Newlines are already translated, only search for \n
2410n/a pos = line.find('\n', start)
2411n/a if pos >= 0:
2412n/a endpos = pos + 1
2413n/a break
2414n/a else:
2415n/a start = len(line)
2416n/a
2417n/a elif self._readuniversal:
2418n/a # Universal newline search. Find any of \r, \r\n, \n
2419n/a # The decoder ensures that \r\n are not split in two pieces
2420n/a
2421n/a # In C we'd look for these in parallel of course.
2422n/a nlpos = line.find("\n", start)
2423n/a crpos = line.find("\r", start)
2424n/a if crpos == -1:
2425n/a if nlpos == -1:
2426n/a # Nothing found
2427n/a start = len(line)
2428n/a else:
2429n/a # Found \n
2430n/a endpos = nlpos + 1
2431n/a break
2432n/a elif nlpos == -1:
2433n/a # Found lone \r
2434n/a endpos = crpos + 1
2435n/a break
2436n/a elif nlpos < crpos:
2437n/a # Found \n
2438n/a endpos = nlpos + 1
2439n/a break
2440n/a elif nlpos == crpos + 1:
2441n/a # Found \r\n
2442n/a endpos = crpos + 2
2443n/a break
2444n/a else:
2445n/a # Found \r
2446n/a endpos = crpos + 1
2447n/a break
2448n/a else:
2449n/a # non-universal
2450n/a pos = line.find(self._readnl)
2451n/a if pos >= 0:
2452n/a endpos = pos + len(self._readnl)
2453n/a break
2454n/a
2455n/a if size >= 0 and len(line) >= size:
2456n/a endpos = size # reached length size
2457n/a break
2458n/a
2459n/a # No line ending seen yet - get more data'
2460n/a while self._read_chunk():
2461n/a if self._decoded_chars:
2462n/a break
2463n/a if self._decoded_chars:
2464n/a line += self._get_decoded_chars()
2465n/a else:
2466n/a # end of file
2467n/a self._set_decoded_chars('')
2468n/a self._snapshot = None
2469n/a return line
2470n/a
2471n/a if size >= 0 and endpos > size:
2472n/a endpos = size # don't exceed size
2473n/a
2474n/a # Rewind _decoded_chars to just after the line ending we found.
2475n/a self._rewind_decoded_chars(len(line) - endpos)
2476n/a return line[:endpos]
2477n/a
2478n/a @property
2479n/a def newlines(self):
2480n/a return self._decoder.newlines if self._decoder else None
2481n/a
2482n/a
2483n/aclass StringIO(TextIOWrapper):
2484n/a """Text I/O implementation using an in-memory buffer.
2485n/a
2486n/a The initial_value argument sets the value of object. The newline
2487n/a argument is like the one of TextIOWrapper's constructor.
2488n/a """
2489n/a
2490n/a def __init__(self, initial_value="", newline="\n"):
2491n/a super(StringIO, self).__init__(BytesIO(),
2492n/a encoding="utf-8",
2493n/a errors="surrogatepass",
2494n/a newline=newline)
2495n/a # Issue #5645: make universal newlines semantics the same as in the
2496n/a # C version, even under Windows.
2497n/a if newline is None:
2498n/a self._writetranslate = False
2499n/a if initial_value is not None:
2500n/a if not isinstance(initial_value, str):
2501n/a raise TypeError("initial_value must be str or None, not {0}"
2502n/a .format(type(initial_value).__name__))
2503n/a self.write(initial_value)
2504n/a self.seek(0)
2505n/a
2506n/a def getvalue(self):
2507n/a self.flush()
2508n/a decoder = self._decoder or self._get_decoder()
2509n/a old_state = decoder.getstate()
2510n/a decoder.reset()
2511n/a try:
2512n/a return decoder.decode(self.buffer.getvalue(), final=True)
2513n/a finally:
2514n/a decoder.setstate(old_state)
2515n/a
2516n/a def __repr__(self):
2517n/a # TextIOWrapper tells the encoding in its repr. In StringIO,
2518n/a # that's an implementation detail.
2519n/a return object.__repr__(self)
2520n/a
2521n/a @property
2522n/a def errors(self):
2523n/a return None
2524n/a
2525n/a @property
2526n/a def encoding(self):
2527n/a return None
2528n/a
2529n/a def detach(self):
2530n/a # This doesn't make sense on StringIO.
2531n/a self._unsupported("detach")