gh-109634: Use :samp: role (GH-109635)

This commit is contained in:
Serhiy Storchaka 2023-09-23 09:31:20 +03:00 committed by GitHub
parent 5e7ea95d9d
commit 92af0cc580
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
30 changed files with 99 additions and 95 deletions

View file

@ -132,4 +132,4 @@ modules (including Python) to be able to see your identifiers, you have to say
Developer Studio will throw in a lot of import libraries that you do not really
need, adding about 100K to your executable. To get rid of them, use the Project
Settings dialog, Link tab, to specify *ignore default libraries*. Add the
correct :file:`msvcrtxx.lib` to the list of libraries.
correct :file:`msvcrt{xx}.lib` to the list of libraries.

View file

@ -1728,7 +1728,7 @@ when (and if) the logged message is actually about to be output to a log by a
handler. So the only slightly unusual thing which might trip you up is that the
parentheses go around the format string and the arguments, not just the format
string. That's because the __ notation is just syntax sugar for a constructor
call to one of the XXXMessage classes.
call to one of the :samp:`{XXX}Message` classes.
If you prefer, you can use a :class:`LoggerAdapter` to achieve a similar effect
to the above, as in the following example::
@ -2644,7 +2644,7 @@ when (and if) the logged message is actually about to be output to a log by a
handler. So the only slightly unusual thing which might trip you up is that the
parentheses go around the format string and the arguments, not just the format
string. Thats because the __ notation is just syntax sugar for a constructor
call to one of the ``XXXMessage`` classes shown above.
call to one of the :samp:`{XXX}Message` classes shown above.
.. _filters-dictconfig:

View file

@ -979,7 +979,7 @@ provided:
#. :class:`NullHandler` instances do nothing with error messages. They are used
by library developers who want to use logging, but want to avoid the 'No
handlers could be found for logger XXX' message which can be displayed if
handlers could be found for logger *XXX*' message which can be displayed if
the library user has not configured logging. See :ref:`library-config` for
more information.

View file

@ -345,9 +345,10 @@ The following error handlers can be used with all Python
+-------------------------+-----------------------------------------------+
| ``'backslashreplace'`` | Replace with backslashed escape sequences. |
| | On encoding, use hexadecimal form of Unicode |
| | code point with formats ``\xhh`` ``\uxxxx`` |
| | ``\Uxxxxxxxx``. On decoding, use hexadecimal |
| | form of byte value with format ``\xhh``. |
| | code point with formats :samp:`\\x{hh}` |
| | :samp:`\\u{xxxx}` :samp:`\\U{xxxxxxxx}`. |
| | On decoding, use hexadecimal form of byte |
| | value with format :samp:`\\x{hh}`. |
| | Implemented in |
| | :func:`backslashreplace_errors`. |
+-------------------------+-----------------------------------------------+
@ -373,8 +374,9 @@ The following error handlers are only applicable to encoding (within
+=========================+===============================================+
| ``'xmlcharrefreplace'`` | Replace with XML/HTML numeric character |
| | reference, which is a decimal form of Unicode |
| | code point with format ``&#num;`` Implemented |
| | in :func:`xmlcharrefreplace_errors`. |
| | code point with format :samp:`&#{num};`. |
| | Implemented in |
| | :func:`xmlcharrefreplace_errors`. |
+-------------------------+-----------------------------------------------+
| ``'namereplace'`` | Replace with ``\N{...}`` escape sequences, |
| | what appears in the braces is the Name |
@ -478,8 +480,9 @@ functions:
Malformed data is replaced by a backslashed escape sequence.
On encoding, use the hexadecimal form of Unicode code point with formats
``\xhh`` ``\uxxxx`` ``\Uxxxxxxxx``. On decoding, use the hexadecimal form of
byte value with format ``\xhh``.
:samp:`\\x{hh}` :samp:`\\u{xxxx}` :samp:`\\U{xxxxxxxx}`.
On decoding, use the hexadecimal form of
byte value with format :samp:`\\x{hh}`.
.. versionchanged:: 3.5
Works with decoding and translating.
@ -492,7 +495,7 @@ functions:
The unencodable character is replaced by an appropriate XML/HTML numeric
character reference, which is a decimal form of Unicode code point with
format ``&#num;`` .
format :samp:`&#{num};` .
.. function:: namereplace_errors(exception)
@ -1346,9 +1349,10 @@ encodings.
| | | supported. |
+--------------------+---------+---------------------------+
| raw_unicode_escape | | Latin-1 encoding with |
| | | ``\uXXXX`` and |
| | | ``\UXXXXXXXX`` for other |
| | | code points. Existing |
| | | :samp:`\\u{XXXX}` and |
| | | :samp:`\\U{XXXXXXXX}`` |
| | | for other code points. |
| | | Existing |
| | | backslashes are not |
| | | escaped in any way. |
| | | It is used in the Python |

View file

@ -31,7 +31,7 @@ compile Python sources.
Positional arguments are files to compile or directories that contain
source files, traversed recursively. If no argument is given, behave as if
the command line was ``-l <directories from sys.path>``.
the command line was :samp:`-l {<directories from sys.path>}`.
.. cmdoption:: -l

View file

@ -61,7 +61,7 @@ By default, ``pip`` is installed into the current virtual environment
active virtual environment). The installation location can be controlled
through two additional command line options:
* ``--root <dir>``: Installs ``pip`` relative to the given root directory
* :samp:`--root {dir}`: Installs ``pip`` relative to the given root directory
rather than the root of the currently active virtual environment (if any)
or the default root for the current Python installation.
* ``--user``: Installs ``pip`` into the user site packages directory rather

View file

@ -1271,7 +1271,7 @@ are always available. They are listed here in alphabetical order.
* ``'xmlcharrefreplace'`` is only supported when writing to a file.
Characters not supported by the encoding are replaced with the
appropriate XML character reference ``&#nnn;``.
appropriate XML character reference :samp:`&#{nnn};`.
* ``'backslashreplace'`` replaces malformed data by Python's backslashed
escape sequences.

View file

@ -173,7 +173,7 @@ implementations do nothing (except for :meth:`~HTMLParser.handle_startendtag`):
.. method:: HTMLParser.handle_charref(name)
This method is called to process decimal and hexadecimal numeric character
references of the form ``&#NNN;`` and ``&#xNNN;``. For example, the decimal
references of the form :samp:`&#{NNN};` and :samp:`&#x{NNN};`. For example, the decimal
equivalent for ``&gt;`` is ``&#62;``, whereas the hexadecimal is ``&#x3E;``;
in this case the method will receive ``'62'`` or ``'x3E'``. This method
is never called if *convert_charrefs* is ``True``.

View file

@ -217,7 +217,7 @@ provides three different variants:
attribute holds the default values for *message* and *explain* that
will be used if no value is provided; for unknown codes the default value
for both is the string ``???``. The body will be empty if the method is
HEAD or the response code is one of the following: ``1xx``,
HEAD or the response code is one of the following: :samp:`1{xx}`,
``204 No Content``, ``205 Reset Content``, ``304 Not Modified``.
.. versionchanged:: 3.4

View file

@ -88,8 +88,8 @@ startup by the :c:func:`PyConfig_Read` function: see
On some systems, conversion using the file system encoding may fail. In this
case, Python uses the :ref:`surrogateescape encoding error handler
<surrogateescape>`, which means that undecodable bytes are replaced by a
Unicode character U+DCxx on decoding, and these are again translated to the
original byte on encoding.
Unicode character U+DC\ *xx* on decoding, and these are again
translated to the original byte on encoding.
The :term:`file system encoding <filesystem encoding and error handler>` must

View file

@ -660,7 +660,7 @@ three digits in length.
Unknown escapes consisting of ``'\'`` and an ASCII letter now are errors.
.. versionchanged:: 3.8
The ``'\N{name}'`` escape sequence has been added. As in string literals,
The :samp:`'\\N\\{{name}\\}'` escape sequence has been added. As in string literals,
it expands to the named Unicode character (e.g. ``'\N{EM DASH}'``).

View file

@ -753,7 +753,7 @@ always available.
Return the current value of the flags that are used for
:c:func:`dlopen` calls. Symbolic names for the flag values can be
found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
found in the :mod:`os` module (:samp:`RTLD_{xxx}` constants, e.g.
:const:`os.RTLD_LAZY`).
.. availability:: Unix.
@ -1441,7 +1441,7 @@ always available.
lazy resolving of symbols when importing a module, if called as
``sys.setdlopenflags(0)``. To share symbols across extension modules, call as
``sys.setdlopenflags(os.RTLD_GLOBAL)``. Symbolic names for the flag values
can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
can be found in the :mod:`os` module (:samp:`RTLD_{xxx}` constants, e.g.
:const:`os.RTLD_LAZY`).
.. availability:: Unix.

View file

@ -598,7 +598,7 @@ task isn't already covered by the URL parsing functions above.
.. function:: quote(string, safe='/', encoding=None, errors=None)
Replace special characters in *string* using the ``%xx`` escape. Letters,
Replace special characters in *string* using the :samp:`%{xx}` escape. Letters,
digits, and the characters ``'_.-~'`` are never quoted. By default, this
function is intended for quoting the path section of a URL. The optional
*safe* parameter specifies additional ASCII characters that should not be
@ -645,7 +645,7 @@ task isn't already covered by the URL parsing functions above.
.. function:: unquote(string, encoding='utf-8', errors='replace')
Replace ``%xx`` escapes with their single-character equivalent.
Replace :samp:`%{xx}` escapes with their single-character equivalent.
The optional *encoding* and *errors* parameters specify how to decode
percent-encoded sequences into Unicode characters, as accepted by the
:meth:`bytes.decode` method.
@ -676,7 +676,7 @@ task isn't already covered by the URL parsing functions above.
.. function:: unquote_to_bytes(string)
Replace ``%xx`` escapes with their single-octet equivalent, and return a
Replace :samp:`%{xx}` escapes with their single-octet equivalent, and return a
:class:`bytes` object.
*string* may be either a :class:`str` or a :class:`bytes` object.

View file

@ -557,51 +557,51 @@ Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in string and
bytes literals are interpreted according to rules similar to those used by
Standard C. The recognized escape sequences are:
+-----------------+---------------------------------+-------+
| Escape Sequence | Meaning | Notes |
+=================+=================================+=======+
| ``\``\ <newline>| Backslash and newline ignored | \(1) |
+-----------------+---------------------------------+-------+
| ``\\`` | Backslash (``\``) | |
+-----------------+---------------------------------+-------+
| ``\'`` | Single quote (``'``) | |
+-----------------+---------------------------------+-------+
| ``\"`` | Double quote (``"``) | |
+-----------------+---------------------------------+-------+
| ``\a`` | ASCII Bell (BEL) | |
+-----------------+---------------------------------+-------+
| ``\b`` | ASCII Backspace (BS) | |
+-----------------+---------------------------------+-------+
| ``\f`` | ASCII Formfeed (FF) | |
+-----------------+---------------------------------+-------+
| ``\n`` | ASCII Linefeed (LF) | |
+-----------------+---------------------------------+-------+
| ``\r`` | ASCII Carriage Return (CR) | |
+-----------------+---------------------------------+-------+
| ``\t`` | ASCII Horizontal Tab (TAB) | |
+-----------------+---------------------------------+-------+
| ``\v`` | ASCII Vertical Tab (VT) | |
+-----------------+---------------------------------+-------+
| ``\ooo`` | Character with octal value | (2,4) |
| | *ooo* | |
+-----------------+---------------------------------+-------+
| ``\xhh`` | Character with hex value *hh* | (3,4) |
+-----------------+---------------------------------+-------+
+-------------------------+---------------------------------+-------+
| Escape Sequence | Meaning | Notes |
+=========================+=================================+=======+
| ``\``\ <newline> | Backslash and newline ignored | \(1) |
+-------------------------+---------------------------------+-------+
| ``\\`` | Backslash (``\``) | |
+-------------------------+---------------------------------+-------+
| ``\'`` | Single quote (``'``) | |
+-------------------------+---------------------------------+-------+
| ``\"`` | Double quote (``"``) | |
+-------------------------+---------------------------------+-------+
| ``\a`` | ASCII Bell (BEL) | |
+-------------------------+---------------------------------+-------+
| ``\b`` | ASCII Backspace (BS) | |
+-------------------------+---------------------------------+-------+
| ``\f`` | ASCII Formfeed (FF) | |
+-------------------------+---------------------------------+-------+
| ``\n`` | ASCII Linefeed (LF) | |
+-------------------------+---------------------------------+-------+
| ``\r`` | ASCII Carriage Return (CR) | |
+-------------------------+---------------------------------+-------+
| ``\t`` | ASCII Horizontal Tab (TAB) | |
+-------------------------+---------------------------------+-------+
| ``\v`` | ASCII Vertical Tab (VT) | |
+-------------------------+---------------------------------+-------+
| :samp:`\\{ooo}` | Character with octal value | (2,4) |
| | *ooo* | |
+-------------------------+---------------------------------+-------+
| :samp:`\\x{hh}` | Character with hex value *hh* | (3,4) |
+-------------------------+---------------------------------+-------+
Escape sequences only recognized in string literals are:
+-----------------+---------------------------------+-------+
| Escape Sequence | Meaning | Notes |
+=================+=================================+=======+
| ``\N{name}`` | Character named *name* in the | \(5) |
| | Unicode database | |
+-----------------+---------------------------------+-------+
| ``\uxxxx`` | Character with 16-bit hex value | \(6) |
| | *xxxx* | |
+-----------------+---------------------------------+-------+
| ``\Uxxxxxxxx`` | Character with 32-bit hex value | \(7) |
| | *xxxxxxxx* | |
+-----------------+---------------------------------+-------+
+-------------------------+---------------------------------+-------+
| Escape Sequence | Meaning | Notes |
+=========================+=================================+=======+
| :samp:`\\N\\{{name}\\}` | Character named *name* in the | \(5) |
| | Unicode database | |
+-------------------------+---------------------------------+-------+
| :samp:`\\u{xxxx}` | Character with 16-bit hex value | \(6) |
| | *xxxx* | |
+-------------------------+---------------------------------+-------+
| :samp:`\\U{xxxxxxxx}` | Character with 32-bit hex value | \(7) |
| | *xxxxxxxx* | |
+-------------------------+---------------------------------+-------+
Notes:

View file

@ -1012,7 +1012,7 @@ differently depending if the ``Py_BUILD_CORE_MODULE`` macro is defined:
* Use ``Py_IMPORTED_SYMBOL`` otherwise.
If the ``Py_BUILD_CORE_BUILTIN`` macro is used by mistake on a C extension
built as a shared library, its ``PyInit_xxx()`` function is not exported,
built as a shared library, its :samp:`PyInit_{xxx}()` function is not exported,
causing an :exc:`ImportError` on import.
@ -1033,8 +1033,8 @@ Preprocessor flags
.. envvar:: CPPFLAGS
(Objective) C/C++ preprocessor flags, e.g. ``-I<include dir>`` if you have
headers in a nonstandard directory ``<include dir>``.
(Objective) C/C++ preprocessor flags, e.g. :samp:`-I{include_dir}` if you have
headers in a nonstandard directory *include_dir*.
Both :envvar:`CPPFLAGS` and :envvar:`LDFLAGS` need to contain the shell's
value to be able to build extension modules using the
@ -1223,8 +1223,8 @@ Linker flags
.. envvar:: LDFLAGS
Linker flags, e.g. ``-L<lib dir>`` if you have libraries in a nonstandard
directory ``<lib dir>``.
Linker flags, e.g. :samp:`-L{lib_dir}` if you have libraries in a nonstandard
directory *lib_dir*.
Both :envvar:`CPPFLAGS` and :envvar:`LDFLAGS` need to contain the shell's
value to be able to build extension modules using the

View file

@ -889,7 +889,7 @@ minor version. I.e. ``/usr/bin/python3.7-32`` will request usage of the
The "-64" suffix is deprecated, and now implies "any architecture that is
not provably i386/32-bit". To request a specific environment, use the new
``-V:<TAG>`` argument with the complete tag.
:samp:`-V:{TAG}` argument with the complete tag.
The ``/usr/bin/env`` form of shebang line has one further special property.
Before looking for installed Python interpreters, this form will search the
@ -1192,7 +1192,7 @@ non-standard paths in the registry and user site-packages.
* Adds ``._pth`` file support and removes ``applocal`` option from
``pyvenv.cfg``.
* Adds ``pythonXX.zip`` as a potential landmark when directly adjacent
* Adds :file:`python{XX}.zip` as a potential landmark when directly adjacent
to the executable.
.. deprecated::

View file

@ -153,9 +153,9 @@ Lundh. A detailed explanation of the interface was written up as :pep:`100`,
significant points about the Unicode interfaces.
In Python source code, Unicode strings are written as ``u"string"``. Arbitrary
Unicode characters can be written using a new escape sequence, ``\uHHHH``, where
Unicode characters can be written using a new escape sequence, :samp:`\\u{HHHH}`, where
*HHHH* is a 4-digit hexadecimal number from 0000 to FFFF. The existing
``\xHHHH`` escape sequence can also be used, and octal escapes can be used for
:samp:`\\x{HH}` escape sequence can also be used, and octal escapes can be used for
characters up to U+01FF, which is represented by ``\777``.
Unicode strings, just like regular strings, are an immutable sequence type.

View file

@ -125,7 +125,7 @@ and to C extension code as :c:data:`!Py_Py3kWarningFlag`.
.. seealso::
The 3xxx series of PEPs, which contains proposals for Python 3.0.
The 3\ *xxx* series of PEPs, which contains proposals for Python 3.0.
:pep:`3000` describes the development process for Python 3.0.
Start with :pep:`3100` that describes the general goals for Python
3.0, and then explore the higher-numbered PEPS that propose

View file

@ -218,7 +218,7 @@ Windows ``py.exe`` launcher improvements
The copy of the :ref:`launcher` included with Python 3.11 has been significantly
updated. It now supports company/tag syntax as defined in :pep:`514` using the
``-V:<company>/<tag>`` argument instead of the limited ``-<major>.<minor>``.
:samp:`-V:{<company>}/{<tag>}` argument instead of the limited :samp:`-{<major>}.{<minor>}`.
This allows launching distributions other than ``PythonCore``,
the one hosted on `python.org <https://www.python.org>`_.
@ -227,8 +227,8 @@ installs will be searched. For example, ``-V:OtherPython/`` will select the
"best" tag registered for ``OtherPython``, while ``-V:3.11`` or ``-V:/3.11``
will select the "best" distribution with tag ``3.11``.
When using the legacy ``-<major>``, ``-<major>.<minor>``,
``-<major>-<bitness>`` or ``-<major>.<minor>-<bitness>`` arguments,
When using the legacy :samp:`-{<major>}`, :samp:`-{<major>}.{<minor>}`,
:samp:`-{<major>}-{<bitness>}` or :samp:`-{<major>}.{<minor>}-{<bitness>}` arguments,
all existing behaviour should be preserved from past versions,
and only releases from ``PythonCore`` will be selected.
However, the ``-64`` suffix now implies "not 32-bit" (not necessarily x86-64),

View file

@ -2067,7 +2067,7 @@ The :pep:`418` added new functions to the :mod:`time` module:
Other new functions:
* :func:`~time.clock_getres`, :func:`~time.clock_gettime` and
:func:`~time.clock_settime` functions with ``CLOCK_xxx`` constants.
:func:`~time.clock_settime` functions with :samp:`CLOCK_{xxx}` constants.
(Contributed by Victor Stinner in :issue:`10278`.)
To improve cross platform consistency, :func:`~time.sleep` now raises a

View file

@ -2085,7 +2085,7 @@ Deprecations in the Python API
:meth:`importlib.abc.MetaPathFinder.find_spec`;
:meth:`!importlib.abc.PathEntryFinder.find_loader` and
:meth:`!find_module` are replaced by
:meth:`importlib.abc.PathEntryFinder.find_spec`; all of the ``xxxLoader`` ABC
:meth:`importlib.abc.PathEntryFinder.find_spec`; all of the :samp:`{xxx}Loader` ABC
``load_module`` methods (:meth:`!importlib.abc.Loader.load_module`,
:meth:`!importlib.abc.InspectLoader.load_module`,
:meth:`!importlib.abc.FileLoader.load_module`,

View file

@ -404,7 +404,7 @@ Other Language Changes
or :meth:`~object.__complex__` is not available.
(Contributed by Serhiy Storchaka in :issue:`20092`.)
* Added support of ``\N{name}`` escapes in :mod:`regular expressions <re>`::
* Added support of :samp:`\\N\\{{name}\\}` escapes in :mod:`regular expressions <re>`::
>>> notice = 'Copyright © 2019'
>>> copyright_year_pattern = re.compile(r'\N{copyright sign}\s*(\d{4})')

View file

@ -5350,7 +5350,7 @@ in a virtual environment.
.. nonce: FbHZuS
.. section: Windows
Fix :file:`py.exe` launcher handling of ``-V:<company>/`` option when
Fix :file:`py.exe` launcher handling of :samp:`-V:{<company>}/` option when
default preferences have been set in environment variables or configuration
files.

View file

@ -8,7 +8,7 @@ The IDNA codec decoder used on DNS hostnames by :mod:`socket` or
:mod:`asyncio` related name resolution functions no longer involves a
quadratic algorithm. This prevents a potential CPU denial of service if an
out-of-spec excessive length hostname involving bidirectional characters
were decoded. Some protocols such as :mod:`urllib` http ``3xx`` redirects
were decoded. Some protocols such as :mod:`urllib` http :samp:`3{xx}` redirects
potentially allow for an attacker to supply such a name.
Individual labels within an IDNA encoded DNS name will now raise an error

View file

@ -9,7 +9,7 @@ within a garbage request to be printed to the stderr server log.
This is done by changing the :mod:`http.server`
:class:`BaseHTTPRequestHandler` ``.log_message`` method to replace control
characters with a ``\xHH`` hex escape before printing.
characters with a :samp:`\\x{HH}` hex escape before printing.
..

View file

@ -168,7 +168,7 @@ Sanad Zaki Rizvi.
Idle editor default font. Switch from Courier to platform-sensitive
TkFixedFont. This should not affect current customized font selections. If
there is a problem, edit $HOME/.idlerc/config-main.cfg and remove 'fontxxx'
there is a problem, edit $HOME/.idlerc/config-main.cfg and remove ':samp:`font{xxx}`'
entries from [Editor Window]. Patch by Mark Roseman.
..

View file

@ -189,7 +189,7 @@ comprehensions correspond to the opening brace.
.. nonce: 0Gh-Ty
.. section: Core and Builtins
Hide the private _Py_atomic_xxx symbols from the public Python.h header to
Hide the private :samp:`_Py_atomic_{xxx}` symbols from the public Python.h header to
fix a compilation error with OpenMP. PyThreadState_GET() becomes an alias to
PyThreadState_Get() to avoid ABI incompatibilities.

View file

@ -8253,7 +8253,7 @@ Explain how IDLE's Shell displays output.
Improve the doc about IDLE running user code. The section is renamed from
"IDLE -- console differences" is renamed "Running user code". It mostly
covers the implications of using custom sys.stdxxx objects.
covers the implications of using custom :samp:sys.std{xxx}` objects.
..

View file

@ -1087,7 +1087,7 @@ on the ABI.
Change ``PyAPI_FUNC(type)``, ``PyAPI_DATA(type)`` and ``PyMODINIT_FUNC``
macros of ``pyport.h`` when ``Py_BUILD_CORE_MODULE`` is defined. The
``Py_BUILD_CORE_MODULE`` define must be now be used to build a C extension
as a dynamic library accessing Python internals: export the PyInit_xxx()
as a dynamic library accessing Python internals: export the :samp:`PyInit_{xxx}()`
function in DLL exports on Windows.
..

View file

@ -4118,7 +4118,7 @@ Add tests for ROT-13 codec.
.. nonce: Zoe9ek
.. section: Tests
Added tests for PyDateTime_xxx_GET_xxx() macros of the C API of the
Added tests for :samp:`PyDateTime_{xxx}_GET_{xxx}()` macros of the C API of the
:mod:`datetime` module. Patch by Joannah Nanjekye.
..
@ -4576,7 +4576,7 @@ distutils bdist_wininst: bdist_wininst only works on Windows.
.. nonce: j5ebdT
.. section: Build
Many ``PyRun_XXX()`` functions like :c:func:`PyRun_String` were no longer
Many :samp:`PyRun_{XXX}()` functions like :c:func:`PyRun_String` were no longer
exported in ``libpython38.dll`` by mistake. Export them again to fix the ABI
compatibility.