From 2744bccb821786611e7d6575f5c8664c64061df8 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Fri, 19 Nov 2021 02:02:59 +0000 Subject: [PATCH 01/18] Improve cross-references in the data model documentation --- Doc/reference/datamodel.rst | 259 +++++++++--------- .../2021-11-19-02-02-32.bpo-45840.A51B2S.rst | 1 + 2 files changed, 137 insertions(+), 123 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2021-11-19-02-02-32.bpo-45840.A51B2S.rst diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 1ecfa81e3b3363..cdc6dc6cd88391 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -188,7 +188,7 @@ Ellipsis representation in computers. The string representations of the numeric classes, computed by - :meth:`__repr__` and :meth:`__str__`, have the following + :meth:`~object.__repr__` and :meth:`~object.__str__`, have the following properties: * They are valid numeric literals which, when passed to their @@ -677,13 +677,13 @@ Callable types returns an asynchronous iterator object which can be used in an :keyword:`async for` statement to execute the body of the function. - Calling the asynchronous iterator's :meth:`aiterator.__anext__` method - will return an :term:`awaitable` which when awaited - will execute until it provides a value using the :keyword:`yield` - expression. When the function executes an empty :keyword:`return` - statement or falls off the end, a :exc:`StopAsyncIteration` exception - is raised and the asynchronous iterator will have reached the end of - the set of values to be yielded. + Calling the asynchronous iterator's + :meth:`aiterator.__anext__` method will return an + :term:`awaitable` which when awaited will execute until it provides a + value using the :keyword:`yield` expression. When the function executes + an empty :keyword:`return` statement or falls off the end, a + :exc:`StopAsyncIteration` exception is raised and the asynchronous + iterator will have reached the end of the set of values to be yielded. Built-in functions .. index:: @@ -715,13 +715,13 @@ Callable types Classes Classes are callable. These objects normally act as factories for new instances of themselves, but variations are possible for class types that - override :meth:`__new__`. The arguments of the call are passed to - :meth:`__new__` and, in the typical case, to :meth:`__init__` to - initialize the new instance. + override :meth:`~object.__new__`. The arguments of the call are passed + to :meth:`__new__` and, in the typical case, to :meth:`~object.__init__` + to initialize the new instance. Class Instances Instances of arbitrary classes can be made callable by defining a - :meth:`__call__` method in their class. + :meth:`~object.__call__` method in their class. Modules @@ -880,15 +880,15 @@ Class instances section :ref:`descriptors` for another way in which attributes of a class retrieved via its instances may differ from the objects actually stored in the class's :attr:`~object.__dict__`. If no class attribute is found, and the - object's class has a :meth:`__getattr__` method, that is called to satisfy - the lookup. + object's class has a :meth:`~object.__getattr__` method, that is called to + satisfy the lookup. .. index:: triple: class instance; attribute; assignment Attribute assignments and deletions update the instance's dictionary, never a - class's dictionary. If the class has a :meth:`__setattr__` or - :meth:`__delattr__` method, this is called instead of updating the instance - dictionary directly. + class's dictionary. If the class has a :meth:`~object.__setattr__` or + :meth:`~object.__delattr__` method, this is called instead of updating the + instance dictionary directly. .. index:: object: numeric @@ -1176,8 +1176,9 @@ Internal types Slice objects .. index:: builtin: slice - Slice objects are used to represent slices for :meth:`__getitem__` - methods. They are also created by the built-in :func:`slice` function. + Slice objects are used to represent slices for + :meth:`~object.__getitem__` methods. They are also created by the + built-in :func:`slice` function. .. index:: single: start (slice object attribute) @@ -1229,17 +1230,18 @@ A class can implement certain operations that are invoked by special syntax (such as arithmetic operations or subscripting and slicing) by defining methods with special names. This is Python's approach to :dfn:`operator overloading`, allowing classes to define their own behavior with respect to language -operators. For instance, if a class defines a method named :meth:`__getitem__`, -and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent -to ``type(x).__getitem__(x, i)``. Except where mentioned, attempts to execute an -operation raise an exception when no appropriate method is defined (typically -:exc:`AttributeError` or :exc:`TypeError`). +operators. For instance, if a class defines a method named +:meth:`~object.__getitem__`, and ``x`` is an instance of this class, then +``x[i]`` is roughly equivalent to ``type(x).__getitem__(x, i)``. Except where +mentioned, attempts to execute an operation raise an exception when no +appropriate method is defined (typically :exc:`AttributeError` or +:exc:`TypeError`). Setting a special method to ``None`` indicates that the corresponding operation is not available. For example, if a class sets -:meth:`__iter__` to ``None``, the class is not iterable, so calling +:meth:`~object.__iter__` to ``None``, the class is not iterable, so calling :func:`iter` on its instances will raise a :exc:`TypeError` (without -falling back to :meth:`__getitem__`). [#]_ +falling back to :meth:`~object.__getitem__`). [#]_ When implementing a class that emulates any built-in type, it is important that the emulation only be implemented to the degree that it makes sense for the @@ -1789,8 +1791,9 @@ Invoking Descriptors In general, a descriptor is an object attribute with "binding behavior", one whose attribute access has been overridden by methods in the descriptor -protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of -those methods are defined for an object, it is said to be a descriptor. +protocol: :meth:`~object.__get__`, :meth:`~object.__set__`, and +:meth:`~object.__delete__`. If any of those methods are defined for an object, +it is said to be a descriptor. The default behavior for attribute access is to get, set, or delete the attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain @@ -1825,18 +1828,20 @@ Super Binding For instance bindings, the precedence of descriptor invocation depends on which descriptor methods are defined. A descriptor can define any combination -of :meth:`__get__`, :meth:`__set__` and :meth:`__delete__`. If it does not -define :meth:`__get__`, then accessing the attribute will return the descriptor -object itself unless there is a value in the object's instance dictionary. If -the descriptor defines :meth:`__set__` and/or :meth:`__delete__`, it is a data -descriptor; if it defines neither, it is a non-data descriptor. Normally, data -descriptors define both :meth:`__get__` and :meth:`__set__`, while non-data -descriptors have just the :meth:`__get__` method. Data descriptors with -:meth:`__get__` and :meth:`__set__` (and/or :meth:`__delete__`) defined always override a redefinition in an -instance dictionary. In contrast, non-data descriptors can be overridden by -instances. - -Python methods (including :func:`staticmethod` and :func:`classmethod`) are +of :meth:`~object.__get__`, :meth:`~object.__set__` and +:meth:`~object.__delete__`. If it does not define :meth:`__get__`, then +accessing the attribute will return the descriptor object itself unless there +is a value in the object's instance dictionary. If the descriptor defines +:meth:`__set__` and/or :meth:`__delete__`, it is a data descriptor; if it +defines neither, it is a non-data descriptor. Normally, data descriptors +define both :meth:`__get__` and :meth:`__set__`, while non-data descriptors +have just the :meth:`__get__` method. Data descriptors with :meth:`__get__` +and :meth:`__set__` (and/or :meth:`__delete__`) defined always override a +redefinition in an instance dictionary. In contrast, non-data descriptors can +be overridden by instances. + +Python methods (including those decorated with +:func:`@staticmethod` and :func:`@classmethod`) are implemented as non-data descriptors. Accordingly, instances can redefine and override methods. This allows individual instances to acquire behaviors that differ from other instances of the same class. @@ -1851,47 +1856,48 @@ __slots__ ^^^^^^^^^ *__slots__* allow us to explicitly declare data members (like -properties) and deny the creation of *__dict__* and *__weakref__* +properties) and deny the creation of :attr:`~object.__dict__` and *__weakref__* (unless explicitly declared in *__slots__* or available in a parent.) -The space saved over using *__dict__* can be significant. +The space saved over using :attr:`~object.__dict__` can be significant. Attribute lookup speed can be significantly improved as well. .. data:: object.__slots__ This class variable can be assigned a string, iterable, or sequence of strings with variable names used by instances. *__slots__* reserves space - for the declared variables and prevents the automatic creation of *__dict__* - and *__weakref__* for each instance. + for the declared variables and prevents the automatic creation of + :attr:`~object.__dict__` and *__weakref__* for each instance. Notes on using *__slots__* """""""""""""""""""""""""" -* When inheriting from a class without *__slots__*, the *__dict__* and - *__weakref__* attribute of the instances will always be accessible. +* When inheriting from a class without *__slots__*, the + :attr:`~object.__dict__` and *__weakref__* attribute of the instances will + always be accessible. -* Without a *__dict__* variable, instances cannot be assigned new variables not - listed in the *__slots__* definition. Attempts to assign to an unlisted - variable name raises :exc:`AttributeError`. If dynamic assignment of new - variables is desired, then add ``'__dict__'`` to the sequence of strings in - the *__slots__* declaration. +* Without a :attr:`~object.__dict__` variable, instances cannot be assigned new + variables not listed in the *__slots__* definition. Attempts to assign to an + unlisted variable name raises :exc:`AttributeError`. If dynamic assignment of + new variables is desired, then add ``'__dict__'`` to the sequence of strings + in the *__slots__* declaration. * Without a *__weakref__* variable for each instance, classes defining - *__slots__* do not support weak references to its instances. If weak reference - support is needed, then add ``'__weakref__'`` to the sequence of strings in the - *__slots__* declaration. + *__slots__* do not support :mod:`weak references` to its instances. + If weak reference support is needed, then add ``'__weakref__'`` to the + sequence of strings in the *__slots__* declaration. -* *__slots__* are implemented at the class level by creating descriptors - (:ref:`descriptors`) for each variable name. As a result, class attributes - cannot be used to set default values for instance variables defined by - *__slots__*; otherwise, the class attribute would overwrite the descriptor - assignment. +* *__slots__* are implemented at the class level by creating + :ref:`descriptors` for each variable name. As a result, class + attributes cannot be used to set default values for instance variables + defined by *__slots__*; otherwise, the class attribute would overwrite the + descriptor assignment. * The action of a *__slots__* declaration is not limited to the class where it is defined. *__slots__* declared in parents are available in - child classes. However, child subclasses will get a *__dict__* and - *__weakref__* unless they also define *__slots__* (which should only + child classes. However, child subclasses will get a :attr:`~object.__dict__` + and *__weakref__* unless they also define *__slots__* (which should only contain names of any *additional* slots). * If a class defines a slot also defined in a base class, the instance variable @@ -1906,24 +1912,25 @@ Notes on using *__slots__* used; however, in the future, special meaning may be assigned to the values corresponding to each key. -* *__class__* assignment works only if both classes have the same *__slots__*. +* :attr:`~instance.__class__` assignment works only if both classes have the + same *__slots__*. -* Multiple inheritance with multiple slotted parent classes can be used, - but only one parent is allowed to have attributes created by slots - (the other bases must have empty slot layouts) - violations raise - :exc:`TypeError`. +* :ref:`Multiple inheritance` with multiple slotted parent + classes can be used, but only one parent is allowed to have attributes + created by slots (the other bases must have empty slot layouts) - violations + raise :exc:`TypeError`. -* If an iterator is used for *__slots__* then a descriptor is created for each - of the iterator's values. However, the *__slots__* attribute will be an empty - iterator. +* If an :term:`iterator` is used for *__slots__* then a :term:`descriptor` is + created for each of the iterator's values. However, the *__slots__* attribute + will be an empty iterator. .. _class-customization: Customizing class creation -------------------------- -Whenever a class inherits from another class, *__init_subclass__* is -called on that class. This way, it is possible to write classes which +Whenever a class inherits from another class, :meth:`~object.__init_subclass__` +is called on that class. This way, it is possible to write classes which change the behavior of subclasses. This is closely related to class decorators, but where class decorators only affect the specific class they're applied to, ``__init_subclass__`` solely applies to future subclasses of the @@ -1963,7 +1970,7 @@ class defining the method. When a class is created, :meth:`type.__new__` scans the class variables -and makes callbacks to those with a :meth:`__set_name__` hook. +and makes callbacks to those with a :meth:`~object.__set_name__` hook. .. method:: object.__set_name__(self, owner, name) @@ -2075,9 +2082,10 @@ Once the appropriate metaclass has been identified, then the class namespace is prepared. If the metaclass has a ``__prepare__`` attribute, it is called as ``namespace = metaclass.__prepare__(name, bases, **kwds)`` (where the additional keyword arguments, if any, come from the class definition). The -``__prepare__`` method should be implemented as a :func:`classmethod`. The -namespace returned by ``__prepare__`` is passed in to ``__new__``, but when -the final class object is created the namespace is copied into a new ``dict``. +``__prepare__`` method should be implemented as a +:func:`classmethod`. The namespace returned by ``__prepare__`` is +passed in to ``__new__``, but when the final class object is created the +namespace is copied into a new ``dict``. If the metaclass has no ``__prepare__`` attribute, then the class namespace is initialised as an empty ordered mapping. @@ -2373,33 +2381,38 @@ Emulating container types ------------------------- The following methods can be defined to implement container objects. Containers -usually are sequences (such as lists or tuples) or mappings (like dictionaries), -but can represent other containers as well. The first set of methods is used -either to emulate a sequence or to emulate a mapping; the difference is that for -a sequence, the allowable keys should be the integers *k* for which ``0 <= k < -N`` where *N* is the length of the sequence, or slice objects, which define a -range of items. It is also recommended that mappings provide the methods -:meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`, -:meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`!copy`, and -:meth:`update` behaving similar to those for Python's standard dictionary -objects. The :mod:`collections.abc` module provides a -:class:`~collections.abc.MutableMapping` -abstract base class to help create those methods from a base set of -:meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and :meth:`keys`. +usually are :term:`sequences` (such as :class:`lists` or +:class:`tuples`) or :term:`mappings` (like +:class:`dictionaries`), but can represent other containers as well. The +first set of methods is used either to emulate a sequence or to emulate a +mapping; the difference is that for a sequence, the allowable keys should be +the integers *k* for which ``0 <= k < N`` where *N* is the length of the +sequence, or :class:`slice` objects, which define a range of items. It is also +recommended that mappings provide the methods :meth:`~dict.keys`, +:meth:`~dict.values`, :meth:`~dict.items`, :meth:`~dict.get`, +:meth:`~dict.clear`, :meth:`~dict.setdefault`, :meth:`~dict.pop`, +:meth:`~dict.popitem`, :meth:`~dict.copy`, and :meth:`~dict.update` behaving +similar to those for Python's standard :class:`dictionary` objects. The +:mod:`collections.abc` module provides a +:class:`~collections.abc.MutableMapping` :term:`abstract base class` to help +create those methods from a base set of :meth:`~object.__getitem__`, +:meth:`~object.__setitem__`, :meth:`~object.__delitem__`, and :meth:`keys`. Mutable sequences should provide methods :meth:`append`, :meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`, -:meth:`reverse` and :meth:`sort`, like Python standard list objects. Finally, -sequence types should implement addition (meaning concatenation) and -multiplication (meaning repetition) by defining the methods :meth:`__add__`, -:meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`, :meth:`__rmul__` and -:meth:`__imul__` described below; they should not define other numerical -operators. It is recommended that both mappings and sequences implement the -:meth:`__contains__` method to allow efficient use of the ``in`` operator; for -mappings, ``in`` should search the mapping's keys; for sequences, it should -search through the values. It is further recommended that both mappings and -sequences implement the :meth:`__iter__` method to allow efficient iteration -through the container; for mappings, :meth:`__iter__` should iterate -through the object's keys; for sequences, it should iterate through the values. +:meth:`reverse` and :meth:`~list.sort`, like Python standard :class:`list` +objects. Finally, sequence types should implement addition (meaning +concatenation) and multiplication (meaning repetition) by defining the methods +:meth:`~object.__add__`, :meth:`~object.__radd__`, :meth:`~object.__iadd__`, +:meth:`~object.__mul__`, :meth:`~object.__rmul__` and :meth:`~object.__imul__` +described below; they should not define other numerical operators. It is +recommended that both mappings and sequences implement the +:meth:`~object.__contains__` method to allow efficient use of the ``in`` +operator; for mappings, ``in`` should search the mapping's keys; for sequences, +it should search through the values. It is further recommended that both +mappings and sequences implement the :meth:`~object.__iter__` method to allow +efficient iteration through the container; for mappings, :meth:`__iter__` +should iterate through the object's keys; for sequences, it should iterate +through the values. .. method:: object.__len__(self) @@ -2812,10 +2825,10 @@ exception:: TypeError: object of type 'C' has no len() The rationale behind this behaviour lies with a number of special methods such -as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects, -including type objects. If the implicit lookup of these methods used the -conventional lookup process, they would fail when invoked on the type object -itself:: +as :meth:`~object.__hash__` and :meth:`~object.__repr__` that are implemented +by all objects, including type objects. If the implicit lookup of these methods +used the conventional lookup process, they would fail when invoked on the type +object itself:: >>> 1 .__hash__() == hash(1) True @@ -2835,7 +2848,7 @@ the instance when looking up special methods:: In addition to bypassing any instance attributes in the interest of correctness, implicit special method lookup generally also bypasses the -:meth:`__getattribute__` method even of the object's metaclass:: +:meth:`~object.__getattribute__` method even of the object's metaclass:: >>> class Meta(type): ... def __getattribute__(*args): @@ -2859,7 +2872,7 @@ correctness, implicit special method lookup generally also bypasses the >>> len(c) # Implicit lookup 10 -Bypassing the :meth:`__getattribute__` machinery in this fashion +Bypassing the :meth:`~object.__getattribute__` machinery in this fashion provides significant scope for speed optimisations within the interpreter, at the cost of some flexibility in the handling of special methods (the special method *must* be set on the class @@ -2876,15 +2889,15 @@ Coroutines Awaitable Objects ----------------- -An :term:`awaitable` object generally implements an :meth:`__await__` method. -:term:`Coroutine objects ` returned from :keyword:`async def` functions -are awaitable. +An :term:`awaitable` object generally implements an :meth:`~object.__await__` +method. :term:`Coroutine objects ` returned from +:keyword:`async def` functions are awaitable. .. note:: The :term:`generator iterator` objects returned from generators decorated with :func:`types.coroutine` - are also awaitable, but they do not implement :meth:`__await__`. + are also awaitable, but they do not implement :meth:`~object.__await__`. .. method:: object.__await__(self) @@ -2903,8 +2916,8 @@ Coroutine Objects ----------------- :term:`Coroutine objects ` are :term:`awaitable` objects. -A coroutine's execution can be controlled by calling :meth:`__await__` and -iterating over the result. When the coroutine has finished executing and +A coroutine's execution can be controlled by calling :meth:`~object.__await__` +and iterating over the result. When the coroutine has finished executing and returns, the iterator raises :exc:`StopIteration`, and the exception's :attr:`~StopIteration.value` attribute holds the return value. If the coroutine raises an exception, it is propagated by the iterator. Coroutines @@ -2922,8 +2935,8 @@ generators, coroutines do not directly support iteration. Starts or resumes execution of the coroutine. If *value* is ``None``, this is equivalent to advancing the iterator returned by - :meth:`__await__`. If *value* is not ``None``, this method delegates - to the :meth:`~generator.send` method of the iterator that caused + :meth:`~object.__await__`. If *value* is not ``None``, this method + delegates to the :meth:`~generator.send` method of the iterator that caused the coroutine to suspend. The result (return value, :exc:`StopIteration`, or other exception) is the same as when iterating over the :meth:`__await__` return value, described above. @@ -2935,7 +2948,7 @@ generators, coroutines do not directly support iteration. the coroutine to suspend, if it has such a method. Otherwise, the exception is raised at the suspension point. The result (return value, :exc:`StopIteration`, or other exception) is the same as - when iterating over the :meth:`__await__` return value, described + when iterating over the :meth:`~object.__await__` return value, described above. If the exception is not caught in the coroutine, it propagates back to the caller. @@ -2989,11 +3002,11 @@ An example of an asynchronous iterable object:: .. versionadded:: 3.5 .. versionchanged:: 3.7 - Prior to Python 3.7, ``__aiter__`` could return an *awaitable* + Prior to Python 3.7, :meth:`~object.__aiter__` could return an *awaitable* that would resolve to an :term:`asynchronous iterator `. - Starting with Python 3.7, ``__aiter__`` must return an + Starting with Python 3.7, :meth:`~object.__aiter__` must return an asynchronous iterator object. Returning anything else will result in a :exc:`TypeError` error. @@ -3036,10 +3049,10 @@ An example of an asynchronous context manager class:: controlled conditions. It generally isn't a good idea though, since it can lead to some very strange behaviour if it is handled incorrectly. -.. [#] The :meth:`__hash__`, :meth:`__iter__`, :meth:`__reversed__`, and - :meth:`__contains__` methods have special handling for this; others - will still raise a :exc:`TypeError`, but may do so by relying on - the behavior that ``None`` is not callable. +.. [#] The :meth:`~object.__hash__`, :meth:`~object.__iter__`, + :meth:`~object.__reversed__`, and :meth:`~object.__contains__` methods have + special handling for this; others will still raise a :exc:`TypeError`, but + may do so by relying on the behavior that ``None`` is not callable. .. [#] "Does not support" here means that the class has no such method, or the method returns ``NotImplemented``. Do not set the method to @@ -3048,5 +3061,5 @@ An example of an asynchronous context manager class:: *blocking* such fallback. .. [#] For operands of the same type, it is assumed that if the non-reflected - method -- such as :meth:`__add__` -- fails then the overall operation is not - supported, which is why the reflected method is not called. + method -- such as :meth:`~object.__add__` -- fails then the overall + operation is not supported, which is why the reflected method is not called. diff --git a/Misc/NEWS.d/next/Documentation/2021-11-19-02-02-32.bpo-45840.A51B2S.rst b/Misc/NEWS.d/next/Documentation/2021-11-19-02-02-32.bpo-45840.A51B2S.rst new file mode 100644 index 00000000000000..87371e5b76bc11 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2021-11-19-02-02-32.bpo-45840.A51B2S.rst @@ -0,0 +1 @@ +Improve cross-references in the documentation for the data model. From 86ca5969122867e2c810e99566e5c99d286033f1 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sat, 20 Nov 2021 00:07:13 +0000 Subject: [PATCH 02/18] Address review --- Doc/reference/datamodel.rst | 152 +++++++++++++++++++----------------- 1 file changed, 80 insertions(+), 72 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index cdc6dc6cd88391..c95a5febb1f209 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -678,12 +678,13 @@ Callable types :keyword:`async for` statement to execute the body of the function. Calling the asynchronous iterator's - :meth:`aiterator.__anext__` method will return an - :term:`awaitable` which when awaited will execute until it provides a - value using the :keyword:`yield` expression. When the function executes - an empty :keyword:`return` statement or falls off the end, a - :exc:`StopAsyncIteration` exception is raised and the asynchronous - iterator will have reached the end of the set of values to be yielded. + :meth:`aiterator.__anext__` method + will return an :term:`awaitable` which when awaited + will execute until it provides a value using the :keyword:`yield` + expression. When the function executes an empty :keyword:`return` + statement or falls off the end, a :exc:`StopAsyncIteration` exception + is raised and the asynchronous iterator will have reached the end of + the set of values to be yielded. Built-in functions .. index:: @@ -715,9 +716,9 @@ Callable types Classes Classes are callable. These objects normally act as factories for new instances of themselves, but variations are possible for class types that - override :meth:`~object.__new__`. The arguments of the call are passed - to :meth:`__new__` and, in the typical case, to :meth:`~object.__init__` - to initialize the new instance. + override :meth:`~object.__new__`. The arguments of the call are passed to + :meth:`__new__` and, in the typical case, to :meth:`~object.__init__` to + initialize the new instance. Class Instances Instances of arbitrary classes can be made callable by defining a @@ -1177,8 +1178,8 @@ Internal types .. index:: builtin: slice Slice objects are used to represent slices for - :meth:`~object.__getitem__` methods. They are also created by the - built-in :func:`slice` function. + :meth:`~object.__getitem__` + methods. They are also created by the built-in :func:`slice` function. .. index:: single: start (slice object attribute) @@ -1231,11 +1232,11 @@ A class can implement certain operations that are invoked by special syntax with special names. This is Python's approach to :dfn:`operator overloading`, allowing classes to define their own behavior with respect to language operators. For instance, if a class defines a method named -:meth:`~object.__getitem__`, and ``x`` is an instance of this class, then -``x[i]`` is roughly equivalent to ``type(x).__getitem__(x, i)``. Except where -mentioned, attempts to execute an operation raise an exception when no -appropriate method is defined (typically :exc:`AttributeError` or -:exc:`TypeError`). +:meth:`~object.__getitem__`, +and ``x`` is an instance of this class, then``x[i]`` is roughly equivalent +to ``type(x).__getitem__(x, i)``. Except where mentioned, attempts to execute an +operation raise an exception when no appropriate method is defined (typically +:exc:`AttributeError` or :exc:`TypeError`). Setting a special method to ``None`` indicates that the corresponding operation is not available. For example, if a class sets @@ -1792,8 +1793,8 @@ Invoking Descriptors In general, a descriptor is an object attribute with "binding behavior", one whose attribute access has been overridden by methods in the descriptor protocol: :meth:`~object.__get__`, :meth:`~object.__set__`, and -:meth:`~object.__delete__`. If any of those methods are defined for an object, -it is said to be a descriptor. +:meth:`~object.__delete__`. If any of +those methods are defined for an object, it is said to be a descriptor. The default behavior for attribute access is to get, set, or delete the attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain @@ -1829,16 +1830,15 @@ Super Binding For instance bindings, the precedence of descriptor invocation depends on which descriptor methods are defined. A descriptor can define any combination of :meth:`~object.__get__`, :meth:`~object.__set__` and -:meth:`~object.__delete__`. If it does not define :meth:`__get__`, then -accessing the attribute will return the descriptor object itself unless there -is a value in the object's instance dictionary. If the descriptor defines -:meth:`__set__` and/or :meth:`__delete__`, it is a data descriptor; if it -defines neither, it is a non-data descriptor. Normally, data descriptors -define both :meth:`__get__` and :meth:`__set__`, while non-data descriptors -have just the :meth:`__get__` method. Data descriptors with :meth:`__get__` -and :meth:`__set__` (and/or :meth:`__delete__`) defined always override a -redefinition in an instance dictionary. In contrast, non-data descriptors can -be overridden by instances. +:meth:`~object.__delete__`. If it does not +define :meth:`__get__`, then accessing the attribute will return the descriptor +object itself unless there is a value in the object's instance dictionary. If +the descriptor defines :meth:`__set__` and/or :meth:`__delete__`, it is a data +descriptor; if it defines neither, it is a non-data descriptor. Normally, data +descriptors define both :meth:`__get__` and :meth:`__set__`, while non-data +descriptors have just the :meth:`__get__` method. Data descriptors with +:meth:`__get__` and :meth:`__set__` (and/or :meth:`__delete__`) defined always override a redefinition in an +instance dictionary. In contrast, non-data descriptors can be overridden by instances. Python methods (including those decorated with :func:`@staticmethod` and :func:`@classmethod`) are @@ -1867,37 +1867,40 @@ Attribute lookup speed can be significantly improved as well. This class variable can be assigned a string, iterable, or sequence of strings with variable names used by instances. *__slots__* reserves space for the declared variables and prevents the automatic creation of - :attr:`~object.__dict__` and *__weakref__* for each instance. + :attr:`~object.__dict__` + and *__weakref__* for each instance. Notes on using *__slots__* """""""""""""""""""""""""" * When inheriting from a class without *__slots__*, the - :attr:`~object.__dict__` and *__weakref__* attribute of the instances will - always be accessible. + :attr:`~object.__dict__` and + *__weakref__* attribute of the instances will always be accessible. * Without a :attr:`~object.__dict__` variable, instances cannot be assigned new - variables not listed in the *__slots__* definition. Attempts to assign to an - unlisted variable name raises :exc:`AttributeError`. If dynamic assignment of - new variables is desired, then add ``'__dict__'`` to the sequence of strings - in the *__slots__* declaration. + variables not + listed in the *__slots__* definition. Attempts to assign to an unlisted + variable name raises :exc:`AttributeError`. If dynamic assignment of new + variables is desired, then add ``'__dict__'`` to the sequence of strings in + the *__slots__* declaration. * Without a *__weakref__* variable for each instance, classes defining *__slots__* do not support :mod:`weak references` to its instances. - If weak reference support is needed, then add ``'__weakref__'`` to the - sequence of strings in the *__slots__* declaration. + If weak reference + support is needed, then add ``'__weakref__'`` to the sequence of strings in + the *__slots__* declaration. * *__slots__* are implemented at the class level by creating - :ref:`descriptors` for each variable name. As a result, class - attributes cannot be used to set default values for instance variables - defined by *__slots__*; otherwise, the class attribute would overwrite the - descriptor assignment. + :ref:`descriptors` for each variable name. As a result, class attributes + cannot be used to set default values for instance variables defined by + *__slots__*; otherwise, the class attribute would overwrite the descriptor + assignment. * The action of a *__slots__* declaration is not limited to the class where it is defined. *__slots__* declared in parents are available in - child classes. However, child subclasses will get a :attr:`~object.__dict__` - and *__weakref__* unless they also define *__slots__* (which should only + child classes. However, child subclasses will get a :attr:`~object.__dict__` and + *__weakref__* unless they also define *__slots__* (which should only contain names of any *additional* slots). * If a class defines a slot also defined in a base class, the instance variable @@ -1916,21 +1919,23 @@ Notes on using *__slots__* same *__slots__*. * :ref:`Multiple inheritance` with multiple slotted parent - classes can be used, but only one parent is allowed to have attributes - created by slots (the other bases must have empty slot layouts) - violations - raise :exc:`TypeError`. + classes can be used, + but only one parent is allowed to have attributes created by slots + (the other bases must have empty slot layouts) - violations raise + :exc:`TypeError`. * If an :term:`iterator` is used for *__slots__* then a :term:`descriptor` is - created for each of the iterator's values. However, the *__slots__* attribute - will be an empty iterator. + created for each + of the iterator's values. However, the *__slots__* attribute will be an empty + iterator. .. _class-customization: Customizing class creation -------------------------- -Whenever a class inherits from another class, :meth:`~object.__init_subclass__` -is called on that class. This way, it is possible to write classes which +Whenever a class inherits from another class, :meth:`~object.__init_subclass__` is +called on that class. This way, it is possible to write classes which change the behavior of subclasses. This is closely related to class decorators, but where class decorators only affect the specific class they're applied to, ``__init_subclass__`` solely applies to future subclasses of the @@ -2083,9 +2088,9 @@ is prepared. If the metaclass has a ``__prepare__`` attribute, it is called as ``namespace = metaclass.__prepare__(name, bases, **kwds)`` (where the additional keyword arguments, if any, come from the class definition). The ``__prepare__`` method should be implemented as a -:func:`classmethod`. The namespace returned by ``__prepare__`` is -passed in to ``__new__``, but when the final class object is created the -namespace is copied into a new ``dict``. +:func:`classmethod`. The +namespace returned by ``__prepare__`` is passed in to ``__new__``, but when +the final class object is created the namespace is copied into a new ``dict``. If the metaclass has no ``__prepare__`` attribute, then the class namespace is initialised as an empty ordered mapping. @@ -2407,12 +2412,12 @@ concatenation) and multiplication (meaning repetition) by defining the methods described below; they should not define other numerical operators. It is recommended that both mappings and sequences implement the :meth:`~object.__contains__` method to allow efficient use of the ``in`` -operator; for mappings, ``in`` should search the mapping's keys; for sequences, -it should search through the values. It is further recommended that both -mappings and sequences implement the :meth:`~object.__iter__` method to allow -efficient iteration through the container; for mappings, :meth:`__iter__` -should iterate through the object's keys; for sequences, it should iterate -through the values. +operator; for +mappings, ``in`` should search the mapping's keys; for sequences, it should +search through the values. It is further recommended that both mappings and +sequences implement the :meth:`~object.__iter__` method to allow efficient iteration +through the container; for mappings, :meth:`__iter__` should iterate +through the object's keys; for sequences, it should iterate through the values. .. method:: object.__len__(self) @@ -2826,9 +2831,10 @@ exception:: The rationale behind this behaviour lies with a number of special methods such as :meth:`~object.__hash__` and :meth:`~object.__repr__` that are implemented -by all objects, including type objects. If the implicit lookup of these methods -used the conventional lookup process, they would fail when invoked on the type -object itself:: +by all objects, +including type objects. If the implicit lookup of these methods used the +conventional lookup process, they would fail when invoked on the type object +itself:: >>> 1 .__hash__() == hash(1) True @@ -2889,9 +2895,9 @@ Coroutines Awaitable Objects ----------------- -An :term:`awaitable` object generally implements an :meth:`~object.__await__` -method. :term:`Coroutine objects ` returned from -:keyword:`async def` functions are awaitable. +An :term:`awaitable` object generally implements an :meth:`~object.__await__` method. +:term:`Coroutine objects ` returned from :keyword:`async def` functions +are awaitable. .. note:: @@ -2916,8 +2922,8 @@ Coroutine Objects ----------------- :term:`Coroutine objects ` are :term:`awaitable` objects. -A coroutine's execution can be controlled by calling :meth:`~object.__await__` -and iterating over the result. When the coroutine has finished executing and +A coroutine's execution can be controlled by calling :meth:`~object.__await__` and +iterating over the result. When the coroutine has finished executing and returns, the iterator raises :exc:`StopIteration`, and the exception's :attr:`~StopIteration.value` attribute holds the return value. If the coroutine raises an exception, it is propagated by the iterator. Coroutines @@ -2935,8 +2941,8 @@ generators, coroutines do not directly support iteration. Starts or resumes execution of the coroutine. If *value* is ``None``, this is equivalent to advancing the iterator returned by - :meth:`~object.__await__`. If *value* is not ``None``, this method - delegates to the :meth:`~generator.send` method of the iterator that caused + :meth:`~object.__await__`. If *value* is not ``None``, this method delegates + to the :meth:`~generator.send` method of the iterator that caused the coroutine to suspend. The result (return value, :exc:`StopIteration`, or other exception) is the same as when iterating over the :meth:`__await__` return value, described above. @@ -3051,8 +3057,9 @@ An example of an asynchronous context manager class:: .. [#] The :meth:`~object.__hash__`, :meth:`~object.__iter__`, :meth:`~object.__reversed__`, and :meth:`~object.__contains__` methods have - special handling for this; others will still raise a :exc:`TypeError`, but - may do so by relying on the behavior that ``None`` is not callable. + special handling for this; others + will still raise a :exc:`TypeError`, but may do so by relying on + the behavior that ``None`` is not callable. .. [#] "Does not support" here means that the class has no such method, or the method returns ``NotImplemented``. Do not set the method to @@ -3062,4 +3069,5 @@ An example of an asynchronous context manager class:: .. [#] For operands of the same type, it is assumed that if the non-reflected method -- such as :meth:`~object.__add__` -- fails then the overall - operation is not supported, which is why the reflected method is not called. + operation is not + supported, which is why the reflected method is not called. From 24fb645e4802d37cf0d05fb92366e9e50806fb05 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sat, 20 Nov 2021 00:13:54 +0000 Subject: [PATCH 03/18] Tweak --- Doc/reference/datamodel.rst | 42 +++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index c95a5febb1f209..67ad3755614397 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1888,11 +1888,11 @@ Notes on using *__slots__* * Without a *__weakref__* variable for each instance, classes defining *__slots__* do not support :mod:`weak references` to its instances. If weak reference - support is needed, then add ``'__weakref__'`` to the sequence of strings in - the *__slots__* declaration. + support is needed, then add ``'__weakref__'`` to the sequence of strings in the + *__slots__* declaration. -* *__slots__* are implemented at the class level by creating - :ref:`descriptors` for each variable name. As a result, class attributes +* *__slots__* are implemented at the class level by creating :ref:`descriptors` + for each variable name. As a result, class attributes cannot be used to set default values for instance variables defined by *__slots__*; otherwise, the class attribute would overwrite the descriptor assignment. @@ -2388,33 +2388,35 @@ Emulating container types The following methods can be defined to implement container objects. Containers usually are :term:`sequences` (such as :class:`lists` or :class:`tuples`) or :term:`mappings` (like -:class:`dictionaries`), but can represent other containers as well. The -first set of methods is used either to emulate a sequence or to emulate a -mapping; the difference is that for a sequence, the allowable keys should be -the integers *k* for which ``0 <= k < N`` where *N* is the length of the -sequence, or :class:`slice` objects, which define a range of items. It is also -recommended that mappings provide the methods :meth:`~dict.keys`, -:meth:`~dict.values`, :meth:`~dict.items`, :meth:`~dict.get`, -:meth:`~dict.clear`, :meth:`~dict.setdefault`, :meth:`~dict.pop`, -:meth:`~dict.popitem`, :meth:`~dict.copy`, and :meth:`~dict.update` behaving -similar to those for Python's standard :class:`dictionary` objects. The -:mod:`collections.abc` module provides a +:class:`dictionaries`), +but can represent other containers as well. The first set of methods is used +either to emulate a sequence or to emulate a mapping; the difference is that for +a sequence, the allowable keys should be the integers *k* for which ``0 <= k < +N`` where *N* is the length of the +sequence, or :class:`slice` objects, which define a +range of items. It is also recommended that mappings provide the methods +:meth:`~dict.keys`, :meth:`~dict.values`, :meth:`~dict.items`, +:meth:`~dict.get`, :meth:`~dict.clear`, :meth:`~dict.setdefault`, +:meth:`~dict.pop`, :meth:`~dict.popitem`, :meth:`~dict.copy`, and +:meth:`~dict.update` behaving similar to those for Python's standard +:class:`dictionary` objects. The :mod:`collections.abc` module provides a :class:`~collections.abc.MutableMapping` :term:`abstract base class` to help create those methods from a base set of :meth:`~object.__getitem__`, :meth:`~object.__setitem__`, :meth:`~object.__delitem__`, and :meth:`keys`. Mutable sequences should provide methods :meth:`append`, :meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`, :meth:`reverse` and :meth:`~list.sort`, like Python standard :class:`list` -objects. Finally, sequence types should implement addition (meaning -concatenation) and multiplication (meaning repetition) by defining the methods +objects. Finally, +sequence types should implement addition (meaning concatenation) and +multiplication (meaning repetition) by defining the methods :meth:`~object.__add__`, :meth:`~object.__radd__`, :meth:`~object.__iadd__`, :meth:`~object.__mul__`, :meth:`~object.__rmul__` and :meth:`~object.__imul__` -described below; they should not define other numerical operators. It is -recommended that both mappings and sequences implement the +described below; they should not define other numerical +operators. It is recommended that both mappings and sequences implement the :meth:`~object.__contains__` method to allow efficient use of the ``in`` operator; for mappings, ``in`` should search the mapping's keys; for sequences, it should -search through the values. It is further recommended that both mappings and +search through the values. It is further recommended that both mappings and sequences implement the :meth:`~object.__iter__` method to allow efficient iteration through the container; for mappings, :meth:`__iter__` should iterate through the object's keys; for sequences, it should iterate through the values. From 3c87bca621f317c7c507c745435c8fe0310c1ddf Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sat, 20 Nov 2021 00:17:06 +0000 Subject: [PATCH 04/18] Tweak again --- Doc/reference/datamodel.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 67ad3755614397..0e03ca70e25dc7 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -881,15 +881,15 @@ Class instances section :ref:`descriptors` for another way in which attributes of a class retrieved via its instances may differ from the objects actually stored in the class's :attr:`~object.__dict__`. If no class attribute is found, and the - object's class has a :meth:`~object.__getattr__` method, that is called to - satisfy the lookup. + object's class has a :meth:`~object.__getattr__` method, that is called to satisfy + the lookup. .. index:: triple: class instance; attribute; assignment Attribute assignments and deletions update the instance's dictionary, never a class's dictionary. If the class has a :meth:`~object.__setattr__` or - :meth:`~object.__delattr__` method, this is called instead of updating the - instance dictionary directly. + :meth:`~object.__delattr__` method, this is called instead of updating the instance + dictionary directly. .. index:: object: numeric @@ -1233,7 +1233,7 @@ with special names. This is Python's approach to :dfn:`operator overloading`, allowing classes to define their own behavior with respect to language operators. For instance, if a class defines a method named :meth:`~object.__getitem__`, -and ``x`` is an instance of this class, then``x[i]`` is roughly equivalent +and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent to ``type(x).__getitem__(x, i)``. Except where mentioned, attempts to execute an operation raise an exception when no appropriate method is defined (typically :exc:`AttributeError` or :exc:`TypeError`). From 0a592691c895446c30e1772fd986ee4c7018edb7 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sat, 20 Nov 2021 00:21:44 +0000 Subject: [PATCH 05/18] Third tweak --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 0e03ca70e25dc7..af2f56a5144cf5 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2412,7 +2412,7 @@ multiplication (meaning repetition) by defining the methods :meth:`~object.__add__`, :meth:`~object.__radd__`, :meth:`~object.__iadd__`, :meth:`~object.__mul__`, :meth:`~object.__rmul__` and :meth:`~object.__imul__` described below; they should not define other numerical -operators. It is recommended that both mappings and sequences implement the +operators. It is recommended that both mappings and sequences implement the :meth:`~object.__contains__` method to allow efficient use of the ``in`` operator; for mappings, ``in`` should search the mapping's keys; for sequences, it should From 29cf6d89178d193dfc87e799146cb30ea771f9c2 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sat, 20 Nov 2021 00:22:56 +0000 Subject: [PATCH 06/18] Fifth tweak --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index af2f56a5144cf5..53aa4da88b2405 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2394,7 +2394,7 @@ either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers *k* for which ``0 <= k < N`` where *N* is the length of the sequence, or :class:`slice` objects, which define a -range of items. It is also recommended that mappings provide the methods +range of items. It is also recommended that mappings provide the methods :meth:`~dict.keys`, :meth:`~dict.values`, :meth:`~dict.items`, :meth:`~dict.get`, :meth:`~dict.clear`, :meth:`~dict.setdefault`, :meth:`~dict.pop`, :meth:`~dict.popitem`, :meth:`~dict.copy`, and From ac2332fdc4f47676eeeed4a2609103ad1f156f67 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sat, 20 Nov 2021 00:25:19 +0000 Subject: [PATCH 07/18] Sixth tweak --- Doc/reference/datamodel.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 53aa4da88b2405..52a503f2adc2fe 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2392,8 +2392,7 @@ usually are :term:`sequences` (such as :class:`lists` or but can represent other containers as well. The first set of methods is used either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers *k* for which ``0 <= k < -N`` where *N* is the length of the -sequence, or :class:`slice` objects, which define a +N`` where *N* is the length of the sequence, or :class:`slice` objects, which define a range of items. It is also recommended that mappings provide the methods :meth:`~dict.keys`, :meth:`~dict.values`, :meth:`~dict.items`, :meth:`~dict.get`, :meth:`~dict.clear`, :meth:`~dict.setdefault`, From b486be5711c5d54a15ea9e57799f621e94adb171 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sat, 20 Nov 2021 00:26:32 +0000 Subject: [PATCH 08/18] Seventh tweak --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 52a503f2adc2fe..48180eda22a341 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2389,7 +2389,7 @@ The following methods can be defined to implement container objects. Containers usually are :term:`sequences` (such as :class:`lists` or :class:`tuples`) or :term:`mappings` (like :class:`dictionaries`), -but can represent other containers as well. The first set of methods is used +but can represent other containers as well. The first set of methods is used either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers *k* for which ``0 <= k < N`` where *N* is the length of the sequence, or :class:`slice` objects, which define a From 45652130db8cb45ca1eb250a6b6487d0948b4d2f Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sat, 20 Nov 2021 00:27:56 +0000 Subject: [PATCH 09/18] Eighth tweak --- Doc/reference/datamodel.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 48180eda22a341..ebfc821c475e57 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1838,7 +1838,8 @@ descriptor; if it defines neither, it is a non-data descriptor. Normally, data descriptors define both :meth:`__get__` and :meth:`__set__`, while non-data descriptors have just the :meth:`__get__` method. Data descriptors with :meth:`__get__` and :meth:`__set__` (and/or :meth:`__delete__`) defined always override a redefinition in an -instance dictionary. In contrast, non-data descriptors can be overridden by instances. +instance dictionary. In contrast, non-data descriptors can be overridden by +instances. Python methods (including those decorated with :func:`@staticmethod` and :func:`@classmethod`) are From 8540cc782294a7e8ed72fda2112837a41d6c126f Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 29 Nov 2021 09:11:16 +0000 Subject: [PATCH 10/18] Update Doc/reference/datamodel.rst Co-authored-by: Serhiy Storchaka --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index ebfc821c475e57..63f148606e2464 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -678,7 +678,7 @@ Callable types :keyword:`async for` statement to execute the body of the function. Calling the asynchronous iterator's - :meth:`aiterator.__anext__` method + :meth:`aiterator.__anext__ ` method will return an :term:`awaitable` which when awaited will execute until it provides a value using the :keyword:`yield` expression. When the function executes an empty :keyword:`return` From d9c84577115a5ed560ea47a8cc726ee4d99ad218 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 29 Nov 2021 09:11:43 +0000 Subject: [PATCH 11/18] Update Doc/reference/datamodel.rst Co-authored-by: Serhiy Storchaka --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 63f148606e2464..d15bedd190502d 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1887,7 +1887,7 @@ Notes on using *__slots__* the *__slots__* declaration. * Without a *__weakref__* variable for each instance, classes defining - *__slots__* do not support :mod:`weak references` to its instances. + *__slots__* do not support :mod:`weak references ` to its instances. If weak reference support is needed, then add ``'__weakref__'`` to the sequence of strings in the *__slots__* declaration. From 18673da83e8a7e65d4bed8ba1997dc646bff1ea7 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 29 Nov 2021 09:16:40 +0000 Subject: [PATCH 12/18] Update Doc/reference/datamodel.rst Co-authored-by: Serhiy Storchaka --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index d15bedd190502d..d9e47cce8fee67 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1919,7 +1919,7 @@ Notes on using *__slots__* * :attr:`~instance.__class__` assignment works only if both classes have the same *__slots__*. -* :ref:`Multiple inheritance` with multiple slotted parent +* :ref:`Multiple inheritance ` with multiple slotted parent classes can be used, but only one parent is allowed to have attributes created by slots (the other bases must have empty slot layouts) - violations raise From 34a0fa2a884f065ffdf213ec47da7a4093b7cc42 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 29 Nov 2021 09:17:04 +0000 Subject: [PATCH 13/18] Update Doc/reference/datamodel.rst Co-authored-by: Serhiy Storchaka --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index d9e47cce8fee67..090165acc55d70 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2387,7 +2387,7 @@ Emulating container types ------------------------- The following methods can be defined to implement container objects. Containers -usually are :term:`sequences` (such as :class:`lists` or +usually are :term:`sequences ` (such as :class:`lists ` or :class:`tuples`) or :term:`mappings` (like :class:`dictionaries`), but can represent other containers as well. The first set of methods is used From 318f545bc932d0c3db476ffc9f0377315f0508e5 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 29 Nov 2021 09:17:20 +0000 Subject: [PATCH 14/18] Update Doc/reference/datamodel.rst Co-authored-by: Serhiy Storchaka --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 090165acc55d70..f718de98e40ee4 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2388,7 +2388,7 @@ Emulating container types The following methods can be defined to implement container objects. Containers usually are :term:`sequences ` (such as :class:`lists ` or -:class:`tuples`) or :term:`mappings` (like +:class:`tuples `) or :term:`mappings ` (like :class:`dictionaries`), but can represent other containers as well. The first set of methods is used either to emulate a sequence or to emulate a mapping; the difference is that for From 8073ec43c5f21fcbd4e9a496261710fbcb1015a8 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 29 Nov 2021 11:09:19 +0000 Subject: [PATCH 15/18] Address review --- Doc/reference/datamodel.rst | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index f718de98e40ee4..27156867513ce1 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1842,7 +1842,7 @@ instance dictionary. In contrast, non-data descriptors can be overridden by instances. Python methods (including those decorated with -:func:`@staticmethod` and :func:`@classmethod`) are +:func:`@staticmethod ` and :func:`@classmethod `) are implemented as non-data descriptors. Accordingly, instances can redefine and override methods. This allows individual instances to acquire behaviors that differ from other instances of the same class. @@ -1892,7 +1892,7 @@ Notes on using *__slots__* support is needed, then add ``'__weakref__'`` to the sequence of strings in the *__slots__* declaration. -* *__slots__* are implemented at the class level by creating :ref:`descriptors` +* *__slots__* are implemented at the class level by creating :ref:`descriptors ` for each variable name. As a result, class attributes cannot be used to set default values for instance variables defined by *__slots__*; otherwise, the class attribute would overwrite the descriptor @@ -2089,7 +2089,7 @@ is prepared. If the metaclass has a ``__prepare__`` attribute, it is called as ``namespace = metaclass.__prepare__(name, bases, **kwds)`` (where the additional keyword arguments, if any, come from the class definition). The ``__prepare__`` method should be implemented as a -:func:`classmethod`. The +:func:`classmethod `. The namespace returned by ``__prepare__`` is passed in to ``__new__``, but when the final class object is created the namespace is copied into a new ``dict``. @@ -2389,23 +2389,22 @@ Emulating container types The following methods can be defined to implement container objects. Containers usually are :term:`sequences ` (such as :class:`lists ` or :class:`tuples `) or :term:`mappings ` (like -:class:`dictionaries`), +:class:`dictionaries `), but can represent other containers as well. The first set of methods is used either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers *k* for which ``0 <= k < N`` where *N* is the length of the sequence, or :class:`slice` objects, which define a range of items. It is also recommended that mappings provide the methods -:meth:`~dict.keys`, :meth:`~dict.values`, :meth:`~dict.items`, -:meth:`~dict.get`, :meth:`~dict.clear`, :meth:`~dict.setdefault`, -:meth:`~dict.pop`, :meth:`~dict.popitem`, :meth:`~dict.copy`, and -:meth:`~dict.update` behaving similar to those for Python's standard -:class:`dictionary` objects. The :mod:`collections.abc` module provides a -:class:`~collections.abc.MutableMapping` :term:`abstract base class` to help -create those methods from a base set of :meth:`~object.__getitem__`, -:meth:`~object.__setitem__`, :meth:`~object.__delitem__`, and :meth:`keys`. +:meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`, +:meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`!copy`, and +:meth:`update` behaving similar to those for Python's standard :class:`dictionary` +objects. The :mod:`collections.abc` module provides a +:class:`~collections.abc.MutableMapping` +:term:`abstract base class` to help create those methods from a base set of +:meth:`~object.__getitem__`, :meth:`~object.__setitem__`, :meth:`~object.__delitem__`, and :meth:`keys`. Mutable sequences should provide methods :meth:`append`, :meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`, -:meth:`reverse` and :meth:`~list.sort`, like Python standard :class:`list` +:meth:`reverse` and :meth:`sort`, like Python standard :class:`list` objects. Finally, sequence types should implement addition (meaning concatenation) and multiplication (meaning repetition) by defining the methods From 07fe82489e341b4d92317d60a561c41afc6ae9db Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 29 Nov 2021 11:11:17 +0000 Subject: [PATCH 16/18] Trailing whitespace --- Doc/reference/datamodel.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 27156867513ce1..a192198c2aa12c 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2395,12 +2395,12 @@ either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers *k* for which ``0 <= k < N`` where *N* is the length of the sequence, or :class:`slice` objects, which define a range of items. It is also recommended that mappings provide the methods -:meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`, +:meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`, :meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`!copy`, and :meth:`update` behaving similar to those for Python's standard :class:`dictionary` objects. The :mod:`collections.abc` module provides a :class:`~collections.abc.MutableMapping` -:term:`abstract base class` to help create those methods from a base set of +:term:`abstract base class` to help create those methods from a base set of :meth:`~object.__getitem__`, :meth:`~object.__setitem__`, :meth:`~object.__delitem__`, and :meth:`keys`. Mutable sequences should provide methods :meth:`append`, :meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`, From ec5a9700fc46fc005ff3c56fe53918521ae95e4e Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 29 Nov 2021 11:13:10 +0000 Subject: [PATCH 17/18] Tweam --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index a192198c2aa12c..1284c57a5d5ffd 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2398,7 +2398,7 @@ range of items. It is also recommended that mappings provide the methods :meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`, :meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`!copy`, and :meth:`update` behaving similar to those for Python's standard :class:`dictionary` -objects. The :mod:`collections.abc` module provides a +objects. The :mod:`collections.abc` module provides a :class:`~collections.abc.MutableMapping` :term:`abstract base class` to help create those methods from a base set of :meth:`~object.__getitem__`, :meth:`~object.__setitem__`, :meth:`~object.__delitem__`, and :meth:`keys`. From 46a4034217070d3ac66256c93b542a2506393fa8 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 1 Dec 2021 23:45:20 +0000 Subject: [PATCH 18/18] Tweak again --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 1284c57a5d5ffd..487dd67a7b1d19 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2397,7 +2397,7 @@ N`` where *N* is the length of the sequence, or :class:`slice` objects, which de range of items. It is also recommended that mappings provide the methods :meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`, :meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`!copy`, and -:meth:`update` behaving similar to those for Python's standard :class:`dictionary` +:meth:`update` behaving similar to those for Python's standard :class:`dictionary ` objects. The :mod:`collections.abc` module provides a :class:`~collections.abc.MutableMapping` :term:`abstract base class` to help create those methods from a base set of