Skip to content

Commit 02d0951

Browse files
[3.11] gh-101100: Fix most Sphinx nitpicks in the glossary and stdtypes.rst (GH-112757) (#112790)
gh-101100: Fix most Sphinx nitpicks in the glossary and `stdtypes.rst` (GH-112757) (cherry picked from commit e3f670e) Co-authored-by: Alex Waygood <[email protected]>
1 parent f92c8bf commit 02d0951

File tree

2 files changed

+41
-32
lines changed

2 files changed

+41
-32
lines changed

Doc/glossary.rst

Lines changed: 26 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -160,9 +160,9 @@ Glossary
160160
A :term:`file object` able to read and write
161161
:term:`bytes-like objects <bytes-like object>`.
162162
Examples of binary files are files opened in binary mode (``'rb'``,
163-
``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer`,
164-
:data:`sys.stdout.buffer`, and instances of :class:`io.BytesIO` and
165-
:class:`gzip.GzipFile`.
163+
``'wb'`` or ``'rb+'``), :data:`sys.stdin.buffer <sys.stdin>`,
164+
:data:`sys.stdout.buffer <sys.stdout>`, and instances of
165+
:class:`io.BytesIO` and :class:`gzip.GzipFile`.
166166

167167
See also :term:`text file` for a file object able to read and write
168168
:class:`str` objects.
@@ -313,8 +313,9 @@ Glossary
313313
:ref:`class definitions <class>` for more about decorators.
314314

315315
descriptor
316-
Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or
317-
:meth:`__delete__`. When a class attribute is a descriptor, its special
316+
Any object which defines the methods :meth:`~object.__get__`,
317+
:meth:`~object.__set__`, or :meth:`~object.__delete__`.
318+
When a class attribute is a descriptor, its special
318319
binding behavior is triggered upon attribute lookup. Normally, using
319320
*a.b* to get, set or delete an attribute looks up the object named *b* in
320321
the class dictionary for *a*, but if *b* is a descriptor, the respective
@@ -328,7 +329,8 @@ Glossary
328329

329330
dictionary
330331
An associative array, where arbitrary keys are mapped to values. The
331-
keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
332+
keys can be any object with :meth:`~object.__hash__` and
333+
:meth:`~object.__eq__` methods.
332334
Called a hash in Perl.
333335

334336
dictionary comprehension
@@ -392,7 +394,7 @@ Glossary
392394

393395
file object
394396
An object exposing a file-oriented API (with methods such as
395-
:meth:`read()` or :meth:`write()`) to an underlying resource. Depending
397+
:meth:`!read` or :meth:`!write`) to an underlying resource. Depending
396398
on the way it was created, a file object can mediate access to a real
397399
on-disk file or to another type of storage or communication device
398400
(for example standard input/output, in-memory buffers, sockets, pipes,
@@ -568,8 +570,9 @@ Glossary
568570

569571
hashable
570572
An object is *hashable* if it has a hash value which never changes during
571-
its lifetime (it needs a :meth:`__hash__` method), and can be compared to
572-
other objects (it needs an :meth:`__eq__` method). Hashable objects which
573+
its lifetime (it needs a :meth:`~object.__hash__` method), and can be
574+
compared to other objects (it needs an :meth:`~object.__eq__` method).
575+
Hashable objects which
573576
compare equal must have the same hash value.
574577

575578
Hashability makes an object usable as a dictionary key and a set member,
@@ -645,7 +648,8 @@ Glossary
645648
iterables include all sequence types (such as :class:`list`, :class:`str`,
646649
and :class:`tuple`) and some non-sequence types like :class:`dict`,
647650
:term:`file objects <file object>`, and objects of any classes you define
648-
with an :meth:`__iter__` method or with a :meth:`~object.__getitem__` method
651+
with an :meth:`~iterator.__iter__` method or with a
652+
:meth:`~object.__getitem__` method
649653
that implements :term:`sequence` semantics.
650654

651655
Iterables can be
@@ -654,7 +658,7 @@ Glossary
654658
as an argument to the built-in function :func:`iter`, it returns an
655659
iterator for the object. This iterator is good for one pass over the set
656660
of values. When using iterables, it is usually not necessary to call
657-
:func:`iter` or deal with iterator objects yourself. The ``for``
661+
:func:`iter` or deal with iterator objects yourself. The :keyword:`for`
658662
statement does that automatically for you, creating a temporary unnamed
659663
variable to hold the iterator for the duration of the loop. See also
660664
:term:`iterator`, :term:`sequence`, and :term:`generator`.
@@ -665,8 +669,8 @@ Glossary
665669
:func:`next`) return successive items in the stream. When no more data
666670
are available a :exc:`StopIteration` exception is raised instead. At this
667671
point, the iterator object is exhausted and any further calls to its
668-
:meth:`__next__` method just raise :exc:`StopIteration` again. Iterators
669-
are required to have an :meth:`__iter__` method that returns the iterator
672+
:meth:`!__next__` method just raise :exc:`StopIteration` again. Iterators
673+
are required to have an :meth:`~iterator.__iter__` method that returns the iterator
670674
object itself so every iterator is also iterable and may be used in most
671675
places where other iterables are accepted. One notable exception is code
672676
which attempts multiple iteration passes. A container object (such as a
@@ -680,7 +684,7 @@ Glossary
680684
.. impl-detail::
681685

682686
CPython does not consistently apply the requirement that an iterator
683-
define :meth:`__iter__`.
687+
define :meth:`~iterator.__iter__`.
684688

685689
key function
686690
A key function or collation function is a callable that returns a value
@@ -874,7 +878,8 @@ Glossary
874878
Old name for the flavor of classes now used for all class objects. In
875879
earlier Python versions, only new-style classes could use Python's newer,
876880
versatile features like :attr:`~object.__slots__`, descriptors,
877-
properties, :meth:`__getattribute__`, class methods, and static methods.
881+
properties, :meth:`~object.__getattribute__`, class methods, and static
882+
methods.
878883

879884
object
880885
Any data with state (attributes or value) and defined behavior
@@ -954,7 +959,7 @@ Glossary
954959
finders implement.
955960

956961
path entry hook
957-
A callable on the :data:`sys.path_hook` list which returns a :term:`path
962+
A callable on the :data:`sys.path_hooks` list which returns a :term:`path
958963
entry finder` if it knows how to find modules on a specific :term:`path
959964
entry`.
960965

@@ -1086,18 +1091,18 @@ Glossary
10861091
sequence
10871092
An :term:`iterable` which supports efficient element access using integer
10881093
indices via the :meth:`~object.__getitem__` special method and defines a
1089-
:meth:`__len__` method that returns the length of the sequence.
1094+
:meth:`~object.__len__` method that returns the length of the sequence.
10901095
Some built-in sequence types are :class:`list`, :class:`str`,
10911096
:class:`tuple`, and :class:`bytes`. Note that :class:`dict` also
1092-
supports :meth:`~object.__getitem__` and :meth:`__len__`, but is considered a
1097+
supports :meth:`~object.__getitem__` and :meth:`!__len__`, but is considered a
10931098
mapping rather than a sequence because the lookups use arbitrary
10941099
:term:`immutable` keys rather than integers.
10951100

10961101
The :class:`collections.abc.Sequence` abstract base class
10971102
defines a much richer interface that goes beyond just
1098-
:meth:`~object.__getitem__` and :meth:`__len__`, adding :meth:`count`,
1099-
:meth:`index`, :meth:`__contains__`, and
1100-
:meth:`__reversed__`. Types that implement this expanded
1103+
:meth:`~object.__getitem__` and :meth:`~object.__len__`, adding
1104+
:meth:`count`, :meth:`index`, :meth:`~object.__contains__`, and
1105+
:meth:`~object.__reversed__`. Types that implement this expanded
11011106
interface can be registered explicitly using
11021107
:func:`~abc.ABCMeta.register`.
11031108

Doc/library/stdtypes.rst

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,8 @@ Any object can be tested for truth value, for use in an :keyword:`if` or
4444
.. index:: single: true
4545

4646
By default, an object is considered true unless its class defines either a
47-
:meth:`~object.__bool__` method that returns ``False`` or a :meth:`__len__` method that
47+
:meth:`~object.__bool__` method that returns ``False`` or a
48+
:meth:`~object.__len__` method that
4849
returns zero, when called with the object. [1]_ Here are most of the built-in
4950
objects considered false:
5051

@@ -197,7 +198,7 @@ exception.
197198

198199
Two more operations with the same syntactic priority, :keyword:`in` and
199200
:keyword:`not in`, are supported by types that are :term:`iterable` or
200-
implement the :meth:`__contains__` method.
201+
implement the :meth:`~object.__contains__` method.
201202

202203
.. _typesnumeric:
203204

@@ -711,7 +712,7 @@ that's defined for any rational number, and hence applies to all instances of
711712
:class:`int` and :class:`fractions.Fraction`, and all finite instances of
712713
:class:`float` and :class:`decimal.Decimal`. Essentially, this function is
713714
given by reduction modulo ``P`` for a fixed prime ``P``. The value of ``P`` is
714-
made available to Python as the :attr:`modulus` attribute of
715+
made available to Python as the :attr:`~sys.hash_info.modulus` attribute of
715716
:data:`sys.hash_info`.
716717

717718
.. impl-detail::
@@ -866,9 +867,9 @@ Generator Types
866867
---------------
867868

868869
Python's :term:`generator`\s provide a convenient way to implement the iterator
869-
protocol. If a container object's :meth:`__iter__` method is implemented as a
870+
protocol. If a container object's :meth:`~iterator.__iter__` method is implemented as a
870871
generator, it will automatically return an iterator object (technically, a
871-
generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__`
872+
generator object) supplying the :meth:`!__iter__` and :meth:`~generator.__next__`
872873
methods.
873874
More information about generators can be found in :ref:`the documentation for
874875
the yield expression <yieldexpr>`.
@@ -3624,7 +3625,7 @@ The conversion types are:
36243625
+------------+-----------------------------------------------------+-------+
36253626
| ``'b'`` | Bytes (any object that follows the | \(5) |
36263627
| | :ref:`buffer protocol <bufferobjects>` or has | |
3627-
| | :meth:`__bytes__`). | |
3628+
| | :meth:`~object.__bytes__`). | |
36283629
+------------+-----------------------------------------------------+-------+
36293630
| ``'s'`` | ``'s'`` is an alias for ``'b'`` and should only | \(6) |
36303631
| | be used for Python2/3 code bases. | |
@@ -4359,7 +4360,8 @@ The constructors for both classes work the same:
43594360
:meth:`symmetric_difference_update` methods will accept any iterable as an
43604361
argument.
43614362

4362-
Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and
4363+
Note, the *elem* argument to the :meth:`~object.__contains__`,
4364+
:meth:`remove`, and
43634365
:meth:`discard` methods may be a set. To support searching for an equivalent
43644366
frozenset, a temporary one is created from *elem*.
43654367

@@ -5178,9 +5180,11 @@ instantiated from the type::
51785180
TypeError: cannot create 'types.UnionType' instances
51795181

51805182
.. note::
5181-
The :meth:`__or__` method for type objects was added to support the syntax
5182-
``X | Y``. If a metaclass implements :meth:`__or__`, the Union may
5183-
override it::
5183+
The :meth:`!__or__` method for type objects was added to support the syntax
5184+
``X | Y``. If a metaclass implements :meth:`!__or__`, the Union may
5185+
override it:
5186+
5187+
.. doctest::
51845188

51855189
>>> class M(type):
51865190
... def __or__(self, other):
@@ -5192,7 +5196,7 @@ instantiated from the type::
51925196
>>> C | int
51935197
'Hello'
51945198
>>> int | C
5195-
int | __main__.C
5199+
int | C
51965200

51975201
.. seealso::
51985202

0 commit comments

Comments
 (0)