[Python-checkins] [3.7] bpo-35054: Add more index entries for symbols. (GH-10064). (GH-10120)
Serhiy Storchaka
webhook-mailer at python.org
Fri Oct 26 04:18:55 EDT 2018
https://github.com/python/cpython/commit/9a75b8470a2e0de5406edcabba140f023c99c6a9
commit: 9a75b8470a2e0de5406edcabba140f023c99c6a9
branch: 3.7
author: Serhiy Storchaka <storchaka at gmail.com>
committer: GitHub <noreply at github.com>
date: 2018-10-26T11:18:42+03:00
summary:
[3.7] bpo-35054: Add more index entries for symbols. (GH-10064). (GH-10120)
(cherry picked from commit ddb961d2abe5d5fde76d85b21a77e4e91e0043ad)
Co-authored-by: Serhiy Storchaka <storchaka at gmail.com>
files:
M Doc/library/configparser.rst
M Doc/library/constants.rst
M Doc/library/datetime.rst
M Doc/library/doctest.rst
M Doc/library/gettext.rst
M Doc/library/os.path.rst
M Doc/library/os.rst
M Doc/library/re.rst
M Doc/library/site.rst
M Doc/library/stdtypes.rst
M Doc/library/string.rst
M Doc/library/struct.rst
M Doc/library/sys.rst
M Doc/library/time.rst
M Doc/library/traceback.rst
M Doc/library/urllib.request.rst
M Doc/library/winreg.rst
M Doc/reference/compound_stmts.rst
M Doc/reference/datamodel.rst
M Doc/reference/executionmodel.rst
M Doc/reference/expressions.rst
M Doc/reference/import.rst
M Doc/reference/lexical_analysis.rst
M Doc/reference/simple_stmts.rst
M Doc/tutorial/controlflow.rst
M Doc/tutorial/introduction.rst
diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index 4430e39b7c5b..1c479bf9080a 100644
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -295,6 +295,8 @@ On top of the core functionality, :class:`ConfigParser` supports
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
@@ -323,6 +325,8 @@ from ``get()`` calls.
``%(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
diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst
index 78f161963698..634ff00035b3 100644
--- a/Doc/library/constants.rst
+++ b/Doc/library/constants.rst
@@ -51,10 +51,11 @@ A small number of constants live in the built-in namespace. They are:
See :exc:`NotImplementedError` for details on when to use it.
+.. index:: single: ...; ellipsis literal
.. data:: Ellipsis
- The same as ``...``. Special value used mostly in conjunction with extended
- slicing syntax for user-defined container data types.
+ The same as the ellipsis literal "``...``". Special value used mostly in conjunction
+ with extended slicing syntax for user-defined container data types.
.. data:: __debug__
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 7a276b139f5e..e7a0fdbc67a3 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -1999,6 +1999,9 @@ Class attributes:
The UTC timezone, ``timezone(timedelta(0))``.
+.. index::
+ single: %; datetime format
+
.. _strftime-strptime-behavior:
:meth:`strftime` and :meth:`strptime` Behavior
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index 587a0a09a947..d463356e7adc 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -321,6 +321,10 @@ but doctest isn't trying to do an exact emulation of any specific Python shell.
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.
@@ -481,6 +485,8 @@ Some details you should read once, but won't need to remember:
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::
@@ -532,6 +538,7 @@ doctest decides whether actual output matches an example's expected output:
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
@@ -551,6 +558,7 @@ doctest decides whether actual output matches an example's expected output:
your source.
+.. index:: single: ...; in doctests
.. data:: ELLIPSIS
When specified, an ellipsis marker (``...``) in the expected output can match
@@ -686,6 +694,10 @@ useful unless you intend to extend :mod:`doctest` internals via subclassing:
MY_FLAG = register_optionflag('MY_FLAG')
+.. index::
+ single: #; in doctests
+ single: +; in doctests
+ single: -; in doctests
.. _doctest-directives:
Directives
diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst
index 407853c2d7ef..93748a2e4726 100644
--- a/Doc/library/gettext.rst
+++ b/Doc/library/gettext.rst
@@ -61,6 +61,7 @@ class-based API instead.
*domain*, which is returned.
+.. index:: single: _; gettext
.. function:: gettext(message)
Return the localized translation of *message*, based on the current global
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 75e7e5be9121..1f767170b5a5 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -152,6 +152,8 @@ the :mod:`glob` module.)
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
@@ -175,6 +177,9 @@ the :mod:`glob` module.)
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
+.. index::
+ single: $; environment variables expansion
+ single: %; environment variables expansion (Windows)
.. function:: expandvars(path)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 907c6c307fb1..899780d140a1 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -4012,6 +4012,7 @@ are defined for all platforms.
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
@@ -4019,6 +4020,7 @@ Higher-level operations on pathnames are defined in the :mod:`os.path` module.
:mod:`os.path`.
+.. index:: single: ..; in pathnames
.. data:: pardir
The constant string used by the operating system to refer to the parent
@@ -4026,6 +4028,8 @@ Higher-level operations on pathnames are defined in the :mod:`os.path` module.
: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.
@@ -4035,6 +4039,7 @@ Higher-level operations on pathnames are defined in the :mod:`os.path` module.
useful. Also available via :mod:`os.path`.
+.. index:: single: /; in pathnames
.. data:: altsep
An alternative character used by the operating system to separate pathname
@@ -4043,12 +4048,14 @@ Higher-level operations on pathnames are defined in the :mod:`os.path` module.
: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
diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index cc3516acfae7..f25d3d679a23 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -93,15 +93,21 @@ the expression ``(?:a{6})*`` matches any multiple of six ``'a'`` characters.
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``
@@ -111,20 +117,31 @@ The special characters are:
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
@@ -134,6 +151,10 @@ The special characters are:
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
@@ -155,6 +176,8 @@ The special characters are:
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
@@ -168,12 +191,18 @@ The special characters are:
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
@@ -185,10 +214,14 @@ The special characters are:
``[(+*)]`` 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
@@ -200,6 +233,11 @@ The special characters are:
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
@@ -214,6 +252,8 @@ The special characters are:
: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
@@ -225,6 +265,10 @@ The special characters are:
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
@@ -232,6 +276,8 @@ The special characters are:
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
@@ -253,6 +299,8 @@ The special characters are:
: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
@@ -285,6 +333,8 @@ The special characters are:
.. 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
@@ -310,10 +360,14 @@ The special characters are:
| | * ``\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.
@@ -322,11 +376,15 @@ The special characters are:
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
@@ -352,6 +410,8 @@ The special characters are:
.. 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
@@ -373,6 +433,8 @@ If the ordinary character is not an ASCII digit or an ASCII letter, then the
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'``,
@@ -383,9 +445,13 @@ character ``'$'``.
``'['`` 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,
@@ -400,6 +466,8 @@ character ``'$'``.
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'``,
@@ -409,6 +477,8 @@ character ``'$'``.
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
@@ -419,11 +489,15 @@ character ``'$'``.
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
@@ -436,11 +510,15 @@ character ``'$'``.
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
@@ -454,6 +532,8 @@ character ``'$'``.
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
@@ -461,9 +541,25 @@ character ``'$'``.
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::
@@ -620,6 +716,8 @@ form.
.. 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
@@ -776,6 +874,8 @@ form.
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
diff --git a/Doc/library/site.rst b/Doc/library/site.rst
index 5b5ed93a1b7b..e6a2980953d8 100644
--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
@@ -49,6 +49,10 @@ the key "include-system-site-packages" set to anything other than "false"
(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
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index efa0a89490e1..130e58fa7ab9 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -248,8 +248,12 @@ and imaginary parts.
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: //
@@ -2096,8 +2100,7 @@ expression support in the :mod:`re` module).
single: string; interpolation, printf
single: printf-style formatting
single: sprintf-style formatting
- single: % formatting
- single: % interpolation
+ single: %; printf-style formatting
.. note::
@@ -2125,16 +2128,24 @@ components, which must occur in this order:
#. 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
@@ -2158,6 +2169,12 @@ sequential parameter list).
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 |
+=========+=====================================================================+
@@ -3210,18 +3227,17 @@ place, and instead produce new objects.
----------------------------------
.. 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::
@@ -3247,16 +3263,24 @@ components, which must occur in this order:
#. 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
@@ -3280,6 +3304,12 @@ sequential parameter list).
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 |
+=========+=====================================================================+
@@ -4582,6 +4612,7 @@ supports no special operations. There is exactly one null object, named
It is written as ``None``.
+.. index:: single: ...; ellipsis literal
.. _bltin-ellipsis-object:
The Ellipsis Object
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 0fec3df3e3c1..55913f8c07f5 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -192,6 +192,15 @@ subclasses can define their own format string syntax). The syntax is
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
@@ -323,6 +332,12 @@ affect the :func:`format` function.
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 |
+=========+==========================================================+
@@ -349,6 +364,11 @@ meaning in this case.
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 |
+=========+==========================================================+
@@ -363,6 +383,8 @@ following:
+---------+----------------------------------------------------------+
+.. 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
@@ -375,6 +397,8 @@ decimal-point character appears in the result of these conversions
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.
@@ -382,6 +406,8 @@ 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'``,
@@ -668,6 +694,8 @@ formatting facilities in Python. As an example of a library built on template
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 ``$``.
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index f10fbe4fc0df..3b15158f3f8c 100644
--- a/Doc/library/struct.rst
+++ b/Doc/library/struct.rst
@@ -117,6 +117,13 @@ By default, C types are represented in the machine's native format and byte
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:
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 33a7b692ddec..358b11820c62 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1044,6 +1044,8 @@ always available.
.. 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
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index 56f972c9d032..d76e089c23b4 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -369,6 +369,9 @@ Functions
: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
@@ -500,6 +503,9 @@ Functions
it is 3.
+.. index::
+ single: %; datetime format
+
.. function:: strptime(string[, format])
Parse a string representing a time according to a format. The return value
diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index 7ac3cacd3d1c..a21ef8ed9f36 100644
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -44,7 +44,11 @@ The module defines the following functions:
* 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.
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index cbbec0cd8311..982f57f1fe61 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -297,7 +297,7 @@ The following classes are provided:
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.
diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst
index 14f7896f840e..99be47fb4b9c 100644
--- a/Doc/library/winreg.rst
+++ b/Doc/library/winreg.rst
@@ -224,6 +224,9 @@ This module offers the following functions:
See :ref:`above <exception-changed>`.
+.. index::
+ single: %; environment variables expansion (Windows)
+
.. function:: ExpandEnvironmentStrings(str)
Expands environment variable placeholders ``%NAME%`` in strings like
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index c49efa5889f2..812a7de483c6 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -21,6 +21,7 @@ also syntactically compound statements.
.. 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
@@ -84,8 +85,7 @@ The :keyword:`if` statement
statement: if
keyword: elif
keyword: else
- keyword: elif
- keyword: else
+ single: :; compound statement
The :keyword:`if` statement is used for conditional execution:
@@ -111,6 +111,7 @@ The :keyword:`while` statement
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:
@@ -149,6 +150,7 @@ The :keyword:`for` statement
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:
@@ -229,7 +231,9 @@ The :keyword:`try` statement
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:
@@ -263,6 +267,8 @@ 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
@@ -374,8 +380,11 @@ The :keyword:`with` statement
=============================
.. 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`).
@@ -462,6 +471,10 @@ Function definitions
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`):
@@ -491,7 +504,7 @@ The function definition does not execute the function body; this gets executed
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
@@ -514,6 +527,7 @@ except that the original function is not temporarily bound to the name ``func``.
.. 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
@@ -540,8 +554,8 @@ e.g.::
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
@@ -554,7 +568,10 @@ 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
+.. 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
@@ -616,6 +633,10 @@ Class definitions
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`):
@@ -654,6 +675,9 @@ the definition syntax.
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)
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 735ecbf66939..55783506aa64 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -165,7 +165,9 @@ NotImplemented
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
@@ -1831,8 +1833,9 @@ Metaclasses
^^^^^^^^^^^
.. 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
diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst
index d08abdf3343f..5c83181440bc 100644
--- a/Doc/reference/executionmodel.rst
+++ b/Doc/reference/executionmodel.rst
@@ -52,7 +52,7 @@ Binding of names
: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
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 4bacac33ae7b..d210769225d4 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -128,7 +128,10 @@ value.
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:
@@ -146,8 +149,9 @@ immutable, the rules for literals apply (i.e., two occurrences of the empty
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*
@@ -168,6 +172,11 @@ called "displays", each of them in two flavors:
* 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::
@@ -199,6 +208,9 @@ type, ``yield`` and ``yield from`` expressions are prohibited in the implicitly
nested scope (in Python 3.7, such expressions emit :exc:`DeprecationWarning`
when compiled, in Python 3.8+ they will emit :exc:`SyntaxError`).
+.. 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
@@ -228,6 +240,9 @@ List displays
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:
@@ -247,8 +262,12 @@ the list is constructed from the elements resulting from the comprehension.
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:
@@ -271,9 +290,14 @@ dictionary.
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:
@@ -292,7 +316,9 @@ used as a key into the dictionary to store the corresponding datum. This means
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
@@ -322,8 +348,11 @@ prevails.
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:
@@ -379,6 +408,7 @@ Yield expressions
.. index::
keyword: yield
+ keyword: from
pair: yield; expression
pair: generator; function
@@ -444,6 +474,9 @@ finalized (by reaching a zero reference count or by being garbage collected),
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
@@ -723,7 +756,9 @@ syntax is:
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:
@@ -749,7 +784,10 @@ same attribute reference may yield different objects.
Subscriptions
-------------
-.. index:: single: subscription
+.. index::
+ single: subscription
+ single: [; subscription
+ single: ]; subscription
.. index::
object: sequence
@@ -806,6 +844,8 @@ Slicings
.. index::
single: slicing
single: slice
+ single: :; slicing
+ single: ,; slicing
.. index::
object: sequence
@@ -855,6 +895,10 @@ substituting ``None`` for missing expressions.
object: callable
single: call
single: argument; call semantics
+ single: (; call
+ single: ); call
+ single: ,; argument list
+ single: =; in function calls
.. _calls:
@@ -1037,6 +1081,7 @@ a class instance:
if that method was called.
+.. index:: keyword: await
.. _await:
Await expression
@@ -1056,6 +1101,10 @@ Can only be used inside a :term:`coroutine function`.
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:
@@ -1098,15 +1147,21 @@ All unary arithmetic and bitwise operations have the same priority:
.. 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
@@ -1136,7 +1191,9 @@ operators and one for additive operators:
: `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
@@ -1156,6 +1213,8 @@ builtin Python types implement this operator.
.. 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.
@@ -1164,7 +1223,9 @@ integer; the result is that of mathematical division with the 'floor' function
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
@@ -1189,14 +1250,20 @@ The floor division operator, the modulo operator, and the :func:`divmod`
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.
@@ -1207,7 +1274,10 @@ 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:
@@ -1237,7 +1307,9 @@ Each of the three bitwise operations has a different priority level:
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.
@@ -1245,6 +1317,7 @@ integers.
.. index::
pair: bitwise; xor
pair: exclusive; or
+ operator: ^
The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which
must be integers.
@@ -1252,6 +1325,7 @@ 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.
@@ -1262,9 +1336,15 @@ 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
@@ -1582,6 +1662,8 @@ Conditional expressions
.. 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`]
@@ -1608,10 +1690,11 @@ Lambdas
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
@@ -1632,7 +1715,10 @@ annotations.
Expression lists
================
-.. index:: pair: expression; list
+.. index::
+ pair: expression; list
+ single: comma; expression list
+ single: ,; expression list
.. productionlist::
expression_list: `expression` ("," `expression`)* [","]
@@ -1694,7 +1780,8 @@ their suffixes::
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
@@ -1742,7 +1829,7 @@ precedence and have a left-to-right chaining feature as described in the
+-----------------------------------------------+-------------------------------------+
| ``**`` | Exponentiation [#]_ |
+-----------------------------------------------+-------------------------------------+
-| ``await`` ``x`` | Await expression |
+| :keyword:`await` ``x`` | Await expression |
+-----------------------------------------------+-------------------------------------+
| ``x[index]``, ``x[index:index]``, | Subscription, slicing, |
| ``x(arguments...)``, ``x.attribute`` | call, attribute reference |
diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index 44b5b818aa82..7c4f275a4342 100644
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -127,8 +127,8 @@ Namespace packages
------------------
.. 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
diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst
index 84e8c783838b..72da30a3773f 100644
--- a/Doc/reference/lexical_analysis.rst
+++ b/Doc/reference/lexical_analysis.rst
@@ -65,6 +65,7 @@ Comments
--------
.. 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
@@ -78,6 +79,7 @@ Encoding declarations
---------------------
.. 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
@@ -349,6 +351,9 @@ exactly as written here:
assert del global not with
async elif if or yield
+.. index::
+ single: _, identifiers
+ single: __, identifiers
.. _id-classes:
Reserved classes of identifiers
@@ -395,13 +400,16 @@ Literals
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::
@@ -434,6 +442,8 @@ 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
@@ -442,11 +452,19 @@ of three single or double quotes (these are generally referred to as
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'``
@@ -463,6 +481,10 @@ is not supported.
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
@@ -473,6 +495,19 @@ retained), except that three unescaped quotes in a row terminate the literal. (
"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
@@ -601,6 +636,10 @@ and formatted string literals may be concatenated with plain string literals.
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
@@ -735,6 +774,12 @@ 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: _; in numeric literal
+
.. _integers:
Integer literals
@@ -775,6 +820,10 @@ Some examples of 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
@@ -803,6 +852,8 @@ Some examples of floating point literals::
Underscores are now allowed for grouping purposes in literals.
+.. index::
+ single: j; in numeric literal
.. _imaginary:
Imaginary literals
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 9b93601135de..04ed499701c1 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -112,6 +112,12 @@ unacceptable. The rules observed by various types and the exceptions raised are
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.
@@ -321,6 +327,7 @@ Annotated assignment statements
.. 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:
@@ -372,6 +379,7 @@ The :keyword:`assert` statement
.. index::
statement: assert
pair: debugging; assertions
+ single: ,; expression list
Assert statements are a convenient way to insert debugging assertions into a
program:
@@ -713,6 +721,9 @@ The :keyword:`import` statement
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`])*
@@ -762,8 +773,7 @@ available in the local namespace in one of three ways:
.. index::
pair: name; binding
- keyword: from
- exception: ImportError
+ single: from; import statement
The :keyword:`from` form uses a slightly more complex process:
@@ -787,6 +797,8 @@ Examples::
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.
@@ -832,7 +844,9 @@ determine dynamically the modules to be loaded.
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
@@ -919,6 +933,7 @@ The :keyword:`global` statement
.. index::
statement: global
triple: global; name; binding
+ single: ,; identifier list
.. productionlist::
global_stmt: "global" `identifier` ("," `identifier`)*
@@ -963,6 +978,7 @@ The :keyword:`nonlocal` statement
=================================
.. index:: statement: nonlocal
+ single: ,; identifier list
.. productionlist::
nonlocal_stmt: "nonlocal" `identifier` ("," `identifier`)*
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index 4bcdafd73352..f87cd4decd02 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -526,7 +526,7 @@ Arbitrary Argument Lists
------------------------
.. 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
@@ -570,7 +570,7 @@ or tuple::
[3, 4, 5]
.. index::
- statement: **
+ single: **; in function calls
In the same fashion, dictionaries can deliver keyword arguments with the ``**``\
-operator::
@@ -675,7 +675,8 @@ Function Annotations
.. sectionauthor:: Zachary Ware <zachary.ware at 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
diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst
index e68c9b10d03e..f5a394ad4008 100644
--- a/Doc/tutorial/introduction.rst
+++ b/Doc/tutorial/introduction.rst
@@ -11,6 +11,8 @@ with a prompt are output from the interpreter. Note that a secondary prompt on a
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
More information about the Python-checkins
mailing list