@@ -188,7 +188,7 @@ Ellipsis
188
188
representation in computers.
189
189
190
190
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
192
192
properties:
193
193
194
194
* They are valid numeric literals which, when passed to their
@@ -677,7 +677,8 @@ Callable types
677
677
returns an :term: `asynchronous iterator ` object which can be used in an
678
678
:keyword: `async for ` statement to execute the body of the function.
679
679
680
- Calling the asynchronous iterator's :meth: `aiterator.__anext__ ` method
680
+ Calling the asynchronous iterator's
681
+ :meth: `aiterator.__anext__ <object.__anext__> ` method
681
682
will return an :term: `awaitable ` which when awaited
682
683
will execute until it provides a value using the :keyword: `yield `
683
684
expression. When the function executes an empty :keyword: `return `
@@ -715,13 +716,13 @@ Callable types
715
716
Classes
716
717
Classes are callable. These objects normally act as factories for new
717
718
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
720
721
initialize the new instance.
721
722
722
723
Class Instances
723
724
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.
725
726
726
727
727
728
Modules
@@ -880,14 +881,14 @@ Class instances
880
881
section :ref: `descriptors ` for another way in which attributes of a class
881
882
retrieved via its instances may differ from the objects actually stored in
882
883
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
884
885
the lookup.
885
886
886
887
.. index :: triple: class instance; attribute; assignment
887
888
888
889
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
891
892
dictionary directly.
892
893
893
894
.. index ::
@@ -1176,7 +1177,8 @@ Internal types
1176
1177
Slice objects
1177
1178
.. index :: builtin: slice
1178
1179
1179
- Slice objects are used to represent slices for :meth: `__getitem__ `
1180
+ Slice objects are used to represent slices for
1181
+ :meth: `~object.__getitem__ `
1180
1182
methods. They are also created by the built-in :func: `slice ` function.
1181
1183
1182
1184
.. index ::
@@ -1229,17 +1231,18 @@ A class can implement certain operations that are invoked by special syntax
1229
1231
(such as arithmetic operations or subscripting and slicing) by defining methods
1230
1232
with special names. This is Python's approach to :dfn: `operator overloading `,
1231
1233
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__ `,
1233
1236
and ``x `` is an instance of this class, then ``x[i] `` is roughly equivalent
1234
1237
to ``type(x).__getitem__(x, i) ``. Except where mentioned, attempts to execute an
1235
1238
operation raise an exception when no appropriate method is defined (typically
1236
1239
:exc: `AttributeError ` or :exc: `TypeError `).
1237
1240
1238
1241
Setting a special method to ``None `` indicates that the corresponding
1239
1242
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
1241
1244
:func: `iter ` on its instances will raise a :exc: `TypeError ` (without
1242
- falling back to :meth: `__getitem__ `). [# ]_
1245
+ falling back to :meth: `~object. __getitem__ `). [# ]_
1243
1246
1244
1247
When implementing a class that emulates any built-in type, it is important that
1245
1248
the emulation only be implemented to the degree that it makes sense for the
@@ -1789,7 +1792,8 @@ Invoking Descriptors
1789
1792
1790
1793
In general, a descriptor is an object attribute with "binding behavior", one
1791
1794
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
1793
1797
those methods are defined for an object, it is said to be a descriptor.
1794
1798
1795
1799
The default behavior for attribute access is to get, set, or delete the
@@ -1853,7 +1857,8 @@ Super Binding
1853
1857
1854
1858
For instance bindings, the precedence of descriptor invocation depends on
1855
1859
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
1857
1862
define :meth: `__get__ `, then accessing the attribute will return the descriptor
1858
1863
object itself unless there is a value in the object's instance dictionary. If
1859
1864
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
1864
1869
instance dictionary. In contrast, non-data descriptors can be overridden by
1865
1870
instances.
1866
1871
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
1868
1874
implemented as non-data descriptors. Accordingly, instances can redefine and
1869
1875
override methods. This allows individual instances to acquire behaviors that
1870
1876
differ from other instances of the same class.
@@ -1879,46 +1885,50 @@ __slots__
1879
1885
^^^^^^^^^
1880
1886
1881
1887
*__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__ *
1883
1889
(unless explicitly declared in *__slots__ * or available in a parent.)
1884
1890
1885
- The space saved over using * __dict__ * can be significant.
1891
+ The space saved over using :attr: ` ~object. __dict__` can be significant.
1886
1892
Attribute lookup speed can be significantly improved as well.
1887
1893
1888
1894
.. data :: object.__slots__
1889
1895
1890
1896
This class variable can be assigned a string, iterable, or sequence of
1891
1897
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__ `
1893
1900
and *__weakref__ * for each instance.
1894
1901
1895
1902
1896
1903
Notes on using *__slots__ *
1897
1904
""""""""""""""""""""""""""
1898
1905
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
1900
1908
*__weakref__ * attribute of the instances will always be accessible.
1901
1909
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
1903
1912
listed in the *__slots__ * definition. Attempts to assign to an unlisted
1904
1913
variable name raises :exc: `AttributeError `. If dynamic assignment of new
1905
1914
variables is desired, then add ``'__dict__' `` to the sequence of strings in
1906
1915
the *__slots__ * declaration.
1907
1916
1908
1917
* 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
1910
1920
support is needed, then add ``'__weakref__' `` to the sequence of strings in the
1911
1921
*__slots__ * declaration.
1912
1922
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
1915
1925
cannot be used to set default values for instance variables defined by
1916
1926
*__slots__ *; otherwise, the class attribute would overwrite the descriptor
1917
1927
assignment.
1918
1928
1919
1929
* The action of a *__slots__ * declaration is not limited to the class
1920
1930
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
1922
1932
*__weakref__ * unless they also define *__slots__ * (which should only
1923
1933
contain names of any *additional * slots).
1924
1934
@@ -1934,14 +1944,17 @@ Notes on using *__slots__*
1934
1944
used; however, in the future, special meaning may be assigned to the values
1935
1945
corresponding to each key.
1936
1946
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__ *.
1938
1949
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,
1940
1952
but only one parent is allowed to have attributes created by slots
1941
1953
(the other bases must have empty slot layouts) - violations raise
1942
1954
:exc: `TypeError `.
1943
1955
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
1945
1958
of the iterator's values. However, the *__slots__ * attribute will be an empty
1946
1959
iterator.
1947
1960
@@ -1950,7 +1963,7 @@ Notes on using *__slots__*
1950
1963
Customizing class creation
1951
1964
--------------------------
1952
1965
1953
- Whenever a class inherits from another class, * __init_subclass__ * is
1966
+ Whenever a class inherits from another class, :meth: ` ~object. __init_subclass__` is
1954
1967
called on that class. This way, it is possible to write classes which
1955
1968
change the behavior of subclasses. This is closely related to class
1956
1969
decorators, but where class decorators only affect the specific class they're
@@ -1991,7 +2004,7 @@ class defining the method.
1991
2004
1992
2005
1993
2006
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.
1995
2008
1996
2009
.. method :: object.__set_name__(self, owner, name)
1997
2010
@@ -2103,7 +2116,8 @@ Once the appropriate metaclass has been identified, then the class namespace
2103
2116
is prepared. If the metaclass has a ``__prepare__ `` attribute, it is called
2104
2117
as ``namespace = metaclass.__prepare__(name, bases, **kwds) `` (where the
2105
2118
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
2107
2121
namespace returned by ``__prepare__ `` is passed in to ``__new__ ``, but when
2108
2122
the final class object is created the namespace is copied into a new ``dict ``.
2109
2123
@@ -2401,31 +2415,36 @@ Emulating container types
2401
2415
-------------------------
2402
2416
2403
2417
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> `),
2405
2421
but can represent other containers as well. The first set of methods is used
2406
2422
either to emulate a sequence or to emulate a mapping; the difference is that for
2407
2423
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
2409
2425
range of items. It is also recommended that mappings provide the methods
2410
2426
:meth: `keys `, :meth: `values `, :meth: `items `, :meth: `get `, :meth: `clear `,
2411
2427
: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> `
2413
2429
objects. The :mod: `collections.abc ` module provides a
2414
2430
: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 `.
2417
2433
Mutable sequences should provide methods :meth: `append `, :meth: `count `,
2418
2434
: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,
2420
2437
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
2424
2442
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
2426
2445
mappings, ``in `` should search the mapping's keys; for sequences, it should
2427
2446
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
2429
2448
through the container; for mappings, :meth: `__iter__ ` should iterate
2430
2449
through the object's keys; for sequences, it should iterate through the values.
2431
2450
@@ -2838,7 +2857,8 @@ exception::
2838
2857
TypeError: object of type 'C' has no len()
2839
2858
2840
2859
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,
2842
2862
including type objects. If the implicit lookup of these methods used the
2843
2863
conventional lookup process, they would fail when invoked on the type object
2844
2864
itself::
@@ -2861,7 +2881,7 @@ the instance when looking up special methods::
2861
2881
2862
2882
In addition to bypassing any instance attributes in the interest of
2863
2883
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::
2865
2885
2866
2886
>>> class Meta(type):
2867
2887
... def __getattribute__(*args):
@@ -2885,7 +2905,7 @@ correctness, implicit special method lookup generally also bypasses the
2885
2905
>>> len(c) # Implicit lookup
2886
2906
10
2887
2907
2888
- Bypassing the :meth: `__getattribute__ ` machinery in this fashion
2908
+ Bypassing the :meth: `~object. __getattribute__ ` machinery in this fashion
2889
2909
provides significant scope for speed optimisations within the
2890
2910
interpreter, at the cost of some flexibility in the handling of
2891
2911
special methods (the special method *must * be set on the class
@@ -2902,15 +2922,15 @@ Coroutines
2902
2922
Awaitable Objects
2903
2923
-----------------
2904
2924
2905
- An :term: `awaitable ` object generally implements an :meth: `__await__ ` method.
2925
+ An :term: `awaitable ` object generally implements an :meth: `~object. __await__ ` method.
2906
2926
:term: `Coroutine objects <coroutine> ` returned from :keyword: `async def ` functions
2907
2927
are awaitable.
2908
2928
2909
2929
.. note ::
2910
2930
2911
2931
The :term: `generator iterator ` objects returned from generators
2912
2932
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__ `.
2914
2934
2915
2935
.. method :: object.__await__(self)
2916
2936
@@ -2929,7 +2949,7 @@ Coroutine Objects
2929
2949
-----------------
2930
2950
2931
2951
: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
2933
2953
iterating over the result. When the coroutine has finished executing and
2934
2954
returns, the iterator raises :exc: `StopIteration `, and the exception's
2935
2955
:attr: `~StopIteration.value ` attribute holds the return value. If the
@@ -2948,7 +2968,7 @@ generators, coroutines do not directly support iteration.
2948
2968
2949
2969
Starts or resumes execution of the coroutine. If *value * is ``None ``,
2950
2970
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
2952
2972
to the :meth: `~generator.send ` method of the iterator that caused
2953
2973
the coroutine to suspend. The result (return value,
2954
2974
:exc: `StopIteration `, or other exception) is the same as when
@@ -2961,7 +2981,7 @@ generators, coroutines do not directly support iteration.
2961
2981
the coroutine to suspend, if it has such a method. Otherwise,
2962
2982
the exception is raised at the suspension point. The result
2963
2983
(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
2965
2985
above. If the exception is not caught in the coroutine, it propagates
2966
2986
back to the caller.
2967
2987
@@ -3015,11 +3035,11 @@ An example of an asynchronous iterable object::
3015
3035
.. versionadded :: 3.5
3016
3036
3017
3037
.. 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 *
3019
3039
that would resolve to an
3020
3040
:term: `asynchronous iterator <asynchronous iterator> `.
3021
3041
3022
- Starting with Python 3.7, `` __aiter__ ` ` must return an
3042
+ Starting with Python 3.7, :meth: ` ~object. __aiter__ ` must return an
3023
3043
asynchronous iterator object. Returning anything else
3024
3044
will result in a :exc: `TypeError ` error.
3025
3045
@@ -3062,8 +3082,9 @@ An example of an asynchronous context manager class::
3062
3082
controlled conditions. It generally isn't a good idea though, since it can
3063
3083
lead to some very strange behaviour if it is handled incorrectly.
3064
3084
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
3067
3088
will still raise a :exc: `TypeError `, but may do so by relying on
3068
3089
the behavior that ``None `` is not callable.
3069
3090
@@ -3074,5 +3095,6 @@ An example of an asynchronous context manager class::
3074
3095
*blocking * such fallback.
3075
3096
3076
3097
.. [# ] 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
3078
3100
supported, which is why the reflected method is not called.
0 commit comments