Update language reference for PEP 646

Author: mrahtz

Doc/reference/compound_stmts.rst

@@ -1208,18 +1208,15 @@ A function definition defines a user-defined function object (see section
 :ref:`types`):
 
 .. productionlist:: python-grammar
-   funcdef: [`decorators`] "def" `funcname` [`type_params`] "(" [`parameter_list`] ")"
-          : ["->" `expression`] ":" `suite`
+   funcdef: [`decorators`] "def" `funcname` [`type_params`] "(" [`parameter_list`] ")" : ["->" `expression`] ":" `suite`
    decorators: `decorator`+
    decorator: "@" `assignment_expression` NEWLINE
-   parameter_list: `defparameter` ("," `defparameter`)* "," "/" ["," [`parameter_list_no_posonly`]]
-                 :   | `parameter_list_no_posonly`
-   parameter_list_no_posonly: `defparameter` ("," `defparameter`)* ["," [`parameter_list_starargs`]]
-                            : | `parameter_list_starargs`
-   parameter_list_starargs: "*" [`parameter`] ("," `defparameter`)* ["," ["**" `parameter` [","]]]
-                          : | "**" `parameter` [","]
    parameter: `identifier` [":" `expression`]
+   star_parameter: `identifier` [":" ["*"] `expression`]
    defparameter: `parameter` ["=" `expression`]
+   parameter_list: `defparameter` ("," `defparameter`)* "," "/" ["," [`parameter_list_no_posonly`]] : | `parameter_list_no_posonly`
+   parameter_list_no_posonly: `defparameter` ("," `defparameter`)* ["," [`parameter_list_starargs`]] : | `parameter_list_starargs`
+   parameter_list_starargs: "*" [`star_parameter`] ("," `defparameter`)* ["," ["**" `parameter` [","]]] : | "**" `parameter` [","]
    funcname: `identifier`
 
 
@@ -1323,9 +1320,11 @@ and may only be passed by positional arguments.
    single: ->; function annotations
    single: : (colon); function annotations
 
-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
+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``.
+(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
@@ -1336,6 +1335,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 "``*args``" may have an annotation
+   "``: *expression``". See :pep:`646` for details.
+
 .. index:: pair: lambda; expression
 
 It is also possible to create anonymous functions (functions not bound to a

Doc/reference/expressions.rst

@@ -873,9 +873,13 @@ primary is subscripted, the evaluated result of the expression list will be
 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
+is 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 details.
 
 For built-in objects, there are two types of objects that support subscription
 via :meth:`~object.__getitem__`:
@@ -1874,7 +1878,7 @@ Expression lists
    single: , (comma); expression list
 
 .. productionlist:: python-grammar
-   expression_list: `expression` ("," `expression`)* [","]
+   expression_list: `starred_expression` ("," `starred_expression`)* [","]
    starred_list: `starred_item` ("," `starred_item`)* [","]
    starred_expression: `expression` | (`starred_item` ",")* [`starred_item`]
    starred_item: `assignment_expression` | "*" `or_expr`
@@ -1898,6 +1902,9 @@ the unpacking.
 .. 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,