diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index 4430e39b7c5..1c479bf9080 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 78f16196369..634ff00035b 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 7a276b139f5..e7a0fdbc67a 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 587a0a09a94..d463356e7ad 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: .. 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 407853c2d7e..93748a2e472 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 75e7e5be912..1f767170b5a 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 907c6c307fb..899780d140a 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 cc3516acfae..f25d3d679a2 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 ``''``. +.. 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...)`` 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: (?`` will use the substring matched by the group named ``name``, as diff --git a/Doc/library/site.rst b/Doc/library/site.rst index 5b5ed93a1b7..e6a2980953d 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 efa0a89490e..130e58fa7ab 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 0fec3df3e3c..55913f8c07f 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 `, 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 `_ 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 f10fbe4fc0d..3b15158f3f8 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 33a7b692dde..358b11820c6 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 56f972c9d03..d76e089c23b 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 7ac3cacd3d1..a21ef8ed9f3 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 cbbec0cd831..982f57f1fe6 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:`_proxy`. If no proxy environment variables are set, then + ``_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 14f7896f840..99be47fb4b9 100644 --- a/Doc/library/winreg.rst +++ b/Doc/library/winreg.rst @@ -224,6 +224,9 @@ This module offers the following functions: See :ref:`above `. +.. 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 c49efa5889f..812a7de483c 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 ` 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 `. +.. 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 735ecbf6693..55783506aa6 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 d08abdf3343..5c83181440b 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 4bacac33ae7..d210769225d 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 `` 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 44b5b818aa8..7c4f275a434 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 `, 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 84e8c783838..72da30a3773 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 9b93601135d..04ed499701c 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 4bcdafd7335..f87cd4decd0 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 .. index:: pair: function; annotations - single: -> (return annotation assignment) + single: ->; function annotations + single: :; function annotations :ref:`Function annotations ` 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 e68c9b10d03..f5a394ad400 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