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

gh-101100: Fix Sphinx nitpicks in `library/functions.rst` (#112669)

This commit is contained in:
Alex Waygood 2023-12-04 11:05:20 +00:00 committed by GitHub
parent a74902a14c
commit cda737924f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 67 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
Doc/library/functions.rst
View File

@ -57,7 +57,8 @@ are always available. They are listed here in alphabetical order.
.. function:: abs(x)
Return the absolute value of a number. The argument may be an
integer, a floating point number, or an object implementing :meth:`__abs__`.
integer, a floating point number, or an object implementing
:meth:`~object.__abs__`.
If the argument is a complex number, its magnitude is returned.
@ -235,7 +236,7 @@ are always available. They are listed here in alphabetical order.
:const:`False` if not. If this returns ``True``, it is still possible that a
call fails, but if it is ``False``, calling *object* will never succeed.
Note that classes are callable (calling a class returns a new instance);
instances are callable if their class has a :meth:`__call__` method.
instances are callable if their class has a :meth:`~object.__call__` method.
.. versionadded:: 3.2
This function was first removed in Python 3.0 and then brought back
@ -432,15 +433,18 @@ are always available. They are listed here in alphabetical order.
Without arguments, return the list of names in the current local scope. With an
argument, attempt to return a list of valid attributes for that object.
If the object has a method named :meth:`__dir__`, this method will be called and
If the object has a method named :meth:`~object.__dir__`,
this method will be called and
must return the list of attributes. This allows objects that implement a custom
:func:`__getattr__` or :func:`__getattribute__` function to customize the way
:func:`~object.__getattr__` or :func:`~object.__getattribute__` function
to customize the way
:func:`dir` reports their attributes.
If the object does not provide :meth:`__dir__`, the function tries its best to
gather information from the object's :attr:`~object.__dict__` attribute, if defined, and
If the object does not provide :meth:`~object.__dir__`,
the function tries its best to gather information from the object's
:attr:`~object.__dict__` attribute, if defined, and
from its type object. The resulting list is not necessarily complete and may
be inaccurate when the object has a custom :func:`__getattr__`.
be inaccurate when the object has a custom :func:`~object.__getattr__`.
The default :func:`dir` mechanism behaves differently with different types of
objects, as it attempts to produce the most relevant, rather than complete,
@ -664,7 +668,7 @@ are always available. They are listed here in alphabetical order.
sign: "+" | "-"
infinity: "Infinity" | "inf"
nan: "nan"
digitpart: `digit` (["_"] `digit`)*
digitpart: `!digit` (["_"] `!digit`)*
number: [`digitpart`] "." `digitpart` | `digitpart` ["."]
exponent: ("e" | "E") ["+" | "-"] `digitpart`
floatnumber: number [`exponent`]
@ -727,8 +731,8 @@ are always available. They are listed here in alphabetical order.
A call to ``format(value, format_spec)`` is translated to
``type(value).__format__(value, format_spec)`` which bypasses the instance
dictionary when searching for the value's :meth:`__format__` method. A
:exc:`TypeError` exception is raised if the method search reaches
dictionary when searching for the value's :meth:`~object.__format__` method.
A :exc:`TypeError` exception is raised if the method search reaches
:mod:`object` and the *format_spec* is non-empty, or if either the
*format_spec* or the return value are not strings.
@ -792,9 +796,9 @@ are always available. They are listed here in alphabetical order.
.. note::
For objects with custom :meth:`__hash__` methods, note that :func:`hash`
For objects with custom :meth:`~object.__hash__` methods,
note that :func:`hash`
truncates the return value based on the bit width of the host machine.
See :meth:`__hash__ <object.__hash__>` for details.
.. function:: help()
help(request)
@ -982,7 +986,8 @@ are always available. They are listed here in alphabetical order.
Return an :term:`iterator` object. The first argument is interpreted very
differently depending on the presence of the second argument. Without a
second argument, *object* must be a collection object which supports the
:term:`iterable` protocol (the :meth:`__iter__` method), or it must support
:term:`iterable` protocol (the :meth:`~object.__iter__` method),
or it must support
the sequence protocol (the :meth:`~object.__getitem__` method with integer arguments
starting at ``0``). If it does not support either of those protocols,
:exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
@ -1500,38 +1505,44 @@ are always available. They are listed here in alphabetical order.
"""Get the current voltage."""
return self._voltage
The ``@property`` decorator turns the :meth:`voltage` method into a "getter"
The ``@property`` decorator turns the :meth:`!voltage` method into a "getter"
for a read-only attribute with the same name, and it sets the docstring for
*voltage* to "Get the current voltage."
A property object has :attr:`~property.getter`, :attr:`~property.setter`,
and :attr:`~property.deleter` methods usable as decorators that create a
copy of the property with the corresponding accessor function set to the
decorated function. This is best explained with an example::
.. decorator:: property.getter
.. decorator:: property.setter
.. decorator:: property.deleter
class C:
def __init__(self):
self._x = None
A property object has ``getter``, ``setter``,
and ``deleter`` methods usable as decorators that create a
copy of the property with the corresponding accessor function set to the
decorated function. This is best explained with an example:
@property
def x(self):
"""I'm the 'x' property."""
return self._x
.. testcode::
@x.setter
def x(self, value):
self._x = value
class C:
def __init__(self):
self._x = None
@x.deleter
def x(self):
del self._x
@property
def x(self):
"""I'm the 'x' property."""
return self._x
This code is exactly equivalent to the first example. Be sure to give the
additional functions the same name as the original property (``x`` in this
case.)
@x.setter
def x(self, value):
self._x = value
The returned property object also has the attributes ``fget``, ``fset``, and
``fdel`` corresponding to the constructor arguments.
@x.deleter
def x(self):
del self._x
This code is exactly equivalent to the first example. Be sure to give the
additional functions the same name as the original property (``x`` in this
case.)
The returned property object also has the attributes ``fget``, ``fset``, and
``fdel`` corresponding to the constructor arguments.
.. versionchanged:: 3.5
The docstrings of property objects are now writeable.
@ -1554,7 +1565,8 @@ are always available. They are listed here in alphabetical order.
representation is a string enclosed in angle brackets that contains the name
of the type of the object together with additional information often
including the name and address of the object. A class can control what this
function returns for its instances by defining a :meth:`__repr__` method.
function returns for its instances
by defining a :meth:`~object.__repr__` method.
If :func:`sys.displayhook` is not accessible, this function will raise
:exc:`RuntimeError`.
@ -1562,9 +1574,9 @@ are always available. They are listed here in alphabetical order.
.. function:: reversed(seq)
Return a reverse :term:`iterator`. *seq* must be an object which has
a :meth:`__reversed__` method or supports the sequence protocol (the
:meth:`__len__` method and the :meth:`~object.__getitem__` method with integer
arguments starting at ``0``).
a :meth:`~object.__reversed__` method or supports the sequence protocol (the
:meth:`~object.__len__` method and the :meth:`~object.__getitem__` method
with integer arguments starting at ``0``).
.. function:: round(number, ndigits=None)
@ -1635,13 +1647,21 @@ are always available. They are listed here in alphabetical order.
Return a :term:`slice` object representing the set of indices specified by
``range(start, stop, step)``. The *start* and *step* arguments default to
``None``. Slice objects have read-only data attributes :attr:`~slice.start`,
:attr:`~slice.stop`, and :attr:`~slice.step` which merely return the argument
values (or their default). They have no other explicit functionality;
however, they are used by NumPy and other third-party packages.
``None``.
.. attribute:: slice.start
.. attribute:: slice.stop
.. attribute:: slice.step
Slice objects have read-only data attributes :attr:`!start`,
:attr:`!stop`, and :attr:`!step` which merely return the argument
values (or their default). They have no other explicit functionality;
however, they are used by NumPy and other third-party packages.
Slice objects are also generated when extended indexing syntax is used. For
example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See
:func:`itertools.islice` for an alternate version that returns an iterator.
:func:`itertools.islice` for an alternate version that returns an
:term:`iterator`.
.. versionchanged:: 3.12
Slice objects are now :term:`hashable` (provided :attr:`~slice.start`,
@ -1808,7 +1828,8 @@ are always available. They are listed here in alphabetical order.
Note that :func:`super` is implemented as part of the binding process for
explicit dotted attribute lookups such as ``super().__getitem__(name)``.
It does so by implementing its own :meth:`__getattribute__` method for searching
It does so by implementing its own :meth:`~object.__getattribute__` method
for searching
classes in a predictable order that supports cooperative multiple inheritance.
Accordingly, :func:`super` is undefined for implicit lookups using statements or
operators such as ``super()[name]``.

1
Doc/tools/.nitignore
View File

@ -56,7 +56,6 @@ Doc/library/exceptions.rst
Doc/library/faulthandler.rst
Doc/library/fcntl.rst
Doc/library/ftplib.rst
Doc/library/functions.rst
Doc/library/functools.rst
Doc/library/http.client.rst
Doc/library/http.cookiejar.rst