diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 68dcfc00bbd99c..a257945a51f3cf 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -48,9 +48,16 @@ Atoms .. index:: atom Atoms are the most basic elements of expressions. -The simplest atoms are :ref:`names ` or literals. -Forms enclosed in parentheses, brackets or braces are also categorized -syntactically as atoms. +The simplest atoms are :ref:`builtin constants `, +:ref:`names ` and :ref:`literals `. +More complex atoms are enclosed in paired delimiters: + +- ``()`` (parentheses): :ref:`groups `, + :ref:`tuple displays `, + :ref:`yield atoms `, and + :ref:`generator expressions `; +- ``[]`` (square brackets): :ref:`list displays `; +- ``{}`` (curly braces): :ref:`dictionary ` and :ref:`set ` displays. Formally, the syntax for atoms is: @@ -58,20 +65,23 @@ Formally, the syntax for atoms is: :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 `, +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 ` and +:ref:`generator expressions ` 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 `), + 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 ` +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 `:: + + >>> ('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 `, + 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 `: + + + >>> 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 ===================