interpolation. This means values can be preprocessed before returning them
from ``get()`` calls.
+.. index:: single: %; interpolation in configuration files
+
.. class:: BasicInterpolation()
The default implementation used by :class:`ConfigParser`. It enables
``%(my_dir)s/Pictures`` as the value of ``my_pictures`` and
``%(home_dir)s/lumberjack`` as the value of ``my_dir``.
+.. index:: single: $; interpolation in configuration files
+
.. class:: ExtendedInterpolation()
An alternative handler for interpolation which implements a more advanced
See :exc:`NotImplementedError` for details on when to use it.
+.. index:: single: ...; ellipsis literal
.. data:: Ellipsis
- The same as the ellipsis literal "...". Special value used mostly in conjunction
+ The same as the ellipsis literal "``...``". Special value used mostly in conjunction
with extended slicing syntax for user-defined container data types.
The UTC timezone, ``timezone(timedelta(0))``.
+.. index::
+ single: %; datetime format
+
.. _strftime-strptime-behavior:
:meth:`strftime` and :meth:`strptime` Behavior
NO!!!
>>>
+.. index::
+ single: >>>; interpreter prompt
+ single: ...; interpreter prompt
+
Any expected output must immediately follow the final ``'>>> '`` or ``'... '``
line containing the code, and the expected output (if any) extends to the next
``'>>> '`` or all-whitespace line.
to test a :exc:`SyntaxError` that omits the traceback header, you will need to
manually add the traceback header line to your test example.
+.. index:: single: ^; caret
+
* For some :exc:`SyntaxError`\ s, Python displays the character position of the
syntax error, using a ``^`` marker::
option will probably go away, but not for several years.
+.. index:: single: <BLANKLINE>
.. data:: DONT_ACCEPT_BLANKLINE
By default, if an expected output block contains a line containing only the
your source.
+.. index:: single: ...; in doctests
.. data:: ELLIPSIS
When specified, an ellipsis marker (``...``) in the expected output can match
MY_FLAG = register_optionflag('MY_FLAG')
+.. index::
+ single: #; in doctests
+ single: +; in doctests
+ single: -; in doctests
.. _doctest-directives:
Directives
*domain*, which is returned.
+.. index:: single: _; gettext
.. function:: gettext(message)
Return the localized translation of *message*, based on the current global
Accepts a :term:`path-like object`.
+.. index:: single: ~; home directory expansion
+
.. function:: expanduser(path)
On Unix and Windows, return the argument with an initial component of ``~`` or
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
+.. index::
+ single: $; environment variables expansion
+ single: %; environment variables expansion (Windows)
.. function:: expandvars(path)
Higher-level operations on pathnames are defined in the :mod:`os.path` module.
+.. index:: single: .; in pathnames
.. data:: curdir
The constant string used by the operating system to refer to the current
:mod:`os.path`.
+.. index:: single: ..; in pathnames
.. data:: pardir
The constant string used by the operating system to refer to the parent
:mod:`os.path`.
+.. index:: single: /; in pathnames
+.. index:: single: \; in pathnames (Windows)
.. data:: sep
The character used by the operating system to separate pathname components.
useful. Also available via :mod:`os.path`.
+.. index:: single: /; in pathnames
.. data:: altsep
An alternative character used by the operating system to separate pathname
:mod:`os.path`.
+.. index:: single: .; in pathnames
.. data:: extsep
The character which separates the base filename from the extension; for example,
the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`.
+.. index:: single: :; path separator (POSIX)
.. data:: pathsep
The character conventionally used by the operating system to separate search
The special characters are:
+.. index:: single: .; in regular expressions
+
``.``
(Dot.) In the default mode, this matches any character except a newline. If
the :const:`DOTALL` flag has been specified, this matches any character
including a newline.
+.. index:: single: ^; in regular expressions
+
``^``
(Caret.) Matches the start of the string, and in :const:`MULTILINE` mode also
matches immediately after each newline.
+.. index:: single: $; in regular expressions
+
``$``
Matches the end of the string or just before the newline at the end of the
string, and in :const:`MULTILINE` mode also matches before a newline. ``foo``
a single ``$`` in ``'foo\n'`` will find two (empty) matches: one just before
the newline, and one at the end of the string.
+.. index:: single: *; in regular expressions
+
``*``
Causes the resulting RE to match 0 or more repetitions of the preceding RE, as
many repetitions as are possible. ``ab*`` will match 'a', 'ab', or 'a' followed
by any number of 'b's.
+.. index:: single: +; in regular expressions
+
``+``
Causes the resulting RE to match 1 or more repetitions of the preceding RE.
``ab+`` will match 'a' followed by any non-zero number of 'b's; it will not
match just 'a'.
+.. index:: single: ?; in regular expressions
+
``?``
Causes the resulting RE to match 0 or 1 repetitions of the preceding RE.
``ab?`` will match either 'a' or 'ab'.
+.. index::
+ single: *?; in regular expressions
+ single: +?; in regular expressions
+ single: ??; in regular expressions
+
``*?``, ``+?``, ``??``
The ``'*'``, ``'+'``, and ``'?'`` qualifiers are all :dfn:`greedy`; they match
as much text as possible. Sometimes this behaviour isn't desired; if the RE
characters as possible will be matched. Using the RE ``<.*?>`` will match
only ``'<a>'``.
+.. index::
+ single: {; in regular expressions
+ single: }; in regular expressions
+
``{m}``
Specifies that exactly *m* copies of the previous RE should be matched; fewer
matches cause the entire RE not to match. For example, ``a{6}`` will match
6-character string ``'aaaaaa'``, ``a{3,5}`` will match 5 ``'a'`` characters,
while ``a{3,5}?`` will only match 3 characters.
+.. index:: single: \; in regular expressions
+
``\``
Either escapes special characters (permitting you to match characters like
``'*'``, ``'?'``, and so forth), or signals a special sequence; special
is complicated and hard to understand, so it's highly recommended that you use
raw strings for all but the simplest expressions.
+.. index::
+ single: [; in regular expressions
+ single: ]; in regular expressions
+
``[]``
Used to indicate a set of characters. In a set:
* Characters can be listed individually, e.g. ``[amk]`` will match ``'a'``,
``'m'``, or ``'k'``.
+ .. index:: single: -; in regular expressions
+
* Ranges of characters can be indicated by giving two characters and separating
them by a ``'-'``, for example ``[a-z]`` will match any lowercase ASCII letter,
``[0-5][0-9]`` will match all the two-digits numbers from ``00`` to ``59``, and
``[(+*)]`` will match any of the literal characters ``'('``, ``'+'``,
``'*'``, or ``')'``.
+ .. index:: single: \; in regular expressions
+
* Character classes such as ``\w`` or ``\S`` (defined below) are also accepted
inside a set, although the characters they match depends on whether
:const:`ASCII` or :const:`LOCALE` mode is in force.
+ .. index:: single: ^; in regular expressions
+
* Characters that are not within a range can be matched by :dfn:`complementing`
the set. If the first character of the set is ``'^'``, all the characters
that are *not* in the set will be matched. For example, ``[^5]`` will match
place it at the beginning of the set. For example, both ``[()[\]{}]`` and
``[]()[{}]`` will both match a parenthesis.
+ .. .. index:: single: --; in regular expressions
+ .. .. index:: single: &&; in regular expressions
+ .. .. index:: single: ~~; in regular expressions
+ .. .. index:: single: ||; in regular expressions
+
* Support of nested sets and set operations as in `Unicode Technical
Standard #18`_ might be added in the future. This would change the
syntax, so to facilitate this change a :exc:`FutureWarning` will be raised
:exc:`FutureWarning` is raised if a character set contains constructs
that will change semantically in the future.
+.. index:: single: |; in regular expressions
+
``|``
``A|B``, where *A* and *B* can be arbitrary REs, creates a regular expression that
will match either *A* or *B*. An arbitrary number of REs can be separated by the
greedy. To match a literal ``'|'``, use ``\|``, or enclose it inside a
character class, as in ``[|]``.
+.. index::
+ single: (; in regular expressions
+ single: ); in regular expressions
+
``(...)``
Matches whatever regular expression is inside the parentheses, and indicates the
start and end of a group; the contents of a group can be retrieved after a match
special sequence, described below. To match the literals ``'('`` or ``')'``,
use ``\(`` or ``\)``, or enclose them inside a character class: ``[(]``, ``[)]``.
+.. index:: single: (?; in regular expressions
+
``(?...)``
This is an extension notation (a ``'?'`` following a ``'('`` is not meaningful
otherwise). The first character after the ``'?'`` determines what the meaning
:func:`re.compile` function. Flags should be used first in the
expression string.
+.. index:: single: (?:; in regular expressions
+
``(?:...)``
A non-capturing version of regular parentheses. Matches whatever regular
expression is inside the parentheses, but the substring matched by the group
.. versionchanged:: 3.7
The letters ``'a'``, ``'L'`` and ``'u'`` also can be used in a group.
+.. index:: single: (?P<; in regular expressions
+
``(?P<name>...)``
Similar to regular parentheses, but the substring matched by the group is
accessible via the symbolic group name *name*. Group names must be valid
| | * ``\1`` |
+---------------------------------------+----------------------------------+
+.. index:: single: (?P=; in regular expressions
+
``(?P=name)``
A backreference to a named group; it matches whatever text was matched by the
earlier group named *name*.
+.. index:: single: (?#; in regular expressions
+
``(?#...)``
A comment; the contents of the parentheses are simply ignored.
called a :dfn:`lookahead assertion`. For example, ``Isaac (?=Asimov)`` will match
``'Isaac '`` only if it's followed by ``'Asimov'``.
+.. index:: single: (?!; in regular expressions
+
``(?!...)``
Matches if ``...`` doesn't match next. This is a :dfn:`negative lookahead assertion`.
For example, ``Isaac (?!Asimov)`` will match ``'Isaac '`` only if it's *not*
followed by ``'Asimov'``.
+.. index:: single: (?<=; in regular expressions
+
``(?<=...)``
Matches if the current position in the string is preceded by a match for ``...``
that ends at the current position. This is called a :dfn:`positive lookbehind
.. versionchanged:: 3.5
Added support for group references of fixed length.
+.. index:: single: (?<!; in regular expressions
+
``(?<!...)``
Matches if the current position in the string is not preceded by a match for
``...``. This is called a :dfn:`negative lookbehind assertion`. Similar to
resulting RE will match the second character. For example, ``\$`` matches the
character ``'$'``.
+.. index:: single: \; in regular expressions
+
``\number``
Matches the contents of the group of the same number. Groups are numbered
starting from 1. For example, ``(.+) \1`` matches ``'the the'`` or ``'55 55'``,
``'['`` and ``']'`` of a character class, all numeric escapes are treated as
characters.
+.. index:: single: \A; in regular expressions
+
``\A``
Matches only at the start of the string.
+.. index:: single: \b; in regular expressions
+
``\b``
Matches the empty string, but only at the beginning or end of a word.
A word is defined as a sequence of word characters. Note that formally,
Inside a character range, ``\b`` represents the backspace character, for
compatibility with Python's string literals.
+.. index:: single: \B; in regular expressions
+
``\B``
Matches the empty string, but only when it is *not* at the beginning or end
of a word. This means that ``r'py\B'`` matches ``'python'``, ``'py3'``,
be changed by using the :const:`ASCII` flag. Word boundaries are
determined by the current locale if the :const:`LOCALE` flag is used.
+.. index:: single: \d; in regular expressions
+
``\d``
For Unicode (str) patterns:
Matches any Unicode decimal digit (that is, any character in
For 8-bit (bytes) patterns:
Matches any decimal digit; this is equivalent to ``[0-9]``.
+.. index:: single: \D; in regular expressions
+
``\D``
Matches any character which is not a decimal digit. This is
the opposite of ``\d``. If the :const:`ASCII` flag is used this
becomes the equivalent of ``[^0-9]``.
+.. index:: single: \s; in regular expressions
+
``\s``
For Unicode (str) patterns:
Matches Unicode whitespace characters (which includes
Matches characters considered whitespace in the ASCII character set;
this is equivalent to ``[ \t\n\r\f\v]``.
+.. index:: single: \S; in regular expressions
+
``\S``
Matches any character which is not a whitespace character. This is
the opposite of ``\s``. If the :const:`ASCII` flag is used this
becomes the equivalent of ``[^ \t\n\r\f\v]``.
+.. index:: single: \w; in regular expressions
+
``\w``
For Unicode (str) patterns:
Matches Unicode word characters; this includes most characters
used, matches characters considered alphanumeric in the current locale
and the underscore.
+.. index:: single: \W; in regular expressions
+
``\W``
Matches any character which is not a word character. This is
the opposite of ``\w``. If the :const:`ASCII` flag is used this
used, matches characters considered alphanumeric in the current locale
and the underscore.
+.. index:: single: \Z; in regular expressions
+
``\Z``
Matches only at the end of the string.
+.. index::
+ single: \a; in regular expressions
+ single: \b; in regular expressions
+ single: \f; in regular expressions
+ single: \n; in regular expressions
+ single: \N; in regular expressions
+ single: \r; in regular expressions
+ single: \t; in regular expressions
+ single: \u; in regular expressions
+ single: \U; in regular expressions
+ single: \v; in regular expressions
+ single: \x; in regular expressions
+ single: \\; in regular expressions
+
Most of the standard escapes supported by Python string literals are also
accepted by the regular expression parser::
.. data:: X
VERBOSE
+ .. index:: single: #; in regular expressions
+
This flag allows you to write regular expressions that look nicer and are
more readable by allowing you to visually separate logical sections of the
pattern and add comments. Whitespace within the pattern is ignored, except
when not adjacent to a previous empty match, so ``sub('x*', '-', 'abxd')`` returns
``'-a-b--d-'``.
+ .. index:: single: \g; in regular expressions
+
In string-type *repl* arguments, in addition to the character escapes and
backreferences described above,
``\g<name>`` will use the substring matched by the group named ``name``, as
(case-insensitive), the system-level prefixes will still also be
searched for site-packages; otherwise they won't.
+.. index::
+ single: #; comment
+ statement: import
+
A path configuration file is a file whose name has the form :file:`{name}.pth`
and exists in one of the four directories mentioned above; its contents are
additional items (one per line) to be added to ``sys.path``. Non-existing items
builtin: int
builtin: float
builtin: complex
- operator: +
- operator: -
+ single: operator; +
+ single: +; unary operator
+ single: +; binary operator
+ single: operator; -
+ single: -; unary operator
+ single: -; binary operator
operator: *
operator: /
operator: //
single: string; interpolation, printf
single: printf-style formatting
single: sprintf-style formatting
- single: % formatting
- single: % interpolation
+ single: %; printf-style formatting
.. note::
#. The ``'%'`` character, which marks the start of the specifier.
+.. index::
+ single: (; in printf-style formatting
+ single: ); in printf-style formatting
+
#. Mapping key (optional), consisting of a parenthesised sequence of characters
(for example, ``(somename)``).
#. Conversion flags (optional), which affect the result of some conversion
types.
+.. index:: single: *; in printf-style formatting
+
#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the
actual width is read from the next element of the tuple in *values*, and the
object to convert comes after the minimum field width and optional precision.
+.. index:: single: .; in printf-style formatting
+
#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If
specified as ``'*'`` (an asterisk), the actual precision is read from the next
element of the tuple in *values*, and the value to convert comes after the
The conversion flag characters are:
+.. index::
+ single: #; in printf-style formatting
+ single: -; in printf-style formatting
+ single: +; in printf-style formatting
+ single: space; in printf-style formatting
+
+---------+---------------------------------------------------------------------+
| Flag | Meaning |
+=========+=====================================================================+
----------------------------------
.. index::
- single: formatting, bytes (%)
- single: formatting, bytearray (%)
- single: interpolation, bytes (%)
- single: interpolation, bytearray (%)
+ single: formatting; bytes (%)
+ single: formatting; bytearray (%)
+ single: interpolation; bytes (%)
+ single: interpolation; bytearray (%)
single: bytes; formatting
single: bytearray; formatting
single: bytes; interpolation
single: bytearray; interpolation
single: printf-style formatting
single: sprintf-style formatting
- single: % formatting
- single: % interpolation
+ single: %; printf-style formatting
.. note::
#. The ``'%'`` character, which marks the start of the specifier.
+.. index::
+ single: (; in printf-style formatting
+ single: ); in printf-style formatting
+
#. Mapping key (optional), consisting of a parenthesised sequence of characters
(for example, ``(somename)``).
#. Conversion flags (optional), which affect the result of some conversion
types.
+.. index:: single: *; in printf-style formatting
+
#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the
actual width is read from the next element of the tuple in *values*, and the
object to convert comes after the minimum field width and optional precision.
+.. index:: single: .; in printf-style formatting
+
#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If
specified as ``'*'`` (an asterisk), the actual precision is read from the next
element of the tuple in *values*, and the value to convert comes after the
The conversion flag characters are:
+.. index::
+ single: #; in printf-style formatting
+ single: -; in printf-style formatting
+ single: +; in printf-style formatting
+ single: space; in printf-style formatting
+
+---------+---------------------------------------------------------------------+
| Flag | Meaning |
+=========+=====================================================================+
It is written as ``None``.
+.. index:: single: ...; ellipsis literal
.. _bltin-ellipsis-object:
The Ellipsis Object
related to that of :ref:`formatted string literals <f-strings>`, but
there are differences.
+.. index::
+ single: {; in string formatting
+ single: }; in string formatting
+ single: .; in string formatting
+ single: [; in string formatting
+ single: ]; in string formatting
+ single: !; in string formatting
+ single: :; in string formatting
+
Format strings contain "replacement fields" surrounded by curly braces ``{}``.
Anything that is not contained in braces is considered literal text, which is
copied unchanged to the output. If you need to include a brace character in the
The meaning of the various alignment options is as follows:
+ .. index::
+ single: <; in string formatting
+ single: >; in string formatting
+ single: =; in string formatting
+ single: ^; in string formatting
+
+---------+----------------------------------------------------------+
| Option | Meaning |
+=========+==========================================================+
The *sign* option is only valid for number types, and can be one of the
following:
+ .. index::
+ single: +; in string formatting
+ single: -; in string formatting
+ single: space; in string formatting
+
+---------+----------------------------------------------------------+
| Option | Meaning |
+=========+==========================================================+
+---------+----------------------------------------------------------+
+.. index:: single: #; in string formatting
+
The ``'#'`` option causes the "alternate form" to be used for the
conversion. The alternate form is defined differently for different
types. This option is only valid for integer, float, complex and
only if a digit follows it. In addition, for ``'g'`` and ``'G'``
conversions, trailing zeros are not removed from the result.
+.. index:: single: ,; in string formatting
+
The ``','`` option signals the use of a comma for a thousands separator.
For a locale aware separator, use the ``'n'`` integer presentation type
instead.
.. versionchanged:: 3.1
Added the ``','`` option (see also :pep:`378`).
+.. index:: single: _; in string formatting
+
The ``'_'`` option signals the use of an underscore for a thousands
separator for floating point presentation types and for integer
presentation type ``'d'``. For integer presentation types ``'b'``,
strings for i18n, see the
`flufl.i18n <http://flufli18n.readthedocs.io/en/latest/>`_ package.
+.. index:: single: $; in template strings
+
Template strings support ``$``-based substitutions, using the following rules:
* ``$$`` is an escape; it is replaced with a single ``$``.
order, and properly aligned by skipping pad bytes if necessary (according to the
rules used by the C compiler).
+.. index::
+ single: @; in struct format strings
+ single: =; in struct format strings
+ single: <; in struct format strings
+ single: >; in struct format strings
+ single: !; in struct format strings
+
Alternatively, the first character of the format string can be used to indicate
the byte order, size and alignment of the packed data, according to the
following table:
.. index::
single: interpreter prompts
single: prompts, interpreter
+ single: >>>; interpreter prompt
+ single: ...; interpreter prompt
Strings specifying the primary and secondary prompt of the interpreter. These
are only defined if the interpreter is in interactive mode. Their initial
:pep:`475` for the rationale).
+.. index::
+ single: %; datetime format
+
.. function:: strftime(format[, t])
Convert a tuple or :class:`struct_time` representing a time as returned by
it is 3.
+.. index::
+ single: %; datetime format
+
.. function:: strptime(string[, format])
Parse a string representing a time according to a format. The return value
* if *tb* is not ``None``, it prints a header ``Traceback (most recent
call last):``
+
* it prints the exception *etype* and *value* after the stack trace
+
+ .. index:: single: ^; caret
+
* if *type(value)* is :exc:`SyntaxError` and *value* has the appropriate
format, it prints the line where the syntax error occurred with a caret
indicating the approximate position of the error.
Cause requests to go through a proxy. If *proxies* is given, it must be a
dictionary mapping protocol names to URLs of proxies. The default is to read
the list of proxies from the environment variables
- :envvar:`<protocol>_proxy`. If no proxy environment variables are set, then
+ ``<protocol>_proxy``. If no proxy environment variables are set, then
in a Windows environment proxy settings are obtained from the registry's
Internet Settings section, and in a Mac OS X environment proxy information
is retrieved from the OS X System Configuration Framework.
See :ref:`above <exception-changed>`.
+.. index::
+ single: %; environment variables expansion (Windows)
+
.. function:: ExpandEnvironmentStrings(str)
Expands environment variable placeholders ``%NAME%`` in strings like
.. index::
single: clause
single: suite
+ single: ;
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
statement: if
keyword: elif
keyword: else
- keyword: elif
- keyword: else
+ single: :; compound statement
The :keyword:`if` statement is used for conditional execution:
keyword: else
pair: loop; statement
keyword: else
+ single: :; compound statement
The :keyword:`while` statement is used for repeated execution as long as an
expression is true:
keyword: else
pair: target; list
object: sequence
+ single: :; 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:
statement: try
keyword: except
keyword: finally
-.. index:: keyword: except
+ keyword: else
+ keyword: as
+ single: :; compound statement
The :keyword:`try` statement specifies exception handlers and/or cleanup code
for a group of statements:
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
=============================
.. index::
- statement: with
- single: as; with statement
+ statement: with
+ keyword: as
+ single: as; with statement
+ single: ,; with statement
+ single: :; 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`).
object: function
pair: function; name
pair: name; binding
+ single: (; function definition
+ single: ); function definition
+ single: ,; parameter list
+ single: :; compound statement
A function definition defines a user-defined function object (see section
:ref:`types`):
only when the function is called. [#]_
.. index::
- statement: @
+ single: @; 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
.. index::
triple: default; parameter; value
single: argument; function definition
+ single: =; 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
return penguin
.. index::
- statement: *
- statement: **
+ single: *; 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
"``*identifier``" are keyword-only parameters and may only be passed
used keyword arguments.
-.. index:: pair: function; annotations
+.. index::
+ pair: function; annotations
+ single: ->; function annotations
+ single: :; 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
pair: execution; frame
single: inheritance
single: docstring
+ single: (; class definition
+ single: ); class definition
+ single: ,; expression list
+ single: :; compound statement
A class definition defines a class object (see section :ref:`types`):
Class creation can be customized heavily using :ref:`metaclasses <metaclasses>`.
+.. index::
+ single: @; class definition
+
Classes can also be decorated: just like when decorating functions, ::
@f1(arg)
Ellipsis
- .. index:: object: Ellipsis
+ .. index::
+ object: Ellipsis
+ single: ...; ellipsis literal
This type has a single value. There is a single object with this value. This
object is accessed through the literal ``...`` or the built-in name
^^^^^^^^^^^
.. index::
- single: metaclass
- builtin: type
+ single: metaclass
+ builtin: type
+ single: =; class definition
By default, classes are constructed using :func:`type`. The class body is
executed in a new namespace and the class name is bound locally to the
:dfn:`Names` refer to objects. Names are introduced by name binding operations.
-.. index:: statement: from
+.. index:: single: from; import statement
The following constructs bind names: formal parameters to functions,
:keyword:`import` statements, class and function definitions (these bind the
Parenthesized forms
-------------------
-.. index:: single: parenthesized form
+.. index::
+ single: parenthesized form
+ single: (; tuple display
+ single: ); tuple display
A parenthesized form is an optional expression list enclosed in parentheses:
tuple may or may not yield the same object).
.. index::
- single: comma
+ single: comma; tuple display
pair: tuple; display
+ single: ,; tuple display
Note that tuples are not formed by the parentheses, but rather by use of the
comma operator. The exception is the empty tuple, for which parentheses *are*
* they are computed via a set of looping and filtering instructions, called a
:dfn:`comprehension`.
+.. index::
+ single: for; in comprehensions
+ single: if; in comprehensions
+ single: async for; in comprehensions
+
Common syntax elements for comprehensions are:
.. productionlist::
type, ``yield`` and ``yield from`` expressions are prohibited in the implicitly
nested scope.
+.. index::
+ single: await; in comprehensions
+
Since Python 3.6, in an :keyword:`async def` function, an :keyword:`async for`
clause may be used to iterate over a :term:`asynchronous iterator`.
A comprehension in an :keyword:`async def` function may consist of either a
pair: list; comprehensions
pair: empty; list
object: list
+ single: [; list expression
+ single: ]; list expression
+ single: ,; expression list
A list display is a possibly empty series of expressions enclosed in square
brackets:
Set displays
------------
-.. index:: pair: set; display
- object: set
+.. index::
+ pair: set; display
+ object: set
+ single: {; set expression
+ single: }; set expression
+ single: ,; expression list
A set display is denoted by curly braces and distinguishable from dictionary
displays by the lack of colons separating keys and values:
Dictionary displays
-------------------
-.. index:: pair: dictionary; display
- key, datum, key/datum pair
- object: dictionary
+.. index::
+ pair: dictionary; display
+ key, datum, key/datum pair
+ object: dictionary
+ single: {; dictionary expression
+ single: }; dictionary expression
+ single: :; in dictionary expressions
+ single: ,; in dictionary displays
A dictionary display is a possibly empty series of key/datum pairs enclosed in
curly braces:
that you can specify the same key multiple times in the key/datum list, and the
final dictionary's value for that key will be the last one given.
-.. index:: unpacking; dictionary, **; in dictionary displays
+.. index::
+ unpacking; dictionary
+ single: **; in dictionary displays
A double asterisk ``**`` denotes :dfn:`dictionary unpacking`.
Its operand must be a :term:`mapping`. Each mapping item is added
Generator expressions
---------------------
-.. index:: pair: generator; expression
- object: generator
+.. index::
+ pair: generator; expression
+ object: generator
+ single: (; generator expression
+ single: ); generator expression
A generator expression is a compact generator notation in parentheses:
.. index::
keyword: yield
+ keyword: from
pair: yield; expression
pair: generator; function
the generator-iterator's :meth:`~generator.close` method will be called,
allowing any pending :keyword:`finally` clauses to execute.
+.. index::
+ single: from; yield from expression
+
When ``yield from <expr>`` is used, it treats the supplied expression as
a subiterator. All values produced by that subiterator are passed directly
to the caller of the current generator's methods. Any values passed in with
Attribute references
--------------------
-.. index:: pair: attribute; reference
+.. index::
+ pair: attribute; reference
+ single: .; attribute reference
An attribute reference is a primary followed by a period and a name:
Subscriptions
-------------
-.. index:: single: subscription
+.. index::
+ single: subscription
+ single: [; subscription
+ single: ]; subscription
.. index::
object: sequence
.. index::
single: slicing
single: slice
+ single: :; slicing
+ single: ,; slicing
.. index::
object: sequence
object: callable
single: call
single: argument; call semantics
+ single: (; call
+ single: ); call
+ single: ,; argument list
+ single: =; in function calls
.. _calls:
if that method was called.
+.. index:: keyword: await
.. _await:
Await expression
The power operator
==================
+.. index::
+ pair: power; operation
+ operator: **
+
The power operator binds more tightly than unary operators on its left; it binds
less tightly than unary operators on its right. The syntax is:
.. index::
single: negation
single: minus
+ single: operator; -
+ single: -; unary operator
The unary ``-`` (minus) operator yields the negation of its numeric argument.
-.. index:: single: plus
+.. index::
+ single: plus
+ single: operator; +
+ single: +; unary operator
The unary ``+`` (plus) operator yields its numeric argument unchanged.
-.. index:: single: inversion
-
+.. index::
+ single: inversion
+ operator: ~
The unary ``~`` (invert) operator yields the bitwise inversion of its integer
argument. The bitwise inversion of ``x`` is defined as ``-(x+1)``. It only
: `m_expr` "%" `u_expr`
a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr`
-.. index:: single: multiplication
+.. index::
+ single: multiplication
+ operator: *
The ``*`` (multiplication) operator yields the product of its arguments. The
arguments must either both be numbers, or one argument must be an integer and
.. index::
exception: ZeroDivisionError
single: division
+ operator: /
+ operator: //
The ``/`` (division) and ``//`` (floor division) operators yield the quotient of
their arguments. The numeric arguments are first converted to a common type.
applied to the result. Division by zero raises the :exc:`ZeroDivisionError`
exception.
-.. index:: single: modulo
+.. index::
+ single: modulo
+ operator: %
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
function are not defined for complex numbers. Instead, convert to a floating
point number using the :func:`abs` function if appropriate.
-.. index:: single: addition
+.. index::
+ single: addition
+ single: operator; +
+ single: +; binary operator
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 type and then added together.
In the latter case, the sequences are concatenated.
-.. index:: single: subtraction
+.. index::
+ single: subtraction
+ single: operator; -
+ single: -; binary operator
The ``-`` (subtraction) operator yields the difference of its arguments. The
numeric arguments are first converted to a common type.
Shifting operations
===================
-.. index:: pair: shifting; operation
+.. index::
+ pair: shifting; operation
+ operator: <<
+ operator: >>
The shifting operations have lower priority than the arithmetic operations:
xor_expr: `and_expr` | `xor_expr` "^" `and_expr`
or_expr: `xor_expr` | `or_expr` "|" `xor_expr`
-.. index:: pair: bitwise; and
+.. index::
+ pair: bitwise; and
+ operator: &
The ``&`` operator yields the bitwise AND of its arguments, which must be
integers.
.. index::
pair: bitwise; xor
pair: exclusive; or
+ operator: ^
The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which
must be integers.
.. index::
pair: bitwise; or
pair: inclusive; or
+ operator: |
The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which
must be integers.
Comparisons
===========
-.. index:: single: comparison
-
-.. index:: pair: C; language
+.. index::
+ single: comparison
+ pair: C; language
+ operator: <
+ operator: >
+ operator: <=
+ operator: >=
+ operator: ==
+ operator: !=
Unlike C, all comparison operations in Python have the same priority, which is
lower than that of any arithmetic, shifting or bitwise operation. Also unlike
.. index::
pair: conditional; expression
pair: ternary; operator
+ single: if; conditional expression
+ single: else; conditional expression
.. productionlist::
conditional_expression: `or_test` ["if" `or_test` "else" `expression`]
pair: lambda; expression
pair: lambda; form
pair: anonymous; function
+ single: :; lambda expression
.. productionlist::
- lambda_expr: "lambda" [`parameter_list`]: `expression`
- lambda_expr_nocond: "lambda" [`parameter_list`]: `expression_nocond`
+ lambda_expr: "lambda" [`parameter_list`] ":" `expression`
+ lambda_expr_nocond: "lambda" [`parameter_list`] ":" `expression_nocond`
Lambda expressions (sometimes called lambda forms) are used to create anonymous
functions. The expression ``lambda parameters: expression`` yields a function
Expression lists
================
-.. index:: pair: expression; list
+.. index::
+ pair: expression; list
+ single: comma; expression list
+ single: ,; expression list
.. productionlist::
expression_list: `expression` ("," `expression`)* [","]
Operator precedence
===================
-.. index:: pair: operator; precedence
+.. index::
+ pair: operator; precedence
The following table summarizes the operator precedence in Python, from lowest
precedence (least binding) to highest precedence (most binding). Operators in
+-----------------------------------------------+-------------------------------------+
| ``**`` | Exponentiation [#]_ |
+-----------------------------------------------+-------------------------------------+
-| ``await`` ``x`` | Await expression |
+| :keyword:`await` ``x`` | Await expression |
+-----------------------------------------------+-------------------------------------+
| ``x[index]``, ``x[index:index]``, | Subscription, slicing, |
| ``x(arguments...)``, ``x.attribute`` | call, attribute reference |
------------------
.. index::
- pair:: package; namespace
- pair:: package; portion
+ pair: package; namespace
+ pair: package; portion
A namespace package is a composite of various :term:`portions <portion>`,
where each portion contributes a subpackage to the parent package. Portions
--------
.. index:: comment, hash character
+ single: #; 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
---------------------
.. index:: source character set, encoding declarations (source file)
+ single: #; 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
assert del global not with
async elif if or yield
+.. index::
+ single: _, identifiers
+ single: __, identifiers
.. _id-classes:
Reserved classes of identifiers
Literals are notations for constant values of some built-in types.
+.. index:: string literal, bytes literal, ASCII
+ single: '; string literal
+ single: "; string literal
+ single: u'; string literal
+ single: u"; string literal
.. _strings:
String and Bytes literals
-------------------------
-.. index:: string literal, bytes literal, ASCII
-
String literals are described by the following lexical definitions:
.. productionlist::
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
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'``
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
"quote" is the character used to open the literal, i.e. either ``'`` or ``"``.)
.. index:: physical line, escape sequence, Standard C, C
+ single: \; 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
single: string; formatted literal
single: string; interpolated literal
single: f-string
+ single: {; in formatted string literal
+ single: }; in formatted string literal
+ single: !; in formatted string literal
+ single: :; in formatted string literal
.. _f-strings:
Formatted string literals
``1``.
+.. index::
+ single: 0b; integer literal
+ single: 0o; integer literal
+ single: 0x; integer literal
+ single: _; in numeric literal
+
.. _integers:
Integer literals
Underscores are now allowed for grouping purposes in literals.
+.. index::
+ single: .; in numeric literal
+ single: e; in numeric literal
+ single: _; in numeric literal
.. _floating:
Floating point literals
Underscores are now allowed for grouping purposes in literals.
+.. index::
+ single: j; in numeric literal
.. _imaginary:
Imaginary literals
given with the definition of the object types (see section :ref:`types`).
.. index:: triple: target; list; assignment
+ single: ,; in target list
+ single: *; in assignment target list
+ single: [; in assignment target list
+ single: ]; in assignment target list
+ single: (; in assignment target list
+ single: ); in assignment target list
Assignment of an object to a target list, optionally enclosed in parentheses or
square brackets, is recursively defined as follows.
.. index::
pair: annotated; assignment
single: statement; assignment, annotated
+ single: :; annotated variable
Annotation assignment is the combination, in a single statement,
of a variable or attribute annotation and an optional assignment statement:
.. index::
statement: assert
pair: debugging; assertions
+ single: ,; expression list
Assert statements are a convenient way to insert debugging assertions into a
program:
single: module; importing
pair: name; binding
keyword: from
+ keyword: as
+ exception: ImportError
+ single: ,; import statement
.. productionlist::
import_stmt: "import" `module` ["as" `identifier`] ("," `module` ["as" `identifier`])*
.. index::
pair: name; binding
- keyword: from
- exception: ImportError
+ single: from; import statement
The :keyword:`from` form uses a slightly more complex process:
from foo.bar import baz # foo.bar.baz imported and bound as baz
from foo import attr # foo imported and foo.attr bound as attr
+.. index:: single: *; import statement
+
If the list of identifiers is replaced by a star (``'*'``), all public
names defined in the module are bound in the local namespace for the scope
where the :keyword:`import` statement occurs.
Future statements
-----------------
-.. index:: pair: future; statement
+.. index::
+ pair: future; statement
+ single: __future__; future statement
A :dfn:`future statement` is a directive to the compiler that a particular
module should be compiled using syntax or semantics that will be available in a
.. index::
statement: global
triple: global; name; binding
+ single: ,; identifier list
.. productionlist::
global_stmt: "global" `identifier` ("," `identifier`)*
=================================
.. index:: statement: nonlocal
+ single: ,; identifier list
.. productionlist::
nonlocal_stmt: "nonlocal" `identifier` ("," `identifier`)*
------------------------
.. index::
- statement: *
+ single: *; in function calls
Finally, the least frequently used option is to specify that a function can be
called with an arbitrary number of arguments. These arguments will be wrapped
[3, 4, 5]
.. index::
- statement: **
+ single: **; in function calls
In the same fashion, dictionaries can deliver keyword arguments with the ``**``\
-operator::
.. sectionauthor:: Zachary Ware <zachary.ware@gmail.com>
.. index::
pair: function; annotations
- single: -> (return annotation assignment)
+ single: ->; function annotations
+ single: :; function annotations
:ref:`Function annotations <function>` are completely optional metadata
information about the types used by user-defined functions (see :pep:`3107` and
line by itself in an example means you must type a blank line; this is used to
end a multi-line command.
+.. index:: single: #; comment
+
Many of the examples in this manual, even those entered at the interactive
prompt, include comments. Comments in Python start with the hash character,
``#``, and extend to the end of the physical line. A comment may appear at the
projects / python / commitdiff