Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(8)

Side by Side Diff: Doc/library/io.rst

Issue 18758: Fix internal references in the documentation
Patch Set: Created 6 years, 5 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « Doc/library/inspect.rst ('k') | Doc/library/itertools.rst » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`io` --- Core tools for working with streams 1 :mod:`io` --- Core tools for working with streams
2 ================================================= 2 =================================================
3 3
4 .. module:: io 4 .. module:: io
5 :synopsis: Core tools for working with streams. 5 :synopsis: Core tools for working with streams.
6 .. moduleauthor:: Guido van Rossum <guido@python.org> 6 .. moduleauthor:: Guido van Rossum <guido@python.org>
7 .. moduleauthor:: Mike Verdone <mike.verdone@gmail.com> 7 .. moduleauthor:: Mike Verdone <mike.verdone@gmail.com>
8 .. moduleauthor:: Mark Russell <mark.russell@zen.co.uk> 8 .. moduleauthor:: Mark Russell <mark.russell@zen.co.uk>
9 .. moduleauthor:: Antoine Pitrou <solipsis@pitrou.net> 9 .. moduleauthor:: Antoine Pitrou <solipsis@pitrou.net>
10 .. moduleauthor:: Amaury Forgeot d'Arc <amauryfa@gmail.com> 10 .. moduleauthor:: Amaury Forgeot d'Arc <amauryfa@gmail.com>
(...skipping 139 matching lines...) Expand 10 before | Expand all | Expand 10 after
150 The implementation of I/O streams is organized as a hierarchy of classes. First 150 The implementation of I/O streams is organized as a hierarchy of classes. First
151 :term:`abstract base classes <abstract base class>` (ABCs), which are used to 151 :term:`abstract base classes <abstract base class>` (ABCs), which are used to
152 specify the various categories of streams, then concrete classes providing the 152 specify the various categories of streams, then concrete classes providing the
153 standard stream implementations. 153 standard stream implementations.
154 154
155 .. note:: 155 .. note::
156 156
157 The abstract base classes also provide default implementations of some 157 The abstract base classes also provide default implementations of some
158 methods in order to help implementation of concrete stream classes. For 158 methods in order to help implementation of concrete stream classes. For
159 example, :class:`BufferedIOBase` provides unoptimized implementations of 159 example, :class:`BufferedIOBase` provides unoptimized implementations of
160 ``readinto()`` and ``readline()``. 160 :meth:`~IOBase.readinto` and :meth:`~IOBase.readline`.
161 161
162 At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It 162 At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It
163 defines the basic interface to a stream. Note, however, that there is no 163 defines the basic interface to a stream. Note, however, that there is no
164 separation between reading and writing to streams; implementations are allowed 164 separation between reading and writing to streams; implementations are allowed
165 to raise :exc:`UnsupportedOperation` if they do not support a given operation. 165 to raise :exc:`UnsupportedOperation` if they do not support a given operation.
166 166
167 The :class:`RawIOBase` ABC extends :class:`IOBase`. It deals with the reading 167 The :class:`RawIOBase` ABC extends :class:`IOBase`. It deals with the reading
168 and writing of bytes to a stream. :class:`FileIO` subclasses :class:`RawIOBase` 168 and writing of bytes to a stream. :class:`FileIO` subclasses :class:`RawIOBase`
169 to provide an interface to files in the machine's file system. 169 to provide an interface to files in the machine's file system.
170 170
(...skipping 50 matching lines...) Expand 10 before | Expand all | Expand 10 after
221 seeked. 221 seeked.
222 222
223 Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`, 223 Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`,
224 or :meth:`write` because their signatures will vary, implementations and 224 or :meth:`write` because their signatures will vary, implementations and
225 clients should consider those methods part of the interface. Also, 225 clients should consider those methods part of the interface. Also,
226 implementations may raise a :exc:`ValueError` (or :exc:`UnsupportedOperation` ) 226 implementations may raise a :exc:`ValueError` (or :exc:`UnsupportedOperation` )
227 when operations they do not support are called. 227 when operations they do not support are called.
228 228
229 The basic type used for binary data read from or written to a file is 229 The basic type used for binary data read from or written to a file is
230 :class:`bytes`. :class:`bytearray`\s are accepted too, and in some cases 230 :class:`bytes`. :class:`bytearray`\s are accepted too, and in some cases
231 (such as :class:`readinto`) required. Text I/O classes work with 231 (such as :meth:`readinto`) required. Text I/O classes work with
232 :class:`str` data. 232 :class:`str` data.
233 233
234 Note that calling any method (even inquiries) on a closed stream is 234 Note that calling any method (even inquiries) on a closed stream is
235 undefined. Implementations may raise :exc:`ValueError` in this case. 235 undefined. Implementations may raise :exc:`ValueError` in this case.
236 236
237 :class:`IOBase` (and its subclasses) supports the iterator protocol, meaning 237 :class:`IOBase` (and its subclasses) supports the iterator protocol, meaning
238 that an :class:`IOBase` object can be iterated over yielding the lines in a 238 that an :class:`IOBase` object can be iterated over yielding the lines in a
239 stream. Lines are defined slightly differently depending on whether the 239 stream. Lines are defined slightly differently depending on whether the
240 stream is a binary stream (yielding bytes), or a text stream (yielding 240 stream is a binary stream (yielding bytes), or a text stream (yielding
241 character strings). See :meth:`~IOBase.readline` below. 241 character strings). See :meth:`~IOBase.readline` below.
(...skipping 703 matching lines...) Expand 10 before | Expand all | Expand 10 after
945 they can arise from doing I/O in a :mod:`signal` handler. If a thread tries to 945 they can arise from doing I/O in a :mod:`signal` handler. If a thread tries to
946 re-enter a buffered object which it is already accessing, a :exc:`RuntimeError` 946 re-enter a buffered object which it is already accessing, a :exc:`RuntimeError`
947 is raised. Note this doesn't prohibit a different thread from entering the 947 is raised. Note this doesn't prohibit a different thread from entering the
948 buffered object. 948 buffered object.
949 949
950 The above implicitly extends to text files, since the :func:`open()` function 950 The above implicitly extends to text files, since the :func:`open()` function
951 will wrap a buffered object inside a :class:`TextIOWrapper`. This includes 951 will wrap a buffered object inside a :class:`TextIOWrapper`. This includes
952 standard streams and therefore affects the built-in function :func:`print()` as 952 standard streams and therefore affects the built-in function :func:`print()` as
953 well. 953 well.
954 954
OLDNEW
« no previous file with comments | « Doc/library/inspect.rst ('k') | Doc/library/itertools.rst » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+