Lines Matching +full:non +full:- +full:read +full:- +full:only
1 :mod:`io` --- Core tools for working with streams
17 --------------
19 .. _io-overview:
22 --------
32 and *file-like object*.
35 various capabilities: it can be read-only, write-only, or read-write. It can
37 location), or only sequential access (for example in the case of a socket or
56 translation of platform-specific newline characters.
61 f = open("myfile.txt", "r", encoding="utf-8")
63 In-memory text streams are also available as :class:`StringIO` objects::
75 :term:`bytes-like objects <bytes-like object>` and produces :class:`bytes`
77 category of streams can be used for all kinds of non-text data, and also when
85 In-memory binary streams are also available as :class:`BytesIO` objects::
99 Raw I/O (also called *unbuffered I/O*) is generally used as a low-level
100 building-block for binary and text streams; it is rarely useful to directly
109 .. _io-text-encoding:
112 -------------
115 locale-specific (:func:`locale.getencoding`).
118 encoded in UTF-8 (e.g. JSON, TOML, Markdown, etc...) since most Unix
119 platforms use UTF-8 locale by default. This causes bugs because the locale
120 encoding is not UTF-8 for most Windows users. For example::
122 # May not work on Windows when non-ASCII characters in the file.
124 long_description = f.read()
127 explicitly when opening text files. If you want to use UTF-8, pass
128 ``encoding="utf-8"``. To use the current locale encoding,
133 :ref:`utf8-mode`
134 Python UTF-8 Mode can be used to change the default encoding to
135 UTF-8 from locale-specific encoding.
138 Python 3.15 will make :ref:`utf8-mode` default.
140 .. _io-encoding-warning:
142 Opt-in EncodingWarning
149 the ``-X warn_default_encoding`` command line option or set the
157 please consider using UTF-8 by default (i.e. ``encoding="utf-8"``) for
161 High-level Module Interface
162 ---------------------------
171 .. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=…
175 .. audit-event:: open path,mode,flags io.open
204 Otherwise, it returns ``"locale"`` or ``"utf-8"`` depending on
205 :ref:`UTF-8 Mode <utf8-mode>`.
215 return f.read()
220 See :ref:`io-text-encoding` for more information.
225 :func:`text_encoding` returns "utf-8" when UTF-8 mode is enabled and
249 ---------------
278 in-memory bytes.
284 :class:`StringIO` is an in-memory stream for text.
286 Argument names are not part of the specification, and only the arguments of
301 … :class:`IOBase` ``readinto`` and Inherited :class:`IOBase` methods, ``read``,
303 :class:`BufferedIOBase` :class:`IOBase` ``detach``, ``read``, Inherited :class:`IOBase` …
305 :class:`TextIOBase` :class:`IOBase` ``detach``, ``read``, Inherited :class:`IOBase` …
320 implementations represent a file that cannot be read, written or
323 Even though :class:`IOBase` does not declare :meth:`read`
329 The basic type used for binary data read from or written to a file is
330 :class:`bytes`. Other :term:`bytes-like objects <bytes-like object>` are
344 :keyword:`!with` statement's suite is finished---even if an exception occurs::
358 only the first call, however, will have an effect.
373 for read-only and non-blocking streams.
382 Return ``True`` if the stream can be read from. If ``False``, :meth:`read`
385 .. method:: readline(size=-1, /)
387 Read and return one line from the stream. If *size* is specified, at
388 most *size* bytes will be read.
394 .. method:: readlines(hint=-1, /)
396 Read and return a list of lines from the stream. *hint* can be specified
397 to control the number of lines read: no more lines will be read if the
412 * :data:`SEEK_SET` or ``0`` -- start of the stream (the default);
414 * :data:`SEEK_CUR` or ``1`` -- current stream position; *offset* may
416 * :data:`SEEK_END` or ``2`` -- end of the stream; *offset* is usually
444 (on most systems, additional bytes are zero-filled). The new file size
448 Windows will now zero-fill files when extending.
472 Raw binary streams typically provide low-level access to an underlying OS
473 device or API, and do not try to encapsulate it in high-level primitives
474 …(this functionality is done at a higher-level in buffered binary streams and text streams, describ…
480 .. method:: read(size=-1, /)
482 Read up to *size* bytes from the object and return them. As a convenience,
483 if *size* is unspecified or -1, all bytes until EOF are returned.
484 Otherwise, only one system call is ever made. Fewer than *size* bytes may
488 If the object is in non-blocking mode and no bytes are available,
496 Read and return all the bytes from the stream until EOF, using multiple
501 Read bytes into a pre-allocated, writable
502 :term:`bytes-like object` *b*, and return the
503 number of bytes read. For example, *b* might be a :class:`bytearray`.
504 If the object is in non-blocking mode and no bytes
509 Write the given :term:`bytes-like object`, *b*, to the
513 stream, and especially if it is in non-blocking mode. ``None`` is
516 this method returns, so the implementation should only access *b*
525 The main difference with :class:`RawIOBase` is that methods :meth:`read`,
526 :meth:`readinto` and :meth:`write` will try (respectively) to read as much
531 underlying raw stream is in non-blocking mode and cannot take or give
535 Besides, the :meth:`read` method does not have a default
564 .. method:: read(size=-1, /)
566 Read and return up to *size* bytes. If the argument is omitted, ``None``,
567 or negative, data is read and returned until EOF is reached. An empty
573 one raw read will be issued, and a short result does not imply that EOF is
577 non blocking-mode, and has no data available at the moment.
579 .. method:: read1(size=-1, /)
581 Read and return up to *size* bytes, with at most one call to the
582 underlying raw stream's :meth:`~RawIOBase.read` (or
587 If *size* is ``-1`` (the default), an arbitrary number of bytes are
592 Read bytes into a pre-allocated, writable
593 :term:`bytes-like object` *b* and return the number of bytes read.
596 Like :meth:`read`, multiple reads may be issued to the underlying raw
599 A :exc:`BlockingIOError` is raised if the underlying raw stream is in non
600 blocking-mode, and has no data available at the moment.
604 Read bytes into a pre-allocated, writable
605 :term:`bytes-like object` *b*, using at most one call to
606 the underlying raw stream's :meth:`~RawIOBase.read` (or
607 :meth:`~RawIOBase.readinto`) method. Return the number of bytes read.
609 A :exc:`BlockingIOError` is raised if the underlying raw stream is in non
610 blocking-mode, and has no data available at the moment.
616 Write the given :term:`bytes-like object`, *b*, and return the number
623 When in non-blocking mode, a :exc:`BlockingIOError` is raised if the
628 so the implementation should only access *b* during the method call.
636 A raw binary stream representing an OS-level file containing bytes data. It
644 * an integer representing the number of an existing OS-level file descriptor
657 The :meth:`read` (when called with a positive argument), :meth:`readinto`
658 and :meth:`write` methods on this class will only make one system call.
666 The newly created file is :ref:`non-inheritable <fd_inheritance>`.
668 See the :func:`open` built-in function for examples on using the *opener*
676 The file is now non-inheritable.
694 Buffered I/O streams provide a higher-level interface to an I/O device
699 A binary stream using an in-memory bytes buffer. It inherits
703 The optional argument *initial_bytes* is a :term:`bytes-like object` that
732 .. method:: read1(size=-1, /)
734 In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.read`.
747 A buffered binary stream providing higher-level access to a readable, non
765 single read on the raw stream is done to satisfy the call. The number of
768 .. method:: read(size=-1, /)
770 Read and return *size* bytes, or if *size* is not given or negative, until
771 EOF or if the read call would block in non-blocking mode.
773 .. method:: read1(size=-1, /)
775 Read and return up to *size* bytes with only one call on the raw stream.
776 If at least one byte is buffered, only buffered bytes are returned.
777 Otherwise, one raw stream read call is made.
785 A buffered binary stream providing higher-level access to a writeable, non
812 Write the :term:`bytes-like object`, *b*, and return the
813 number of bytes written. When in non-blocking mode, a
820 A buffered binary stream providing higher-level access to a seekable
835 A buffered binary stream providing higher-level access to two non seekable
836 :class:`RawIOBase` raw binary streams---one readable, the other writeable.
900 .. method:: read(size=-1, /)
902 Read and return at most *size* characters from the stream as a single
905 .. method:: readline(size=-1, /)
907 Read until newline or EOF and return a single ``str``. If the stream is
910 If *size* is specified, at most *size* characters will be read.
923 *offset* must be zero, which is a no-operation (all other values
948 A buffered text stream providing higher-level access to a
955 explicitly. See :ref:`io-text-encoding` for more information.
982 are only terminated by the given string, and the line ending is returned to
1035 has already been read from the stream. On the other hand, changing
1049 A text stream using an in-memory text buffer. It inherits
1074 Newlines are decoded as if by :meth:`~TextIOBase.read`, although
1085 # Retrieve file contents -- this will be
1089 # Close object and discard memory buffer --
1104 -----------
1112 By reading and writing only large chunks of data even when the user asks for a
1131 :class:`StringIO`, however, is a native in-memory unicode container and will
1134 Multi-threading
1137 :class:`FileIO` objects are thread-safe to the extent that the operating system
1138 calls (such as ``read(2)`` under Unix) they wrap are thread-safe too.
1145 :class:`TextIOWrapper` objects are not thread-safe.
1154 re-enter a buffered object which it is already accessing, a :exc:`RuntimeError`
1160 standard streams and therefore affects the built-in :func:`print()` function as