Skip to content

Commit

Permalink
pythongh-103921: Document PEP 695 (python#104642)
Browse files Browse the repository at this point in the history 
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
  • Loading branch information
@JelleZijlstra @AlexWaygood
JelleZijlstra and AlexWaygood authored May 26, 2023
1 parent 95f1b1f commit 060277d
Show file tree
Hide file tree
Showing 11 changed files with 1,234 additions and 302 deletions.
102 changes: 100 additions & 2 deletions Doc/library/ast.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -917,6 +917,25 @@ Statements
type_ignores=[])


.. class:: TypeAlias(name, type_params, value)

A :ref:`type alias <type-aliases>` created through the :keyword:`type`
statement. ``name`` is the name of the alias, ``type_params`` is a list of
:ref:`type parameters <ast-type-params>`, and ``value`` is the value of the
type alias.

.. doctest::

>>> print(ast.dump(ast.parse('type Alias = int'), indent=4))
Module(
body=[
TypeAlias(
name=Name(id='Alias', ctx=Store()),
type_params=[],
value=Name(id='int', ctx=Load()))],
type_ignores=[])


Other statements which are only applicable inside functions or loops are
described in other sections.

Expand Down Expand Up @@ -1644,15 +1663,93 @@ Pattern matching
value=Constant(value=Ellipsis))])])],
type_ignores=[])

.. _ast-type-params:

Type parameters
^^^^^^^^^^^^^^^

:ref:`Type parameters <type-params>` can exist on classes, functions, and type
aliases.

.. class:: TypeVar(name, bound)

A :class:`typing.TypeVar`. ``name`` is the name of the type variable.
``bound`` is the bound or constraints, if any. If ``bound`` is a :class:`Tuple`,
it represents constraints; otherwise it represents the bound.

.. doctest::

>>> print(ast.dump(ast.parse("type Alias[T: int] = list[T]"), indent=4))
Module(
body=[
TypeAlias(
name=Name(id='Alias', ctx=Store()),
type_params=[
TypeVar(
name='T',
bound=Name(id='int', ctx=Load()))],
value=Subscript(
value=Name(id='list', ctx=Load()),
slice=Name(id='T', ctx=Load()),
ctx=Load()))],
type_ignores=[])

.. class:: ParamSpec(name)

A :class:`typing.ParamSpec`. ``name`` is the name of the parameter specification.

.. doctest::

>>> print(ast.dump(ast.parse("type Alias[**P] = Callable[P, int]"), indent=4))
Module(
body=[
TypeAlias(
name=Name(id='Alias', ctx=Store()),
type_params=[
ParamSpec(name='P')],
value=Subscript(
value=Name(id='Callable', ctx=Load()),
slice=Tuple(
elts=[
Name(id='P', ctx=Load()),
Name(id='int', ctx=Load())],
ctx=Load()),
ctx=Load()))],
type_ignores=[])

.. class:: TypeVarTuple(name)

A :class:`typing.TypeVarTuple`. ``name`` is the name of the type variable tuple.

.. doctest::

>>> print(ast.dump(ast.parse("type Alias[*Ts] = tuple[*Ts]"), indent=4))
Module(
body=[
TypeAlias(
name=Name(id='Alias', ctx=Store()),
type_params=[
TypeVarTuple(name='Ts')],
value=Subscript(
value=Name(id='tuple', ctx=Load()),
slice=Tuple(
elts=[
Starred(
value=Name(id='Ts', ctx=Load()),
ctx=Load())],
ctx=Load()),
ctx=Load()))],
type_ignores=[])

Function and class definitions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. class:: FunctionDef(name, args, body, decorator_list, returns, type_comment)
.. class:: FunctionDef(name, type_params, args, body, decorator_list, returns, type_comment)

A function definition.

* ``name`` is a raw string of the function name.
* ``type_params`` is a list of :ref:`type parameters <ast-type-params>`.
* ``args`` is an :class:`arguments` node.
* ``body`` is the list of nodes inside the function.
* ``decorator_list`` is the list of decorators to be applied, stored outermost
Expand Down Expand Up @@ -1820,11 +1917,12 @@ Function and class definitions
type_ignores=[])


.. class:: ClassDef(name, bases, keywords, body, decorator_list)
.. class:: ClassDef(name, type_params, bases, keywords, body, decorator_list)

A class definition.

* ``name`` is a raw string for the class name
* ``type_params`` is a list of :ref:`type parameters <ast-type-params>`.
* ``bases`` is a list of nodes for explicitly specified base classes.
* ``keywords`` is a list of :class:`keyword` nodes, principally for 'metaclass'.
Other keywords will be passed to the metaclass, as per `PEP-3115
Expand Down
111 changes: 91 additions & 20 deletions Doc/library/dis.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -188,9 +188,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
For a module, it disassembles all functions. For a class, it disassembles
all methods (including class and static methods). For a code object or
sequence of raw bytecode, it prints one line per bytecode instruction.
It also recursively disassembles nested code objects (the code of
comprehensions, generator expressions and nested functions, and the code
used for building nested classes).
It also recursively disassembles nested code objects. These can include
generator expressions, nested functions, the bodies of nested classes,
and the code objects used for :ref:`annotation scopes <annotation-scopes>`.
Strings are first compiled to code objects with the :func:`compile`
built-in function before being disassembled. If no object is provided, this
function disassembles the last traceback.
Expand Down Expand Up @@ -926,6 +926,27 @@ iterations of the loop.
.. opcode:: LOAD_NAME (namei)

Pushes the value associated with ``co_names[namei]`` onto the stack.
The name is looked up within the locals, then the globals, then the builtins.


.. opcode:: LOAD_LOCALS

Pushes a reference to the locals dictionary onto the stack. This is used
to prepare namespace dictionaries for :opcode:`LOAD_FROM_DICT_OR_DEREF`
and :opcode:`LOAD_FROM_DICT_OR_GLOBALS`.

.. versionadded:: 3.12


.. opcode:: LOAD_FROM_DICT_OR_GLOBALS (i)

Pops a mapping off the stack and looks up the value for ``co_names[namei]``.
If the name is not found there, looks it up in the globals and then the builtins,
similar to :opcode:`LOAD_GLOBAL`.
This is used for loading global variables in
:ref:`annotation scopes <annotation-scopes>` within class bodies.

.. versionadded:: 3.12


.. opcode:: BUILD_TUPLE (count)
Expand Down Expand Up @@ -1243,16 +1264,17 @@ iterations of the loop.
``i`` is no longer offset by the length of ``co_varnames``.


.. opcode:: LOAD_CLASSDEREF (i)
.. opcode:: LOAD_FROM_DICT_OR_DEREF (i)

Much like :opcode:`LOAD_DEREF` but first checks the locals dictionary before
consulting the cell. This is used for loading free variables in class
bodies.

.. versionadded:: 3.4
Pops a mapping off the stack and looks up the name associated with
slot ``i`` of the "fast locals" storage in this mapping.
If the name is not found there, loads it from the cell contained in
slot ``i``, similar to :opcode:`LOAD_DEREF`. This is used for loading
free variables in class bodies (which previously used
:opcode:`!LOAD_CLASSDEREF`) and in
:ref:`annotation scopes <annotation-scopes>` within class bodies.

.. versionchanged:: 3.11
``i`` is no longer offset by the length of ``co_varnames``.
.. versionadded:: 3.12


.. opcode:: STORE_DEREF (i)
Expand Down Expand Up @@ -1504,13 +1526,45 @@ iterations of the loop.

The operand determines which intrinsic function is called:

* ``0`` Not valid
* ``1`` Prints the argument to standard out. Used in the REPL.
* ``2`` Performs ``import *`` for the named module.
* ``3`` Extracts the return value from a ``StopIteration`` exception.
* ``4`` Wraps an aync generator value
* ``5`` Performs the unary ``+`` operation
* ``6`` Converts a list to a tuple
+-----------------------------------+-----------------------------------+
| Operand | Description |
+===================================+===================================+
| ``INTRINSIC_1_INVALID`` | Not valid |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_PRINT`` | Prints the argument to standard |
| | out. Used in the REPL. |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_IMPORT_STAR`` | Performs ``import *`` for the |
| | named module. |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_STOPITERATION_ERROR`` | Extracts the return value from a |
| | ``StopIteration`` exception. |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_ASYNC_GEN_WRAP`` | Wraps an aync generator value |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_UNARY_POSITIVE`` | Performs the unary ``+`` |
| | operation |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_LIST_TO_TUPLE`` | Converts a list to a tuple |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_TYPEVAR`` | Creates a :class:`typing.TypeVar` |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_PARAMSPEC`` | Creates a |
| | :class:`typing.ParamSpec` |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_TYPEVARTUPLE`` | Creates a |
| | :class:`typing.TypeVarTuple` |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_SUBSCRIPT_GENERIC`` | Returns :class:`typing.Generic` |
| | subscripted with the argument |
+-----------------------------------+-----------------------------------+
| ``INTRINSIC_TYPEALIAS`` | Creates a |
| | :class:`typing.TypeAliasType`; |
| | used in the :keyword:`type` |
| | statement. The argument is a tuple|
| | of the type alias's name, |
| | type parameters, and value. |
+-----------------------------------+-----------------------------------+

.. versionadded:: 3.12

Expand All @@ -1522,8 +1576,25 @@ iterations of the loop.

The operand determines which intrinsic function is called:

* ``0`` Not valid
* ``1`` Calculates the :exc:`ExceptionGroup` to raise from a ``try-except*``.
+----------------------------------------+-----------------------------------+
| Operand | Description |
+========================================+===================================+
| ``INTRINSIC_2_INVALID`` | Not valid |
+----------------------------------------+-----------------------------------+
| ``INTRINSIC_PREP_RERAISE_STAR`` | Calculates the |
| | :exc:`ExceptionGroup` to raise |
| | from a ``try-except*``. |
+----------------------------------------+-----------------------------------+
| ``INTRINSIC_TYPEVAR_WITH_BOUND`` | Creates a :class:`typing.TypeVar` |
| | with a bound. |
+----------------------------------------+-----------------------------------+
| ``INTRINSIC_TYPEVAR_WITH_CONSTRAINTS`` | Creates a |
| | :class:`typing.TypeVar` with |
| | constraints. |
+----------------------------------------+-----------------------------------+
| ``INTRINSIC_SET_FUNCTION_TYPE_PARAMS`` | Sets the ``__type_params__`` |
| | attribute of a function. |
+----------------------------------------+-----------------------------------+

.. versionadded:: 3.12

Expand Down
8 changes: 8 additions & 0 deletions Doc/library/stdtypes.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5476,6 +5476,14 @@ types, where they are relevant. Some of these are not reported by the
.. versionadded:: 3.3


.. attribute:: definition.__type_params__

The :ref:`type parameters <type-params>` of generic classes, functions,
and :ref:`type aliases <type-aliases>`.

.. versionadded:: 3.12


.. attribute:: class.__mro__

This attribute is a tuple of classes that are considered when looking for
Expand Down
Loading

0 comments on commit 060277d

Please sign in to comment.