diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/inspect.rst | 367 | ||||
| -rw-r--r-- | Doc/library/types.rst | 12 | ||||
| -rw-r--r-- | Doc/reference/compound_stmts.rst | 11 | ||||
| -rw-r--r-- | Doc/reference/datamodel.rst | 9 | ||||
| -rw-r--r-- | Doc/whatsnew/3.6.rst | 26 |
5 files changed, 245 insertions, 180 deletions
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 5cb7c22..1977d88 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -34,185 +34,190 @@ provided as convenient choices for the second argument to :func:`getmembers`. They also help you determine when you can expect to find the following special attributes: -+-----------+-----------------+---------------------------+ -| Type | Attribute | Description | -+===========+=================+===========================+ -| module | __doc__ | documentation string | -+-----------+-----------------+---------------------------+ -| | __file__ | filename (missing for | -| | | built-in modules) | -+-----------+-----------------+---------------------------+ -| class | __doc__ | documentation string | -+-----------+-----------------+---------------------------+ -| | __name__ | name with which this | -| | | class was defined | -+-----------+-----------------+---------------------------+ -| | __qualname__ | qualified name | -+-----------+-----------------+---------------------------+ -| | __module__ | name of module in which | -| | | this class was defined | -+-----------+-----------------+---------------------------+ -| method | __doc__ | documentation string | -+-----------+-----------------+---------------------------+ -| | __name__ | name with which this | -| | | method was defined | -+-----------+-----------------+---------------------------+ -| | __qualname__ | qualified name | -+-----------+-----------------+---------------------------+ -| | __func__ | function object | -| | | containing implementation | -| | | of method | -+-----------+-----------------+---------------------------+ -| | __self__ | instance to which this | -| | | method is bound, or | -| | | ``None`` | -+-----------+-----------------+---------------------------+ -| function | __doc__ | documentation string | -+-----------+-----------------+---------------------------+ -| | __name__ | name with which this | -| | | function was defined | -+-----------+-----------------+---------------------------+ -| | __qualname__ | qualified name | -+-----------+-----------------+---------------------------+ -| | __code__ | code object containing | -| | | compiled function | -| | | :term:`bytecode` | -+-----------+-----------------+---------------------------+ -| | __defaults__ | tuple of any default | -| | | values for positional or | -| | | keyword parameters | -+-----------+-----------------+---------------------------+ -| | __kwdefaults__ | mapping of any default | -| | | values for keyword-only | -| | | parameters | -+-----------+-----------------+---------------------------+ -| | __globals__ | global namespace in which | -| | | this function was defined | -+-----------+-----------------+---------------------------+ -| | __annotations__ | mapping of parameters | -| | | names to annotations; | -| | | ``"return"`` key is | -| | | reserved for return | -| | | annotations. | -+-----------+-----------------+---------------------------+ -| traceback | tb_frame | frame object at this | -| | | level | -+-----------+-----------------+---------------------------+ -| | tb_lasti | index of last attempted | -| | | instruction in bytecode | -+-----------+-----------------+---------------------------+ -| | tb_lineno | current line number in | -| | | Python source code | -+-----------+-----------------+---------------------------+ -| | tb_next | next inner traceback | -| | | object (called by this | -| | | level) | -+-----------+-----------------+---------------------------+ -| frame | f_back | next outer frame object | -| | | (this frame's caller) | -+-----------+-----------------+---------------------------+ -| | f_builtins | builtins namespace seen | -| | | by this frame | -+-----------+-----------------+---------------------------+ -| | f_code | code object being | -| | | executed in this frame | -+-----------+-----------------+---------------------------+ -| | f_globals | global namespace seen by | -| | | this frame | -+-----------+-----------------+---------------------------+ -| | f_lasti | index of last attempted | -| | | instruction in bytecode | -+-----------+-----------------+---------------------------+ -| | f_lineno | current line number in | -| | | Python source code | -+-----------+-----------------+---------------------------+ -| | f_locals | local namespace seen by | -| | | this frame | -+-----------+-----------------+---------------------------+ -| | f_restricted | 0 or 1 if frame is in | -| | | restricted execution mode | -+-----------+-----------------+---------------------------+ -| | f_trace | tracing function for this | -| | | frame, or ``None`` | -+-----------+-----------------+---------------------------+ -| code | co_argcount | number of arguments (not | -| | | including \* or \*\* | -| | | args) | -+-----------+-----------------+---------------------------+ -| | co_code | string of raw compiled | -| | | bytecode | -+-----------+-----------------+---------------------------+ -| | co_consts | tuple of constants used | -| | | in the bytecode | -+-----------+-----------------+---------------------------+ -| | co_filename | name of file in which | -| | | this code object was | -| | | created | -+-----------+-----------------+---------------------------+ -| | co_firstlineno | number of first line in | -| | | Python source code | -+-----------+-----------------+---------------------------+ -| | co_flags | bitmap: 1=optimized ``|`` | -| | | 2=newlocals ``|`` 4=\*arg | -| | | ``|`` 8=\*\*arg | -+-----------+-----------------+---------------------------+ -| | co_lnotab | encoded mapping of line | -| | | numbers to bytecode | -| | | indices | -+-----------+-----------------+---------------------------+ -| | co_name | name with which this code | -| | | object was defined | -+-----------+-----------------+---------------------------+ -| | co_names | tuple of names of local | -| | | variables | -+-----------+-----------------+---------------------------+ -| | co_nlocals | number of local variables | -+-----------+-----------------+---------------------------+ -| | co_stacksize | virtual machine stack | -| | | space required | -+-----------+-----------------+---------------------------+ -| | co_varnames | tuple of names of | -| | | arguments and local | -| | | variables | -+-----------+-----------------+---------------------------+ -| generator | __name__ | name | -+-----------+-----------------+---------------------------+ -| | __qualname__ | qualified name | -+-----------+-----------------+---------------------------+ -| | gi_frame | frame | -+-----------+-----------------+---------------------------+ -| | gi_running | is the generator running? | -+-----------+-----------------+---------------------------+ -| | gi_code | code | -+-----------+-----------------+---------------------------+ -| | gi_yieldfrom | object being iterated by | -| | | ``yield from``, or | -| | | ``None`` | -+-----------+-----------------+---------------------------+ -| coroutine | __name__ | name | -+-----------+-----------------+---------------------------+ -| | __qualname__ | qualified name | -+-----------+-----------------+---------------------------+ -| | cr_await | object being awaited on, | -| | | or ``None`` | -+-----------+-----------------+---------------------------+ -| | cr_frame | frame | -+-----------+-----------------+---------------------------+ -| | cr_running | is the coroutine running? | -+-----------+-----------------+---------------------------+ -| | cr_code | code | -+-----------+-----------------+---------------------------+ -| builtin | __doc__ | documentation string | -+-----------+-----------------+---------------------------+ -| | __name__ | original name of this | -| | | function or method | -+-----------+-----------------+---------------------------+ -| | __qualname__ | qualified name | -+-----------+-----------------+---------------------------+ -| | __self__ | instance to which a | -| | | method is bound, or | -| | | ``None`` | -+-----------+-----------------+---------------------------+ ++-----------+----------------------+---------------------------+ +| Type | Attribute | Description | ++===========+======================+===========================+ +| module | __doc__ | documentation string | ++-----------+----------------------+---------------------------+ +| | __file__ | filename (missing for | +| | | built-in modules) | ++-----------+----------------------+---------------------------+ +| class | __doc__ | documentation string | ++-----------+----------------------+---------------------------+ +| | __name__ | name with which this | +| | | class was defined | ++-----------+----------------------+---------------------------+ +| | __qualname__ | qualified name | ++-----------+----------------------+---------------------------+ +| | __module__ | name of module in which | +| | | this class was defined | ++-----------+----------------------+---------------------------+ +| | __definition_order__ | the names of the class's | +| | | attributes, in the order | +| | | in which they were | +| | | defined (if known) | ++-----------+----------------------+---------------------------+ +| method | __doc__ | documentation string | ++-----------+----------------------+---------------------------+ +| | __name__ | name with which this | +| | | method was defined | ++-----------+----------------------+---------------------------+ +| | __qualname__ | qualified name | ++-----------+----------------------+---------------------------+ +| | __func__ | function object | +| | | containing implementation | +| | | of method | ++-----------+----------------------+---------------------------+ +| | __self__ | instance to which this | +| | | method is bound, or | +| | | ``None`` | ++-----------+----------------------+---------------------------+ +| function | __doc__ | documentation string | ++-----------+----------------------+---------------------------+ +| | __name__ | name with which this | +| | | function was defined | ++-----------+----------------------+---------------------------+ +| | __qualname__ | qualified name | ++-----------+----------------------+---------------------------+ +| | __code__ | code object containing | +| | | compiled function | +| | | :term:`bytecode` | ++-----------+----------------------+---------------------------+ +| | __defaults__ | tuple of any default | +| | | values for positional or | +| | | keyword parameters | ++-----------+----------------------+---------------------------+ +| | __kwdefaults__ | mapping of any default | +| | | values for keyword-only | +| | | parameters | ++-----------+----------------------+---------------------------+ +| | __globals__ | global namespace in which | +| | | this function was defined | ++-----------+----------------------+---------------------------+ +| | __annotations__ | mapping of parameters | +| | | names to annotations; | +| | | ``"return"`` key is | +| | | reserved for return | +| | | annotations. | ++-----------+----------------------+---------------------------+ +| traceback | tb_frame | frame object at this | +| | | level | ++-----------+----------------------+---------------------------+ +| | tb_lasti | index of last attempted | +| | | instruction in bytecode | ++-----------+----------------------+---------------------------+ +| | tb_lineno | current line number in | +| | | Python source code | ++-----------+----------------------+---------------------------+ +| | tb_next | next inner traceback | +| | | object (called by this | +| | | level) | ++-----------+----------------------+---------------------------+ +| frame | f_back | next outer frame object | +| | | (this frame's caller) | ++-----------+----------------------+---------------------------+ +| | f_builtins | builtins namespace seen | +| | | by this frame | ++-----------+----------------------+---------------------------+ +| | f_code | code object being | +| | | executed in this frame | ++-----------+----------------------+---------------------------+ +| | f_globals | global namespace seen by | +| | | this frame | ++-----------+----------------------+---------------------------+ +| | f_lasti | index of last attempted | +| | | instruction in bytecode | ++-----------+----------------------+---------------------------+ +| | f_lineno | current line number in | +| | | Python source code | ++-----------+----------------------+---------------------------+ +| | f_locals | local namespace seen by | +| | | this frame | ++-----------+----------------------+---------------------------+ +| | f_restricted | 0 or 1 if frame is in | +| | | restricted execution mode | ++-----------+----------------------+---------------------------+ +| | f_trace | tracing function for this | +| | | frame, or ``None`` | ++-----------+----------------------+---------------------------+ +| code | co_argcount | number of arguments (not | +| | | including \* or \*\* | +| | | args) | ++-----------+----------------------+---------------------------+ +| | co_code | string of raw compiled | +| | | bytecode | ++-----------+----------------------+---------------------------+ +| | co_consts | tuple of constants used | +| | | in the bytecode | ++-----------+----------------------+---------------------------+ +| | co_filename | name of file in which | +| | | this code object was | +| | | created | ++-----------+----------------------+---------------------------+ +| | co_firstlineno | number of first line in | +| | | Python source code | ++-----------+----------------------+---------------------------+ +| | co_flags | bitmap: 1=optimized ``|`` | +| | | 2=newlocals ``|`` 4=\*arg | +| | | ``|`` 8=\*\*arg | ++-----------+----------------------+---------------------------+ +| | co_lnotab | encoded mapping of line | +| | | numbers to bytecode | +| | | indices | ++-----------+----------------------+---------------------------+ +| | co_name | name with which this code | +| | | object was defined | ++-----------+----------------------+---------------------------+ +| | co_names | tuple of names of local | +| | | variables | ++-----------+----------------------+---------------------------+ +| | co_nlocals | number of local variables | ++-----------+----------------------+---------------------------+ +| | co_stacksize | virtual machine stack | +| | | space required | ++-----------+----------------------+---------------------------+ +| | co_varnames | tuple of names of | +| | | arguments and local | +| | | variables | ++-----------+----------------------+---------------------------+ +| generator | __name__ | name | ++-----------+----------------------+---------------------------+ +| | __qualname__ | qualified name | ++-----------+----------------------+---------------------------+ +| | gi_frame | frame | ++-----------+----------------------+---------------------------+ +| | gi_running | is the generator running? | ++-----------+----------------------+---------------------------+ +| | gi_code | code | ++-----------+----------------------+---------------------------+ +| | gi_yieldfrom | object being iterated by | +| | | ``yield from``, or | +| | | ``None`` | ++-----------+----------------------+---------------------------+ +| coroutine | __name__ | name | ++-----------+----------------------+---------------------------+ +| | __qualname__ | qualified name | ++-----------+----------------------+---------------------------+ +| | cr_await | object being awaited on, | +| | | or ``None`` | ++-----------+----------------------+---------------------------+ +| | cr_frame | frame | ++-----------+----------------------+---------------------------+ +| | cr_running | is the coroutine running? | ++-----------+----------------------+---------------------------+ +| | cr_code | code | ++-----------+----------------------+---------------------------+ +| builtin | __doc__ | documentation string | ++-----------+----------------------+---------------------------+ +| | __name__ | original name of this | +| | | function or method | ++-----------+----------------------+---------------------------+ +| | __qualname__ | qualified name | ++-----------+----------------------+---------------------------+ +| | __self__ | instance to which a | +| | | method is bound, or | +| | | ``None`` | ++-----------+----------------------+---------------------------+ .. versionchanged:: 3.5 @@ -221,6 +226,10 @@ attributes: The ``__name__`` attribute of generators is now set from the function name, instead of the code name, and it can now be modified. +.. versionchanged:: 3.6 + + Add ``__definition_order__`` to classes. + .. function:: getmembers(object[, predicate]) diff --git a/Doc/library/types.rst b/Doc/library/types.rst index 118bc4c..5eb84c1 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -53,8 +53,20 @@ Dynamic Type Creation in *kwds* argument with any ``'metaclass'`` entry removed. If no *kwds* argument is passed in, this will be an empty dict. + .. impl-detail:: + + CPython uses :class:`collections.OrderedDict` for the default + namespace. + .. versionadded:: 3.3 + .. versionchanged:: 3.6 + + The default value for the ``namespace`` element of the returned + tuple has changed from :func:`dict`. Now an insertion-order- + preserving mapping is used when the metaclass does not have a + ``__prepare__`` method, + .. seealso:: :ref:`metaclasses` diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 1c5bbdf..2eab29a 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -632,6 +632,17 @@ list for the base classes and the saved local namespace for the attribute dictionary. The class name is bound to this class object in the original local namespace. +The order in which attributes are defined in the class body is preserved +in the ``__definition_order__`` attribute on the new class. If that order +is not known then the attribute is set to :const:`None`. The class body +may include a ``__definition_order__`` attribute. In that case it is used +directly. The value must be a tuple of identifiers or ``None``, otherwise +:exc:`TypeError` will be raised when the class statement is executed. + +.. versionchanged:: 3.6 + + Add ``__definition_order__`` to classes. + Class creation can be customized heavily using :ref:`metaclasses <metaclasses>`. Classes can also be decorated: just like when decorating functions, :: diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index e7328ab..00785ed 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1750,7 +1750,14 @@ as ``namespace = metaclass.__prepare__(name, bases, **kwds)`` (where the additional keyword arguments, if any, come from the class definition). If the metaclass has no ``__prepare__`` attribute, then the class namespace -is initialised as an empty :func:`dict` instance. +is initialised as an empty ordered mapping. + +.. impl-detail:: + + In CPython the default is :class:`collections.OrderedDict`. + +.. versionchanged:: 3.6 + Defaults to :class:`collections.OrderedDict` instead of :func:`dict`. .. seealso:: diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst index e560fba..031bf79 100644 --- a/Doc/whatsnew/3.6.rst +++ b/Doc/whatsnew/3.6.rst @@ -92,6 +92,7 @@ Windows improvements: :pep:`4XX` - Python Virtual Environments PEP written by Carl Meyer +.. XXX PEP 520: :ref:`Preserving Class Attribute Definition Order<whatsnew-deforder>` New Features ============ @@ -271,6 +272,31 @@ Example of fatal error on buffer overflow using (Contributed by Victor Stinner in :issue:`26516` and :issue:`26564`.) +.. _whatsnew-deforder: + +PEP 520: Preserving Class Attribute Definition Order +---------------------------------------------------- + +Attributes in a class definition body have a natural ordering: the same +order in which the names appear in the source. This order is now +preserved in the new class's ``__definition_order__`` attribute. It is +a tuple of the attribute names, in the order in which they appear in +the class definition body. + +For types that don't have a definition (e.g. builtins), or the attribute +order could not be determined, ``__definition_order__`` is ``None``. + +Also, the effective default class *execution* namespace (returned from +``type.__prepare__()``) is now an insertion-order-preserving mapping. +For CPython, it is now ``collections.OrderedDict``. Note that the +class namespace, ``cls.__dict__``, is unchanged. + +.. seealso:: + + :pep:`520` - Preserving Class Attribute Definition Order + PEP written and implemented by Eric Snow. + + Other Language Changes ====================== |