From 99d2598d9e2ceddef36ef514622e0ea700a565c9 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 13 Nov 2026 01:50:45 +0200 Subject: [PATCH] gh-148467: Move BufferedIOBase close to concrete implementations (GH-150838) This reverts commit b6c7beb722deedc5125c81747af5c1f1204e2619. (cherry picked from commit ecefd40671f340d543c214b80744d4301d249f37) Co-authored-by: Serhiy Storchaka Co-authored-by: Cody Maloney --- Doc/library/io.rst | 149 +++++++++++++++++++++++---------------------- 1 file changed, 75 insertions(+), 74 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index fd98b9dc080b7f..153ba86596c126 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -526,6 +526,81 @@ I/O base classes write calls until all unwritten bytes are written. High-level I/O objects like :ref:`binary-io` and :ref:`text-io` implement retry behavior. + +Raw file I/O +^^^^^^^^^^^^ + +.. class:: FileIO(name, mode='r', closefd=True, opener=None) + + A raw binary stream representing an OS-level file containing bytes data. It + inherits from :class:`RawIOBase` and implements its low-level access design. + This means :meth:`~RawIOBase.write` does not guarantee all bytes are written + and :meth:`~RawIOBase.read` may read less bytes than requested even when more + bytes may be present in the underlying file. To get "write all" and + "read at least" behavior, use :ref:`binary-io`. + + The *name* can be one of two things: + + * a character string or :class:`bytes` object representing the path to the + file which will be opened. In this case closefd must be ``True`` (the default) + otherwise an error will be raised. + * an integer representing the number of an existing OS-level file descriptor + to which the resulting :class:`FileIO` object will give access. When the + FileIO object is closed this fd will be closed as well, unless *closefd* + is set to ``False``. + + The *mode* can be ``'r'``, ``'w'``, ``'x'`` or ``'a'`` for reading + (default), writing, exclusive creation or appending. The file will be + created if it doesn't exist when opened for writing or appending; it will be + truncated when opened for writing. :exc:`FileExistsError` will be raised if + it already exists when opened for creating. Opening a file for creating + implies writing, so this mode behaves in a similar way to ``'w'``. Add a + ``'+'`` to the mode to allow simultaneous reading and writing. + + A custom opener can be used by passing a callable as *opener*. The underlying + file descriptor for the file object is then obtained by calling *opener* with + (*name*, *flags*). *opener* must return an open file descriptor (passing + :mod:`os.open` as *opener* results in functionality similar to passing + ``None``). + + The newly created file is :ref:`non-inheritable `. + + See the :func:`open` built-in function for examples on using the *opener* + parameter. + + .. warning:: + :class:`FileIO` is a low-level I/O object and members, such as + :meth:`~RawIOBase.read` and :meth:`~RawIOBase.write`, need to have their + return values checked explicitly in a retry loop to implement "write all" + and "read at least" behavior. High-level I/O objects :ref:`binary-io` and + :ref:`text-io` implement retry behavior. + + .. versionchanged:: 3.3 + The *opener* parameter was added. + The ``'x'`` mode was added. + + .. versionchanged:: 3.4 + The file is now non-inheritable. + + :class:`FileIO` provides these data attributes in addition to those from + :class:`RawIOBase` and :class:`IOBase`: + + .. attribute:: mode + + The mode as given in the constructor. + + .. attribute:: name + + The file name. This is the file descriptor of the file when no name is + given in the constructor. + + +Buffered streams +^^^^^^^^^^^^^^^^ + +Buffered I/O streams provide a higher-level interface to an I/O device +than raw I/O does. + .. class:: BufferedIOBase Base class for binary streams that support some kind of buffering. @@ -647,80 +722,6 @@ I/O base classes so the implementation should only access *b* during the method call. -Raw file I/O -^^^^^^^^^^^^ - -.. class:: FileIO(name, mode='r', closefd=True, opener=None) - - A raw binary stream representing an OS-level file containing bytes data. It - inherits from :class:`RawIOBase` and implements its low-level access design. - This means :meth:`~RawIOBase.write` does not guarantee all bytes are written - and :meth:`~RawIOBase.read` may read less bytes than requested even when more - bytes may be present in the underlying file. To get "write all" and - "read at least" behavior, use :ref:`binary-io`. - - The *name* can be one of two things: - - * a character string or :class:`bytes` object representing the path to the - file which will be opened. In this case closefd must be ``True`` (the default) - otherwise an error will be raised. - * an integer representing the number of an existing OS-level file descriptor - to which the resulting :class:`FileIO` object will give access. When the - FileIO object is closed this fd will be closed as well, unless *closefd* - is set to ``False``. - - The *mode* can be ``'r'``, ``'w'``, ``'x'`` or ``'a'`` for reading - (default), writing, exclusive creation or appending. The file will be - created if it doesn't exist when opened for writing or appending; it will be - truncated when opened for writing. :exc:`FileExistsError` will be raised if - it already exists when opened for creating. Opening a file for creating - implies writing, so this mode behaves in a similar way to ``'w'``. Add a - ``'+'`` to the mode to allow simultaneous reading and writing. - - A custom opener can be used by passing a callable as *opener*. The underlying - file descriptor for the file object is then obtained by calling *opener* with - (*name*, *flags*). *opener* must return an open file descriptor (passing - :mod:`os.open` as *opener* results in functionality similar to passing - ``None``). - - The newly created file is :ref:`non-inheritable `. - - See the :func:`open` built-in function for examples on using the *opener* - parameter. - - .. warning:: - :class:`FileIO` is a low-level I/O object and members, such as - :meth:`~RawIOBase.read` and :meth:`~RawIOBase.write`, need to have their - return values checked explicitly in a retry loop to implement "write all" - and "read at least" behavior. High-level I/O objects :ref:`binary-io` and - :ref:`text-io` implement retry behavior. - - .. versionchanged:: 3.3 - The *opener* parameter was added. - The ``'x'`` mode was added. - - .. versionchanged:: 3.4 - The file is now non-inheritable. - - :class:`FileIO` provides these data attributes in addition to those from - :class:`RawIOBase` and :class:`IOBase`: - - .. attribute:: mode - - The mode as given in the constructor. - - .. attribute:: name - - The file name. This is the file descriptor of the file when no name is - given in the constructor. - - -Buffered streams -^^^^^^^^^^^^^^^^ - -Buffered I/O streams provide a higher-level interface to an I/O device -than raw I/O does. - .. class:: BytesIO(initial_bytes=b'') A binary stream using an in-memory bytes buffer. It inherits from