diff options
Diffstat (limited to 'Doc/reference/datamodel.rst')
| -rw-r--r-- | Doc/reference/datamodel.rst | 358 |
1 files changed, 288 insertions, 70 deletions
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 1560ad0..2f5625b 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -454,6 +454,19 @@ Callable types .. tabularcolumns:: |l|L|l| + .. index:: + single: __doc__ (function attribute) + single: __name__ (function attribute) + single: __module__ (function attribute) + single: __dict__ (function attribute) + single: __defaults__ (function attribute) + single: __closure__ (function attribute) + single: __code__ (function attribute) + single: __globals__ (function attribute) + single: __annotations__ (function attribute) + single: __kwdefaults__ (function attribute) + pair: global; namespace + +-------------------------+-------------------------------+-----------+ | Attribute | Meaning | | +=========================+===============================+===========+ @@ -462,10 +475,11 @@ Callable types | | unavailable; not inherited by | | | | subclasses | | +-------------------------+-------------------------------+-----------+ - | :attr:`__name__` | The function's name | Writable | + | :attr:`~definition.\ | The function's name | Writable | + | __name__` | | | +-------------------------+-------------------------------+-----------+ - | :attr:`__qualname__` | The function's | Writable | - | | :term:`qualified name` | | + | :attr:`~definition.\ | The function's | Writable | + | __qualname__` | :term:`qualified name` | | | | | | | | .. versionadded:: 3.3 | | +-------------------------+-------------------------------+-----------+ @@ -489,7 +503,7 @@ Callable types | | module in which the function | | | | was defined. | | +-------------------------+-------------------------------+-----------+ - | :attr:`__dict__` | The namespace supporting | Writable | + | :attr:`~object.__dict__`| The namespace supporting | Writable | | | arbitrary function | | | | attributes. | | +-------------------------+-------------------------------+-----------+ @@ -519,19 +533,6 @@ Callable types Additional information about a function's definition can be retrieved from its code object; see the description of internal types below. - .. index:: - single: __doc__ (function attribute) - single: __name__ (function attribute) - single: __module__ (function attribute) - single: __dict__ (function attribute) - single: __defaults__ (function attribute) - single: __closure__ (function attribute) - single: __code__ (function attribute) - single: __globals__ (function attribute) - single: __annotations__ (function attribute) - single: __kwdefaults__ (function attribute) - pair: global; namespace - Instance methods .. index:: object: method @@ -550,7 +551,7 @@ Callable types Special read-only attributes: :attr:`__self__` is the class instance object, :attr:`__func__` is the function object; :attr:`__doc__` is the method's - documentation (same as ``__func__.__doc__``); :attr:`__name__` is the + documentation (same as ``__func__.__doc__``); :attr:`~definition.__name__` is the method name (same as ``__func__.__name__``); :attr:`__module__` is the name of the module the method was defined in, or ``None`` if unavailable. @@ -616,6 +617,16 @@ Callable types exception is raised and the iterator will have reached the end of the set of values to be returned. + Coroutine functions + .. index:: + single: coroutine; function + + A function or method which is defined using :keyword:`async def` is called + a :dfn:`coroutine function`. Such a function, when called, returns a + :term:`coroutine` object. It may contain :keyword:`await` expressions, + as well as :keyword:`async with` and :keyword:`async for` statements. See + also the :ref:`coroutine-objects` section. + Built-in functions .. index:: object: built-in function @@ -627,7 +638,7 @@ Callable types standard built-in module). The number and type of the arguments are determined by the C function. Special read-only attributes: :attr:`__doc__` is the function's documentation string, or ``None`` if - unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is + unavailable; :attr:`~definition.__name__` is the function's name; :attr:`__self__` is set to ``None`` (but see the next item); :attr:`__module__` is the name of the module the function was defined in or ``None`` if unavailable. @@ -677,7 +688,7 @@ Modules .. index:: single: __dict__ (module attribute) - Special read-only attribute: :attr:`__dict__` is the module's namespace as a + Special read-only attribute: :attr:`~object.__dict__` is the module's namespace as a dictionary object. .. impl-detail:: @@ -733,7 +744,7 @@ Custom classes method object, it is transformed into the object wrapped by the static method object. See section :ref:`descriptors` for another way in which attributes retrieved from a class may differ from those actually contained in its - :attr:`__dict__`. + :attr:`~object.__dict__`. .. index:: triple: class; attribute; assignment @@ -751,12 +762,12 @@ Custom classes single: __bases__ (class attribute) single: __doc__ (class attribute) - Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is - the module name in which the class was defined; :attr:`__dict__` is the + Special attributes: :attr:`~definition.__name__` is the class name; :attr:`__module__` is + the module name in which the class was defined; :attr:`~object.__dict__` is the dictionary containing the class's namespace; :attr:`~class.__bases__` is a - tuple (possibly empty or a singleton) containing the base classes, in the + tuple (possibly a singleton) containing the base classes, in the order of their occurrence in the base class list; :attr:`__doc__` is the - class's documentation string, or None if undefined. + class's documentation string, or ``None`` if undefined. Class instances .. index:: @@ -775,7 +786,7 @@ Class instances class method objects are also transformed; see above under "Classes". See 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:`__dict__`. If no class attribute is found, and the + 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. @@ -836,11 +847,9 @@ Internal types definitions may change with future versions of the interpreter, but they are mentioned here for completeness. - Code objects - .. index:: - single: bytecode - object: code + .. index:: bytecode, object; code, code object + Code objects Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`. The difference between a code object and a function object is that the function object contains an explicit reference to the function's globals (the module in @@ -1108,7 +1117,7 @@ Basic customization instance; for example: ``BaseClass.__init__(self, [args...])``. Because :meth:`__new__` and :meth:`__init__` work together in constructing - objects (:meth:`__new__` to create it, and :meth:`__init__` to customise it), + objects (:meth:`__new__` to create it, and :meth:`__init__` to customize it), no non-``None`` value may be returned by :meth:`__init__`; doing so will cause a :exc:`TypeError` to be raised at runtime. @@ -1296,11 +1305,14 @@ Basic customization Called by built-in function :func:`hash` and for operations on members of hashed collections including :class:`set`, :class:`frozenset`, and - :class:`dict`. :meth:`__hash__` should return an integer. The only - required property is that objects which compare equal have the same hash - value; it is advised to somehow mix together (e.g. using exclusive or) the - hash values for the components of the object that also play a part in - comparison of objects. + :class:`dict`. :meth:`__hash__` should return an integer. The only required + property is that objects which compare equal have the same hash value; it is + advised to mix together the hash values of the components of the object that + also play a part in comparison of objects by packing them into a tuple and + hashing the tuple. Example:: + + def __hash__(self): + return hash((self.name, self.nick, self.color)) .. note:: @@ -1458,7 +1470,7 @@ method (a so-called *descriptor* class) appears in an *owner* class (the descriptor must be in either the owner's class dictionary or in the class dictionary for one of its parents). In the examples below, "the attribute" refers to the attribute whose name is the key of the property in the owner -class' :attr:`__dict__`. +class' :attr:`~object.__dict__`. .. method:: object.__get__(self, instance, owner) @@ -1628,7 +1640,7 @@ By default, classes are constructed using :func:`type`. The class body is executed in a new namespace and the class name is bound locally to the result of ``type(name, bases, namespace)``. -The class creation process can be customised by passing the ``metaclass`` +The class creation process can be customized by passing the ``metaclass`` keyword argument in the class definition line, or by inheriting from an existing class that included such an argument. In the following example, both ``MyClass`` and ``MySubclass`` are instances of ``Meta``:: @@ -1724,6 +1736,11 @@ After the class object is created, it is passed to the class decorators included in the class definition (if any) and the resulting object is bound in the local namespace as the defined class. +When a new class is created by ``type.__new__``, the object provided as the +namespace parameter is copied to a standard Python dictionary and the original +object is discarded. The new copy becomes the :attr:`~object.__dict__` attribute +of the class object. + .. seealso:: :pep:`3135` - New super @@ -1743,11 +1760,11 @@ to remember the order that class variables are defined:: class OrderedClass(type): - @classmethod - def __prepare__(metacls, name, bases, **kwds): + @classmethod + def __prepare__(metacls, name, bases, **kwds): return collections.OrderedDict() - def __new__(cls, name, bases, namespace, **kwds): + def __new__(cls, name, bases, namespace, **kwds): result = type.__new__(cls, name, bases, dict(namespace)) result.members = tuple(namespace) return result @@ -1990,6 +2007,7 @@ left undefined. .. method:: object.__add__(self, other) object.__sub__(self, other) object.__mul__(self, other) + object.__matmul__(self, other) object.__truediv__(self, other) object.__floordiv__(self, other) object.__mod__(self, other) @@ -2006,15 +2024,16 @@ left undefined. builtin: pow builtin: pow - These methods are called to implement the binary arithmetic operations (``+``, - ``-``, ``*``, ``/``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, - ``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression - ``x + y``, where *x* is an instance of a class that has an :meth:`__add__` - method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the - equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be - related to :meth:`__truediv__`. Note that :meth:`__pow__` should be defined - to accept an optional third argument if the ternary version of the built-in - :func:`pow` function is to be supported. + These methods are called to implement the binary arithmetic operations + (``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`, + :func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``). For instance, to + evaluate the expression ``x + y``, where *x* is an instance of a class that + has an :meth:`__add__` method, ``x.__add__(y)`` is called. The + :meth:`__divmod__` method should be the equivalent to using + :meth:`__floordiv__` and :meth:`__mod__`; it should not be related to + :meth:`__truediv__`. Note that :meth:`__pow__` should be defined to accept + an optional third argument if the ternary version of the built-in :func:`pow` + function is to be supported. If one of those methods does not support the operation with the supplied arguments, it should return ``NotImplemented``. @@ -2023,6 +2042,7 @@ left undefined. .. method:: object.__radd__(self, other) object.__rsub__(self, other) object.__rmul__(self, other) + object.__rmatmul__(self, other) object.__rtruediv__(self, other) object.__rfloordiv__(self, other) object.__rmod__(self, other) @@ -2038,14 +2058,14 @@ left undefined. builtin: divmod builtin: pow - These methods are called to implement the binary arithmetic operations (``+``, - ``-``, ``*``, ``/``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, - ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected (swapped) operands. - These functions are only called if the left operand does not support the - corresponding operation and the operands are of different types. [#]_ For - instance, to evaluate the expression ``x - y``, where *y* is an instance of - a class that has an :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if - ``x.__sub__(y)`` returns *NotImplemented*. + These methods are called to implement the binary arithmetic operations + (``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`, + :func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected + (swapped) operands. These functions are only called if the left operand does + not support the corresponding operation and the operands are of different + types. [#]_ For instance, to evaluate the expression ``x - y``, where *y* is + an instance of a class that has an :meth:`__rsub__` method, ``y.__rsub__(x)`` + is called if ``x.__sub__(y)`` returns *NotImplemented*. .. index:: builtin: pow @@ -2063,6 +2083,7 @@ left undefined. .. method:: object.__iadd__(self, other) object.__isub__(self, other) object.__imul__(self, other) + object.__imatmul__(self, other) object.__itruediv__(self, other) object.__ifloordiv__(self, other) object.__imod__(self, other) @@ -2074,17 +2095,17 @@ left undefined. object.__ior__(self, other) These methods are called to implement the augmented arithmetic assignments - (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``, - ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation - in-place (modifying *self*) and return the result (which could be, but does - not have to be, *self*). If a specific method is not defined, the augmented - assignment falls back to the normal methods. For instance, if *x* is an - instance of a class with an :meth:`__iadd__` method, ``x += y`` is equivalent - to ``x = x.__iadd__(y)`` . Otherwise, ``x.__add__(y)`` and ``y.__radd__(x)`` - are considered, as with the evaluation of ``x + y``. In certain situations, - augmented assignment can result in unexpected errors (see - :ref:`faq-augmented-assignment-tuple-error`), but this behavior is in - fact part of the data model. + (``+=``, ``-=``, ``*=``, ``@=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, + ``>>=``, ``&=``, ``^=``, ``|=``). These methods should attempt to do the + operation in-place (modifying *self*) and return the result (which could be, + but does not have to be, *self*). If a specific method is not defined, the + augmented assignment falls back to the normal methods. For instance, if *x* + is an instance of a class with an :meth:`__iadd__` method, ``x += y`` is + equivalent to ``x = x.__iadd__(y)`` . Otherwise, ``x.__add__(y)`` and + ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``. In + certain situations, augmented assignment can result in unexpected errors (see + :ref:`faq-augmented-assignment-tuple-error`), but this behavior is in fact + part of the data model. .. method:: object.__neg__(self) @@ -2174,7 +2195,7 @@ For more information on context managers, see :ref:`typecontextmanager`. .. seealso:: - :pep:`0343` - The "with" statement + :pep:`343` - The "with" statement The specification, background, and examples for the Python :keyword:`with` statement. @@ -2254,6 +2275,203 @@ special methods (the special method *must* be set on the class object itself in order to be consistently invoked by the interpreter). +.. index:: + single: coroutine + +Coroutines +========== + + +Awaitable Objects +----------------- + +An :term:`awaitable` object generally implements an :meth:`__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` or :func:`asyncio.coroutine` + are also awaitable, but they do not implement :meth:`__await__`. + +.. method:: object.__await__(self) + + Must return an :term:`iterator`. Should be used to implement + :term:`awaitable` objects. For instance, :class:`asyncio.Future` implements + this method to be compatible with the :keyword:`await` expression. + +.. versionadded:: 3.5 + +.. seealso:: :pep:`492` for additional information about awaitable objects. + + +.. _coroutine-objects: + +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 +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 +should not directly raise unhandled :exc:`StopIteration` exceptions. + +Coroutines also have the methods listed below, which are analogous to +those of generators (see :ref:`generator-methods`). However, unlike +generators, coroutines do not directly support iteration. + +.. versionchanged:: 3.5.2 + It is a :exc:`RuntimeError` to await on a coroutine more than once. + + +.. method:: coroutine.send(value) + + 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 + 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. + +.. method:: coroutine.throw(type[, value[, traceback]]) + + Raises the specified exception in the coroutine. This method delegates + to the :meth:`~generator.throw` method of the iterator that caused + 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 + above. If the exception is not caught in the coroutine, it propagates + back to the caller. + +.. method:: coroutine.close() + + Causes the coroutine to clean itself up and exit. If the coroutine + is suspended, this method first delegates to the :meth:`~generator.close` + method of the iterator that caused the coroutine to suspend, if it + has such a method. Then it raises :exc:`GeneratorExit` at the + suspension point, causing the coroutine to immediately clean itself up. + Finally, the coroutine is marked as having finished executing, even if + it was never started. + + Coroutine objects are automatically closed using the above process when + they are about to be destroyed. + +.. _async-iterators: + +Asynchronous Iterators +---------------------- + +An *asynchronous iterable* is able to call asynchronous code in its +``__aiter__`` implementation, and an *asynchronous iterator* can call +asynchronous code in its ``__anext__`` method. + +Asynchronous iterators can be used in an :keyword:`async for` statement. + +.. method:: object.__aiter__(self) + + Must return an *asynchronous iterator* object. + +.. method:: object.__anext__(self) + + Must return an *awaitable* resulting in a next value of the iterator. Should + raise a :exc:`StopAsyncIteration` error when the iteration is over. + +An example of an asynchronous iterable object:: + + class Reader: + async def readline(self): + ... + + def __aiter__(self): + return self + + async def __anext__(self): + val = await self.readline() + if val == b'': + raise StopAsyncIteration + return val + +.. versionadded:: 3.5 + +.. note:: + + .. versionchanged:: 3.5.2 + Starting with CPython 3.5.2, ``__aiter__`` can directly return + :term:`asynchronous iterators <asynchronous iterator>`. Returning + an :term:`awaitable` object will result in a + :exc:`PendingDeprecationWarning`. + + The recommended way of writing backwards compatible code in + CPython 3.5.x is to continue returning awaitables from + ``__aiter__``. If you want to avoid the PendingDeprecationWarning + and keep the code backwards compatible, the following decorator + can be used:: + + import functools + import sys + + if sys.version_info < (3, 5, 2): + def aiter_compat(func): + @functools.wraps(func) + async def wrapper(self): + return func(self) + return wrapper + else: + def aiter_compat(func): + return func + + Example:: + + class AsyncIterator: + + @aiter_compat + def __aiter__(self): + return self + + async def __anext__(self): + ... + + Starting with CPython 3.6, the :exc:`PendingDeprecationWarning` + will be replaced with the :exc:`DeprecationWarning`. + In CPython 3.7, returning an awaitable from ``__aiter__`` will + result in a :exc:`RuntimeError`. + + +Asynchronous Context Managers +----------------------------- + +An *asynchronous context manager* is a *context manager* that is able to +suspend execution in its ``__aenter__`` and ``__aexit__`` methods. + +Asynchronous context managers can be used in an :keyword:`async with` statement. + +.. method:: object.__aenter__(self) + + This method is semantically similar to the :meth:`__enter__`, with only + difference that it must return an *awaitable*. + +.. method:: object.__aexit__(self, exc_type, exc_value, traceback) + + This method is semantically similar to the :meth:`__exit__`, with only + difference that it must return an *awaitable*. + +An example of an asynchronous context manager class:: + + class AsyncContextManager: + async def __aenter__(self): + await log('entering context') + + async def __aexit__(self, exc_type, exc, tb): + await log('exiting context') + +.. versionadded:: 3.5 + + .. rubric:: Footnotes .. [#] It *is* possible in some cases to change an object's type, under certain |