@@ -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