diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 4c0731e951de70c098c4fcf99219ada74ca9371a..aecc3b877d8faaf8150fde9d87866b8364c6b0ba 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1796,7 +1796,7 @@ is not possible due to its implementation being opaque at build time. Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after first calling :c:func:`PyThread_tss_delete` to ensure any associated thread locals have been unassigned. This is a no-op if the *key* - argument is `NULL`. + argument is ``NULL``. .. note:: A freed key becomes a dangling pointer. You should reset the key to diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index d740e4eb0897e54caa1b7f51569a9c55d7f01209..ac352047798eb43f5a48c75695646e1ec77c1eb5 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -40,7 +40,7 @@ Type Objects .. c:function:: unsigned long PyType_GetFlags(PyTypeObject* type) Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily - meant for use with `Py_LIMITED_API`; the individual flag bits are + meant for use with ``Py_LIMITED_API``; the individual flag bits are guaranteed to be stable across Python releases, but access to :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API. diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index 9da1d01abd6f51b33be0c63044020d2ba8d64a44..9dbfacd73cc6c73f2cb4acbf49e3b7baaaf54f95 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -155,7 +155,7 @@ Why can't I use an assignment in an expression? Starting in Python 3.8, you can! -Assignment expressions using the walrus operator `:=` assign a variable in an +Assignment expressions using the walrus operator ``:=`` assign a variable in an expression:: while chunk := fp.read(200): diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst index 7b1cf75fa81f080aab3f1f0a42b4253f00e4fdc2..bad5e508b01900ec31d8c0290e65ec2162af4761 100644 --- a/Doc/howto/enum.rst +++ b/Doc/howto/enum.rst @@ -1120,7 +1120,7 @@ Enum Classes The :class:`EnumType` metaclass is responsible for providing the :meth:`__contains__`, :meth:`__dir__`, :meth:`__iter__` and other methods that allow one to do things with an :class:`Enum` class that fail on a typical -class, such as `list(Color)` or `some_enum_var in Color`. :class:`EnumType` is +class, such as ``list(Color)`` or ``some_enum_var in Color``. :class:`EnumType` is responsible for ensuring that various other methods on the final :class:`Enum` class are correct (such as :meth:`__new__`, :meth:`__getnewargs__`, :meth:`__str__` and :meth:`__repr__`). diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index b49b00dc38616dffa9514e08c258e6c15e374222..c51071879a4b97686c3727ab124c592afb71bbd8 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -769,7 +769,7 @@ To run a logging listener in production, you may need to use a process-managemen such as `Supervisor <http://supervisord.org/>`_. `Here <https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b>`_ is a Gist which provides the bare-bones files to run the above functionality using Supervisor: you -will need to change the `/path/to/` parts in the Gist to reflect the actual paths you +will need to change the ``/path/to/`` parts in the Gist to reflect the actual paths you want to use. @@ -2981,7 +2981,7 @@ Formatting times using UTC (GMT) via configuration -------------------------------------------------- Sometimes you want to format times using UTC, which can be done using a class -such as `UTCFormatter`, shown below:: +such as ``UTCFormatter``, shown below:: import logging import time diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst index f98876a3352e4db112fcfc5e65d5013470fef98a..87065273dab7a4540b11c13bebfd18e6324ff562 100644 --- a/Doc/howto/logging.rst +++ b/Doc/howto/logging.rst @@ -552,14 +552,14 @@ raw message. If there is no date format string, the default date format is: %Y-%m-%d %H:%M:%S -with the milliseconds tacked on at the end. The ``style`` is one of `%`, '{' -or '$'. If one of these is not specified, then '%' will be used. +with the milliseconds tacked on at the end. The ``style`` is one of ``'%'``, +``'{'``, or ``'$'``. If one of these is not specified, then ``'%'`` will be used. -If the ``style`` is '%', the message format string uses +If the ``style`` is ``'%'``, the message format string uses ``%(<dictionary key>)s`` styled string substitution; the possible keys are -documented in :ref:`logrecord-attributes`. If the style is '{', the message +documented in :ref:`logrecord-attributes`. If the style is ``'{'``, the message format string is assumed to be compatible with :meth:`str.format` (using -keyword arguments), while if the style is '$' then the message format string +keyword arguments), while if the style is ``'$'`` then the message format string should conform to what is expected by :meth:`string.Template.substitute`. .. versionchanged:: 3.2 diff --git a/Doc/install/index.rst b/Doc/install/index.rst index 84df5e7cb3689d067828baecd473059f70e894f3..d2d8e567c03c2bbb03910bceb7a699db4136547a 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -761,7 +761,7 @@ And on Windows, the configuration files are: +--------------+-------------------------------------------------+-------+ On all platforms, the "personal" file can be temporarily disabled by -passing the `--no-user-cfg` option. +passing the ``--no-user-cfg`` option. Notes: diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst index 8b67f4b8957ef6bb38caa856c7832acdeaa7ca56..969354ceb163b5883e2f01fd8fd70427e5a9ab63 100644 --- a/Doc/library/asyncio-protocol.rst +++ b/Doc/library/asyncio-protocol.rst @@ -553,7 +553,7 @@ accept factories that return streaming protocols. a connection is open. However, :meth:`protocol.eof_received() <Protocol.eof_received>` - is called at most once. Once `eof_received()` is called, + is called at most once. Once ``eof_received()`` is called, ``data_received()`` is not called anymore. .. method:: Protocol.eof_received() diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 221197ea40ffd9096e12b48de1deddd4918fee47..27054d74cd434198e1aca7163568cf5dcfc0af82 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -629,7 +629,7 @@ Timeouts Change the time the timeout will trigger. - If *when* is `None`, any current deadline will be removed, and the + If *when* is ``None``, any current deadline will be removed, and the context manager will wait indefinitely. If *when* is a float, it is set as the new deadline. @@ -865,17 +865,17 @@ Running in Threads # blocking_io complete at 19:50:54 # finished main at 19:50:54 - Directly calling `blocking_io()` in any coroutine would block the event loop + Directly calling ``blocking_io()`` in any coroutine would block the event loop for its duration, resulting in an additional 1 second of run time. Instead, - by using `asyncio.to_thread()`, we can run it in a separate thread without + by using ``asyncio.to_thread()``, we can run it in a separate thread without blocking the event loop. .. note:: - Due to the :term:`GIL`, `asyncio.to_thread()` can typically only be used + Due to the :term:`GIL`, ``asyncio.to_thread()`` can typically only be used to make IO-bound functions non-blocking. However, for extension modules that release the GIL or alternative Python implementations that don't - have one, `asyncio.to_thread()` can also be used for CPU-bound functions. + have one, ``asyncio.to_thread()`` can also be used for CPU-bound functions. .. versionadded:: 3.9 diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst index 7b74bbd652be3890a3dc577612250e283884f052..d201dc963b599506b26dc5bb9ba078c82f208eec 100644 --- a/Doc/library/bdb.rst +++ b/Doc/library/bdb.rst @@ -143,7 +143,7 @@ The :mod:`bdb` module also defines two classes: For real file names, the canonical form is an operating-system-dependent, :func:`case-normalized <os.path.normcase>` :func:`absolute path - <os.path.abspath>`. A *filename* with angle brackets, such as `"<stdin>"` + <os.path.abspath>`. A *filename* with angle brackets, such as ``"<stdin>"`` generated in interactive mode, is returned unchanged. .. method:: reset() diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst index 999892e95f47152ba3d3bc526a6933552194a102..ae5a1598f84b44e61f52c97348c4d0fb3e7e622b 100644 --- a/Doc/library/bz2.rst +++ b/Doc/library/bz2.rst @@ -206,7 +206,7 @@ Incremental (de)compression will be set to ``True``. Attempting to decompress data after the end of stream is reached - raises an `EOFError`. Any data found after the end of the + raises an :exc:`EOFError`. Any data found after the end of the stream is ignored and saved in the :attr:`~.unused_data` attribute. .. versionchanged:: 3.5 @@ -303,7 +303,7 @@ Using :class:`BZ2Compressor` for incremental compression: >>> out = out + comp.flush() The example above uses a very "nonrandom" stream of data -(a stream of `b"z"` chunks). Random data tends to compress poorly, +(a stream of ``b"z"`` chunks). Random data tends to compress poorly, while ordered, repetitive data usually yields a high compression ratio. Writing and reading a bzip2-compressed file in binary mode: diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst index 95c9e50991423f9026a13938d7701c75d4437809..8106cc235e5a3c027ae965feab84c5f1d0fe0a90 100644 --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -152,7 +152,7 @@ And:: All threads enqueued to ``ThreadPoolExecutor`` will be joined before the interpreter can exit. Note that the exit handler which does this is - executed *before* any exit handlers added using `atexit`. This means + executed *before* any exit handlers added using ``atexit``. This means exceptions in the main thread must be caught and handled in order to signal threads to exit gracefully. For this reason, it is recommended that ``ThreadPoolExecutor`` not be used for long-running tasks. @@ -411,13 +411,13 @@ The :class:`Future` class encapsulates the asynchronous execution of a callable. tests. If the method returns ``False`` then the :class:`Future` was cancelled, - i.e. :meth:`Future.cancel` was called and returned `True`. Any threads + i.e. :meth:`Future.cancel` was called and returned ``True``. Any threads waiting on the :class:`Future` completing (i.e. through :func:`as_completed` or :func:`wait`) will be woken up. If the method returns ``True`` then the :class:`Future` was not cancelled and has been put in the running state, i.e. calls to - :meth:`Future.running` will return `True`. + :meth:`Future.running` will return ``True``. This method can only be called once and cannot be called after :meth:`Future.set_result` or :meth:`Future.set_exception` have been diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 99c35a8e595f2017772abad06676f33107a07ef1..2900f77589e31b632eb4c565571893bff94c2679 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1934,7 +1934,7 @@ Utility functions .. function:: GetLastError() Windows only: Returns the last error code set by Windows in the calling thread. - This function calls the Windows `GetLastError()` function directly, + This function calls the Windows ``GetLastError()`` function directly, it does not return the ctypes-private copy of the error code. .. function:: get_errno() diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index a7cc4952778011afd7bffaed91b1eca8f43c5f1c..83e19fac6520ebeb1cfbae8398040f7b39f030a7 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -278,7 +278,7 @@ The module :mod:`curses` defines the following functions: Change the definition of a color, taking the number of the color to be changed followed by three RGB values (for the amounts of red, green, and blue components). The value of *color_number* must be between ``0`` and - `COLORS - 1`. Each of *r*, *g*, *b*, must be a value between ``0`` and + ``COLORS - 1``. Each of *r*, *g*, *b*, must be a value between ``0`` and ``1000``. When :func:`init_color` is used, all occurrences of that color on the screen immediately change to the new definition. This function is a no-op on most terminals; it is active only if :func:`can_change_color` returns ``True``. diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index b4580d1879c0187e136761539e90a0a5ad97f702..8a7d99999f5dbd7f26364226fab66575f65325d4 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -1769,7 +1769,7 @@ Other constructor: ISO 8601 format, with the following exceptions: 1. Time zone offsets may have fractional seconds. - 2. The leading `T`, normally required in cases where there may be ambiguity between + 2. The leading ``T``, normally required in cases where there may be ambiguity between a date and a time, is not required. 3. Fractional seconds may have any number of digits (anything beyond 6 will be truncated). @@ -2265,7 +2265,7 @@ where historical changes have been made to civil time. two digits of ``offset.hours`` and ``offset.minutes`` respectively. .. versionchanged:: 3.6 - Name generated from ``offset=timedelta(0)`` is now plain `'UTC'`, not + Name generated from ``offset=timedelta(0)`` is now plain ``'UTC'``, not ``'UTC+00:00'``. diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index e7d3950fd143872ecaad6cd2d0a490060390a103..6bce940f75004bc329ac3cff393722ffa6be3a55 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -576,11 +576,11 @@ Decimal objects Alternative constructor that only accepts instances of :class:`float` or :class:`int`. - Note `Decimal.from_float(0.1)` is not the same as `Decimal('0.1')`. + Note ``Decimal.from_float(0.1)`` is not the same as ``Decimal('0.1')``. Since 0.1 is not exactly representable in binary floating point, the value is stored as the nearest representable value which is - `0x1.999999999999ap-4`. That equivalent value in decimal is - `0.1000000000000000055511151231257827021181583404541015625`. + ``0x1.999999999999ap-4``. That equivalent value in decimal is + ``0.1000000000000000055511151231257827021181583404541015625``. .. note:: From Python 3.2 onwards, a :class:`Decimal` instance can also be constructed directly from a :class:`float`. @@ -1209,7 +1209,7 @@ In addition to the three supplied contexts, new contexts can be created with the .. method:: exp(x) - Returns `e ** x`. + Returns ``e ** x``. .. method:: fma(x, y, z) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index d2925929c6c90e176cebcc72b904d0570fab46a1..98866b72a30a9390db0b07c45584144e645486ed 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -373,7 +373,7 @@ details of bytecode instructions as :class:`Instruction` instances: .. class:: Positions - In case the information is not available, some fields might be `None`. + In case the information is not available, some fields might be ``None``. .. data:: lineno .. data:: end_lineno diff --git a/Doc/library/email.compat32-message.rst b/Doc/library/email.compat32-message.rst index 4eaa9d588ca35e28cb9e2d2fe54d01b2bbd706e7..5bef155a4af3103a1a610e281290cf8f2770bde4 100644 --- a/Doc/library/email.compat32-message.rst +++ b/Doc/library/email.compat32-message.rst @@ -298,7 +298,7 @@ Here are the methods of the :class:`Message` class: In a model generated from bytes, any header values that (in contravention of the RFCs) contain non-ASCII bytes will, when retrieved through this interface, be represented as :class:`~email.header.Header` objects with - a charset of `unknown-8bit`. + a charset of ``unknown-8bit``. .. method:: __len__() diff --git a/Doc/library/email.headerregistry.rst b/Doc/library/email.headerregistry.rst index 98527cea43da2a3b6b3c60776811755736152c63..00a954e0307ea640d03ca2c0a0b3c7c814dc7f94 100644 --- a/Doc/library/email.headerregistry.rst +++ b/Doc/library/email.headerregistry.rst @@ -153,7 +153,7 @@ headers. specified as ``-0000`` (indicating it is in UTC but contains no information about the source timezone), then :attr:`.datetime` will be a naive :class:`~datetime.datetime`. If a specific timezone offset is - found (including `+0000`), then :attr:`.datetime` will contain an aware + found (including ``+0000``), then :attr:`.datetime` will contain an aware ``datetime`` that uses :class:`datetime.timezone` to record the timezone offset. diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index d6792ed6fb77fb3b0f7162cd17f82cb871c066e1..9beebd2a85e5d91d2be0dda524bacad5a734bd43 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -144,7 +144,7 @@ The :mod:`functools` module defines the following functions: arguments to the function must be hashable. Distinct argument patterns may be considered to be distinct calls with - separate cache entries. For example, `f(a=1, b=2)` and `f(b=2, a=1)` + separate cache entries. For example, ``f(a=1, b=2)`` and ``f(b=2, a=1)`` differ in their keyword argument order and may have two separate cache entries. @@ -191,7 +191,7 @@ The :mod:`functools` module defines the following functions: The cache keeps references to the arguments and return values until they age out of the cache or until the cache is cleared. - If a method is cached, the `self` instance argument is included in the + If a method is cached, the ``self`` instance argument is included in the cache. See :ref:`faq-cache-method-calls` An `LRU (least recently used) cache diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index 0906ce7cb7a2d9c99c696a6a94da1730ef25a401..a96fc8b8ff7eaf7effc8a999aff90f3dcfb18948 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -432,7 +432,7 @@ Constructor functions also accept the following tree hashing parameters: BLAKE2s, 0 in sequential mode). * *last_node*: boolean indicating whether the processed node is the last - one (`False` for sequential mode). + one (``False`` for sequential mode). .. figure:: hashlib-blake2-tree.png :alt: Explanation of tree mode parameters. diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 8fd6b3537019aa96efba28c0ac60ac62eb1a81ab..0968509fbafec29b5584f38e8fc9ff2938521f61 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -1055,10 +1055,10 @@ Text I/O The initial value of the buffer can be set by providing *initial_value*. If newline translation is enabled, newlines will be encoded as if by :meth:`~TextIOBase.write`. The stream is positioned at the start of the - buffer which emulates opening an existing file in a `w+` mode, making it + buffer which emulates opening an existing file in a ``w+`` mode, making it ready for an immediate write from the beginning or for a write that - would overwrite the initial value. To emulate opening a file in an `a+` - mode ready for appending, use `f.seek(0, io.SEEK_END)` to reposition the + would overwrite the initial value. To emulate opening a file in an ``a+`` + mode ready for appending, use ``f.seek(0, io.SEEK_END)`` to reposition the stream at the end of the buffer. The *newline* argument works like that of :class:`TextIOWrapper`, diff --git a/Doc/library/lzma.rst b/Doc/library/lzma.rst index 21092645366da757c1940fc84723357202428272..868d4dcfb6c996f709687c9766612c92f52e72ef 100644 --- a/Doc/library/lzma.rst +++ b/Doc/library/lzma.rst @@ -258,7 +258,7 @@ Compressing and decompressing data in memory will be set to ``True``. Attempting to decompress data after the end of stream is reached - raises an `EOFError`. Any data found after the end of the + raises an :exc:`EOFError`. Any data found after the end of the stream is ignored and saved in the :attr:`~.unused_data` attribute. .. versionchanged:: 3.5 diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 9a4e2f875fc69bc36ca4c9df4d184f2418b845d6..633cd0869d83119d823d9236a159e365797200e0 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -3180,7 +3180,7 @@ features: system records access and modification times; see :func:`~os.stat`. The best way to preserve exact times is to use the *st_atime_ns* and *st_mtime_ns* fields from the :func:`os.stat` result object with the *ns* parameter to - `utime`. + :func:`utime`. This function can support :ref:`specifying a file descriptor <path_fd>`, :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not @@ -4071,7 +4071,7 @@ written in Python, such as a mail server's external command delivery program. library :c:data:`POSIX_SPAWN_RESETIDS` flag. If the *setsid* argument is ``True``, it will create a new session ID - for `posix_spawn`. *setsid* requires :c:data:`POSIX_SPAWN_SETSID` + for ``posix_spawn``. *setsid* requires :c:data:`POSIX_SPAWN_SETSID` or :c:data:`POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError` is raised. diff --git a/Doc/library/select.rst b/Doc/library/select.rst index a8df81f5bd1f0714dee09a6a2ddaac68738aedc4..2890706bab729c59781ba9331e0c54887db326fb 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -61,7 +61,7 @@ The module defines the following: events. *sizehint* informs epoll about the expected number of events to be - registered. It must be positive, or `-1` to use the default. It is only + registered. It must be positive, or ``-1`` to use the default. It is only used on older systems where :c:func:`epoll_create1` is not available; otherwise it has no effect (though its value is still checked). diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index b1c2ab07740f0f149a29c3c6047881b612d696e4..8c260897dbaabc6d59b2dd7031bf352098a95020 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -642,7 +642,7 @@ The following functions all create :ref:`socket objects <socket-objects>`. When :const:`SOCK_NONBLOCK` or :const:`SOCK_CLOEXEC` bit flags are applied to *type* they are cleared, and :attr:`socket.type` will not reflect them. They are still passed - to the underlying system `socket()` call. Therefore, + to the underlying system ``socket()`` call. Therefore, :: diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst index bf869903c0f84e4712bb76eb39505dda2aa7d602..78c4bc521fdd38634f9d649b83590d2218279200 100644 --- a/Doc/library/statistics.rst +++ b/Doc/library/statistics.rst @@ -813,7 +813,7 @@ of applications in statistics. The relative likelihood is computed as the probability of a sample occurring in a narrow range divided by the width of the range (hence the word "density"). Since the likelihood is relative to other points, - its value can be greater than `1.0`. + its value can be greater than ``1.0``. .. method:: NormalDist.cdf(x) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index aab3f6aa83fced96b9459dfa51ba309376fe29b3..542b08b1878ed0b1eafe6039a1eda5b53cf66466 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -250,7 +250,7 @@ always available. Print low-level information to stderr about the state of CPython's memory allocator. - If Python is `built in debug mode <debug-build>` (:option:`configure + If Python is :ref:`built in debug mode <debug-build>` (:option:`configure --with-pydebug option <--with-pydebug>`), it also performs some expensive internal consistency checks. @@ -349,7 +349,7 @@ always available. files to (and read them from) a parallel directory tree rooted at this directory, rather than from ``__pycache__`` directories in the source code tree. Any ``__pycache__`` directories in the source code tree will be ignored - and new `.pyc` files written within the pycache prefix. Thus if you use + and new ``.pyc`` files written within the pycache prefix. Thus if you use :mod:`compileall` as a pre-build step, you must ensure you run it with the same pycache prefix (if any) that you will use at runtime. @@ -874,7 +874,7 @@ always available. .. function:: get_asyncgen_hooks() Returns an *asyncgen_hooks* object, which is similar to a - :class:`~collections.namedtuple` of the form `(firstiter, finalizer)`, + :class:`~collections.namedtuple` of the form ``(firstiter, finalizer)``, where *firstiter* and *finalizer* are expected to be either ``None`` or functions which take an :term:`asynchronous generator iterator` as an argument, and are used to schedule finalization of an asynchronous diff --git a/Doc/library/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst index 054efa81266326bb00da9302643bb1d540c0f15a..f9a207bad6903f440484062dadfc3e5b253ae244 100644 --- a/Doc/library/unittest.mock-examples.rst +++ b/Doc/library/unittest.mock-examples.rst @@ -1116,7 +1116,7 @@ on first use). That aside there is a way to use ``mock`` to affect the results of an import. Importing fetches an *object* from the :data:`sys.modules` dictionary. Note that it fetches an *object*, which need not be a module. Importing a module for the -first time results in a module object being put in `sys.modules`, so usually +first time results in a module object being put in ``sys.modules``, so usually when you import something you get a module back. This need not be the case however. diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst index 82e5d6aea2310e619da0076a3c5fa483c47603c5..72a7a98c2ac4f212f7b597085b26bfe2352758df 100644 --- a/Doc/library/xml.dom.minidom.rst +++ b/Doc/library/xml.dom.minidom.rst @@ -148,8 +148,8 @@ module documentation. This section lists the differences between the API and Similarly, explicitly stating the *standalone* argument causes the standalone document declarations to be added to the prologue of the XML document. - If the value is set to `True`, `standalone="yes"` is added, - otherwise it is set to `"no"`. + If the value is set to ``True``, ``standalone="yes"`` is added, + otherwise it is set to ``"no"``. Not stating the argument will omit the declaration from the document. .. versionchanged:: 3.8 diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst index 8b09acd4bd3049100b5e9196d1bdfe86d98359d5..bd2c49a6edab7fa4859ecb83788f2d4b2550a86d 100644 --- a/Doc/library/xmlrpc.client.rst +++ b/Doc/library/xmlrpc.client.rst @@ -60,7 +60,7 @@ between conformable Python objects and XML on the wire. may be passed to calls. The *headers* parameter is an optional sequence of HTTP headers to send with each request, expressed as a sequence of 2-tuples representing the header - name and value. (e.g. `[('Header-Name', 'value')]`). + name and value. (e.g. ``[('Header-Name', 'value')]``). The obsolete *use_datetime* flag is similar to *use_builtin_types* but it applies only to date/time values. diff --git a/Doc/library/xmlrpc.server.rst b/Doc/library/xmlrpc.server.rst index 9778a859da1fbf70b7b1a08f211b1964fda85a1c..016369d2b89d2c37f1c9ee12dc2b9232d307f31d 100644 --- a/Doc/library/xmlrpc.server.rst +++ b/Doc/library/xmlrpc.server.rst @@ -263,7 +263,7 @@ This ExampleService demo can be invoked from the command line:: The client that interacts with the above server is included in -`Lib/xmlrpc/client.py`:: +``Lib/xmlrpc/client.py``:: server = ServerProxy("http://localhost:8000") diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 6b5e0e1628f143482bb46304313202f60894a6bd..cc969752d5d7b75dcf2ad0a2ef594734e086969f 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1551,7 +1551,7 @@ built-in types. true). * Mappings (instances of :class:`dict`) compare equal if and only if they have - equal `(key, value)` pairs. Equality comparison of the keys and values + equal ``(key, value)`` pairs. Equality comparison of the keys and values enforces reflexivity. Order comparisons (``<``, ``>``, ``<=``, and ``>=``) raise :exc:`TypeError`. diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 0d8c029550081cd5c3e42d6bd052cf9a25bf9dd5..70d946ab4db9e2b702a88f050be2b3751944d8a2 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -816,7 +816,7 @@ The path based finder iterates over every entry in the search path, and for each of these, looks for an appropriate :term:`path entry finder` (:class:`~importlib.abc.PathEntryFinder`) for the path entry. Because this can be an expensive operation (e.g. there may be -`stat()` call overheads for this search), the path based finder maintains +``stat()`` call overheads for this search), the path based finder maintains a cache mapping path entries to path entry finders. This cache is maintained in :data:`sys.path_importer_cache` (despite the name, this cache actually stores finder objects rather than being limited to :term:`importer` objects). diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 8311de0457f6afa62781555342adfd711616b9b1..5c9937fb5b6d72f0276e9fc8b7603d6e5e89ece1 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -994,20 +994,12 @@ The :keyword:`!nonlocal` statement .. productionlist:: python-grammar nonlocal_stmt: "nonlocal" `identifier` ("," `identifier`)* -.. XXX add when implemented - : ["=" (`target_list` "=")+ starred_expression] - : | "nonlocal" identifier augop expression_list - The :keyword:`nonlocal` statement causes the listed identifiers to refer to previously bound variables in the nearest enclosing scope excluding globals. This is important because the default behavior for binding is to search the local namespace first. The statement allows encapsulated code to rebind variables outside of the local scope besides the global (module) scope. -.. XXX not implemented - The :keyword:`nonlocal` statement may prepend an assignment or augmented - assignment, but not an expression. - Names listed in a :keyword:`nonlocal` statement, unlike those listed in a :keyword:`global` statement, must refer to pre-existing bindings in an enclosing scope (the scope in which a new binding should be created cannot diff --git a/Doc/requirements.txt b/Doc/requirements.txt index be058733fcf4d71cbac7d4b672248e2a4009e29d..7f82dc32113a9d7924a5fb1cbe5e58697e1e1fbc 100644 --- a/Doc/requirements.txt +++ b/Doc/requirements.txt @@ -10,7 +10,7 @@ blurb # sphinx-lint 0.6.2 yields many default role errors due to the new regular # expression used for default role detection, so we don't use the version # until the errors are fixed. -sphinx-lint<1,!=0.6.2 +sphinx-lint==0.6.4 # The theme used by the documentation is stored separately, so we need # to install that as well. diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 8ce9884c76fe2105d7ca76d368c4eeec04606ce5..c387528d87cd2a030775b3c15d965f1d9e80d7b9 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -750,12 +750,12 @@ Compiler flags In particular, :envvar:`CFLAGS` should not contain: - * the compiler flag `-I` (for setting the search path for include files). - The `-I` flags are processed from left to right, and any flags in - :envvar:`CFLAGS` would take precedence over user- and package-supplied `-I` + * the compiler flag ``-I`` (for setting the search path for include files). + The ``-I`` flags are processed from left to right, and any flags in + :envvar:`CFLAGS` would take precedence over user- and package-supplied ``-I`` flags. - * hardening flags such as `-Werror` because distributions cannot control + * hardening flags such as ``-Werror`` because distributions cannot control whether packages installed by users conform to such heightened standards. @@ -873,9 +873,9 @@ Linker flags In particular, :envvar:`LDFLAGS` should not contain: - * the compiler flag `-L` (for setting the search path for libraries). - The `-L` flags are processed from left to right, and any flags in - :envvar:`LDFLAGS` would take precedence over user- and package-supplied `-L` + * the compiler flag ``-L`` (for setting the search path for libraries). + The ``-L`` flags are processed from left to right, and any flags in + :envvar:`LDFLAGS` would take precedence over user- and package-supplied ``-L`` flags. .. envvar:: CONFIGURE_LDFLAGS_NODIST diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst index 061cfa5be88f29b2bd872346421caf308d333361..24c02c99f871d56adee38450d64a590b9afe90b0 100644 --- a/Doc/using/unix.rst +++ b/Doc/using/unix.rst @@ -170,7 +170,7 @@ Custom OpenSSL $ popd 3. Build Python with custom OpenSSL - (see the configure `--with-openssl` and `--with-openssl-rpath` options) + (see the configure ``--with-openssl`` and ``--with-openssl-rpath`` options) .. code-block:: shell-session diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index e338b11e1aa025c1d5b1945443828d171b402d4c..4ab68e140b9e310850b0ec61a908af46e5185234 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -203,7 +203,7 @@ of available options is shown below. +---------------------------+--------------------------------------+--------------------------+ | Include_pip | Install bundled pip and setuptools | 1 | +---------------------------+--------------------------------------+--------------------------+ -| Include_symbols | Install debugging symbols (`*`.pdb) | 0 | +| Include_symbols | Install debugging symbols (``*.pdb``)| 0 | +---------------------------+--------------------------------------+--------------------------+ | Include_tcltk | Install Tcl/Tk support and IDLE | 1 | +---------------------------+--------------------------------------+--------------------------+ diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index 6dddf37415edc8a8b06078184e4e42ee181a879f..b96dfe9159da1a45233473b4c984c3a995eaa9ba 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -717,13 +717,13 @@ This will produce the output:: PEP 3101: Advanced String Formatting ===================================================== -In Python 3.0, the `%` operator is supplemented by a more powerful string +In Python 3.0, the ``%`` operator is supplemented by a more powerful string formatting method, :meth:`format`. Support for the :meth:`str.format` method has been backported to Python 2.6. -In 2.6, both 8-bit and Unicode strings have a `.format()` method that +In 2.6, both 8-bit and Unicode strings have a ``.format()`` method that treats the string as a template and takes the arguments to be formatted. -The formatting template uses curly brackets (`{`, `}`) as special characters:: +The formatting template uses curly brackets (``{``, ``}``) as special characters:: >>> # Substitute positional argument 0 into the string. >>> "User ID: {0}".format("root") diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst index 3df9f8a4798ffa3bd584ec8aeb31d43382c95562..82f5ea3b31275b3a6f2b477db692408503576543 100644 --- a/Doc/whatsnew/2.7.rst +++ b/Doc/whatsnew/2.7.rst @@ -2485,8 +2485,8 @@ In the standard library: * The ElementTree library, :mod:`xml.etree`, no longer escapes ampersands and angle brackets when outputting an XML processing - instruction (which looks like `<?xml-stylesheet href="#style1"?>`) - or comment (which looks like `<!-- comment -->`). + instruction (which looks like ``<?xml-stylesheet href="#style1"?>``) + or comment (which looks like ``<!-- comment -->``). (Patch by Neil Muller; :issue:`2746`.) * The :meth:`~StringIO.StringIO.readline` method of :class:`~StringIO.StringIO` objects now does diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst index db8d9281b1f2ed1ae478bbaaa5f6749f8d94c77f..24d5bba66e33003717bda600874c45cf6aa91de6 100644 --- a/Doc/whatsnew/3.10.rst +++ b/Doc/whatsnew/3.10.rst @@ -1183,7 +1183,7 @@ and will be incorrect in some rare cases, including some ``_``-s in New in 3.10 maintenance releases. -Apply syntax highlighting to `.pyi` files. (Contributed by Alex +Apply syntax highlighting to ``.pyi`` files. (Contributed by Alex Waygood and Terry Jan Reedy in :issue:`45447`.) Include prompts when saving Shell with inputs and outputs. diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index b5ca28e97b4218bdc2b54f204804be35004dd5d4..10534b1b367d2ded099a8e8dd848492648d68eab 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -740,7 +740,7 @@ hashlib IDLE and idlelib ---------------- -* Apply syntax highlighting to `.pyi` files. (Contributed by Alex +* Apply syntax highlighting to ``.pyi`` files. (Contributed by Alex Waygood and Terry Jan Reedy in :issue:`45447`.) * Include prompts when saving Shell with inputs and outputs. diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst index 7b12e631fd819f3cbfbecd27f9df5615caa90be6..3becd3f7192815c6981fae5a97347c8d2376a809 100644 --- a/Doc/whatsnew/3.2.rst +++ b/Doc/whatsnew/3.2.rst @@ -1746,7 +1746,7 @@ names. instead of module names for running specific tests (:issue:`10620`). The new test discovery can find tests within packages, locating any test importable from the top-level directory. The top-level directory can be specified with - the `-t` option, a pattern for matching files with ``-p``, and a directory to + the ``-t`` option, a pattern for matching files with ``-p``, and a directory to start discovery with ``-s``: .. code-block:: shell-session @@ -1858,7 +1858,7 @@ asyncore :class:`asyncore.dispatcher` now provides a :meth:`~asyncore.dispatcher.handle_accepted()` method -returning a `(sock, addr)` pair which is called when a connection has actually +returning a ``(sock, addr)`` pair which is called when a connection has actually been established with a new remote endpoint. This is supposed to be used as a replacement for old :meth:`~asyncore.dispatcher.handle_accept()` and avoids the user to call :meth:`~asyncore.dispatcher.accept()` directly. diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst index fef1a8ac4c010137955e456664ff388e9a937b18..96a632577b2c5666a4520048fd716668988d67ea 100644 --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -2389,10 +2389,10 @@ Porting Python code :attr:`sys.path_importer_cache` where it represents the use of implicit finders, but semantically it should not change anything. -* :class:`importlib.abc.Finder` no longer specifies a `find_module()` abstract +* :class:`importlib.abc.Finder` no longer specifies a ``find_module()`` abstract method that must be implemented. If you were relying on subclasses to implement that method, make sure to check for the method's existence first. - You will probably want to check for `find_loader()` first, though, in the + You will probably want to check for ``find_loader()`` first, though, in the case of working with :term:`path entry finders <path entry finder>`. * :mod:`pkgutil` has been converted to use :mod:`importlib` internally. This diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst index 625373d508989671faa538925b89280ab43ef7cc..f9cceecbcbb94b03936881415ddeb87f4f0a6e93 100644 --- a/Doc/whatsnew/3.5.rst +++ b/Doc/whatsnew/3.5.rst @@ -2469,11 +2469,11 @@ Changes in the Python API ``opt-`` tag in ``.pyc`` file names. The :func:`importlib.util.cache_from_source` has gained an *optimization* parameter to help control the ``opt-`` tag. Because of this, the - *debug_override* parameter of the function is now deprecated. `.pyo` files + *debug_override* parameter of the function is now deprecated. ``.pyo`` files are also no longer supported as a file argument to the Python interpreter and thus serve no purpose when distributed on their own (i.e. sourceless code distribution). Due to the fact that the magic number for bytecode has changed - in Python 3.5, all old `.pyo` files from previous versions of Python are + in Python 3.5, all old ``.pyo`` files from previous versions of Python are invalid regardless of this PEP. * The :mod:`socket` module now exports the :data:`~socket.CAN_RAW_FD_FRAMES` diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst index bcca28d2f7ba85cad61eee13b9b152adbedfc8ea..70e45258654f41b23e93248851a1201b5ec103e6 100644 --- a/Doc/whatsnew/3.6.rst +++ b/Doc/whatsnew/3.6.rst @@ -960,8 +960,8 @@ contextlib The :class:`contextlib.AbstractContextManager` class has been added to provide an abstract base class for context managers. It provides a -sensible default implementation for `__enter__()` which returns -``self`` and leaves `__exit__()` an abstract method. A matching +sensible default implementation for ``__enter__()`` which returns +``self`` and leaves ``__exit__()`` an abstract method. A matching class has been added to the :mod:`typing` module as :class:`typing.ContextManager`. (Contributed by Brett Cannon in :issue:`25609`.) @@ -1388,7 +1388,7 @@ are treated as punctuation. site ---- -When specifying paths to add to :attr:`sys.path` in a `.pth` file, +When specifying paths to add to :attr:`sys.path` in a ``.pth`` file, you may now specify file paths on top of directories (e.g. zip files). (Contributed by Wolfgang Langner in :issue:`26587`). diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index 5bb3d2a436b6756860f3be131b06cd27bcc4e016..de03e5bedeaa3546f2a816e6b2c4a83aaaff2991 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -2497,7 +2497,7 @@ number of other issues). Some known details affected: * :c:func:`PySys_AddWarnOptionUnicode` is not currently usable by embedding applications due to the requirement to create a Unicode object prior to - calling `Py_Initialize`. Use :c:func:`PySys_AddWarnOption` instead. + calling ``Py_Initialize``. Use :c:func:`PySys_AddWarnOption` instead. * warnings filters added by an embedding application with :c:func:`PySys_AddWarnOption` should now more consistently take precedence diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst index ff01a65772991f01f243395df1fb9a19bfd811f6..624e71f9254c457b1120ec3bb1b62bd159ff0101 100644 --- a/Doc/whatsnew/3.9.rst +++ b/Doc/whatsnew/3.9.rst @@ -500,7 +500,7 @@ Reedy in :issue:`40468`.) Move the indent space setting from the Font tab to the new Windows tab. (Contributed by Mark Roseman and Terry Jan Reedy in :issue:`33962`.) -Apply syntax highlighting to `.pyi` files. (Contributed by Alex +Apply syntax highlighting to ``.pyi`` files. (Contributed by Alex Waygood and Terry Jan Reedy in :issue:`45447`.) imaplib