Skip to content

Commit c0521fe

Browse files
authored
bpo-45840: Improve cross-references in the data model documentation (GH-29633)
1 parent 2b318ce commit c0521fe

File tree

2 files changed

+77
-54
lines changed

2 files changed

+77
-54
lines changed

Doc/reference/datamodel.rst

Lines changed: 76 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -188,7 +188,7 @@ Ellipsis
188188
representation in computers.
189189

190190
The string representations of the numeric classes, computed by
191-
:meth:`__repr__` and :meth:`__str__`, have the following
191+
:meth:`~object.__repr__` and :meth:`~object.__str__`, have the following
192192
properties:
193193

194194
* They are valid numeric literals which, when passed to their
@@ -677,7 +677,8 @@ Callable types
677677
returns an :term:`asynchronous iterator` object which can be used in an
678678
:keyword:`async for` statement to execute the body of the function.
679679

680-
Calling the asynchronous iterator's :meth:`aiterator.__anext__` method
680+
Calling the asynchronous iterator's
681+
:meth:`aiterator.__anext__ <object.__anext__>` method
681682
will return an :term:`awaitable` which when awaited
682683
will execute until it provides a value using the :keyword:`yield`
683684
expression. When the function executes an empty :keyword:`return`
@@ -715,13 +716,13 @@ Callable types
715716
Classes
716717
Classes are callable. These objects normally act as factories for new
717718
instances of themselves, but variations are possible for class types that
718-
override :meth:`__new__`. The arguments of the call are passed to
719-
:meth:`__new__` and, in the typical case, to :meth:`__init__` to
719+
override :meth:`~object.__new__`. The arguments of the call are passed to
720+
:meth:`__new__` and, in the typical case, to :meth:`~object.__init__` to
720721
initialize the new instance.
721722

722723
Class Instances
723724
Instances of arbitrary classes can be made callable by defining a
724-
:meth:`__call__` method in their class.
725+
:meth:`~object.__call__` method in their class.
725726

726727

727728
Modules
@@ -880,14 +881,14 @@ Class instances
880881
section :ref:`descriptors` for another way in which attributes of a class
881882
retrieved via its instances may differ from the objects actually stored in
882883
the class's :attr:`~object.__dict__`. If no class attribute is found, and the
883-
object's class has a :meth:`__getattr__` method, that is called to satisfy
884+
object's class has a :meth:`~object.__getattr__` method, that is called to satisfy
884885
the lookup.
885886

886887
.. index:: triple: class instance; attribute; assignment
887888

888889
Attribute assignments and deletions update the instance's dictionary, never a
889-
class's dictionary. If the class has a :meth:`__setattr__` or
890-
:meth:`__delattr__` method, this is called instead of updating the instance
890+
class's dictionary. If the class has a :meth:`~object.__setattr__` or
891+
:meth:`~object.__delattr__` method, this is called instead of updating the instance
891892
dictionary directly.
892893

893894
.. index::
@@ -1176,7 +1177,8 @@ Internal types
11761177
Slice objects
11771178
.. index:: builtin: slice
11781179

1179-
Slice objects are used to represent slices for :meth:`__getitem__`
1180+
Slice objects are used to represent slices for
1181+
:meth:`~object.__getitem__`
11801182
methods. They are also created by the built-in :func:`slice` function.
11811183

11821184
.. index::
@@ -1229,17 +1231,18 @@ A class can implement certain operations that are invoked by special syntax
12291231
(such as arithmetic operations or subscripting and slicing) by defining methods
12301232
with special names. This is Python's approach to :dfn:`operator overloading`,
12311233
allowing classes to define their own behavior with respect to language
1232-
operators. For instance, if a class defines a method named :meth:`__getitem__`,
1234+
operators. For instance, if a class defines a method named
1235+
:meth:`~object.__getitem__`,
12331236
and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent
12341237
to ``type(x).__getitem__(x, i)``. Except where mentioned, attempts to execute an
12351238
operation raise an exception when no appropriate method is defined (typically
12361239
:exc:`AttributeError` or :exc:`TypeError`).
12371240

12381241
Setting a special method to ``None`` indicates that the corresponding
12391242
operation is not available. For example, if a class sets
1240-
:meth:`__iter__` to ``None``, the class is not iterable, so calling
1243+
:meth:`~object.__iter__` to ``None``, the class is not iterable, so calling
12411244
:func:`iter` on its instances will raise a :exc:`TypeError` (without
1242-
falling back to :meth:`__getitem__`). [#]_
1245+
falling back to :meth:`~object.__getitem__`). [#]_
12431246

12441247
When implementing a class that emulates any built-in type, it is important that
12451248
the emulation only be implemented to the degree that it makes sense for the
@@ -1789,7 +1792,8 @@ Invoking Descriptors
17891792

17901793
In general, a descriptor is an object attribute with "binding behavior", one
17911794
whose attribute access has been overridden by methods in the descriptor
1792-
protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of
1795+
protocol: :meth:`~object.__get__`, :meth:`~object.__set__`, and
1796+
:meth:`~object.__delete__`. If any of
17931797
those methods are defined for an object, it is said to be a descriptor.
17941798

17951799
The default behavior for attribute access is to get, set, or delete the
@@ -1853,7 +1857,8 @@ Super Binding
18531857

18541858
For instance bindings, the precedence of descriptor invocation depends on
18551859
which descriptor methods are defined. A descriptor can define any combination
1856-
of :meth:`__get__`, :meth:`__set__` and :meth:`__delete__`. If it does not
1860+
of :meth:`~object.__get__`, :meth:`~object.__set__` and
1861+
:meth:`~object.__delete__`. If it does not
18571862
define :meth:`__get__`, then accessing the attribute will return the descriptor
18581863
object itself unless there is a value in the object's instance dictionary. If
18591864
the descriptor defines :meth:`__set__` and/or :meth:`__delete__`, it is a data
@@ -1864,7 +1869,8 @@ descriptors have just the :meth:`__get__` method. Data descriptors with
18641869
instance dictionary. In contrast, non-data descriptors can be overridden by
18651870
instances.
18661871

1867-
Python methods (including :func:`staticmethod` and :func:`classmethod`) are
1872+
Python methods (including those decorated with
1873+
:func:`@staticmethod <staticmethod>` and :func:`@classmethod <classmethod>`) are
18681874
implemented as non-data descriptors. Accordingly, instances can redefine and
18691875
override methods. This allows individual instances to acquire behaviors that
18701876
differ from other instances of the same class.
@@ -1879,46 +1885,50 @@ __slots__
18791885
^^^^^^^^^
18801886

18811887
*__slots__* allow us to explicitly declare data members (like
1882-
properties) and deny the creation of *__dict__* and *__weakref__*
1888+
properties) and deny the creation of :attr:`~object.__dict__` and *__weakref__*
18831889
(unless explicitly declared in *__slots__* or available in a parent.)
18841890

1885-
The space saved over using *__dict__* can be significant.
1891+
The space saved over using :attr:`~object.__dict__` can be significant.
18861892
Attribute lookup speed can be significantly improved as well.
18871893

18881894
.. data:: object.__slots__
18891895

18901896
This class variable can be assigned a string, iterable, or sequence of
18911897
strings with variable names used by instances. *__slots__* reserves space
1892-
for the declared variables and prevents the automatic creation of *__dict__*
1898+
for the declared variables and prevents the automatic creation of
1899+
:attr:`~object.__dict__`
18931900
and *__weakref__* for each instance.
18941901

18951902

18961903
Notes on using *__slots__*
18971904
""""""""""""""""""""""""""
18981905

1899-
* When inheriting from a class without *__slots__*, the *__dict__* and
1906+
* When inheriting from a class without *__slots__*, the
1907+
:attr:`~object.__dict__` and
19001908
*__weakref__* attribute of the instances will always be accessible.
19011909

1902-
* Without a *__dict__* variable, instances cannot be assigned new variables not
1910+
* Without a :attr:`~object.__dict__` variable, instances cannot be assigned new
1911+
variables not
19031912
listed in the *__slots__* definition. Attempts to assign to an unlisted
19041913
variable name raises :exc:`AttributeError`. If dynamic assignment of new
19051914
variables is desired, then add ``'__dict__'`` to the sequence of strings in
19061915
the *__slots__* declaration.
19071916

19081917
* Without a *__weakref__* variable for each instance, classes defining
1909-
*__slots__* do not support weak references to its instances. If weak reference
1918+
*__slots__* do not support :mod:`weak references <weakref>` to its instances.
1919+
If weak reference
19101920
support is needed, then add ``'__weakref__'`` to the sequence of strings in the
19111921
*__slots__* declaration.
19121922

1913-
* *__slots__* are implemented at the class level by creating descriptors
1914-
(:ref:`descriptors`) for each variable name. As a result, class attributes
1923+
* *__slots__* are implemented at the class level by creating :ref:`descriptors <descriptors>`
1924+
for each variable name. As a result, class attributes
19151925
cannot be used to set default values for instance variables defined by
19161926
*__slots__*; otherwise, the class attribute would overwrite the descriptor
19171927
assignment.
19181928

19191929
* The action of a *__slots__* declaration is not limited to the class
19201930
where it is defined. *__slots__* declared in parents are available in
1921-
child classes. However, child subclasses will get a *__dict__* and
1931+
child classes. However, child subclasses will get a :attr:`~object.__dict__` and
19221932
*__weakref__* unless they also define *__slots__* (which should only
19231933
contain names of any *additional* slots).
19241934

@@ -1934,14 +1944,17 @@ Notes on using *__slots__*
19341944
used; however, in the future, special meaning may be assigned to the values
19351945
corresponding to each key.
19361946

1937-
* *__class__* assignment works only if both classes have the same *__slots__*.
1947+
* :attr:`~instance.__class__` assignment works only if both classes have the
1948+
same *__slots__*.
19381949

1939-
* Multiple inheritance with multiple slotted parent classes can be used,
1950+
* :ref:`Multiple inheritance <tut-multiple>` with multiple slotted parent
1951+
classes can be used,
19401952
but only one parent is allowed to have attributes created by slots
19411953
(the other bases must have empty slot layouts) - violations raise
19421954
:exc:`TypeError`.
19431955

1944-
* If an iterator is used for *__slots__* then a descriptor is created for each
1956+
* If an :term:`iterator` is used for *__slots__* then a :term:`descriptor` is
1957+
created for each
19451958
of the iterator's values. However, the *__slots__* attribute will be an empty
19461959
iterator.
19471960

@@ -1950,7 +1963,7 @@ Notes on using *__slots__*
19501963
Customizing class creation
19511964
--------------------------
19521965

1953-
Whenever a class inherits from another class, *__init_subclass__* is
1966+
Whenever a class inherits from another class, :meth:`~object.__init_subclass__` is
19541967
called on that class. This way, it is possible to write classes which
19551968
change the behavior of subclasses. This is closely related to class
19561969
decorators, but where class decorators only affect the specific class they're
@@ -1991,7 +2004,7 @@ class defining the method.
19912004

19922005

19932006
When a class is created, :meth:`type.__new__` scans the class variables
1994-
and makes callbacks to those with a :meth:`__set_name__` hook.
2007+
and makes callbacks to those with a :meth:`~object.__set_name__` hook.
19952008

19962009
.. method:: object.__set_name__(self, owner, name)
19972010

@@ -2103,7 +2116,8 @@ Once the appropriate metaclass has been identified, then the class namespace
21032116
is prepared. If the metaclass has a ``__prepare__`` attribute, it is called
21042117
as ``namespace = metaclass.__prepare__(name, bases, **kwds)`` (where the
21052118
additional keyword arguments, if any, come from the class definition). The
2106-
``__prepare__`` method should be implemented as a :func:`classmethod`. The
2119+
``__prepare__`` method should be implemented as a
2120+
:func:`classmethod <classmethod>`. The
21072121
namespace returned by ``__prepare__`` is passed in to ``__new__``, but when
21082122
the final class object is created the namespace is copied into a new ``dict``.
21092123

@@ -2401,31 +2415,36 @@ Emulating container types
24012415
-------------------------
24022416

24032417
The following methods can be defined to implement container objects. Containers
2404-
usually are sequences (such as lists or tuples) or mappings (like dictionaries),
2418+
usually are :term:`sequences <sequence>` (such as :class:`lists <list>` or
2419+
:class:`tuples <tuple>`) or :term:`mappings <mapping>` (like
2420+
:class:`dictionaries <dict>`),
24052421
but can represent other containers as well. The first set of methods is used
24062422
either to emulate a sequence or to emulate a mapping; the difference is that for
24072423
a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
2408-
N`` where *N* is the length of the sequence, or slice objects, which define a
2424+
N`` where *N* is the length of the sequence, or :class:`slice` objects, which define a
24092425
range of items. It is also recommended that mappings provide the methods
24102426
:meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`,
24112427
:meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`!copy`, and
2412-
:meth:`update` behaving similar to those for Python's standard dictionary
2428+
:meth:`update` behaving similar to those for Python's standard :class:`dictionary <dict>`
24132429
objects. The :mod:`collections.abc` module provides a
24142430
:class:`~collections.abc.MutableMapping`
2415-
abstract base class to help create those methods from a base set of
2416-
:meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and :meth:`keys`.
2431+
:term:`abstract base class` to help create those methods from a base set of
2432+
:meth:`~object.__getitem__`, :meth:`~object.__setitem__`, :meth:`~object.__delitem__`, and :meth:`keys`.
24172433
Mutable sequences should provide methods :meth:`append`, :meth:`count`,
24182434
:meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`,
2419-
:meth:`reverse` and :meth:`sort`, like Python standard list objects. Finally,
2435+
:meth:`reverse` and :meth:`sort`, like Python standard :class:`list`
2436+
objects. Finally,
24202437
sequence types should implement addition (meaning concatenation) and
2421-
multiplication (meaning repetition) by defining the methods :meth:`__add__`,
2422-
:meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`, :meth:`__rmul__` and
2423-
:meth:`__imul__` described below; they should not define other numerical
2438+
multiplication (meaning repetition) by defining the methods
2439+
:meth:`~object.__add__`, :meth:`~object.__radd__`, :meth:`~object.__iadd__`,
2440+
:meth:`~object.__mul__`, :meth:`~object.__rmul__` and :meth:`~object.__imul__`
2441+
described below; they should not define other numerical
24242442
operators. It is recommended that both mappings and sequences implement the
2425-
:meth:`__contains__` method to allow efficient use of the ``in`` operator; for
2443+
:meth:`~object.__contains__` method to allow efficient use of the ``in``
2444+
operator; for
24262445
mappings, ``in`` should search the mapping's keys; for sequences, it should
24272446
search through the values. It is further recommended that both mappings and
2428-
sequences implement the :meth:`__iter__` method to allow efficient iteration
2447+
sequences implement the :meth:`~object.__iter__` method to allow efficient iteration
24292448
through the container; for mappings, :meth:`__iter__` should iterate
24302449
through the object's keys; for sequences, it should iterate through the values.
24312450

@@ -2838,7 +2857,8 @@ exception::
28382857
TypeError: object of type 'C' has no len()
28392858

28402859
The rationale behind this behaviour lies with a number of special methods such
2841-
as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects,
2860+
as :meth:`~object.__hash__` and :meth:`~object.__repr__` that are implemented
2861+
by all objects,
28422862
including type objects. If the implicit lookup of these methods used the
28432863
conventional lookup process, they would fail when invoked on the type object
28442864
itself::
@@ -2861,7 +2881,7 @@ the instance when looking up special methods::
28612881

28622882
In addition to bypassing any instance attributes in the interest of
28632883
correctness, implicit special method lookup generally also bypasses the
2864-
:meth:`__getattribute__` method even of the object's metaclass::
2884+
:meth:`~object.__getattribute__` method even of the object's metaclass::
28652885

28662886
>>> class Meta(type):
28672887
... def __getattribute__(*args):
@@ -2885,7 +2905,7 @@ correctness, implicit special method lookup generally also bypasses the
28852905
>>> len(c) # Implicit lookup
28862906
10
28872907

2888-
Bypassing the :meth:`__getattribute__` machinery in this fashion
2908+
Bypassing the :meth:`~object.__getattribute__` machinery in this fashion
28892909
provides significant scope for speed optimisations within the
28902910
interpreter, at the cost of some flexibility in the handling of
28912911
special methods (the special method *must* be set on the class
@@ -2902,15 +2922,15 @@ Coroutines
29022922
Awaitable Objects
29032923
-----------------
29042924

2905-
An :term:`awaitable` object generally implements an :meth:`__await__` method.
2925+
An :term:`awaitable` object generally implements an :meth:`~object.__await__` method.
29062926
:term:`Coroutine objects <coroutine>` returned from :keyword:`async def` functions
29072927
are awaitable.
29082928

29092929
.. note::
29102930

29112931
The :term:`generator iterator` objects returned from generators
29122932
decorated with :func:`types.coroutine`
2913-
are also awaitable, but they do not implement :meth:`__await__`.
2933+
are also awaitable, but they do not implement :meth:`~object.__await__`.
29142934

29152935
.. method:: object.__await__(self)
29162936

@@ -2929,7 +2949,7 @@ Coroutine Objects
29292949
-----------------
29302950

29312951
:term:`Coroutine objects <coroutine>` are :term:`awaitable` objects.
2932-
A coroutine's execution can be controlled by calling :meth:`__await__` and
2952+
A coroutine's execution can be controlled by calling :meth:`~object.__await__` and
29332953
iterating over the result. When the coroutine has finished executing and
29342954
returns, the iterator raises :exc:`StopIteration`, and the exception's
29352955
:attr:`~StopIteration.value` attribute holds the return value. If the
@@ -2948,7 +2968,7 @@ generators, coroutines do not directly support iteration.
29482968

29492969
Starts or resumes execution of the coroutine. If *value* is ``None``,
29502970
this is equivalent to advancing the iterator returned by
2951-
:meth:`__await__`. If *value* is not ``None``, this method delegates
2971+
:meth:`~object.__await__`. If *value* is not ``None``, this method delegates
29522972
to the :meth:`~generator.send` method of the iterator that caused
29532973
the coroutine to suspend. The result (return value,
29542974
:exc:`StopIteration`, or other exception) is the same as when
@@ -2961,7 +2981,7 @@ generators, coroutines do not directly support iteration.
29612981
the coroutine to suspend, if it has such a method. Otherwise,
29622982
the exception is raised at the suspension point. The result
29632983
(return value, :exc:`StopIteration`, or other exception) is the same as
2964-
when iterating over the :meth:`__await__` return value, described
2984+
when iterating over the :meth:`~object.__await__` return value, described
29652985
above. If the exception is not caught in the coroutine, it propagates
29662986
back to the caller.
29672987

@@ -3015,11 +3035,11 @@ An example of an asynchronous iterable object::
30153035
.. versionadded:: 3.5
30163036

30173037
.. versionchanged:: 3.7
3018-
Prior to Python 3.7, ``__aiter__`` could return an *awaitable*
3038+
Prior to Python 3.7, :meth:`~object.__aiter__` could return an *awaitable*
30193039
that would resolve to an
30203040
:term:`asynchronous iterator <asynchronous iterator>`.
30213041

3022-
Starting with Python 3.7, ``__aiter__`` must return an
3042+
Starting with Python 3.7, :meth:`~object.__aiter__` must return an
30233043
asynchronous iterator object. Returning anything else
30243044
will result in a :exc:`TypeError` error.
30253045

@@ -3062,8 +3082,9 @@ An example of an asynchronous context manager class::
30623082
controlled conditions. It generally isn't a good idea though, since it can
30633083
lead to some very strange behaviour if it is handled incorrectly.
30643084
3065-
.. [#] The :meth:`__hash__`, :meth:`__iter__`, :meth:`__reversed__`, and
3066-
:meth:`__contains__` methods have special handling for this; others
3085+
.. [#] The :meth:`~object.__hash__`, :meth:`~object.__iter__`,
3086+
:meth:`~object.__reversed__`, and :meth:`~object.__contains__` methods have
3087+
special handling for this; others
30673088
will still raise a :exc:`TypeError`, but may do so by relying on
30683089
the behavior that ``None`` is not callable.
30693090
@@ -3074,5 +3095,6 @@ An example of an asynchronous context manager class::
30743095
*blocking* such fallback.
30753096
30763097
.. [#] For operands of the same type, it is assumed that if the non-reflected
3077-
method -- such as :meth:`__add__` -- fails then the overall operation is not
3098+
method -- such as :meth:`~object.__add__` -- fails then the overall
3099+
operation is not
30783100
supported, which is why the reflected method is not called.
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Improve cross-references in the documentation for the data model.

0 commit comments

Comments
 (0)