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

gh-101100: Fix most Sphinx nitpicks in the glossary and `stdtypes.rst` (#112757)

This commit is contained in:
Alex Waygood 2023-12-06 08:44:06 +00:00 committed by GitHub
parent f8c0198e3b
commit e3f670e137
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 41 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
Doc/glossary.rst
View File

@ -151,9 +151,9 @@ Glossary
A :term:`file object` able to read and write
:term:`bytes-like objects <bytes-like object>`.
Examples of binary files are files opened in binary mode (``'rb'``,
``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer`,
:data:`sys.stdout.buffer`, and instances of :class:`io.BytesIO` and
:class:`gzip.GzipFile`.
``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer <sys.stdin>`,
:data:`sys.stdout.buffer <sys.stdout>`, and instances of
:class:`io.BytesIO` and :class:`gzip.GzipFile`.
See also :term:`text file` for a file object able to read and write
:class:`str` objects.
@ -304,8 +304,9 @@ Glossary
:ref:`class definitions <class>` for more about decorators.
descriptor
Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or
:meth:`__delete__`. When a class attribute is a descriptor, its special
Any object which defines the methods :meth:`~object.__get__`,
:meth:`~object.__set__`, or :meth:`~object.__delete__`.
When a class attribute is a descriptor, its special
binding behavior is triggered upon attribute lookup. Normally, using
*a.b* to get, set or delete an attribute looks up the object named *b* in
the class dictionary for *a*, but if *b* is a descriptor, the respective
@ -319,7 +320,8 @@ Glossary
dictionary
An associative array, where arbitrary keys are mapped to values. The
keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
keys can be any object with :meth:`~object.__hash__` and
:meth:`~object.__eq__` methods.
Called a hash in Perl.
dictionary comprehension
@ -383,7 +385,7 @@ Glossary
file object
An object exposing a file-oriented API (with methods such as
:meth:`read()` or :meth:`write()`) to an underlying resource. Depending
:meth:`!read` or :meth:`!write`) to an underlying resource. Depending
on the way it was created, a file object can mediate access to a real
on-disk file or to another type of storage or communication device
(for example standard input/output, in-memory buffers, sockets, pipes,
@ -559,8 +561,9 @@ Glossary
hashable
An object is *hashable* if it has a hash value which never changes during
its lifetime (it needs a :meth:`__hash__` method), and can be compared to
other objects (it needs an :meth:`__eq__` method). Hashable objects which
its lifetime (it needs a :meth:`~object.__hash__` method), and can be
compared to other objects (it needs an :meth:`~object.__eq__` method).
Hashable objects which
compare equal must have the same hash value.
Hashability makes an object usable as a dictionary key and a set member,
@ -646,7 +649,8 @@ Glossary
iterables include all sequence types (such as :class:`list`, :class:`str`,
and :class:`tuple`) and some non-sequence types like :class:`dict`,
:term:`file objects <file object>`, and objects of any classes you define
with an :meth:`__iter__` method or with a :meth:`~object.__getitem__` method
with an :meth:`~iterator.__iter__` method or with a
:meth:`~object.__getitem__` method
that implements :term:`sequence` semantics.
Iterables can be
@ -655,7 +659,7 @@ Glossary
as an argument to the built-in function :func:`iter`, it returns an
iterator for the object. This iterator is good for one pass over the set
of values. When using iterables, it is usually not necessary to call
:func:`iter` or deal with iterator objects yourself. The ``for``
:func:`iter` or deal with iterator objects yourself. The :keyword:`for`
statement does that automatically for you, creating a temporary unnamed
variable to hold the iterator for the duration of the loop. See also
:term:`iterator`, :term:`sequence`, and :term:`generator`.
@ -666,8 +670,8 @@ Glossary
:func:`next`) return successive items in the stream. When no more data
are available a :exc:`StopIteration` exception is raised instead. At this
point, the iterator object is exhausted and any further calls to its
:meth:`__next__` method just raise :exc:`StopIteration` again. Iterators
are required to have an :meth:`__iter__` method that returns the iterator
:meth:`!__next__` method just raise :exc:`StopIteration` again. Iterators
are required to have an :meth:`~iterator.__iter__` method that returns the iterator
object itself so every iterator is also iterable and may be used in most
places where other iterables are accepted. One notable exception is code
which attempts multiple iteration passes. A container object (such as a
@ -681,7 +685,7 @@ Glossary
.. impl-detail::
CPython does not consistently apply the requirement that an iterator
define :meth:`__iter__`.
define :meth:`~iterator.__iter__`.
key function
A key function or collation function is a callable that returns a value
@ -875,7 +879,8 @@ Glossary
Old name for the flavor of classes now used for all class objects. In
earlier Python versions, only new-style classes could use Python's newer,
versatile features like :attr:`~object.__slots__`, descriptors,
properties, :meth:`__getattribute__`, class methods, and static methods.
properties, :meth:`~object.__getattribute__`, class methods, and static
methods.
object
Any data with state (attributes or value) and defined behavior
@ -955,7 +960,7 @@ Glossary
finders implement.
path entry hook
A callable on the :data:`sys.path_hook` list which returns a :term:`path
A callable on the :data:`sys.path_hooks` list which returns a :term:`path
entry finder` if it knows how to find modules on a specific :term:`path
entry`.
@ -1089,18 +1094,18 @@ Glossary
sequence
An :term:`iterable` which supports efficient element access using integer
indices via the :meth:`~object.__getitem__` special method and defines a
:meth:`__len__` method that returns the length of the sequence.
:meth:`~object.__len__` method that returns the length of the sequence.
Some built-in sequence types are :class:`list`, :class:`str`,
:class:`tuple`, and :class:`bytes`. Note that :class:`dict` also
supports :meth:`~object.__getitem__` and :meth:`__len__`, but is considered a
supports :meth:`~object.__getitem__` and :meth:`!__len__`, but is considered a
mapping rather than a sequence because the lookups use arbitrary
:term:`immutable` keys rather than integers.
The :class:`collections.abc.Sequence` abstract base class
defines a much richer interface that goes beyond just
:meth:`~object.__getitem__` and :meth:`__len__`, adding :meth:`count`,
:meth:`index`, :meth:`__contains__`, and
:meth:`__reversed__`. Types that implement this expanded
:meth:`~object.__getitem__` and :meth:`~object.__len__`, adding
:meth:`count`, :meth:`index`, :meth:`~object.__contains__`, and
:meth:`~object.__reversed__`. Types that implement this expanded
interface can be registered explicitly using
:func:`~abc.ABCMeta.register`.

26
Doc/library/stdtypes.rst
View File

@ -44,7 +44,8 @@ Any object can be tested for truth value, for use in an :keyword:`if` or
.. index:: single: true
By default, an object is considered true unless its class defines either a
:meth:`~object.__bool__` method that returns ``False`` or a :meth:`__len__` method that
:meth:`~object.__bool__` method that returns ``False`` or a
:meth:`~object.__len__` method that
returns zero, when called with the object. [1]_ Here are most of the built-in
objects considered false:
@ -197,7 +198,7 @@ exception.
Two more operations with the same syntactic priority, :keyword:`in` and
:keyword:`not in`, are supported by types that are :term:`iterable` or
implement the :meth:`__contains__` method.
implement the :meth:`~object.__contains__` method.
.. _typesnumeric:
@ -717,7 +718,7 @@ that's defined for any rational number, and hence applies to all instances of
:class:`int` and :class:`fractions.Fraction`, and all finite instances of
:class:`float` and :class:`decimal.Decimal`. Essentially, this function is
given by reduction modulo ``P`` for a fixed prime ``P``. The value of ``P`` is
made available to Python as the :attr:`modulus` attribute of
made available to Python as the :attr:`~sys.hash_info.modulus` attribute of
:data:`sys.hash_info`.
.. impl-detail::
@ -906,9 +907,9 @@ Generator Types
---------------
Python's :term:`generator`\s provide a convenient way to implement the iterator
protocol. If a container object's :meth:`__iter__` method is implemented as a
protocol. If a container object's :meth:`~iterator.__iter__` method is implemented as a
generator, it will automatically return an iterator object (technically, a
generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__`
generator object) supplying the :meth:`!__iter__` and :meth:`~generator.__next__`
methods.
More information about generators can be found in :ref:`the documentation for
the yield expression <yieldexpr>`.
@ -3672,7 +3673,7 @@ The conversion types are:
+------------+-----------------------------------------------------+-------+
| ``'b'`` | Bytes (any object that follows the | \(5) |
| | :ref:`buffer protocol <bufferobjects>` or has | |
| | :meth:`__bytes__`). | |
| | :meth:`~object.__bytes__`). | |
+------------+-----------------------------------------------------+-------+
| ``'s'`` | ``'s'`` is an alias for ``'b'`` and should only | \(6) |
| | be used for Python2/3 code bases. | |
@ -4410,7 +4411,8 @@ The constructors for both classes work the same:
:meth:`symmetric_difference_update` methods will accept any iterable as an
argument.
Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and
Note, the *elem* argument to the :meth:`~object.__contains__`,
:meth:`remove`, and
:meth:`discard` methods may be a set. To support searching for an equivalent
frozenset, a temporary one is created from *elem*.
@ -5236,9 +5238,11 @@ instantiated from the type::
TypeError: cannot create 'types.UnionType' instances
.. note::
The :meth:`__or__` method for type objects was added to support the syntax
``X | Y``. If a metaclass implements :meth:`__or__`, the Union may
override it::
The :meth:`!__or__` method for type objects was added to support the syntax
``X | Y``. If a metaclass implements :meth:`!__or__`, the Union may
override it:
.. doctest::
>>> class M(type):
... def __or__(self, other):
@ -5250,7 +5254,7 @@ instantiated from the type::
>>> C | int
'Hello'
>>> int | C
int | __main__.C
int | C
.. seealso::