@@ -785,47 +785,42 @@ Text I/O
785785 inherits :class: `codecs.IncrementalDecoder `.
786786
787787
788- Advanced topics
789- ---------------
790-
791- Here we will discuss several advanced topics pertaining to the concrete
792- I/O implementations described above.
793-
794788Performance
795- ^^^^^^^^^^^
789+ -----------
790+
791+ This section discusses the performance of the provided concrete I/O
792+ implementations.
796793
797794Binary I/O
798- """"""""""
799-
800- By reading and writing only large chunks of data even when the user asks
801- for a single byte, buffered I/O is designed to hide any inefficiency in
802- calling and executing the operating system's unbuffered I/O routines. The
803- gain will vary very much depending on the OS and the kind of I/O which is
804- performed (for example, on some contemporary OSes such as Linux, unbuffered
805- disk I/O can be as fast as buffered I/O). The bottom line, however, is
806- that buffered I/O will offer you predictable performance regardless of the
807- platform and the backing device. Therefore, it is most always preferable to
808- use buffered I/O rather than unbuffered I/O.
795+ ^^^^^^^^^^
796+
797+ By reading and writing only large chunks of data even when the user asks for a
798+ single byte, buffered I/O hides any inefficiency in calling and executing the
799+ operating system's unbuffered I/O routines. The gain depends on the OS and the
800+ kind of I/O which is performed. For example, on some modern OSes such as Linux,
801+ unbuffered disk I/O can be as fast as buffered I/O. The bottom line, however,
802+ is that buffered I/O offers predictable performance regardless of the platform
803+ and the backing device. Therefore, it is most always preferable to use buffered
804+ I/O rather than unbuffered I/O for binary datal
809805
810806Text I/O
811- """"""""
807+ ^^^^^^^^
812808
813809Text I/O over a binary storage (such as a file) is significantly slower than
814- binary I/O over the same storage, because it implies conversions from
815- unicode to binary data using a character codec. This can become noticeable
816- if you handle huge amounts of text data (for example very large log files).
817- Also, :meth: `TextIOWrapper.tell ` and :meth: `TextIOWrapper.seek ` are both
818- quite slow due to the reconstruction algorithm used.
810+ binary I/O over the same storage, because it requires conversions between
811+ unicode and binary data using a character codec. This can become noticeable
812+ handling huge amounts of text data like large log files. Also,
813+ :meth: `TextIOWrapper.tell ` and :meth: `TextIOWrapper.seek ` are both quite slow
814+ due to the reconstruction algorithm used.
819815
820816:class: `StringIO `, however, is a native in-memory unicode container and will
821817exhibit similar speed to :class: `BytesIO `.
822818
823819Multi-threading
824820^^^^^^^^^^^^^^^
825821
826- :class: `FileIO ` objects are thread-safe to the extent that the operating
827- system calls (such as ``read(2) `` under Unix) they are wrapping are thread-safe
828- too.
822+ :class: `FileIO ` objects are thread-safe to the extent that the operating system
823+ calls (such as ``read(2) `` under Unix) they wrap are thread-safe too.
829824
830825Binary buffered objects (instances of :class: `BufferedReader `,
831826:class: `BufferedWriter `, :class: `BufferedRandom ` and :class: `BufferedRWPair `)
@@ -840,12 +835,13 @@ Reentrancy
840835Binary buffered objects (instances of :class: `BufferedReader `,
841836:class: `BufferedWriter `, :class: `BufferedRandom ` and :class: `BufferedRWPair `)
842837are not reentrant. While reentrant calls will not happen in normal situations,
843- they can arise if you are doing I/O in a :mod: `signal ` handler. If it is
844- attempted to enter a buffered object again while already being accessed
845- *from the same thread *, then a :exc: `RuntimeError ` is raised.
846-
847- The above implicitly extends to text files, since the :func: `open() `
848- function will wrap a buffered object inside a :class: `TextIOWrapper `. This
849- includes standard streams and therefore affects the built-in function
850- :func: `print() ` as well.
838+ they can arise from doing I/O in a :mod: `signal ` handler. If a thread tries to
839+ renter a buffered object which it is already accessing, a :exc: `RuntimeError ` is
840+ raised. Note this doesn't prohibit a different thread from entering the
841+ buffered object.
842+
843+ The above implicitly extends to text files, since the :func: `open() ` function
844+ will wrap a buffered object inside a :class: `TextIOWrapper `. This includes
845+ standard streams and therefore affects the built-in function :func: `print() ` as
846+ well.
851847
0 commit comments