Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Docs: Fix Sphinx warnings in io.rst (#107903) 

- Mark up parameter and argument names properly
- If possible, link to docs for methods like `seek`, `tell`, `write`, `read`, etc.

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
This commit is contained in:
Erlend E. Aasland 2023-08-17 21:19:01 +02:00 committed by GitHub
parent 75b3db8445
commit 5c76899dad
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 36 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
Doc/library/io.rst
View File

@ -38,9 +38,9 @@ location), or only sequential access (for example in the case of a socket or
pipe).
All streams are careful about the type of data you give to them. For example
giving a :class:`str` object to the ``write()`` method of a binary stream
giving a :class:`str` object to the :meth:`!write` method of a binary stream
will raise a :exc:`TypeError`. So will giving a :class:`bytes` object to the
``write()`` method of a text stream.
:meth:`!write` method of a text stream.
.. versionchanged:: 3.3
Operations that used to raise :exc:`IOError` now raise :exc:`OSError`, since
@ -146,7 +146,7 @@ Opt-in EncodingWarning
See :pep:`597` for more details.
To find where the default locale encoding is used, you can enable
the ``-X warn_default_encoding`` command line option or set the
the :option:`-X warn_default_encoding <-X>` command line option or set the
:envvar:`PYTHONWARNDEFAULTENCODING` environment variable, which will
emit an :exc:`EncodingWarning` when the default encoding is used.
@ -175,7 +175,7 @@ High-level Module Interface
.. audit-event:: open path,mode,flags io.open
This function raises an :ref:`auditing event <auditing>` ``open`` with
arguments ``path``, ``mode`` and ``flags``. The ``mode`` and ``flags``
arguments *path*, *mode* and *flags*. The *mode* and *flags*
arguments may have been modified or inferred from the original call.
@ -184,10 +184,10 @@ High-level Module Interface
Opens the provided file with mode ``'rb'``. This function should be used
when the intent is to treat the contents as executable code.
``path`` should be a :class:`str` and an absolute path.
*path* should be a :class:`str` and an absolute path.
The behavior of this function may be overridden by an earlier call to the
:c:func:`PyFile_SetOpenCodeHook`. However, assuming that ``path`` is a
:c:func:`PyFile_SetOpenCodeHook`. However, assuming that *path* is a
:class:`str` and an absolute path, ``open_code(path)`` should always behave
the same as ``open(path, 'rb')``. Overriding the behavior is intended for
additional validation or preprocessing of the file.
@ -258,7 +258,7 @@ standard stream implementations.
The abstract base classes also provide default implementations of some
methods in order to help implementation of concrete stream classes. For
example, :class:`BufferedIOBase` provides unoptimized implementations of
:meth:`~IOBase.readinto` and :meth:`~IOBase.readline`.
:meth:`!readinto` and :meth:`!readline`.
At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It
defines the basic interface to a stream. Note, however, that there is no
@ -320,8 +320,8 @@ I/O Base Classes
implementations represent a file that cannot be read, written or
seeked.
Even though :class:`IOBase` does not declare :meth:`read`
or :meth:`write` because their signatures will vary, implementations and
Even though :class:`IOBase` does not declare :meth:`!read`
or :meth:`!write` because their signatures will vary, implementations and
clients should consider those methods part of the interface. Also,
implementations may raise a :exc:`ValueError` (or :exc:`UnsupportedOperation`)
when operations they do not support are called.
@ -379,8 +379,8 @@ I/O Base Classes
.. method:: readable()
Return ``True`` if the stream can be read from. If ``False``, :meth:`read`
will raise :exc:`OSError`.
Return ``True`` if the stream can be read from.
If ``False``, :meth:`!read` will raise :exc:`OSError`.
.. method:: readline(size=-1, /)
@ -401,25 +401,25 @@ I/O Base Classes
hint.
Note that it's already possible to iterate on file objects using ``for
line in file: ...`` without calling ``file.readlines()``.
line in file: ...`` without calling :meth:`!file.readlines`.
.. method:: seek(offset, whence=SEEK_SET, /)
Change the stream position to the given byte *offset*. *offset* is
interpreted relative to the position indicated by *whence*. The default
value for *whence* is :data:`SEEK_SET`. Values for *whence* are:
value for *whence* is :data:`!SEEK_SET`. Values for *whence* are:
* :data:`SEEK_SET` or ``0`` -- start of the stream (the default);
* :data:`!SEEK_SET` or ``0`` -- start of the stream (the default);
*offset* should be zero or positive
* :data:`SEEK_CUR` or ``1`` -- current stream position; *offset* may
* :data:`!SEEK_CUR` or ``1`` -- current stream position; *offset* may
be negative
* :data:`SEEK_END` or ``2`` -- end of the stream; *offset* is usually
* :data:`!SEEK_END` or ``2`` -- end of the stream; *offset* is usually
negative
Return the new absolute position.
.. versionadded:: 3.1
The ``SEEK_*`` constants.
The :data:`!SEEK_*` constants.
.. versionadded:: 3.3
Some operating systems could support additional values, like
@ -450,7 +450,7 @@ I/O Base Classes
.. method:: writable()
Return ``True`` if the stream supports writing. If ``False``,
:meth:`write` and :meth:`truncate` will raise :exc:`OSError`.
:meth:`!write` and :meth:`truncate` will raise :exc:`OSError`.
.. method:: writelines(lines, /)
@ -654,8 +654,9 @@ Raw File I/O
implies writing, so this mode behaves in a similar way to ``'w'``. Add a
``'+'`` to the mode to allow simultaneous reading and writing.
The :meth:`read` (when called with a positive argument), :meth:`readinto`
and :meth:`write` methods on this class will only make one system call.
The :meth:`~RawIOBase.read` (when called with a positive argument),
:meth:`~RawIOBase.readinto` and :meth:`~RawIOBase.write` methods on this
class will only make one system call.
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
@ -791,8 +792,8 @@ than raw I/O does.
object under various conditions, including:
* when the buffer gets too small for all pending data;
* when :meth:`flush()` is called;
* when a :meth:`seek()` is requested (for :class:`BufferedRandom` objects);
* when :meth:`flush` is called;
* when a :meth:`~IOBase.seek` is requested (for :class:`BufferedRandom` objects);
* when the :class:`BufferedWriter` object is closed or destroyed.
The constructor creates a :class:`BufferedWriter` for the given writeable
@ -826,8 +827,8 @@ than raw I/O does.
:data:`DEFAULT_BUFFER_SIZE`.
:class:`BufferedRandom` is capable of anything :class:`BufferedReader` or
:class:`BufferedWriter` can do. In addition, :meth:`seek` and :meth:`tell`
are guaranteed to be implemented.
:class:`BufferedWriter` can do. In addition, :meth:`~IOBase.seek` and
:meth:`~IOBase.tell` are guaranteed to be implemented.
.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)
@ -904,7 +905,7 @@ Text I/O
.. method:: readline(size=-1, /)
Read until newline or EOF and return a single ``str``. If the stream is
Read until newline or EOF and return a single :class:`str`. If the stream is
already at EOF, an empty string is returned.
If *size* is specified, at most *size* characters will be read.
@ -913,22 +914,22 @@ Text I/O
Change the stream position to the given *offset*. Behaviour depends on
the *whence* parameter. The default value for *whence* is
:data:`SEEK_SET`.
:data:`!SEEK_SET`.
* :data:`SEEK_SET` or ``0``: seek from the start of the stream
* :data:`!SEEK_SET` or ``0``: seek from the start of the stream
(the default); *offset* must either be a number returned by
:meth:`TextIOBase.tell`, or zero. Any other *offset* value
produces undefined behaviour.
* :data:`SEEK_CUR` or ``1``: "seek" to the current position;
* :data:`!SEEK_CUR` or ``1``: "seek" to the current position;
*offset* must be zero, which is a no-operation (all other values
are unsupported).
* :data:`SEEK_END` or ``2``: seek to the end of the stream;
* :data:`!SEEK_END` or ``2``: seek to the end of the stream;
*offset* must be zero (all other values are unsupported).
Return the new absolute position as an opaque number.
.. versionadded:: 3.1
The ``SEEK_*`` constants.
The :data:`!SEEK_*` constants.
.. method:: tell()
@ -988,10 +989,10 @@ Text I/O
takes place. If *newline* is any of the other legal values, any ``'\n'``
characters written are translated to the given string.
If *line_buffering* is ``True``, :meth:`flush` is implied when a call to
If *line_buffering* is ``True``, :meth:`~IOBase.flush` is implied when a call to
write contains a newline character or a carriage return.
If *write_through* is ``True``, calls to :meth:`write` are guaranteed
If *write_through* is ``True``, calls to :meth:`~BufferedIOBase.write` are guaranteed
not to be buffered: any data written on the :class:`TextIOWrapper`
object is immediately handled to its underlying binary *buffer*.
@ -1070,7 +1071,7 @@ Text I/O
.. method:: getvalue()
Return a ``str`` containing the entire contents of the buffer.
Return a :class:`str` containing the entire contents of the buffer.
Newlines are decoded as if by :meth:`~TextIOBase.read`, although
the stream position is not changed.
@ -1125,7 +1126,7 @@ Text I/O over a binary storage (such as a file) is significantly slower than
binary I/O over the same storage, because it requires conversions between
unicode and binary data using a character codec. This can become noticeable
handling huge amounts of text data like large log files. Also,
:meth:`TextIOWrapper.tell` and :meth:`TextIOWrapper.seek` are both quite slow
:meth:`~TextIOBase.tell` and :meth:`~TextIOBase.seek` are both quite slow
due to the reconstruction algorithm used.
:class:`StringIO`, however, is a native in-memory unicode container and will
@ -1135,7 +1136,7 @@ Multi-threading
^^^^^^^^^^^^^^^
:class:`FileIO` objects are thread-safe to the extent that the operating system
calls (such as ``read(2)`` under Unix) they wrap are thread-safe too.
calls (such as :manpage:`read(2)` under Unix) they wrap are thread-safe too.
Binary buffered objects (instances of :class:`BufferedReader`,
:class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`)

1
Doc/tools/.nitignore
View File

@ -89,7 +89,6 @@ Doc/library/http.server.rst
Doc/library/importlib.resources.rst
Doc/library/importlib.rst
Doc/library/inspect.rst
Doc/library/io.rst
Doc/library/locale.rst
Doc/library/logging.config.rst
Doc/library/logging.handlers.rst