Skip to content

Commit 4005685

Browse files
hugovkserhiy-storchakacmaloney
authored
[3.14] gh-148467: Move BufferedIOBase close to concrete implementations (GH-150838) (#162038)
This reverts commit b6c7beb. (cherry picked from commit ecefd40) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Cody Maloney <cmaloney@theoreticalchaos.com>
1 parent 39e17fa commit 4005685

1 file changed

Lines changed: 75 additions & 74 deletions

File tree

‎Doc/library/io.rst‎

Lines changed: 75 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -547,6 +547,81 @@ I/O Base Classes
547547
write calls until all unwritten bytes are written. High-level I/O
548548
objects like :ref:`binary-io` and :ref:`text-io` implement retry behavior.
549549

550+
551+
Raw File I/O
552+
^^^^^^^^^^^^
553+
554+
.. class:: FileIO(name, mode='r', closefd=True, opener=None)
555+
556+
A raw binary stream representing an OS-level file containing bytes data. It
557+
inherits from :class:`RawIOBase` and implements its low-level access design.
558+
This means :meth:`~RawIOBase.write` does not guarantee all bytes are written
559+
and :meth:`~RawIOBase.read` may read less bytes than requested even when more
560+
bytes may be present in the underlying file. To get "write all" and
561+
"read at least" behavior, use :ref:`binary-io`.
562+
563+
The *name* can be one of two things:
564+
565+
* a character string or :class:`bytes` object representing the path to the
566+
file which will be opened. In this case closefd must be ``True`` (the default)
567+
otherwise an error will be raised.
568+
* an integer representing the number of an existing OS-level file descriptor
569+
to which the resulting :class:`FileIO` object will give access. When the
570+
FileIO object is closed this fd will be closed as well, unless *closefd*
571+
is set to ``False``.
572+
573+
The *mode* can be ``'r'``, ``'w'``, ``'x'`` or ``'a'`` for reading
574+
(default), writing, exclusive creation or appending. The file will be
575+
created if it doesn't exist when opened for writing or appending; it will be
576+
truncated when opened for writing. :exc:`FileExistsError` will be raised if
577+
it already exists when opened for creating. Opening a file for creating
578+
implies writing, so this mode behaves in a similar way to ``'w'``. Add a
579+
``'+'`` to the mode to allow simultaneous reading and writing.
580+
581+
A custom opener can be used by passing a callable as *opener*. The underlying
582+
file descriptor for the file object is then obtained by calling *opener* with
583+
(*name*, *flags*). *opener* must return an open file descriptor (passing
584+
:mod:`os.open` as *opener* results in functionality similar to passing
585+
``None``).
586+
587+
The newly created file is :ref:`non-inheritable <fd_inheritance>`.
588+
589+
See the :func:`open` built-in function for examples on using the *opener*
590+
parameter.
591+
592+
.. warning::
593+
:class:`FileIO` is a low-level I/O object and members, such as
594+
:meth:`~RawIOBase.read` and :meth:`~RawIOBase.write`, need to have their
595+
return values checked explicitly in a retry loop to implement "write all"
596+
and "read at least" behavior. High-level I/O objects :ref:`binary-io` and
597+
:ref:`text-io` implement retry behavior.
598+
599+
.. versionchanged:: 3.3
600+
The *opener* parameter was added.
601+
The ``'x'`` mode was added.
602+
603+
.. versionchanged:: 3.4
604+
The file is now non-inheritable.
605+
606+
:class:`FileIO` provides these data attributes in addition to those from
607+
:class:`RawIOBase` and :class:`IOBase`:
608+
609+
.. attribute:: mode
610+
611+
The mode as given in the constructor.
612+
613+
.. attribute:: name
614+
615+
The file name. This is the file descriptor of the file when no name is
616+
given in the constructor.
617+
618+
619+
Buffered Streams
620+
^^^^^^^^^^^^^^^^
621+
622+
Buffered I/O streams provide a higher-level interface to an I/O device
623+
than raw I/O does.
624+
550625
.. class:: BufferedIOBase
551626

552627
Base class for binary streams that support some kind of buffering.
@@ -668,80 +743,6 @@ I/O Base Classes
668743
so the implementation should only access *b* during the method call.
669744

670745

671-
Raw File I/O
672-
^^^^^^^^^^^^
673-
674-
.. class:: FileIO(name, mode='r', closefd=True, opener=None)
675-
676-
A raw binary stream representing an OS-level file containing bytes data. It
677-
inherits from :class:`RawIOBase` and implements its low-level access design.
678-
This means :meth:`~RawIOBase.write` does not guarantee all bytes are written
679-
and :meth:`~RawIOBase.read` may read less bytes than requested even when more
680-
bytes may be present in the underlying file. To get "write all" and
681-
"read at least" behavior, use :ref:`binary-io`.
682-
683-
The *name* can be one of two things:
684-
685-
* a character string or :class:`bytes` object representing the path to the
686-
file which will be opened. In this case closefd must be ``True`` (the default)
687-
otherwise an error will be raised.
688-
* an integer representing the number of an existing OS-level file descriptor
689-
to which the resulting :class:`FileIO` object will give access. When the
690-
FileIO object is closed this fd will be closed as well, unless *closefd*
691-
is set to ``False``.
692-
693-
The *mode* can be ``'r'``, ``'w'``, ``'x'`` or ``'a'`` for reading
694-
(default), writing, exclusive creation or appending. The file will be
695-
created if it doesn't exist when opened for writing or appending; it will be
696-
truncated when opened for writing. :exc:`FileExistsError` will be raised if
697-
it already exists when opened for creating. Opening a file for creating
698-
implies writing, so this mode behaves in a similar way to ``'w'``. Add a
699-
``'+'`` to the mode to allow simultaneous reading and writing.
700-
701-
A custom opener can be used by passing a callable as *opener*. The underlying
702-
file descriptor for the file object is then obtained by calling *opener* with
703-
(*name*, *flags*). *opener* must return an open file descriptor (passing
704-
:mod:`os.open` as *opener* results in functionality similar to passing
705-
``None``).
706-
707-
The newly created file is :ref:`non-inheritable <fd_inheritance>`.
708-
709-
See the :func:`open` built-in function for examples on using the *opener*
710-
parameter.
711-
712-
.. warning::
713-
:class:`FileIO` is a low-level I/O object and members, such as
714-
:meth:`~RawIOBase.read` and :meth:`~RawIOBase.write`, need to have their
715-
return values checked explicitly in a retry loop to implement "write all"
716-
and "read at least" behavior. High-level I/O objects :ref:`binary-io` and
717-
:ref:`text-io` implement retry behavior.
718-
719-
.. versionchanged:: 3.3
720-
The *opener* parameter was added.
721-
The ``'x'`` mode was added.
722-
723-
.. versionchanged:: 3.4
724-
The file is now non-inheritable.
725-
726-
:class:`FileIO` provides these data attributes in addition to those from
727-
:class:`RawIOBase` and :class:`IOBase`:
728-
729-
.. attribute:: mode
730-
731-
The mode as given in the constructor.
732-
733-
.. attribute:: name
734-
735-
The file name. This is the file descriptor of the file when no name is
736-
given in the constructor.
737-
738-
739-
Buffered Streams
740-
^^^^^^^^^^^^^^^^
741-
742-
Buffered I/O streams provide a higher-level interface to an I/O device
743-
than raw I/O does.
744-
745746
.. class:: BytesIO(initial_bytes=b'')
746747

747748
A binary stream using an in-memory bytes buffer. It inherits from

0 commit comments

Comments
 (0)