-
-
Notifications
You must be signed in to change notification settings - Fork 34.5k
gh-141984: Reword and reorganize the first part of Atoms docs #144117
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.
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
Changes from 2 commits
d42489a
477788f
1daedac
47909c2
581821b
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,9 +9,11 @@ Expressions | |
|
|
||
| This chapter explains the meaning of the elements of expressions in Python. | ||
|
|
||
| **Syntax Notes:** In this and the following chapters, extended BNF notation will | ||
| be used to describe syntax, not lexical analysis. When (one alternative of) a | ||
| syntax rule has the form | ||
| **Syntax Notes:** In this and the following chapters, | ||
| :ref:`grammar notation <notation>` will be used to describe syntax, | ||
| not lexical analysis. | ||
|
|
||
| When (one alternative of) a syntax rule has the form | ||
|
|
||
| .. productionlist:: python-grammar | ||
| name: othername | ||
|
|
@@ -29,17 +31,13 @@ Arithmetic conversions | |
|
|
||
| When a description of an arithmetic operator below uses the phrase "the numeric | ||
| arguments are converted to a common real type", this means that the operator | ||
| implementation for built-in types works as follows: | ||
|
|
||
| * If both arguments are complex numbers, no conversion is performed; | ||
|
|
||
| * if either argument is a complex or a floating-point number, the other is converted to a floating-point number; | ||
|
|
||
| * otherwise, both must be integers and no conversion is necessary. | ||
| implementation for built-in numeric types works as described in | ||
|
encukou marked this conversation as resolved.
Outdated
|
||
| :ref:`Numeric Types <stdtypes-mixed-arithmetic>` section of the standard | ||
| library documentation. | ||
|
|
||
| Some additional rules apply for certain operators (e.g., a string as a left | ||
| argument to the '%' operator). Extensions must define their own conversion | ||
| behavior. | ||
| Some additional rules apply for certain operators and non-numeric operands | ||
| (for example, a string as a left argument to the ``%`` operator). | ||
| Extensions must define their own conversion behavior. | ||
|
|
||
|
|
||
| .. _atoms: | ||
|
|
@@ -49,15 +47,57 @@ Atoms | |
|
|
||
| .. index:: atom | ||
|
|
||
| Atoms are the most basic elements of expressions. The simplest atoms are | ||
| identifiers or literals. Forms enclosed in parentheses, brackets or braces are | ||
| also categorized syntactically as atoms. The syntax for atoms is: | ||
| 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. | ||
|
|
||
| .. productionlist:: python-grammar | ||
| atom: `identifier` | `literal` | `enclosure` | ||
| enclosure: `parenth_form` | `list_display` | `dict_display` | `set_display` | ||
| : | `generator_expression` | `yield_atom` | ||
| Formally, the syntax for atoms is: | ||
|
|
||
| .. grammar-snippet:: | ||
| :group: python-grammar | ||
|
|
||
| atom: | ||
| | 'True' | ||
| | 'False' | ||
| | 'None' | ||
| | '...' | ||
| | `identifier` | ||
| | `literal` | ||
| | `enclosure` | ||
| enclosure: | ||
| | `parenth_form` | ||
| | `list_display` | ||
| | `dict_display` | ||
| | `set_display` | ||
| | `generator_expression` | ||
| | `yield_atom` | ||
|
|
||
|
|
||
| .. _atom-singletons: | ||
|
|
||
| Built-in constants | ||
| ------------------ | ||
|
|
||
| The keywords ``True``, ``False``, and ``None`` name | ||
| :ref:`built-in constants <built-in-consts>`. | ||
| The token ``...`` names the :py:data:`Ellipsis` constant. | ||
|
|
||
| Evaluation of these atoms yields the corresponding value. | ||
|
|
||
| .. note:: | ||
|
|
||
| Several more built-in constants are available as global variables, | ||
| but only the ones mentioned here are :ref:`keywords <keywords>`. | ||
| In particular, these names cannot be reassigned or used as attributes | ||
|
encukou marked this conversation as resolved.
Outdated
|
||
|
|
||
| .. code-block:: pycon | ||
|
|
||
| >>> False = 123 | ||
| File "<input>", line 1 | ||
| False = 123 | ||
| ^^^^^ | ||
| SyntaxError: cannot assign to False | ||
|
|
||
| .. _atom-identifiers: | ||
|
|
||
|
|
@@ -131,51 +171,104 @@ Literals | |
|
|
||
| .. index:: single: literal | ||
|
|
||
| Python supports string and bytes literals and various numeric literals: | ||
| A :dfn:`literal` is a textual representation of a value. | ||
| Python supports numeric, string and bytes literals. | ||
| :ref:`Format strings <f-strings>` and :ref:`template strings <t-strings>` | ||
| are treated as string literals. | ||
|
|
||
| Numeric literals consist of a single :token:`NUMBER <python-grammar:NUMBER>` | ||
| token, which names an integer, floating-point number, or an imaginary number. | ||
| See the :ref:`numbers` section in Lexical analysis documentation for details. | ||
|
|
||
| String and bytes literals may consist of several tokens. | ||
| See section :ref:`string-concatenation` for details. | ||
|
|
||
| Note that negative and complex numbers, like ``-3`` or ``3+4.2j``, | ||
| are syntactically not literals, but :ref:`unary <unary>` or | ||
| :ref:`binary <binary>` arithmetic operations involving the ``-`` or ``+`` | ||
| operator. | ||
|
|
||
| Evaluation of a literal yields an object of the given type | ||
| (:class:`int`, :class:`float`, :class:`complex`, :class:`str`, | ||
| :class:`bytes`, or :class:`~string.templatelib.Template`) with the given value. | ||
| The value may be approximated in the case of floating-point | ||
| and imaginary literals. | ||
|
|
||
| The formal grammar for literals is: | ||
|
|
||
| .. grammar-snippet:: | ||
| :group: python-grammar | ||
|
|
||
| literal: `strings` | `NUMBER` | ||
|
|
||
| Evaluation of a literal yields an object of the given type (string, bytes, | ||
| integer, floating-point number, complex number) with the given value. The value | ||
| may be approximated in the case of floating-point and imaginary (complex) | ||
| literals. | ||
| See section :ref:`literals` for details. | ||
| See section :ref:`string-concatenation` for details on ``strings``. | ||
|
|
||
|
|
||
| .. index:: | ||
| triple: immutable; data; type | ||
| pair: immutable; object | ||
|
|
||
| Literals and object identity | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| All literals correspond to immutable data types, and hence the object's identity | ||
| is less important than its value. Multiple evaluations of literals with the | ||
| same value (either the same occurrence in the program text or a different | ||
| occurrence) may obtain the same object or a different object with the same | ||
| value. | ||
|
|
||
| .. admonition:: CPython implementation detail | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why not
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It's hard to see where
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I see, that makes sense. I wonder why
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I assume it's to avoid the box, which would be too distracting for a few sentences. |
||
|
|
||
| For example, in CPython, *small* integers with the same value evaluate | ||
| to the same object:: | ||
|
|
||
| >>> x = 7 | ||
| >>> y = 7 | ||
| >>> x is y | ||
| True | ||
|
|
||
| However, large integers evaluate to different objects:: | ||
|
|
||
| >>> x = 123456789 | ||
| >>> y = 123456789 | ||
| >>> x is y | ||
| False | ||
|
|
||
| This behavior may change in future versions of CPython. | ||
| In particular, the boundary between "small" and "large" integers has | ||
| already changed in the past. | ||
|
|
||
| CPython will emit a :py:exc:`SyntaxWarning` when you compare literals | ||
| using ``is``:: | ||
|
|
||
| >>> x = 7 | ||
| >>> x is 7 | ||
| <input>:1: SyntaxWarning: "is" with 'int' literal. Did you mean "=="? | ||
| True | ||
|
|
||
| See :ref:`faq-identity-with-is` for more information. | ||
|
|
||
| :ref:`Template strings <t-strings>` are immutable but may reference mutable | ||
| objects as :class:`~string.templatelib.Interpolation` values. | ||
| For the purposes of this section, two t-strings have the "same value" if | ||
| both their structure and the *identity* of the values match. | ||
|
|
||
| .. impl-detail:: | ||
|
|
||
| Currently, each evaluation of a template string results in | ||
| a different object. | ||
|
|
||
|
|
||
| .. _string-concatenation: | ||
|
|
||
| String literal concatenation | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| Multiple adjacent string or bytes literals (delimited by whitespace), possibly | ||
| Multiple adjacent string or bytes literals, possibly | ||
| using different quoting conventions, are allowed, and their meaning is the same | ||
| as their concatenation:: | ||
|
|
||
| >>> "hello" 'world' | ||
| "helloworld" | ||
|
|
||
| Formally: | ||
|
|
||
| .. grammar-snippet:: | ||
| :group: python-grammar | ||
|
|
||
| strings: ( `STRING` | `fstring`)+ | `tstring`+ | ||
|
|
||
| This feature is defined at the syntactical level, so it only works with literals. | ||
| To concatenate string expressions at run time, the '+' operator may be used:: | ||
|
|
||
|
|
@@ -208,6 +301,13 @@ string literals:: | |
| >>> t"Hello" t"{name}!" | ||
| Template(strings=('Hello', '!'), interpolations=(...)) | ||
|
|
||
| Formally: | ||
|
|
||
| .. grammar-snippet:: | ||
| :group: python-grammar | ||
|
|
||
| strings: (`STRING` | `fstring`)+ | `tstring`+ | ||
|
|
||
|
|
||
| .. _parenthesized: | ||
|
|
||
|
|
@@ -1297,8 +1397,9 @@ for the operands): ``-1**2`` results in ``-1``. | |
|
|
||
| The power operator has the same semantics as the built-in :func:`pow` function, | ||
| when called with two arguments: it yields its left argument raised to the power | ||
| of its right argument. The numeric arguments are first converted to a common | ||
| type, and the result is of that type. | ||
| of its right argument. | ||
| Numeric arguments are first :ref:`converted to a common type <stdtypes-mixed-arithmetic>`, | ||
| and the result is of that type. | ||
|
|
||
| For int operands, the result has the same type as the operands unless the second | ||
| argument is negative; in that case, all arguments are converted to float and a | ||
|
|
@@ -1384,9 +1485,10 @@ operators and one for additive operators: | |
|
|
||
| The ``*`` (multiplication) operator yields the product of its arguments. The | ||
| arguments must either both be numbers, or one argument must be an integer and | ||
| the other must be a sequence. In the former case, the numbers are converted to a | ||
| common real type and then multiplied together. In the latter case, sequence | ||
| repetition is performed; a negative repetition factor yields an empty sequence. | ||
| the other must be a sequence. In the former case, the numbers are | ||
| :ref:`converted to a common real type <stdtypes-mixed-arithmetic>` and then | ||
| multiplied together. In the latter case, sequence repetition is performed; | ||
| a negative repetition factor yields an empty sequence. | ||
|
|
||
| This operation can be customized using the special :meth:`~object.__mul__` and | ||
| :meth:`~object.__rmul__` methods. | ||
|
|
@@ -1430,8 +1532,9 @@ The floor division operation can be customized using the special | |
| pair: operator; % (percent) | ||
|
|
||
| The ``%`` (modulo) operator yields the remainder from the division of the first | ||
| argument by the second. The numeric arguments are first converted to a common | ||
| type. A zero right argument raises the :exc:`ZeroDivisionError` exception. The | ||
| argument by the second. The numeric arguments are first converted to a | ||
|
encukou marked this conversation as resolved.
Outdated
|
||
| :ref:`converted to a common type <stdtypes-mixed-arithmetic>`. | ||
| A zero right argument raises the :exc:`ZeroDivisionError` exception. The | ||
| arguments may be floating-point numbers, e.g., ``3.14%0.7`` equals ``0.34`` | ||
| (since ``3.14`` equals ``4*0.7 + 0.34``.) The modulo operator always yields a | ||
| result with the same sign as its second operand (or zero); the absolute value of | ||
|
|
@@ -1462,7 +1565,9 @@ floating-point number using the :func:`abs` function if appropriate. | |
|
|
||
| The ``+`` (addition) operator yields the sum of its arguments. The arguments | ||
| must either both be numbers or both be sequences of the same type. In the | ||
| former case, the numbers are converted to a common real type and then added together. | ||
| former case, the numbers are | ||
| :ref:`converted to a common real type <stdtypes-mixed-arithmetic>` and then | ||
| added together. | ||
| In the latter case, the sequences are concatenated. | ||
|
|
||
| This operation can be customized using the special :meth:`~object.__add__` and | ||
|
|
@@ -1477,8 +1582,9 @@ This operation can be customized using the special :meth:`~object.__add__` and | |
| single: operator; - (minus) | ||
| single: - (minus); binary operator | ||
|
|
||
| The ``-`` (subtraction) operator yields the difference of its arguments. The | ||
| numeric arguments are first converted to a common real type. | ||
| The ``-`` (subtraction) operator yields the difference of its arguments. | ||
| The numeric arguments are first | ||
| :ref:`converted to a common real type <stdtypes-mixed-arithmetic>`. | ||
|
|
||
| This operation can be customized using the special :meth:`~object.__sub__` and | ||
| :meth:`~object.__rsub__` methods. | ||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.