mirrors/cosmopolitan
1
0
Fork 0
mirror of https://github.com/jart/cosmopolitan.git synced 2025-05-31 17:52:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

python-3.6.zip added from Github

Browse source 
README.cosmo contains the necessary links.
This commit is contained in:
ahgamut 2021-08-08 09:38:33 +05:30 • committed by Justine Tunney
parent 75fc601ff5
commit 0c4c56ff39
4219 changed files with 1968626 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

842
third_party/python/Doc/reference/compound_stmts.rst vendored Normal file
View file

@ -0,0 +1,842 @@
.. _compound:
*******************
Compound statements
*******************
.. index:: pair: compound; statement
Compound statements contain (groups of) other statements; they affect or control
the execution of those other statements in some way. In general, compound
statements span multiple lines, although in simple incarnations a whole compound
statement may be contained in one line.
The :keyword:`if`, :keyword:`while` and :keyword:`for` statements implement
traditional control flow constructs. :keyword:`try` specifies exception
handlers and/or cleanup code for a group of statements, while the
:keyword:`with` statement allows the execution of initialization and
finalization code around a block of code. Function and class definitions are
also syntactically compound statements.
.. index::
single: clause
single: suite
single: ; (semicolon)
A compound statement consists of one or more 'clauses.' A clause consists of a
header and a 'suite.' The clause headers of a particular compound statement are
all at the same indentation level. Each clause header begins with a uniquely
identifying keyword and ends with a colon. A suite is a group of statements
controlled by a clause. A suite can be one or more semicolon-separated simple
statements on the same line as the header, following the header's colon, or it
can be one or more indented statements on subsequent lines. Only the latter
form of a suite can contain nested compound statements; the following is illegal,
mostly because it wouldn't be clear to which :keyword:`if` clause a following
:keyword:`else` clause would belong::
if test1: if test2: print(x)
Also note that the semicolon binds tighter than the colon in this context, so
that in the following example, either all or none of the :func:`print` calls are
executed::
if x < y < z: print(x); print(y); print(z)
Summarizing:
.. productionlist::
compound_stmt: `if_stmt`
: | `while_stmt`
: | `for_stmt`
: | `try_stmt`
: | `with_stmt`
: | `funcdef`
: | `classdef`
: | `async_with_stmt`
: | `async_for_stmt`
: | `async_funcdef`
suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT
statement: `stmt_list` NEWLINE | `compound_stmt`
stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"]
.. index::
single: NEWLINE token
single: DEDENT token
pair: dangling; else
Note that statements always end in a ``NEWLINE`` possibly followed by a
``DEDENT``. Also note that optional continuation clauses always begin with a
keyword that cannot start a statement, thus there are no ambiguities (the
'dangling :keyword:`else`' problem is solved in Python by requiring nested
:keyword:`if` statements to be indented).
The formatting of the grammar rules in the following sections places each clause
on a separate line for clarity.
.. _if:
.. _elif:
.. _else:
The :keyword:`if` statement
===========================
.. index::
statement: if
keyword: elif
keyword: else
single: : (colon); compound statement
The :keyword:`if` statement is used for conditional execution:
.. productionlist::
if_stmt: "if" `expression` ":" `suite`
: ("elif" `expression` ":" `suite`)*
: ["else" ":" `suite`]
It selects exactly one of the suites by evaluating the expressions one by one
until one is found to be true (see section :ref:`booleans` for the definition of
true and false); then that suite is executed (and no other part of the
:keyword:`if` statement is executed or evaluated). If all expressions are
false, the suite of the :keyword:`else` clause, if present, is executed.
.. _while:
The :keyword:`while` statement
==============================
.. index::
statement: while
keyword: else
pair: loop; statement
keyword: else
single: : (colon); compound statement
The :keyword:`while` statement is used for repeated execution as long as an
expression is true:
.. productionlist::
while_stmt: "while" `expression` ":" `suite`
: ["else" ":" `suite`]
This repeatedly tests the expression and, if it is true, executes the first
suite; if the expression is false (which may be the first time it is tested) the
suite of the :keyword:`else` clause, if present, is executed and the loop
terminates.
.. index::
statement: break
statement: continue
A :keyword:`break` statement executed in the first suite terminates the loop
without executing the :keyword:`else` clause's suite. A :keyword:`continue`
statement executed in the first suite skips the rest of the suite and goes back
to testing the expression.
.. _for:
The :keyword:`for` statement
============================
.. index::
statement: for
keyword: in
keyword: else
pair: target; list
pair: loop; statement
keyword: in
keyword: else
pair: target; list
object: sequence
single: : (colon); compound statement
The :keyword:`for` statement is used to iterate over the elements of a sequence
(such as a string, tuple or list) or other iterable object:
.. productionlist::
for_stmt: "for" `target_list` "in" `expression_list` ":" `suite`
: ["else" ":" `suite`]
The expression list is evaluated once; it should yield an iterable object. An
iterator is created for the result of the ``expression_list``. The suite is
then executed once for each item provided by the iterator, in the order returned
by the iterator. Each item in turn is assigned to the target list using the
standard rules for assignments (see :ref:`assignment`), and then the suite is
executed. When the items are exhausted (which is immediately when the sequence
is empty or an iterator raises a :exc:`StopIteration` exception), the suite in
the :keyword:`else` clause, if present, is executed, and the loop terminates.
.. index::
statement: break
statement: continue
A :keyword:`break` statement executed in the first suite terminates the loop
without executing the :keyword:`else` clause's suite. A :keyword:`continue`
statement executed in the first suite skips the rest of the suite and continues
with the next item, or with the :keyword:`else` clause if there is no next
item.
The for-loop makes assignments to the variables(s) in the target list.
This overwrites all previous assignments to those variables including
those made in the suite of the for-loop::
for i in range(10):
print(i)
i = 5 # this will not affect the for-loop
# because i will be overwritten with the next
# index in the range
.. index::
builtin: range
Names in the target list are not deleted when the loop is finished, but if the
sequence is empty, they will not have been assigned to at all by the loop. Hint:
the built-in function :func:`range` returns an iterator of integers suitable to
emulate the effect of Pascal's ``for i := a to b do``; e.g., ``list(range(3))``
returns the list ``[0, 1, 2]``.
.. note::
.. index::
single: loop; over mutable sequence
single: mutable sequence; loop over
There is a subtlety when the sequence is being modified by the loop (this can
only occur for mutable sequences, e.g. lists). An internal counter is used
to keep track of which item is used next, and this is incremented on each
iteration. When this counter has reached the length of the sequence the loop
terminates. This means that if the suite deletes the current (or a previous)
item from the sequence, the next item will be skipped (since it gets the
index of the current item which has already been treated). Likewise, if the
suite inserts an item in the sequence before the current item, the current
item will be treated again the next time through the loop. This can lead to
nasty bugs that can be avoided by making a temporary copy using a slice of
the whole sequence, e.g., ::
for x in a[:]:
if x < 0: a.remove(x)
.. _try:
.. _except:
.. _finally:
The :keyword:`try` statement
============================
.. index::
statement: try
keyword: except
keyword: finally
keyword: else
keyword: as
single: : (colon); compound statement
The :keyword:`try` statement specifies exception handlers and/or cleanup code
for a group of statements:
.. productionlist::
try_stmt: `try1_stmt` | `try2_stmt`
try1_stmt: "try" ":" `suite`
: ("except" [`expression` ["as" `identifier`]] ":" `suite`)+
: ["else" ":" `suite`]
: ["finally" ":" `suite`]
try2_stmt: "try" ":" `suite`
: "finally" ":" `suite`
The :keyword:`except` clause(s) specify one or more exception handlers. When no
exception occurs in the :keyword:`try` clause, no exception handler is executed.
When an exception occurs in the :keyword:`try` suite, a search for an exception
handler is started. This search inspects the except clauses in turn until one
is found that matches the exception. An expression-less except clause, if
present, must be last; it matches any exception. For an except clause with an
expression, that expression is evaluated, and the clause matches the exception
if the resulting object is "compatible" with the exception. An object is
compatible with an exception if it is the class or a base class of the exception
object or a tuple containing an item compatible with the exception.
If no except clause matches the exception, the search for an exception handler
continues in the surrounding code and on the invocation stack. [#]_
If the evaluation of an expression in the header of an except clause raises an
exception, the original search for a handler is canceled and a search starts for
the new exception in the surrounding code and on the call stack (it is treated
as if the entire :keyword:`try` statement raised the exception).
.. index:: single: as; except clause
When a matching except clause is found, the exception is assigned to the target
specified after the :keyword:`as` keyword in that except clause, if present, and
the except clause's suite is executed. All except clauses must have an
executable block. When the end of this block is reached, execution continues
normally after the entire try statement. (This means that if two nested
handlers exist for the same exception, and the exception occurs in the try
clause of the inner handler, the outer handler will not handle the exception.)
When an exception has been assigned using ``as target``, it is cleared at the
end of the except clause. This is as if ::
except E as N:
foo
was translated to ::
except E as N:
try:
foo
finally:
del N
This means the exception must be assigned to a different name to be able to
refer to it after the except clause. Exceptions are cleared because with the
traceback attached to them, they form a reference cycle with the stack frame,
keeping all locals in that frame alive until the next garbage collection occurs.
.. index::
module: sys
object: traceback
Before an except clause's suite is executed, details about the exception are
stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`.
:func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the
exception instance and a traceback object (see section :ref:`types`) identifying
the point in the program where the exception occurred. :func:`sys.exc_info`
values are restored to their previous values (before the call) when returning
from a function that handled an exception.
.. index::
keyword: else
statement: return
statement: break
statement: continue
The optional :keyword:`else` clause is executed if the control flow leaves the
:keyword:`try` suite, no exception was raised, and no :keyword:`return`,
:keyword:`continue`, or :keyword:`break` statement was executed. Exceptions in
the :keyword:`else` clause are not handled by the preceding :keyword:`except`
clauses.
.. index:: keyword: finally
If :keyword:`finally` is present, it specifies a 'cleanup' handler. The
:keyword:`try` clause is executed, including any :keyword:`except` and
:keyword:`else` clauses. If an exception occurs in any of the clauses and is
not handled, the exception is temporarily saved. The :keyword:`finally` clause
is executed. If there is a saved exception it is re-raised at the end of the
:keyword:`finally` clause. If the :keyword:`finally` clause raises another
exception, the saved exception is set as the context of the new exception.
If the :keyword:`finally` clause executes a :keyword:`return` or :keyword:`break`
statement, the saved exception is discarded::
>>> def f():
... try:
... 1/0
... finally:
... return 42
...
>>> f()
42
The exception information is not available to the program during execution of
the :keyword:`finally` clause.
.. index::
statement: return
statement: break
statement: continue
When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is
executed in the :keyword:`try` suite of a :keyword:`try`...\ :keyword:`finally`
statement, the :keyword:`finally` clause is also executed 'on the way out.' A
:keyword:`continue` statement is illegal in the :keyword:`finally` clause. (The
reason is a problem with the current implementation --- this restriction may be
lifted in the future).
The return value of a function is determined by the last :keyword:`return`
statement executed. Since the :keyword:`finally` clause always executes, a
:keyword:`return` statement executed in the :keyword:`finally` clause will
always be the last one executed::
>>> def foo():
... try:
... return 'try'
... finally:
... return 'finally'
...
>>> foo()
'finally'
Additional information on exceptions can be found in section :ref:`exceptions`,
and information on using the :keyword:`raise` statement to generate exceptions
may be found in section :ref:`raise`.
.. _with:
.. _as:
The :keyword:`with` statement
=============================
.. index::
statement: with
keyword: as
single: as; with statement
single: , (comma); with statement
single: : (colon); compound statement
The :keyword:`with` statement is used to wrap the execution of a block with
methods defined by a context manager (see section :ref:`context-managers`).
This allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally`
usage patterns to be encapsulated for convenient reuse.
.. productionlist::
with_stmt: "with" `with_item` ("," `with_item`)* ":" `suite`
with_item: `expression` ["as" `target`]
The execution of the :keyword:`with` statement with one "item" proceeds as follows:
#. The context expression (the expression given in the :token:`with_item`) is
evaluated to obtain a context manager.
#. The context manager's :meth:`__exit__` is loaded for later use.
#. The context manager's :meth:`__enter__` method is invoked.
#. If a target was included in the :keyword:`with` statement, the return value
from :meth:`__enter__` is assigned to it.
.. note::
The :keyword:`with` statement guarantees that if the :meth:`__enter__`
method returns without an error, then :meth:`__exit__` will always be
called. Thus, if an error occurs during the assignment to the target list,
it will be treated the same as an error occurring within the suite would
be. See step 6 below.
#. The suite is executed.
#. The context manager's :meth:`__exit__` method is invoked. If an exception
caused the suite to be exited, its type, value, and traceback are passed as
arguments to :meth:`__exit__`. Otherwise, three :const:`None` arguments are
supplied.
If the suite was exited due to an exception, and the return value from the
:meth:`__exit__` method was false, the exception is reraised. If the return
value was true, the exception is suppressed, and execution continues with the
statement following the :keyword:`with` statement.
If the suite was exited for any reason other than an exception, the return
value from :meth:`__exit__` is ignored, and execution proceeds at the normal
location for the kind of exit that was taken.
With more than one item, the context managers are processed as if multiple
:keyword:`with` statements were nested::
with A() as a, B() as b:
suite
is equivalent to ::
with A() as a:
with B() as b:
suite
.. versionchanged:: 3.1
Support for multiple context expressions.
.. seealso::
:pep:`343` - The "with" statement
The specification, background, and examples for the Python :keyword:`with`
statement.
.. index::
single: parameter; function definition
.. _function:
.. _def:
Function definitions
====================
.. index::
statement: def
pair: function; definition
pair: function; name
pair: name; binding
object: user-defined function
object: function
pair: function; name
pair: name; binding
single: () (parentheses); function definition
single: , (comma); parameter list
single: : (colon); compound statement
A function definition defines a user-defined function object (see section
:ref:`types`):
.. productionlist::
funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")"
: ["->" `expression`] ":" `suite`
decorators: `decorator`+
decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE
dotted_name: `identifier` ("." `identifier`)*
parameter_list: `defparameter` ("," `defparameter`)* ["," [`parameter_list_starargs`]]
: | `parameter_list_starargs`
parameter_list_starargs: "*" [`parameter`] ("," `defparameter`)* ["," ["**" `parameter` [","]]]
: | "**" `parameter` [","]
parameter: `identifier` [":" `expression`]
defparameter: `parameter` ["=" `expression`]
funcname: `identifier`
A function definition is an executable statement. Its execution binds the
function name in the current local namespace to a function object (a wrapper
around the executable code for the function). This function object contains a
reference to the current global namespace as the global namespace to be used
when the function is called.
The function definition does not execute the function body; this gets executed
only when the function is called. [#]_
.. index::
single: @ (at); function definition
A function definition may be wrapped by one or more :term:`decorator` expressions.
Decorator expressions are evaluated when the function is defined, in the scope
that contains the function definition. The result must be a callable, which is
invoked with the function object as the only argument. The returned value is
bound to the function name instead of the function object. Multiple decorators
are applied in nested fashion. For example, the following code ::
@f1(arg)
@f2
def func(): pass
is roughly equivalent to ::
def func(): pass
func = f1(arg)(f2(func))
except that the original function is not temporarily bound to the name ``func``.
.. index::
triple: default; parameter; value
single: argument; function definition
single: = (equals); function definition
When one or more :term:`parameters <parameter>` have the form *parameter* ``=``
*expression*, the function is said to have "default parameter values." For a
parameter with a default value, the corresponding :term:`argument` may be
omitted from a call, in which
case the parameter's default value is substituted. If a parameter has a default
value, all following parameters up until the "``*``" must also have a default
value --- this is a syntactic restriction that is not expressed by the grammar.
**Default parameter values are evaluated from left to right when the function
definition is executed.** This means that the expression is evaluated once, when
the function is defined, and that the same "pre-computed" value is used for each
call. This is especially important to understand when a default parameter is a
mutable object, such as a list or a dictionary: if the function modifies the
object (e.g. by appending an item to a list), the default value is in effect
modified. This is generally not what was intended. A way around this is to use
``None`` as the default, and explicitly test for it in the body of the function,
e.g.::
def whats_on_the_telly(penguin=None):
if penguin is None:
penguin = []
penguin.append("property of the zoo")
return penguin
.. index::
single: * (asterisk); function definition
single: **; function definition
Function call semantics are described in more detail in section :ref:`calls`. A
function call always assigns values to all parameters mentioned in the parameter
list, either from position arguments, from keyword arguments, or from default
values. If the form "``*identifier``" is present, it is initialized to a tuple
receiving any excess positional parameters, defaulting to the empty tuple.
If the form "``**identifier``" is present, it is initialized to a new
ordered mapping receiving any excess keyword arguments, defaulting to a
new empty mapping of the same type. Parameters after "``*``" or
"``*identifier``" are keyword-only parameters and may only be passed
used keyword arguments.
.. index::
pair: function; annotations
single: ->; function annotations
single: : (colon); function annotations
Parameters may have annotations 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
the form "``-> expression``" after the parameter list. These annotations can be
any valid Python expression and are evaluated when the function definition is
executed. Annotations may be evaluated in a different order than they appear in
the source code. The presence of annotations does not change the semantics of a
function. The annotation values are available as values of a dictionary keyed
by the parameters' names in the :attr:`__annotations__` attribute of the
function object.
.. index:: pair: lambda; expression
It is also possible to create anonymous functions (functions not bound to a
name), for immediate use in expressions. This uses lambda expressions, described in
section :ref:`lambda`. Note that the lambda expression is merely a shorthand for a
simplified function definition; a function defined in a ":keyword:`def`"
statement can be passed around or assigned to another name just like a function
defined by a lambda expression. The ":keyword:`def`" form is actually more powerful
since it allows the execution of multiple statements and annotations.
**Programmer's note:** Functions are first-class objects. A "``def``" statement
executed inside a function definition defines a local function that can be
returned or passed around. Free variables used in the nested function can
access the local variables of the function containing the def. See section
:ref:`naming` for details.
.. seealso::
:pep:`3107` - Function Annotations
The original specification for function annotations.
.. _class:
Class definitions
=================
.. index::
object: class
statement: class
pair: class; definition
pair: class; name
pair: name; binding
pair: execution; frame
single: inheritance
single: docstring
single: () (parentheses); class definition
single: , (comma); expression list
single: : (colon); compound statement
A class definition defines a class object (see section :ref:`types`):
.. productionlist::
classdef: [`decorators`] "class" `classname` [`inheritance`] ":" `suite`
inheritance: "(" [`argument_list`] ")"
classname: `identifier`
A class definition is an executable statement. The inheritance list usually
gives a list of base classes (see :ref:`metaclasses` for more advanced uses), so
each item in the list should evaluate to a class object which allows
subclassing. Classes without an inheritance list inherit, by default, from the
base class :class:`object`; hence, ::
class Foo:
pass
is equivalent to ::
class Foo(object):
pass
The class's suite is then executed in a new execution frame (see :ref:`naming`),
using a newly created local namespace and the original global namespace.
(Usually, the suite contains mostly function definitions.) When the class's
suite finishes execution, its execution frame is discarded but its local
namespace is saved. [#]_ A class object is then created using the inheritance
list for the base classes and the saved local namespace for the attribute
dictionary. The class name is bound to this class object in the original local
namespace.
The order in which attributes are defined in the class body is preserved
in the new class's ``__dict__``. Note that this is reliable only right
after the class is created and only for classes that were defined using
the definition syntax.
Class creation can be customized heavily using :ref:`metaclasses <metaclasses>`.
.. index::
single: @ (at); class definition
Classes can also be decorated: just like when decorating functions, ::
@f1(arg)
@f2
class Foo: pass
is roughly equivalent to ::
class Foo: pass
Foo = f1(arg)(f2(Foo))
The evaluation rules for the decorator expressions are the same as for function
decorators. The result is then bound to the class name.
**Programmer's note:** Variables defined in the class definition are class
attributes; they are shared by instances. Instance attributes can be set in a
method with ``self.name = value``. Both class and instance attributes are
accessible through the notation "``self.name``", and an instance attribute hides
a class attribute with the same name when accessed in this way. Class
attributes can be used as defaults for instance attributes, but using mutable
values there can lead to unexpected results. :ref:`Descriptors <descriptors>`
can be used to create instance variables with different implementation details.
.. seealso::
:pep:`3115` - Metaclasses in Python 3000
The proposal that changed the declaration of metaclasses to the current
syntax, and the semantics for how classes with metaclasses are
constructed.
:pep:`3129` - Class Decorators
The proposal that added class decorators. Function and method decorators
were introduced in :pep:`318`.
Coroutines
==========
.. versionadded:: 3.5
.. index:: statement: async def
.. _`async def`:
Coroutine function definition
-----------------------------
.. productionlist::
async_funcdef: [`decorators`] "async" "def" `funcname` "(" [`parameter_list`] ")"
: ["->" `expression`] ":" `suite`
.. index::
keyword: async
keyword: await
Execution of Python coroutines can be suspended and resumed at many points
(see :term:`coroutine`). In the body of a coroutine, any ``await`` and
``async`` identifiers become reserved keywords; :keyword:`await` expressions,
:keyword:`async for` and :keyword:`async with` can only be used in
coroutine bodies.
Functions defined with ``async def`` syntax are always coroutine functions,
even if they do not contain ``await`` or ``async`` keywords.
It is a :exc:`SyntaxError` to use ``yield from`` expressions in
``async def`` coroutines.
An example of a coroutine function::
async def func(param1, param2):
do_stuff()
await some_coroutine()
.. index:: statement: async for
.. _`async for`:
The :keyword:`async for` statement
----------------------------------
.. productionlist::
async_for_stmt: "async" `for_stmt`
An :term:`asynchronous iterable` is able to call asynchronous code in its
*iter* implementation, and :term:`asynchronous iterator` can call asynchronous
code in its *next* method.
The ``async for`` statement allows convenient iteration over asynchronous
iterators.
The following code::
async for TARGET in ITER:
BLOCK
else:
BLOCK2
Is semantically equivalent to::
iter = (ITER)
iter = type(iter).__aiter__(iter)
running = True
while running:
try:
TARGET = await type(iter).__anext__(iter)
except StopAsyncIteration:
running = False
else:
BLOCK
else:
BLOCK2
See also :meth:`__aiter__` and :meth:`__anext__` for details.
It is a :exc:`SyntaxError` to use ``async for`` statement outside of an
:keyword:`async def` function.
.. index:: statement: async with
.. _`async with`:
The :keyword:`async with` statement
-----------------------------------
.. productionlist::
async_with_stmt: "async" `with_stmt`
An :term:`asynchronous context manager` is a :term:`context manager` that is
able to suspend execution in its *enter* and *exit* methods.
The following code::
async with EXPR as VAR:
BLOCK
Is semantically equivalent to::
mgr = (EXPR)
aexit = type(mgr).__aexit__
aenter = type(mgr).__aenter__(mgr)
VAR = await aenter
try:
BLOCK
except:
if not await aexit(mgr, *sys.exc_info()):
raise
else:
await aexit(mgr, None, None, None)
See also :meth:`__aenter__` and :meth:`__aexit__` for details.
It is a :exc:`SyntaxError` to use ``async with`` statement outside of an
:keyword:`async def` function.
.. seealso::
:pep:`492` - Coroutines with async and await syntax
The proposal that made coroutines a proper standalone concept in Python,
and added supporting syntax.
.. rubric:: Footnotes
.. [#] The exception is propagated to the invocation stack unless
there is a :keyword:`finally` clause which happens to raise another
exception. That new exception causes the old one to be lost.
.. [#] A string literal appearing as the first statement in the function body is
transformed into the function's ``__doc__`` attribute and therefore the
function's :term:`docstring`.
.. [#] A string literal appearing as the first statement in the class body is
transformed into the namespace's ``__doc__`` item and therefore the class's
:term:`docstring`.

2657
third_party/python/Doc/reference/datamodel.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

266
third_party/python/Doc/reference/executionmodel.rst vendored Normal file
View file

@ -0,0 +1,266 @@
.. _execmodel:
***************
Execution model
***************
.. index::
single: execution model
pair: code; block
.. _prog_structure:
Structure of a program
======================
.. index:: block
A Python program is constructed from code blocks.
A :dfn:`block` is a piece of Python program text that is executed as a unit.
The following are blocks: a module, a function body, and a class definition.
Each command typed interactively is a block. A script file (a file given as
standard input to the interpreter or specified as a command line argument to the
interpreter) is a code block. A script command (a command specified on the
interpreter command line with the :option:`-c` option) is a code block. The string
argument passed to the built-in functions :func:`eval` and :func:`exec` is a
code block.
.. index:: pair: execution; frame
A code block is executed in an :dfn:`execution frame`. A frame contains some
administrative information (used for debugging) and determines where and how
execution continues after the code block's execution has completed.
.. _naming:
Naming and binding
==================
.. index::
single: namespace
single: scope
.. _bind_names:
Binding of names
----------------
.. index::
single: name
pair: binding; name
:dfn:`Names` refer to objects. Names are introduced by name binding operations.
.. index:: single: from; import statement
The following constructs bind names: formal parameters to functions,
:keyword:`import` statements, class and function definitions (these bind the
class or function name in the defining block), and targets that are identifiers
if occurring in an assignment, :keyword:`for` loop header, or after
:keyword:`as` in a :keyword:`with` statement or :keyword:`except` clause.
The :keyword:`import` statement
of the form ``from ... import *`` binds all names defined in the imported
module, except those beginning with an underscore. This form may only be used
at the module level.
A target occurring in a :keyword:`del` statement is also considered bound for
this purpose (though the actual semantics are to unbind the name).
Each assignment or import statement occurs within a block defined by a class or
function definition or at the module level (the top-level code block).
.. index:: pair: free; variable
If a name is bound in a block, it is a local variable of that block, unless
declared as :keyword:`nonlocal` or :keyword:`global`. If a name is bound at
the module level, it is a global variable. (The variables of the module code
block are local and global.) If a variable is used in a code block but not
defined there, it is a :dfn:`free variable`.
Each occurrence of a name in the program text refers to the :dfn:`binding` of
that name established by the following name resolution rules.
.. _resolve_names:
Resolution of names
-------------------
.. index:: scope
A :dfn:`scope` defines the visibility of a name within a block. If a local
variable is defined in a block, its scope includes that block. If the
definition occurs in a function block, the scope extends to any blocks contained
within the defining one, unless a contained block introduces a different binding
for the name.
.. index:: single: environment
When a name is used in a code block, it is resolved using the nearest enclosing
scope. The set of all such scopes visible to a code block is called the block's
:dfn:`environment`.
.. index::
single: NameError (built-in exception)
single: UnboundLocalError
When a name is not found at all, a :exc:`NameError` exception is raised.
If the current scope is a function scope, and the name refers to a local
variable that has not yet been bound to a value at the point where the name is
used, an :exc:`UnboundLocalError` exception is raised.
:exc:`UnboundLocalError` is a subclass of :exc:`NameError`.
If a name binding operation occurs anywhere within a code block, all uses of the
name within the block are treated as references to the current block. This can
lead to errors when a name is used within a block before it is bound. This rule
is subtle. Python lacks declarations and allows name binding operations to
occur anywhere within a code block. The local variables of a code block can be
determined by scanning the entire text of the block for name binding operations.
If the :keyword:`global` statement occurs within a block, all uses of the name
specified in the statement refer to the binding of that name in the top-level
namespace. Names are resolved in the top-level namespace by searching the
global namespace, i.e. the namespace of the module containing the code block,
and the builtins namespace, the namespace of the module :mod:`builtins`. The
global namespace is searched first. If the name is not found there, the
builtins namespace is searched. The :keyword:`global` statement must precede
all uses of the name.
The :keyword:`global` statement has the same scope as a name binding operation
in the same block. If the nearest enclosing scope for a free variable contains
a global statement, the free variable is treated as a global.
.. XXX say more about "nonlocal" semantics here
The :keyword:`nonlocal` statement causes corresponding names to refer
to previously bound variables in the nearest enclosing function scope.
:exc:`SyntaxError` is raised at compile time if the given name does not
exist in any enclosing function scope.
.. index:: module: __main__
The namespace for a module is automatically created the first time a module is
imported. The main module for a script is always called :mod:`__main__`.
Class definition blocks and arguments to :func:`exec` and :func:`eval` are
special in the context of name resolution.
A class definition is an executable statement that may use and define names.
These references follow the normal rules for name resolution with an exception
that unbound local variables are looked up in the global namespace.
The namespace of the class definition becomes the attribute dictionary of
the class. The scope of names defined in a class block is limited to the
class block; it does not extend to the code blocks of methods -- this includes
comprehensions and generator expressions since they are implemented using a
function scope. This means that the following will fail::
class A:
a = 42
b = list(a + i for i in range(10))
.. _restrict_exec:
Builtins and restricted execution
---------------------------------
.. index:: pair: restricted; execution
.. impl-detail::
Users should not touch ``__builtins__``; it is strictly an implementation
detail. Users wanting to override values in the builtins namespace should
:keyword:`import` the :mod:`builtins` module and modify its
attributes appropriately.
The builtins namespace associated with the execution of a code block
is actually found by looking up the name ``__builtins__`` in its
global namespace; this should be a dictionary or a module (in the
latter case the module's dictionary is used). By default, when in the
:mod:`__main__` module, ``__builtins__`` is the built-in module
:mod:`builtins`; when in any other module, ``__builtins__`` is an
alias for the dictionary of the :mod:`builtins` module itself.
.. _dynamic-features:
Interaction with dynamic features
---------------------------------
Name resolution of free variables occurs at runtime, not at compile time.
This means that the following code will print 42::
i = 10
def f():
print(i)
i = 42
f()
.. XXX from * also invalid with relative imports (at least currently)
The :func:`eval` and :func:`exec` functions do not have access to the full
environment for resolving names. Names may be resolved in the local and global
namespaces of the caller. Free variables are not resolved in the nearest
enclosing namespace, but in the global namespace. [#]_ The :func:`exec` and
:func:`eval` functions have optional arguments to override the global and local
namespace. If only one namespace is specified, it is used for both.
.. _exceptions:
Exceptions
==========
.. index:: single: exception
.. index::
single: raise an exception
single: handle an exception
single: exception handler
single: errors
single: error handling
Exceptions are a means of breaking out of the normal flow of control of a code
block in order to handle errors or other exceptional conditions. An exception
is *raised* at the point where the error is detected; it may be *handled* by the
surrounding code block or by any code block that directly or indirectly invoked
the code block where the error occurred.
The Python interpreter raises an exception when it detects a run-time error
(such as division by zero). A Python program can also explicitly raise an
exception with the :keyword:`raise` statement. Exception handlers are specified
with the :keyword:`try` ... :keyword:`except` statement. The :keyword:`finally`
clause of such a statement can be used to specify cleanup code which does not
handle the exception, but is executed whether an exception occurred or not in
the preceding code.
.. index:: single: termination model
Python uses the "termination" model of error handling: an exception handler can
find out what happened and continue execution at an outer level, but it cannot
repair the cause of the error and retry the failing operation (except by
re-entering the offending piece of code from the top).
.. index:: single: SystemExit (built-in exception)
When an exception is not handled at all, the interpreter terminates execution of
the program, or returns to its interactive main loop. In either case, it prints
a stack backtrace, except when the exception is :exc:`SystemExit`.
Exceptions are identified by class instances. The :keyword:`except` clause is
selected depending on the class of the instance: it must reference the class of
the instance or a base class thereof. The instance can be received by the
handler and can carry additional information about the exceptional condition.
.. note::
Exception messages are not part of the Python API. Their contents may change
from one version of Python to the next without warning and should not be
relied on by code which will run under multiple versions of the interpreter.
See also the description of the :keyword:`try` statement in section :ref:`try`
and :keyword:`raise` statement in section :ref:`raise`.
.. rubric:: Footnotes
.. [#] This limitation occurs because the code that is executed by these operations
is not available at the time the module is compiled.

1843
third_party/python/Doc/reference/expressions.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

7
third_party/python/Doc/reference/grammar.rst vendored Normal file
View file

@ -0,0 +1,7 @@
Full Grammar specification
==========================
This is the full Python grammar, as it is read by the parser generator and used
to parse Python source files:
.. literalinclude:: ../../Grammar/Grammar

1007
third_party/python/Doc/reference/import.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

29
third_party/python/Doc/reference/index.rst vendored Normal file
View file

@ -0,0 +1,29 @@
.. _reference-index:
#################################
The Python Language Reference
#################################
This reference manual describes the syntax and "core semantics" of the
language. It is terse, but attempts to be exact and complete. The semantics of
non-essential built-in object types and of the built-in functions and modules
are described in :ref:`library-index`. For an informal introduction to the
language, see :ref:`tutorial-index`. For C or C++ programmers, two additional
manuals exist: :ref:`extending-index` describes the high-level picture of how to
write a Python extension module, and the :ref:`c-api-index` describes the
interfaces available to C/C++ programmers in detail.
.. toctree::
:maxdepth: 2
:numbered:
introduction.rst
lexical_analysis.rst
datamodel.rst
executionmodel.rst
import.rst
expressions.rst
simple_stmts.rst
compound_stmts.rst
toplevel_components.rst
grammar.rst

132
third_party/python/Doc/reference/introduction.rst vendored Normal file
View file

@ -0,0 +1,132 @@
.. _introduction:
************
Introduction
************
This reference manual describes the Python programming language. It is not
intended as a tutorial.
While I am trying to be as precise as possible, I chose to use English rather
than formal specifications for everything except syntax and lexical analysis.
This should make the document more understandable to the average reader, but
will leave room for ambiguities. Consequently, if you were coming from Mars and
tried to re-implement Python from this document alone, you might have to guess
things and in fact you would probably end up implementing quite a different
language. On the other hand, if you are using Python and wonder what the precise
rules about a particular area of the language are, you should definitely be able
to find them here. If you would like to see a more formal definition of the
language, maybe you could volunteer your time --- or invent a cloning machine
:-).
It is dangerous to add too many implementation details to a language reference
document --- the implementation may change, and other implementations of the
same language may work differently. On the other hand, CPython is the one
Python implementation in widespread use (although alternate implementations
continue to gain support), and its particular quirks are sometimes worth being
mentioned, especially where the implementation imposes additional limitations.
Therefore, you'll find short "implementation notes" sprinkled throughout the
text.
Every Python implementation comes with a number of built-in and standard
modules. These are documented in :ref:`library-index`. A few built-in modules
are mentioned when they interact in a significant way with the language
definition.
.. _implementations:
Alternate Implementations
=========================
Though there is one Python implementation which is by far the most popular,
there are some alternate implementations which are of particular interest to
different audiences.
Known implementations include:
CPython
This is the original and most-maintained implementation of Python, written in C.
New language features generally appear here first.
Jython
Python implemented in Java. This implementation can be used as a scripting
language for Java applications, or can be used to create applications using the
Java class libraries. It is also often used to create tests for Java libraries.
More information can be found at `the Jython website <http://www.jython.org/>`_.
Python for .NET
This implementation actually uses the CPython implementation, but is a managed
.NET application and makes .NET libraries available. It was created by Brian
Lloyd. For more information, see the `Python for .NET home page
<https://pythonnet.github.io/>`_.
IronPython
An alternate Python for .NET. Unlike Python.NET, this is a complete Python
implementation that generates IL, and compiles Python code directly to .NET
assemblies. It was created by Jim Hugunin, the original creator of Jython. For
more information, see `the IronPython website <http://ironpython.net/>`_.
PyPy
An implementation of Python written completely in Python. It supports several
advanced features not found in other implementations like stackless support
and a Just in Time compiler. One of the goals of the project is to encourage
experimentation with the language itself by making it easier to modify the
interpreter (since it is written in Python). Additional information is
available on `the PyPy project's home page <http://pypy.org/>`_.
Each of these implementations varies in some way from the language as documented
in this manual, or introduces specific information beyond what's covered in the
standard Python documentation. Please refer to the implementation-specific
documentation to determine what else you need to know about the specific
implementation you're using.
.. _notation:
Notation
========
.. index:: BNF, grammar, syntax, notation
The descriptions of lexical analysis and syntax use a modified BNF grammar
notation. This uses the following style of definition:
.. productionlist:: *
name: `lc_letter` (`lc_letter` | "_")*
lc_letter: "a"..."z"
The first line says that a ``name`` is an ``lc_letter`` followed by a sequence
of zero or more ``lc_letter``\ s and underscores. An ``lc_letter`` in turn is
any of the single characters ``'a'`` through ``'z'``. (This rule is actually
adhered to for the names defined in lexical and grammar rules in this document.)
Each rule begins with a name (which is the name defined by the rule) and
``::=``. A vertical bar (``|``) is used to separate alternatives; it is the
least binding operator in this notation. A star (``*``) means zero or more
repetitions of the preceding item; likewise, a plus (``+``) means one or more
repetitions, and a phrase enclosed in square brackets (``[ ]``) means zero or
one occurrences (in other words, the enclosed phrase is optional). The ``*``
and ``+`` operators bind as tightly as possible; parentheses are used for
grouping. Literal strings are enclosed in quotes. White space is only
meaningful to separate tokens. Rules are normally contained on a single line;
rules with many alternatives may be formatted alternatively with each line after
the first beginning with a vertical bar.
.. index:: lexical definitions, ASCII
In lexical definitions (as the example above), two more conventions are used:
Two literal characters separated by three dots mean a choice of any single
character in the given (inclusive) range of ASCII characters. A phrase between
angular brackets (``<...>``) gives an informal description of the symbol
defined; e.g., this could be used to describe the notion of 'control character'
if needed.
Even though the notation used is almost the same, there is a big difference
between the meaning of lexical and syntactic definitions: a lexical definition
operates on the individual characters of the input source, while a syntax
definition operates on the stream of tokens generated by the lexical analysis.
All uses of BNF in the next chapter ("Lexical Analysis") are lexical
definitions; uses in subsequent chapters are syntactic definitions.

939
third_party/python/Doc/reference/lexical_analysis.rst vendored Normal file
View file

@ -0,0 +1,939 @@
.. _lexical:
****************
Lexical analysis
****************
.. index:: lexical analysis, parser, token
A Python program is read by a *parser*. Input to the parser is a stream of
*tokens*, generated by the *lexical analyzer*. This chapter describes how the
lexical analyzer breaks a file into tokens.
Python reads program text as Unicode code points; the encoding of a source file
can be given by an encoding declaration and defaults to UTF-8, see :pep:`3120`
for details. If the source file cannot be decoded, a :exc:`SyntaxError` is
raised.
.. _line-structure:
Line structure
==============
.. index:: line structure
A Python program is divided into a number of *logical lines*.
.. _logical-lines:
Logical lines
-------------
.. index:: logical line, physical line, line joining, NEWLINE token
The end of a logical line is represented by the token NEWLINE. Statements
cannot cross logical line boundaries except where NEWLINE is allowed by the
syntax (e.g., between statements in compound statements). A logical line is
constructed from one or more *physical lines* by following the explicit or
implicit *line joining* rules.
.. _physical-lines:
Physical lines
--------------
A physical line is a sequence of characters terminated by an end-of-line
sequence. In source files and strings, any of the standard platform line
termination sequences can be used - the Unix form using ASCII LF (linefeed),
the Windows form using the ASCII sequence CR LF (return followed by linefeed),
or the old Macintosh form using the ASCII CR (return) character. All of these
forms can be used equally, regardless of platform. The end of input also serves
as an implicit terminator for the final physical line.
When embedding Python, source code strings should be passed to Python APIs using
the standard C conventions for newline characters (the ``\n`` character,
representing ASCII LF, is the line terminator).
.. _comments:
Comments
--------
.. index:: comment, hash character
single: # (hash); comment
A comment starts with a hash character (``#``) that is not part of a string
literal, and ends at the end of the physical line. A comment signifies the end
of the logical line unless the implicit line joining rules are invoked. Comments
are ignored by the syntax; they are not tokens.
.. _encodings:
Encoding declarations
---------------------
.. index:: source character set, encoding declarations (source file)
single: # (hash); source encoding declaration
If a comment in the first or second line of the Python script matches the
regular expression ``coding[=:]\s*([-\w.]+)``, this comment is processed as an
encoding declaration; the first group of this expression names the encoding of
the source code file. The encoding declaration must appear on a line of its
own. If it is the second line, the first line must also be a comment-only line.
The recommended forms of an encoding expression are ::
# -*- coding: <encoding-name> -*-
which is recognized also by GNU Emacs, and ::
# vim:fileencoding=<encoding-name>
which is recognized by Bram Moolenaar's VIM.
If no encoding declaration is found, the default encoding is UTF-8. In
addition, if the first bytes of the file are the UTF-8 byte-order mark
(``b'\xef\xbb\xbf'``), the declared file encoding is UTF-8 (this is supported,
among others, by Microsoft's :program:`notepad`).
If an encoding is declared, the encoding name must be recognized by Python. The
encoding is used for all lexical analysis, including string literals, comments
and identifiers.
.. XXX there should be a list of supported encodings.
.. _explicit-joining:
Explicit line joining
---------------------
.. index:: physical line, line joining, line continuation, backslash character
Two or more physical lines may be joined into logical lines using backslash
characters (``\``), as follows: when a physical line ends in a backslash that is
not part of a string literal or comment, it is joined with the following forming
a single logical line, deleting the backslash and the following end-of-line
character. For example::
if 1900 < year < 2100 and 1 <= month <= 12 \
and 1 <= day <= 31 and 0 <= hour < 24 \
and 0 <= minute < 60 and 0 <= second < 60: # Looks like a valid date
return 1
A line ending in a backslash cannot carry a comment. A backslash does not
continue a comment. A backslash does not continue a token except for string
literals (i.e., tokens other than string literals cannot be split across
physical lines using a backslash). A backslash is illegal elsewhere on a line
outside a string literal.
.. _implicit-joining:
Implicit line joining
---------------------
Expressions in parentheses, square brackets or curly braces can be split over
more than one physical line without using backslashes. For example::
month_names = ['Januari', 'Februari', 'Maart', # These are the
'April', 'Mei', 'Juni', # Dutch names
'Juli', 'Augustus', 'September', # for the months
'Oktober', 'November', 'December'] # of the year
Implicitly continued lines can carry comments. The indentation of the
continuation lines is not important. Blank continuation lines are allowed.
There is no NEWLINE token between implicit continuation lines. Implicitly
continued lines can also occur within triple-quoted strings (see below); in that
case they cannot carry comments.
.. _blank-lines:
Blank lines
-----------
.. index:: single: blank line
A logical line that contains only spaces, tabs, formfeeds and possibly a
comment, is ignored (i.e., no NEWLINE token is generated). During interactive
input of statements, handling of a blank line may differ depending on the
implementation of the read-eval-print loop. In the standard interactive
interpreter, an entirely blank logical line (i.e. one containing not even
whitespace or a comment) terminates a multi-line statement.
.. _indentation:
Indentation
-----------
.. index:: indentation, leading whitespace, space, tab, grouping, statement grouping
Leading whitespace (spaces and tabs) at the beginning of a logical line is used
to compute the indentation level of the line, which in turn is used to determine
the grouping of statements.
Tabs are replaced (from left to right) by one to eight spaces such that the
total number of characters up to and including the replacement is a multiple of
eight (this is intended to be the same rule as used by Unix). The total number
of spaces preceding the first non-blank character then determines the line's
indentation. Indentation cannot be split over multiple physical lines using
backslashes; the whitespace up to the first backslash determines the
indentation.
Indentation is rejected as inconsistent if a source file mixes tabs and spaces
in a way that makes the meaning dependent on the worth of a tab in spaces; a
:exc:`TabError` is raised in that case.
**Cross-platform compatibility note:** because of the nature of text editors on
non-UNIX platforms, it is unwise to use a mixture of spaces and tabs for the
indentation in a single source file. It should also be noted that different
platforms may explicitly limit the maximum indentation level.
A formfeed character may be present at the start of the line; it will be ignored
for the indentation calculations above. Formfeed characters occurring elsewhere
in the leading whitespace have an undefined effect (for instance, they may reset
the space count to zero).
.. index:: INDENT token, DEDENT token
The indentation levels of consecutive lines are used to generate INDENT and
DEDENT tokens, using a stack, as follows.
Before the first line of the file is read, a single zero is pushed on the stack;
this will never be popped off again. The numbers pushed on the stack will
always be strictly increasing from bottom to top. At the beginning of each
logical line, the line's indentation level is compared to the top of the stack.
If it is equal, nothing happens. If it is larger, it is pushed on the stack, and
one INDENT token is generated. If it is smaller, it *must* be one of the
numbers occurring on the stack; all numbers on the stack that are larger are
popped off, and for each number popped off a DEDENT token is generated. At the
end of the file, a DEDENT token is generated for each number remaining on the
stack that is larger than zero.
Here is an example of a correctly (though confusingly) indented piece of Python
code::
def perm(l):
# Compute the list of all permutations of l
if len(l) <= 1:
return [l]
r = []
for i in range(len(l)):
s = l[:i] + l[i+1:]
p = perm(s)
for x in p:
r.append(l[i:i+1] + x)
return r
The following example shows various indentation errors::
def perm(l): # error: first line indented
for i in range(len(l)): # error: not indented
s = l[:i] + l[i+1:]
p = perm(l[:i] + l[i+1:]) # error: unexpected indent
for x in p:
r.append(l[i:i+1] + x)
return r # error: inconsistent dedent
(Actually, the first three errors are detected by the parser; only the last
error is found by the lexical analyzer --- the indentation of ``return r`` does
not match a level popped off the stack.)
.. _whitespace:
Whitespace between tokens
-------------------------
Except at the beginning of a logical line or in string literals, the whitespace
characters space, tab and formfeed can be used interchangeably to separate
tokens. Whitespace is needed between two tokens only if their concatenation
could otherwise be interpreted as a different token (e.g., ab is one token, but
a b is two tokens).
.. _other-tokens:
Other tokens
============
Besides NEWLINE, INDENT and DEDENT, the following categories of tokens exist:
*identifiers*, *keywords*, *literals*, *operators*, and *delimiters*. Whitespace
characters (other than line terminators, discussed earlier) are not tokens, but
serve to delimit tokens. Where ambiguity exists, a token comprises the longest
possible string that forms a legal token, when read from left to right.
.. _identifiers:
Identifiers and keywords
========================
.. index:: identifier, name
Identifiers (also referred to as *names*) are described by the following lexical
definitions.
The syntax of identifiers in Python is based on the Unicode standard annex
UAX-31, with elaboration and changes as defined below; see also :pep:`3131` for
further details.
Within the ASCII range (U+0001..U+007F), the valid characters for identifiers
are the same as in Python 2.x: the uppercase and lowercase letters ``A`` through
``Z``, the underscore ``_`` and, except for the first character, the digits
``0`` through ``9``.
Python 3.0 introduces additional characters from outside the ASCII range (see
:pep:`3131`). For these characters, the classification uses the version of the
Unicode Character Database as included in the :mod:`unicodedata` module.
Identifiers are unlimited in length. Case is significant.
.. productionlist::
identifier: `xid_start` `xid_continue`*
id_start: <all characters in general categories Lu, Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the Other_ID_Start property>
id_continue: <all characters in `id_start`, plus characters in the categories Mn, Mc, Nd, Pc and others with the Other_ID_Continue property>
xid_start: <all characters in `id_start` whose NFKC normalization is in "id_start xid_continue*">
xid_continue: <all characters in `id_continue` whose NFKC normalization is in "id_continue*">
The Unicode category codes mentioned above stand for:
* *Lu* - uppercase letters
* *Ll* - lowercase letters
* *Lt* - titlecase letters
* *Lm* - modifier letters
* *Lo* - other letters
* *Nl* - letter numbers
* *Mn* - nonspacing marks
* *Mc* - spacing combining marks
* *Nd* - decimal numbers
* *Pc* - connector punctuations
* *Other_ID_Start* - explicit list of characters in `PropList.txt
<http://www.unicode.org/Public/9.0.0/ucd/PropList.txt>`_ to support backwards
compatibility
* *Other_ID_Continue* - likewise
All identifiers are converted into the normal form NFKC while parsing; comparison
of identifiers is based on NFKC.
A non-normative HTML file listing all valid identifier characters for Unicode
4.1 can be found at
https://www.dcl.hpi.uni-potsdam.de/home/loewis/table-3131.html.
.. _keywords:
Keywords
--------
.. index::
single: keyword
single: reserved word
The following identifiers are used as reserved words, or *keywords* of the
language, and cannot be used as ordinary identifiers. They must be spelled
exactly as written here:
.. sourcecode:: text
False class finally is return
None continue for lambda try
True def from nonlocal while
and del global not with
as elif if or yield
assert else import pass
break except in raise
.. index::
single: _, identifiers
single: __, identifiers
.. _id-classes:
Reserved classes of identifiers
-------------------------------
Certain classes of identifiers (besides keywords) have special meanings. These
classes are identified by the patterns of leading and trailing underscore
characters:
``_*``
Not imported by ``from module import *``. The special identifier ``_`` is used
in the interactive interpreter to store the result of the last evaluation; it is
stored in the :mod:`builtins` module. When not in interactive mode, ``_``
has no special meaning and is not defined. See section :ref:`import`.
.. note::
The name ``_`` is often used in conjunction with internationalization;
refer to the documentation for the :mod:`gettext` module for more
information on this convention.
``__*__``
System-defined names. These names are defined by the interpreter and its
implementation (including the standard library). Current system names are
discussed in the :ref:`specialnames` section and elsewhere. More will likely
be defined in future versions of Python. *Any* use of ``__*__`` names, in
any context, that does not follow explicitly documented use, is subject to
breakage without warning.
``__*``
Class-private names. Names in this category, when used within the context of a
class definition, are re-written to use a mangled form to help avoid name
clashes between "private" attributes of base and derived classes. See section
:ref:`atom-identifiers`.
.. _literals:
Literals
========
.. index:: literal, constant
Literals are notations for constant values of some built-in types.
.. index:: string literal, bytes literal, ASCII
single: ' (single quote); string literal
single: " (double quote); string literal
single: u'; string literal
single: u"; string literal
.. _strings:
String and Bytes literals
-------------------------
String literals are described by the following lexical definitions:
.. productionlist::
stringliteral: [`stringprefix`](`shortstring` | `longstring`)
stringprefix: "r" | "u" | "R" | "U" | "f" | "F"
: | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | "Rf" | "RF"
shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"'
longstring: "'''" `longstringitem`* "'''" | '"""' `longstringitem`* '"""'
shortstringitem: `shortstringchar` | `stringescapeseq`
longstringitem: `longstringchar` | `stringescapeseq`
shortstringchar: <any source character except "\" or newline or the quote>
longstringchar: <any source character except "\">
stringescapeseq: "\" <any source character>
.. productionlist::
bytesliteral: `bytesprefix`(`shortbytes` | `longbytes`)
bytesprefix: "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb" | "rB" | "Rb" | "RB"
shortbytes: "'" `shortbytesitem`* "'" | '"' `shortbytesitem`* '"'
longbytes: "'''" `longbytesitem`* "'''" | '"""' `longbytesitem`* '"""'
shortbytesitem: `shortbyteschar` | `bytesescapeseq`
longbytesitem: `longbyteschar` | `bytesescapeseq`
shortbyteschar: <any ASCII character except "\" or newline or the quote>
longbyteschar: <any ASCII character except "\">
bytesescapeseq: "\" <any ASCII character>
One syntactic restriction not indicated by these productions is that whitespace
is not allowed between the :token:`stringprefix` or :token:`bytesprefix` and the
rest of the literal. The source character set is defined by the encoding
declaration; it is UTF-8 if no encoding declaration is given in the source file;
see section :ref:`encodings`.
.. index:: triple-quoted string, Unicode Consortium, raw string
single: """; string literal
single: '''; string literal
In plain English: Both types of literals can be enclosed in matching single quotes
(``'``) or double quotes (``"``). They can also be enclosed in matching groups
of three single or double quotes (these are generally referred to as
*triple-quoted strings*). The backslash (``\``) character is used to escape
characters that otherwise have a special meaning, such as newline, backslash
itself, or the quote character.
.. index::
single: b'; bytes literal
single: b"; bytes literal
Bytes literals are always prefixed with ``'b'`` or ``'B'``; they produce an
instance of the :class:`bytes` type instead of the :class:`str` type. They
may only contain ASCII characters; bytes with a numeric value of 128 or greater
must be expressed with escapes.
.. index::
single: r'; raw string literal
single: r"; raw string literal
Both string and bytes literals may optionally be prefixed with a letter ``'r'``
or ``'R'``; such strings are called :dfn:`raw strings` and treat backslashes as
literal characters. As a result, in string literals, ``'\U'`` and ``'\u'``
escapes in raw strings are not treated specially. Given that Python 2.x's raw
unicode literals behave differently than Python 3.x's the ``'ur'`` syntax
is not supported.
.. versionadded:: 3.3
The ``'rb'`` prefix of raw bytes literals has been added as a synonym
of ``'br'``.
.. versionadded:: 3.3
Support for the unicode legacy literal (``u'value'``) was reintroduced
to simplify the maintenance of dual Python 2.x and 3.x codebases.
See :pep:`414` for more information.
.. index::
single: f'; formatted string literal
single: f"; formatted string literal
A string literal with ``'f'`` or ``'F'`` in its prefix is a
:dfn:`formatted string literal`; see :ref:`f-strings`. The ``'f'`` may be
combined with ``'r'``, but not with ``'b'`` or ``'u'``, therefore raw
formatted strings are possible, but formatted bytes literals are not.
In triple-quoted literals, unescaped newlines and quotes are allowed (and are
retained), except that three unescaped quotes in a row terminate the literal. (A
"quote" is the character used to open the literal, i.e. either ``'`` or ``"``.)
.. index:: physical line, escape sequence, Standard C, C
single: \ (backslash); escape sequence
single: \\; escape sequence
single: \a; escape sequence
single: \b; escape sequence
single: \f; escape sequence
single: \n; escape sequence
single: \r; escape sequence
single: \t; escape sequence
single: \v; escape sequence
single: \x; escape sequence
single: \N; escape sequence
single: \u; escape sequence
single: \U; escape sequence
Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in string and
bytes literals are interpreted according to rules similar to those used by
Standard C. The recognized escape sequences are:
+-----------------+---------------------------------+-------+
| Escape Sequence | Meaning | Notes |
+=================+=================================+=======+
| ``\newline`` | Backslash and newline ignored | |
+-----------------+---------------------------------+-------+
| ``\\`` | Backslash (``\``) | |
+-----------------+---------------------------------+-------+
| ``\'`` | Single quote (``'``) | |
+-----------------+---------------------------------+-------+
| ``\"`` | Double quote (``"``) | |
+-----------------+---------------------------------+-------+
| ``\a`` | ASCII Bell (BEL) | |
+-----------------+---------------------------------+-------+
| ``\b`` | ASCII Backspace (BS) | |
+-----------------+---------------------------------+-------+
| ``\f`` | ASCII Formfeed (FF) | |
+-----------------+---------------------------------+-------+
| ``\n`` | ASCII Linefeed (LF) | |
+-----------------+---------------------------------+-------+
| ``\r`` | ASCII Carriage Return (CR) | |
+-----------------+---------------------------------+-------+
| ``\t`` | ASCII Horizontal Tab (TAB) | |
+-----------------+---------------------------------+-------+
| ``\v`` | ASCII Vertical Tab (VT) | |
+-----------------+---------------------------------+-------+
| ``\ooo`` | Character with octal value | (1,3) |
| | *ooo* | |
+-----------------+---------------------------------+-------+
| ``\xhh`` | Character with hex value *hh* | (2,3) |
+-----------------+---------------------------------+-------+
Escape sequences only recognized in string literals are:
+-----------------+---------------------------------+-------+
| Escape Sequence | Meaning | Notes |
+=================+=================================+=======+
| ``\N{name}`` | Character named *name* in the | \(4) |
| | Unicode database | |
+-----------------+---------------------------------+-------+
| ``\uxxxx`` | Character with 16-bit hex value | \(5) |
| | *xxxx* | |
+-----------------+---------------------------------+-------+
| ``\Uxxxxxxxx`` | Character with 32-bit hex value | \(6) |
| | *xxxxxxxx* | |
+-----------------+---------------------------------+-------+
Notes:
(1)
As in Standard C, up to three octal digits are accepted.
(2)
Unlike in Standard C, exactly two hex digits are required.
(3)
In a bytes literal, hexadecimal and octal escapes denote the byte with the
given value. In a string literal, these escapes denote a Unicode character
with the given value.
(4)
.. versionchanged:: 3.3
Support for name aliases [#]_ has been added.
(5)
Exactly four hex digits are required.
(6)
Any Unicode character can be encoded this way. Exactly eight hex digits
are required.
.. index:: unrecognized escape sequence
Unlike Standard C, all unrecognized escape sequences are left in the string
unchanged, i.e., *the backslash is left in the result*. (This behavior is
useful when debugging: if an escape sequence is mistyped, the resulting output
is more easily recognized as broken.) It is also important to note that the
escape sequences only recognized in string literals fall into the category of
unrecognized escapes for bytes literals.
.. versionchanged:: 3.6
Unrecognized escape sequences produce a DeprecationWarning. In
some future version of Python they will be a SyntaxError.
Even in a raw literal, quotes can be escaped with a backslash, but the
backslash remains in the result; for example, ``r"\""`` is a valid string
literal consisting of two characters: a backslash and a double quote; ``r"\"``
is not a valid string literal (even a raw string cannot end in an odd number of
backslashes). Specifically, *a raw literal cannot end in a single backslash*
(since the backslash would escape the following quote character). Note also
that a single backslash followed by a newline is interpreted as those two
characters as part of the literal, *not* as a line continuation.
.. _string-concatenation:
String literal concatenation
----------------------------
Multiple adjacent string or bytes literals (delimited by whitespace), possibly
using different quoting conventions, are allowed, and their meaning is the same
as their concatenation. Thus, ``"hello" 'world'`` is equivalent to
``"helloworld"``. This feature can be used to reduce the number of backslashes
needed, to split long strings conveniently across long lines, or even to add
comments to parts of strings, for example::
re.compile("[A-Za-z_]" # letter or underscore
"[A-Za-z0-9_]*" # letter, digit or underscore
)
Note that this feature is defined at the syntactical level, but implemented at
compile time. The '+' operator must be used to concatenate string expressions
at run time. Also note that literal concatenation can use different quoting
styles for each component (even mixing raw strings and triple quoted strings),
and formatted string literals may be concatenated with plain string literals.
.. index::
single: formatted string literal
single: interpolated string literal
single: string; formatted literal
single: string; interpolated literal
single: f-string
single: {} (curly brackets); in formatted string literal
single: ! (exclamation); in formatted string literal
single: : (colon); in formatted string literal
.. _f-strings:
Formatted string literals
-------------------------
.. versionadded:: 3.6
A :dfn:`formatted string literal` or :dfn:`f-string` is a string literal
that is prefixed with ``'f'`` or ``'F'``. These strings may contain
replacement fields, which are expressions delimited by curly braces ``{}``.
While other string literals always have a constant value, formatted strings
are really expressions evaluated at run time.
Escape sequences are decoded like in ordinary string literals (except when
a literal is also marked as a raw string). After decoding, the grammar
for the contents of the string is:
.. productionlist::
f_string: (`literal_char` | "{{" | "}}" | `replacement_field`)*
replacement_field: "{" `f_expression` ["!" `conversion`] [":" `format_spec`] "}"
f_expression: (`conditional_expression` | "*" `or_expr`)
: ("," `conditional_expression` | "," "*" `or_expr`)* [","]
: | `yield_expression`
conversion: "s" | "r" | "a"
format_spec: (`literal_char` | NULL | `replacement_field`)*
literal_char: <any code point except "{", "}" or NULL>
The parts of the string outside curly braces are treated literally,
except that any doubled curly braces ``'{{'`` or ``'}}'`` are replaced
with the corresponding single curly brace. A single opening curly
bracket ``'{'`` marks a replacement field, which starts with a
Python expression. After the expression, there may be a conversion field,
introduced by an exclamation point ``'!'``. A format specifier may also
be appended, introduced by a colon ``':'``. A replacement field ends
with a closing curly bracket ``'}'``.
Expressions in formatted string literals are treated like regular
Python expressions surrounded by parentheses, with a few exceptions.
An empty expression is not allowed, and a :keyword:`lambda` expression
must be surrounded by explicit parentheses. Replacement expressions
can contain line breaks (e.g. in triple-quoted strings), but they
cannot contain comments. Each expression is evaluated in the context
where the formatted string literal appears, in order from left to right.
.. index::
keyword: await
single: async for; in comprehensions
An :keyword:`await` expression and comprehensions containing an
:keyword:`async for` clause are illegal in the expression in formatted
string literals. (The reason is a problem with the implementation ---
this restriction is lifted in Python 3.7).
If a conversion is specified, the result of evaluating the expression
is converted before formatting. Conversion ``'!s'`` calls :func:`str` on
the result, ``'!r'`` calls :func:`repr`, and ``'!a'`` calls :func:`ascii`.
The result is then formatted using the :func:`format` protocol. The
format specifier is passed to the :meth:`__format__` method of the
expression or conversion result. An empty string is passed when the
format specifier is omitted. The formatted result is then included in
the final value of the whole string.
Top-level format specifiers may include nested replacement fields. These nested
fields may include their own conversion fields and :ref:`format specifiers
<formatspec>`, but may not include more deeply-nested replacement fields. The
:ref:`format specifier mini-language <formatspec>` is the same as that used by
the string .format() method.
Formatted string literals may be concatenated, but replacement fields
cannot be split across literals.
Some examples of formatted string literals::
>>> name = "Fred"
>>> f"He said his name is {name!r}."
"He said his name is 'Fred'."
>>> f"He said his name is {repr(name)}." # repr() is equivalent to !r
"He said his name is 'Fred'."
>>> width = 10
>>> precision = 4
>>> value = decimal.Decimal("12.34567")
>>> f"result: {value:{width}.{precision}}" # nested fields
'result: 12.35'
>>> today = datetime(year=2017, month=1, day=27)
>>> f"{today:%B %d, %Y}" # using date format specifier
'January 27, 2017'
>>> number = 1024
>>> f"{number:#0x}" # using integer format specifier
'0x400'
A consequence of sharing the same syntax as regular string literals is
that characters in the replacement fields must not conflict with the
quoting used in the outer formatted string literal::
f"abc {a["x"]} def" # error: outer string literal ended prematurely
f"abc {a['x']} def" # workaround: use different quoting
Backslashes are not allowed in format expressions and will raise
an error::
f"newline: {ord('\n')}" # raises SyntaxError
To include a value in which a backslash escape is required, create
a temporary variable.
>>> newline = ord('\n')
>>> f"newline: {newline}"
'newline: 10'
Formatted string literals cannot be used as docstrings, even if they do not
include expressions.
::
>>> def foo():
... f"Not a docstring"
...
>>> foo.__doc__ is None
True
See also :pep:`498` for the proposal that added formatted string literals,
and :meth:`str.format`, which uses a related format string mechanism.
.. _numbers:
Numeric literals
----------------
.. index:: number, numeric literal, integer literal
floating point literal, hexadecimal literal
octal literal, binary literal, decimal literal, imaginary literal, complex literal
There are three types of numeric literals: integers, floating point numbers, and
imaginary numbers. There are no complex literals (complex numbers can be formed
by adding a real number and an imaginary number).
Note that numeric literals do not include a sign; a phrase like ``-1`` is
actually an expression composed of the unary operator '``-``' and the literal
``1``.
.. index::
single: 0b; integer literal
single: 0o; integer literal
single: 0x; integer literal
single: _ (underscore); in numeric literal
.. _integers:
Integer literals
----------------
Integer literals are described by the following lexical definitions:
.. productionlist::
integer: `decinteger` | `bininteger` | `octinteger` | `hexinteger`
decinteger: `nonzerodigit` (["_"] `digit`)* | "0"+ (["_"] "0")*
bininteger: "0" ("b" | "B") (["_"] `bindigit`)+
octinteger: "0" ("o" | "O") (["_"] `octdigit`)+
hexinteger: "0" ("x" | "X") (["_"] `hexdigit`)+
nonzerodigit: "1"..."9"
digit: "0"..."9"
bindigit: "0" | "1"
octdigit: "0"..."7"
hexdigit: `digit` | "a"..."f" | "A"..."F"
There is no limit for the length of integer literals apart from what can be
stored in available memory.
Underscores are ignored for determining the numeric value of the literal. They
can be used to group digits for enhanced readability. One underscore can occur
between digits, and after base specifiers like ``0x``.
Note that leading zeros in a non-zero decimal number are not allowed. This is
for disambiguation with C-style octal literals, which Python used before version
3.0.
Some examples of integer literals::
7 2147483647 0o177 0b100110111
3 79228162514264337593543950336 0o377 0xdeadbeef
100_000_000_000 0b_1110_0101
.. versionchanged:: 3.6
Underscores are now allowed for grouping purposes in literals.
.. index::
single: . (dot); in numeric literal
single: e; in numeric literal
single: _ (underscore); in numeric literal
.. _floating:
Floating point literals
-----------------------
Floating point literals are described by the following lexical definitions:
.. productionlist::
floatnumber: `pointfloat` | `exponentfloat`
pointfloat: [`digitpart`] `fraction` | `digitpart` "."
exponentfloat: (`digitpart` | `pointfloat`) `exponent`
digitpart: `digit` (["_"] `digit`)*
fraction: "." `digitpart`
exponent: ("e" | "E") ["+" | "-"] `digitpart`
Note that the integer and exponent parts are always interpreted using radix 10.
For example, ``077e010`` is legal, and denotes the same number as ``77e10``. The
allowed range of floating point literals is implementation-dependent. As in
integer literals, underscores are supported for digit grouping.
Some examples of floating point literals::
3.14 10. .001 1e100 3.14e-10 0e0 3.14_15_93
.. versionchanged:: 3.6
Underscores are now allowed for grouping purposes in literals.
.. index::
single: j; in numeric literal
.. _imaginary:
Imaginary literals
------------------
Imaginary literals are described by the following lexical definitions:
.. productionlist::
imagnumber: (`floatnumber` | `digitpart`) ("j" | "J")
An imaginary literal yields a complex number with a real part of 0.0. Complex
numbers are represented as a pair of floating point numbers and have the same
restrictions on their range. To create a complex number with a nonzero real
part, add a floating point number to it, e.g., ``(3+4j)``. Some examples of
imaginary literals::
3.14j 10.j 10j .001j 1e100j 3.14e-10j 3.14_15_93j
.. _operators:
Operators
=========
.. index:: single: operators
The following tokens are operators:
.. code-block:: none
+ - * ** / // % @
<< >> & | ^ ~
< > <= >= == !=
.. _delimiters:
Delimiters
==========
.. index:: single: delimiters
The following tokens serve as delimiters in the grammar:
.. code-block:: none
( ) [ ] { }
, : . ; @ = ->
+= -= *= /= //= %= @=
&= |= ^= >>= <<= **=
The period can also occur in floating-point and imaginary literals. A sequence
of three periods has a special meaning as an ellipsis literal. The second half
of the list, the augmented assignment operators, serve lexically as delimiters,
but also perform an operation.
The following printing ASCII characters have special meaning as part of other
tokens or are otherwise significant to the lexical analyzer:
.. code-block:: none
' " # \
The following printing ASCII characters are not used in Python. Their
occurrence outside string literals and comments is an unconditional error:
.. code-block:: none
$ ? `
.. rubric:: Footnotes
.. [#] http://www.unicode.org/Public/9.0.0/ucd/NameAliases.txt

1004
third_party/python/Doc/reference/simple_stmts.rst vendored Normal file
View file

File diff suppressed because it is too large Load diff

107
third_party/python/Doc/reference/toplevel_components.rst vendored Normal file
View file

@ -0,0 +1,107 @@
.. _top-level:
********************
Top-level components
********************
.. index:: single: interpreter
The Python interpreter can get its input from a number of sources: from a script
passed to it as standard input or as program argument, typed in interactively,
from a module source file, etc. This chapter gives the syntax used in these
cases.
.. _programs:
Complete Python programs
========================
.. index:: single: program
.. index::
module: sys
module: __main__
module: builtins
While a language specification need not prescribe how the language interpreter
is invoked, it is useful to have a notion of a complete Python program. A
complete Python program is executed in a minimally initialized environment: all
built-in and standard modules are available, but none have been initialized,
except for :mod:`sys` (various system services), :mod:`builtins` (built-in
functions, exceptions and ``None``) and :mod:`__main__`. The latter is used to
provide the local and global namespace for execution of the complete program.
The syntax for a complete Python program is that for file input, described in
the next section.
.. index::
single: interactive mode
module: __main__
The interpreter may also be invoked in interactive mode; in this case, it does
not read and execute a complete program but reads and executes one statement
(possibly compound) at a time. The initial environment is identical to that of
a complete program; each statement is executed in the namespace of
:mod:`__main__`.
.. index::
single: UNIX
single: Windows
single: command line
single: standard input
A complete program can be passed to the interpreter
in three forms: with the :option:`-c` *string* command line option, as a file
passed as the first command line argument, or as standard input. If the file
or standard input is a tty device, the interpreter enters interactive mode;
otherwise, it executes the file as a complete program.
.. _file-input:
File input
==========
All input read from non-interactive files has the same form:
.. productionlist::
file_input: (NEWLINE | `statement`)*
This syntax is used in the following situations:
* when parsing a complete Python program (from a file or from a string);
* when parsing a module;
* when parsing a string passed to the :func:`exec` function;
.. _interactive:
Interactive input
=================
Input in interactive mode is parsed using the following grammar:
.. productionlist::
interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE
Note that a (top-level) compound statement must be followed by a blank line in
interactive mode; this is needed to help the parser detect the end of the input.
.. _expression-input:
Expression input
================
.. index:: single: input
.. index:: builtin: eval
:func:`eval` is used for expression input. It ignores leading whitespace. The
string argument to :func:`eval` must have the following form:
.. productionlist::
eval_input: `expression_list` NEWLINE*