gh-141984: Split Parenthesized form docs into "groups" and "tuple displays"

Doc/reference/expressions.rst

@@ -48,30 +48,40 @@ Atoms
 .. index:: atom
 
 Atoms are the most basic elements of expressions.
-The simplest atoms are :ref:`names <identifiers>` or literals.
-Forms enclosed in parentheses, brackets or braces are also categorized
-syntactically as atoms.
+The simplest atoms are :ref:`builtin constants <atom-singletons>`,
+:ref:`names <identifiers>` and :ref:`literals <atom-literals>`.
+More complex atoms are enclosed in paired delimiters:
+
+- ``()`` (parentheses): :ref:`groups <parenthesized>`,
+  :ref:`tuple displays <tuple-display>`,
+  :ref:`yield atoms <yieldexpr>`, and
+  :ref:`generator expressions <genexpr>`;
+- ``[]`` (square brackets): :ref:`list displays <lists>`;
+- ``{}`` (curly braces): :ref:`dictionary <dict>` and :ref:`set <set>` displays.
 
 Formally, the syntax for atoms is:
 
 .. grammar-snippet::
    :group: python-grammar
 
    atom:
+      | `builtin_constant`
+      | `identifier`
+      | `literal`
+      | `enclosure`
+   builtin_constant:
       | 'True'
       | 'False'
       | 'None'
       | '...'
-      | `identifier`
-      | `literal`
-      | `enclosure`
    enclosure:
-      | `parenth_form`
+      | `group`
+      | `tuple`
+      | `yield_atom`
+      | `generator_expression`
       | `list_display`
       | `dict_display`
       | `set_display`
-      | `generator_expression`
-      | `yield_atom`
 
 
 .. _atom-singletons:
@@ -201,6 +211,7 @@ The formal grammar for literals is:
 
    literal: `strings` | `NUMBER`
 
+.. _literals-identity:
 
 .. index::
    triple: immutable; data; type
@@ -309,38 +320,151 @@ Formally:
    strings: (`STRING` | `fstring`)+ | `tstring`+
 
 
+.. index::
+   single: parenthesized form
+   single: () (parentheses)
+
 .. _parenthesized:
 
-Parenthesized forms
--------------------
+Parenthesized groups
+--------------------
 
-.. index::
-   single: parenthesized form
-   single: () (parentheses); tuple display
+A :dfn:`parenthesized group` is an expression enclosed in parentheses.
+The group evaluates to the same value as the expression inside.
 
-A parenthesized form is an optional expression list enclosed in parentheses:
+Groups are used to override or clarify
+:ref:`operator precedence <operator-precedence>`,
+in the same way as in math notation.
+For example::
 
-.. productionlist:: python-grammar
-   parenth_form: "(" [`starred_expression`] ")"
+   >>> 3 << 2 | 4
+   12
+   >>> 3 << (2 | 4)   # Override precedence of the | (bitwise OR)
+   192
+   >>> (3 << 2) | 4   # Same as without parentheses (but more clear)
+   12
 
-A parenthesized expression list yields whatever that expression list yields: if
-the list contains at least one comma, it yields a tuple; otherwise, it yields
-the single expression that makes up the expression list.
+Note that not everything in parentheses is a *group*.
+Specifically, a parenthesized group must include exactly one expression,
+and cannot end with a comma.
+See :ref:`tuple displays <tuple-display>` and
+:ref:`generator expressions <genexpr>` for other parenthesized forms.
 
-.. index:: pair: empty; tuple
+Formally, the syntax for groups is:
+
+.. grammar-snippet::
+   :group: python-grammar
+
+   group: '(' `assignment_expression` ')'
 
-An empty pair of parentheses yields an empty tuple object.  Since tuples are
-immutable, the same rules as for literals apply (i.e., two occurrences of the empty
-tuple may or may not yield the same object).
 
 .. index::
+   single: tuple display
    single: comma
    single: , (comma)
 
-Note that tuples are not formed by the parentheses, but rather by use of the
-comma.  The exception is the empty tuple, for which parentheses *are*
-required --- allowing unparenthesized "nothing" in expressions would cause
-ambiguities and allow common typos to pass uncaught.
+.. _tuple-display:
+
+Tuple displays
+--------------
+
+A :dfn:`tuple display` is a parenthesized expression that evaluates to a
+:class:`tuple` object.
+
+In the most common form, the parentheses contain two or more comma-separated
+expressions::
+
+   >>> (1, 2)
+   (1, 2)
+   >>> ('one', 'two', 'thr' + 'ee')
+   ('one', 'two', 'three')
+
+The expressions may be followed by an additional comma, which has no effect::
+
+   >>> (1, 2,)
+   (1, 2)
+
+.. note::
+
+   The trailing comma is often used for tuple displays that span multiple lines
+   (using :ref:`implicit line joining <implicit-joining>`),
+   so when a new entry is later added at the end, the existing line does not
+   need to be modified::
+
+      >>> (
+      ...     'one',
+      ...     'two',
+      ...     'three',
+      ... )
+      ('one', 'two', 'three')
+
+At runtime, evaluating a tuple display results in a tuple that contains
+the results of the expressions, in order.
+Since tuples are immutable, :ref:`object identity rules for literals <literals-identity>`
+also apply to tuples: two occurrences of tuples with the same values may
+or may not yield the same object.
+
+A tuple display may also contain a *single* expression.
+In this case, the trailing comma is mandatory -- without it, you get a
+:ref:`parenthesized group <parenthesized>`::
+
+   >>> ('single',)  # single-element tuple
+   ('single',)
+   >>> ('single')   # no comma: single string
+   'single'
+
+.. index:: pair: empty; tuple
+
+A tuple display may also contain *zero* expressions:
+empty parentheses denote the empty tuple.
+A trailing comma is *not* allowed in this case.
+
+.. code-block::
+
+   >>> ()
+   ()
+
+To put it in other words, a tuple display is a parenthesized list of either:
+
+- two or more comma-separated expressions, or
+- zero or more expressions, each followed by a comma.
+
+.. note::
+
+   Python's syntax also includes :ref:`expression lists <exprlists>`,
+   where a comma-separated list of expressions is *not* enclosed in parentheses
+   but evaluates to tuple.
+
+   In other words, when it comes to tuple syntax, the comma is more important
+   that the use of parentheses.
+   Only the empty tuple is spelled without a comma.
+
+.. index::
+   pair: iterable; unpacking
+   single: * (asterisk); in expression lists
+
+Any expression in a tuple display may be prefixed with an asterisk (``*``).
+This denotes :ref:`iterable unpacking as in expression lists <iterable-unpacking>`:
+
+
+   >>> numbers = (1, 2)
+   >>> (*numbers, 'word', *numbers)
+   (1, 2, 'word', 1, 2)
+
+.. versionadded:: 3.5
+   Iterable unpacking in tuple displays, originally proposed by :pep:`448`.
+
+.. index:: pair: trailing; comma
+
+The formal grammar for tuple expressions is:
+
+.. grammar-snippet::
+   :group: python-grammar
+
+   tuple:
+      | '(' `flexible_expression` (',' `flexible_expression`)+ [','] ')'
+      | '(' `flexible_expression` ',' ')'
+      | '(' ')'
 
 
 .. _comprehensions:
@@ -2178,6 +2302,10 @@ functions created with lambda expressions cannot contain statements or
 annotations.
 
 
+.. index::
+   single: comma
+   single: , (comma)
+
 .. _exprlists:
 
 Expression lists
@@ -2202,12 +2330,32 @@ containing at least one comma yields a tuple.  The length of
 the tuple is the number of expressions in the list.  The expressions are
 evaluated from left to right.
 
+.. index:: pair: trailing; comma
+
+A trailing comma is required only to create a one-item tuple,
+such as ``1,``; it is optional in all other cases.
+A single expression without a
+trailing comma doesn't create a tuple, but rather yields the value of that
+expression. (To create an empty tuple, use an empty pair of parentheses:
+``()``.)
+
+
+.. _iterable-unpacking:
+
 .. index::
    pair: iterable; unpacking
    single: * (asterisk); in expression lists
 
-An asterisk ``*`` denotes :dfn:`iterable unpacking`.  Its operand must be
-an :term:`iterable`.  The iterable is expanded into a sequence of items,
+Iterable unpacking
+------------------
+
+In an expression list or tuple, list or set display, any expression
+may be prefixed with an asterisk (``*``).
+This denotes :dfn:`iterable unpacking`.
+
+At runtime, the asterisk-prefixed expression must evaluate
+to an :term:`iterable`.
+The iterable is expanded into a sequence of items,
 which are included in the new tuple, list, or set, at the site of
 the unpacking.
 
@@ -2217,15 +2365,6 @@ the unpacking.
 .. 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,
-such as ``1,``; it is optional in all other cases.
-A single expression without a
-trailing comma doesn't create a tuple, but rather yields the value of that
-expression. (To create an empty tuple, use an empty pair of parentheses:
-``()``.)
-
 
 .. _evalorder:
 
@@ -2249,6 +2388,7 @@ their suffixes::
 
 
 .. _operator-summary:
+.. _operator-precedence:
 
 Operator precedence
 ===================