Skip to content

gh-115528: Update language reference for PEP 646 #120294

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

gh-115528: Update language reference for PEP 646 #120294

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a44de6d
Update language reference for PEP 646
mrahtz Jun 9, 2024
bdab626
Attempt 2
mrahtz Jun 30, 2024
3059bd9
Cleanups
mrahtz Jun 30, 2024
e7c8c25
Simplify
mrahtz Jun 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions Doc/reference/compound_stmts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1217,9 +1217,10 @@ A function definition defines a user-defined function object (see section
: | `parameter_list_no_posonly`
parameter_list_no_posonly: `defparameter` ("," `defparameter`)* ["," [`parameter_list_starargs`]]
: | `parameter_list_starargs`
parameter_list_starargs: "*" [`parameter`] ("," `defparameter`)* ["," ["**" `parameter` [","]]]
parameter_list_starargs: "*" [`star_parameter`] ("," `defparameter`)* ["," ["**" `parameter` [","]]]
: | "**" `parameter` [","]
parameter: `identifier` [":" `expression`]
star_parameter: `identifier` [":" ["*"] `expression`]
defparameter: `parameter` ["=" `expression`]
funcname: `identifier`

Expand Down Expand Up @@ -1326,7 +1327,8 @@ and may only be passed by positional arguments.

Parameters may have an :term:`annotation <function annotation>` of the form "``: expression``"
following the parameter name. Any parameter may have an annotation, even those of the form
``*identifier`` or ``**identifier``. Functions may have "return" annotation of
``*identifier`` or ``**identifier``. (As a special case, parameters of the form
``*identifier`` may have an annotation "``: *expression``".) Functions may have "return" annotation of
the form "``-> expression``" after the parameter list. These annotations can be
any valid Python expression. The presence of annotations does not change the
semantics of a function. The annotation values are available as values of
Expand All @@ -1337,6 +1339,10 @@ enables postponed evaluation. Otherwise, they are evaluated when the function
definition is executed. In this case annotations may be evaluated in
a different order than they appear in the source code.

.. versionchanged:: 3.11
Parameters of the form "``*identifier``" may have an annotation
"``: *expression``". See :pep:`646`.

.. index:: pair: lambda; expression

It is also possible to create anonymous functions (functions not bound to a
Expand Down
69 changes: 39 additions & 30 deletions Doc/reference/expressions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,8 +252,8 @@
A list display is a possibly empty series of expressions enclosed in square
brackets:

.. productionlist:: python-grammar

Check warning on line 255 in Doc/reference/expressions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

'token' reference target not found: python-grammar:expression_list
list_display: "[" [`starred_list` | `comprehension`] "]"
list_display: "[" [`expression_list` | `comprehension`] "]"

A list display yields a new list object, the contents being specified by either
a list of expressions or a comprehension. When a comma-separated list of
Expand All @@ -277,8 +277,8 @@
A set display is denoted by curly braces and distinguishable from dictionary
displays by the lack of colons separating keys and values:

.. productionlist:: python-grammar

Check warning on line 280 in Doc/reference/expressions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

'token' reference target not found: python-grammar:expression_list
set_display: "{" (`starred_list` | `comprehension`) "}"
set_display: "{" (`expression_list` | `comprehension`) "}"

A set display yields a new mutable set object, the contents being specified by
either a sequence of expressions or a comprehension. When a comma-separated
Expand Down Expand Up @@ -420,10 +420,10 @@
pair: yield; expression
pair: generator; function

.. productionlist:: python-grammar

Check warning on line 423 in Doc/reference/expressions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

'token' reference target not found: python-grammar:yield_list
yield_atom: "(" `yield_expression` ")"
yield_from: "yield" "from" `expression`
yield_expression: "yield" `expression_list` | `yield_from`
yield_expression: "yield" `yield_list` | `yield_from`

The yield expression is used when defining a :term:`generator` function
or an :term:`asynchronous generator` function and
Expand All @@ -450,12 +450,12 @@
functions are described separately in section
:ref:`asynchronous-generator-functions`.

When a generator function is called, it returns an iterator known as a

Check warning on line 453 in Doc/reference/expressions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

'token' reference target not found: python-grammar:expression_list

Check warning on line 453 in Doc/reference/expressions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

'token' reference target not found: python-grammar:expression_list
generator. That generator then controls the execution of the generator
function. The execution starts when one of the generator's methods is called.
At that time, the execution proceeds to the first yield expression, where it is
suspended again, returning the value of :token:`~python-grammar:expression_list`
to the generator's caller,
suspended again, returning the value of
:token:`~python-grammar:expression_list` to the generator's caller,
or ``None`` if :token:`~python-grammar:expression_list` is omitted.
By suspended, we mean that all local state is
retained, including the current bindings of local variables, the instruction
Expand Down Expand Up @@ -540,14 +540,14 @@

.. method:: generator.__next__()

Starts the execution of a generator function or resumes it at the last

Check warning on line 543 in Doc/reference/expressions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

'token' reference target not found: python-grammar:expression_list
executed yield expression. When a generator function is resumed with a
:meth:`~generator.__next__` method, the current yield expression always
evaluates to :const:`None`. The execution then continues to the next yield
expression, where the generator is suspended again, and the value of the
:token:`~python-grammar:expression_list` is returned to :meth:`__next__`'s
caller. If the generator exits without yielding another value, a
:exc:`StopIteration` exception is raised.
:token:`~python-grammar:expression_list` is returned to
:meth:`__next__`'s caller. If the generator exits without yielding another
value, a :exc:`StopIteration` exception is raised.

This method is normally called implicitly, e.g. by a :keyword:`for` loop, or
by the built-in :func:`next` function.
Expand Down Expand Up @@ -661,20 +661,20 @@
:keyword:`async for` statement in a coroutine function analogously to
how a generator object would be used in a :keyword:`for` statement.

Calling one of the asynchronous generator's methods returns an :term:`awaitable`

Check warning on line 664 in Doc/reference/expressions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

'token' reference target not found: python-grammar:expression_list
object, and the execution starts when this object is awaited on. At that time,
the execution proceeds to the first yield expression, where it is suspended
again, returning the value of :token:`~python-grammar:expression_list` to the
awaiting coroutine. As with a generator, suspension means that all local state
is retained, including the current bindings of local variables, the instruction
pointer, the internal evaluation stack, and the state of any exception handling.
When the execution is resumed by awaiting on the next object returned by the
asynchronous generator's methods, the function can proceed exactly as if the
yield expression were just another external call. The value of the yield
expression after resuming depends on the method which resumed the execution. If
:meth:`~agen.__anext__` is used then the result is :const:`None`. Otherwise, if
:meth:`~agen.asend` is used, then the result will be the value passed in to that
method.
again, returning the value of :token:`~python-grammar:expression_list`
to the awaiting coroutine. As with a generator, suspension means that all local
state is retained, including the current bindings of local variables, the
instruction pointer, the internal evaluation stack, and the state of any
exception handling. When the execution is resumed by awaiting on the next object
returned by the asynchronous generator's methods, the function can proceed
exactly as if the yield expression were just another external call. The value of
the yield expression after resuming depends on the method which resumed the
execution. If :meth:`~agen.__anext__` is used then the result is :const:`None`.
Otherwise, if :meth:`~agen.asend` is used, then the result will be the value
passed in to that method.

If an asynchronous generator happens to exit early by :keyword:`break`, the caller
task being cancelled, or other exceptions, the generator's async cleanup code
Expand Down Expand Up @@ -723,15 +723,15 @@

.. coroutinemethod:: agen.__anext__()

Returns an awaitable which when run starts to execute the asynchronous

Check warning on line 726 in Doc/reference/expressions.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

'token' reference target not found: python-grammar:expression_list
generator or resumes it at the last executed yield expression. When an
asynchronous generator function is resumed with an :meth:`~agen.__anext__`
method, the current yield expression always evaluates to :const:`None` in the
returned awaitable, which when run will continue to the next yield
expression. The value of the :token:`~python-grammar:expression_list` of the
yield expression is the value of the :exc:`StopIteration` exception raised by
the completing coroutine. If the asynchronous generator exits without
yielding another value, the awaitable instead raises a
expression. The value of the :token:`~python-grammar:expression_list`
of the yield expression is the value of the :exc:`StopIteration` exception
raised by the completing coroutine. If the asynchronous generator exits
without yielding another value, the awaitable instead raises a
:exc:`StopAsyncIteration` exception, signalling that the asynchronous
iteration has completed.

Expand Down Expand Up @@ -873,9 +873,13 @@
passed to one of these methods. For more details on when ``__class_getitem__``
is called instead of ``__getitem__``, see :ref:`classgetitem-versus-getitem`.

If the expression list contains at least one comma, it will evaluate to a
:class:`tuple` containing the items of the expression list. Otherwise, the
expression list will evaluate to the value of the list's sole member.
If the expression list contains at least one comma, or if any of the expressions
are starred, the expression list will evaluate to a :class:`tuple` containing
the items of the expression list. Otherwise, the expression list will evaluate
to the value of the list's sole member.

.. versionchanged:: 3.11
Expressions in an expression list may be starred. See :pep:`646`.

For built-in objects, there are two types of objects that support subscription
via :meth:`~object.__getitem__`:
Expand Down Expand Up @@ -1874,10 +1878,12 @@
single: , (comma); expression list

.. productionlist:: python-grammar
expression_list: `expression` ("," `expression`)* [","]
starred_list: `starred_item` ("," `starred_item`)* [","]
starred_expression: `expression` | (`starred_item` ",")* [`starred_item`]
starred_item: `assignment_expression` | "*" `or_expr`

expression_list: `flexible_expression` ("," `flexible_expression`)* [","]
yield_list: `expression` ["," `expression_list`]
| `starred_expression` "," [`expression_list`]
flexible_expression: `assignment_expression` | `starred_expression`
starred_expression: "*" `or_expr`

.. index:: pair: object; tuple

Expand All @@ -1898,6 +1904,9 @@
.. versionadded:: 3.5
Iterable unpacking in expression lists, originally proposed by :pep:`448`.

.. versionadded:: 3.11
Any item in an expression list may be starred. See :pep:`646`.

.. index:: pair: trailing; comma

A trailing comma is required only to create a one-item tuple,
Expand Down
Loading