traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[3.9] bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) (GH-21901) 

* bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844)

Enable Sphinx 3.2 "c_allow_pre_v3" option and disable the
c_warn_on_allowed_pre_v3 option to make the documentation compatible
with Sphinx 2 and Sphinx 3.

(cherry picked from commit 423e77d6de)

* bpo-40204: Fix Sphinx sytanx in howto/instrumentation.rst (GH-21858)

Use generic '.. object::' to declare markers, rather than abusing
'..  c:function::' which fails on Sphinx 3.

(cherry picked from commit 43577c01a2)

* bpo-40204: Fix duplicates in the documentation (GH-21857)

Fix two Sphinx 3 issues:

Doc/c-api/buffer.rst:304: WARNING: Duplicate C declaration, also defined in 'c-api/buffer'.
Declaration is 'PyBUF_ND'.

Doc/c-api/unicode.rst:1603: WARNING: Duplicate C declaration, also defined in 'c-api/unicode'.
Declaration is 'PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)'.

(cherry picked from commit 46d10b1237)

* bpo-40204: Add :noindex: in the documentation (GH-21859)

Add :noindex: to duplicated documentation to fix "duplicate object
description" errors.

For example, fix this Sphinx 3 issue:

Doc/library/configparser.rst:1146: WARNING: duplicate object
description of configparser.ConfigParser.optionxform, other instance
in library/configparser, use :noindex: for one of them

(cherry picked from commit d3ded08048)

* bpo-40204, doc: Fix syntax of C variables (GH-21846)

For example, fix the following Sphinx 3 errors:

Doc/c-api/buffer.rst:102: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 5]
  void \*obj
  -----^

Doc/c-api/arg.rst:130: WARNING: Unparseable C cross-reference: 'PyObject*'
Invalid C declaration: Expected end of definition. [error at 8]
  PyObject*
  --------^

The modified documentation is compatible with Sphinx 2 and Sphinx 3.

(cherry picked from commit 474652fe93)

* bpo-40204: Fix reference to terms in the doc (GH-21865)

Sphinx 3 requires to refer to terms with the exact case.

For example, fix the Sphinx 3 warning:

Doc/library/pkgutil.rst:71: WARNING: term Loader not found in case
sensitive match.made a reference to loader instead.

(cherry picked from commit bb0b08540c)

* bpo-40204: Fix duplicated productionlist names in the doc (GH-21900)

Sphinx 3 disallows having more than one productionlist markup with
the same name. Simply remove names in this case, since names are not
shown anyway. For example, fix the Sphinx 3 warning:

Doc/reference/introduction.rst:96: duplicate token description
of *:name, other instance in reference/expressions

(cherry picked from commit 1abeda80f7)
This commit is contained in:
Victor Stinner 2020-08-19 19:25:22 +02:00 committed by GitHub
parent e3cafebb5c
commit 8f88190af5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
47 changed files with 254 additions and 240 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
Doc/c-api/arg.rst
View File

@ -131,12 +131,12 @@ which disallows mutable objects such as :class:`bytearray`.
``S`` (:class:`bytes`) [PyBytesObject \*]
Requires that the Python object is a :class:`bytes` object, without
attempting any conversion. Raises :exc:`TypeError` if the object is not
a bytes object. The C variable may also be declared as :c:type:`PyObject\*`.
a bytes object. The C variable may also be declared as :c:type:`PyObject*`.
``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
Requires that the Python object is a :class:`bytearray` object, without
attempting any conversion. Raises :exc:`TypeError` if the object is not
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject*`.
``u`` (:class:`str`) [const Py_UNICODE \*]
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
@ -183,7 +183,7 @@ which disallows mutable objects such as :class:`bytearray`.
``U`` (:class:`str`) [PyObject \*]
Requires that the Python object is a Unicode object, without attempting
any conversion. Raises :exc:`TypeError` if the object is not a Unicode
object. The C variable may also be declared as :c:type:`PyObject\*`.
object. The C variable may also be declared as :c:type:`PyObject*`.
``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
This format accepts any object which implements the read-write buffer
@ -196,10 +196,10 @@ which disallows mutable objects such as :class:`bytearray`.
It only works for encoded data without embedded NUL bytes.
This format requires two arguments. The first is only used as input, and
must be a :c:type:`const char\*` which points to the name of an encoding as a
must be a :c:type:`const char*` which points to the name of an encoding as a
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:type:`char\*\*`; the value of the pointer it
second argument must be a :c:type:`char**`; the value of the pointer it
references will be set to a buffer with the contents of the argument text.
The text will be encoded in the encoding specified by the first argument.
@ -219,10 +219,10 @@ which disallows mutable objects such as :class:`bytearray`.
characters.
It requires three arguments. The first is only used as input, and must be a
:c:type:`const char\*` which points to the name of an encoding as a
:c:type:`const char*` which points to the name of an encoding as a
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:type:`char\*\*`; the value of the pointer it
second argument must be a :c:type:`char**`; the value of the pointer it
references will be set to a buffer with the contents of the argument text.
The text will be encoded in the encoding specified by the first argument.
The third argument must be a pointer to an integer; the referenced integer
@ -322,7 +322,7 @@ Other objects
``O!`` (object) [*typeobject*, PyObject \*]
Store a Python object in a C object pointer. This is similar to ``O``, but
takes two C arguments: the first is the address of a Python type object, the
second is the address of the C variable (of type :c:type:`PyObject\*`) into which
second is the address of the C variable (of type :c:type:`PyObject*`) into which
the object pointer is stored. If the Python object does not have the required
type, :exc:`TypeError` is raised.
@ -331,13 +331,13 @@ Other objects
``O&`` (object) [*converter*, *anything*]
Convert a Python object to a C variable through a *converter* function. This
takes two arguments: the first is a function, the second is the address of a C
variable (of arbitrary type), converted to :c:type:`void \*`. The *converter*
variable (of arbitrary type), converted to :c:type:`void *`. The *converter*
function in turn is called as follows::
status = converter(object, address);
where *object* is the Python object to be converted and *address* is the
:c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
:c:type:`void*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
The returned *status* should be ``1`` for a successful conversion and ``0`` if
the conversion has failed. When the conversion fails, the *converter* function
should raise an exception and leave the content of *address* unmodified.
@ -483,7 +483,7 @@ API Functions
*args*; it must actually be a tuple. The length of the tuple must be at least
*min* and no more than *max*; *min* and *max* may be equal. Additional
arguments must be passed to the function, each of which should be a pointer to a
:c:type:`PyObject\*` variable; these will be filled in with the values from
:c:type:`PyObject*` variable; these will be filled in with the values from
*args*; they will contain borrowed references. The variables which correspond
to optional parameters not given by *args* will not be filled in; these should
be initialized by the caller. This function returns true on success and false if
@ -652,8 +652,8 @@ Building values
``O&`` (object) [*converter*, *anything*]
Convert *anything* to a Python object through a *converter* function. The
function is called with *anything* (which should be compatible with :c:type:`void
\*`) as its argument and should return a "new" Python object, or ``NULL`` if an
function is called with *anything* (which should be compatible with :c:type:`void*`)
as its argument and should return a "new" Python object, or ``NULL`` if an
error occurred.
``(items)`` (:class:`tuple`) [*matching-items*]

28
Doc/c-api/buffer.rst
View File

@ -89,7 +89,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
.. c:type:: Py_buffer
.. c:member:: void \*buf
.. c:member:: void *buf
A pointer to the start of the logical structure described by the buffer
fields. This can be any location within the underlying physical memory
@ -99,7 +99,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
For :term:`contiguous` arrays, the value points to the beginning of
the memory block.
.. c:member:: void \*obj
.. c:member:: void *obj
A new reference to the exporting object. The reference is owned by
the consumer and automatically decremented and set to ``NULL`` by
@ -145,7 +145,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
:c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
.. c:member:: const char \*format
.. c:member:: const char *format
A *NUL* terminated string in :mod:`struct` module style syntax describing
the contents of a single item. If this is ``NULL``, ``"B"`` (unsigned bytes)
@ -164,7 +164,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
to 64. Exporters MUST respect this limit, consumers of multi-dimensional
buffers SHOULD be able to handle up to :c:macro:`PyBUF_MAX_NDIM` dimensions.
.. c:member:: Py_ssize_t \*shape
.. c:member:: Py_ssize_t *shape
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
indicating the shape of the memory as an n-dimensional array. Note that
@ -177,7 +177,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
The shape array is read-only for the consumer.
.. c:member:: Py_ssize_t \*strides
.. c:member:: Py_ssize_t *strides
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
giving the number of bytes to skip to get to a new element in each
@ -189,7 +189,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
The strides array is read-only for the consumer.
.. c:member:: Py_ssize_t \*suboffsets
.. c:member:: Py_ssize_t *suboffsets
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`.
If ``suboffsets[n] >= 0``, the values stored along the nth dimension are
@ -207,7 +207,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
The suboffsets array is read-only for the consumer.
.. c:member:: void \*internal
.. c:member:: void *internal
This is for use internally by the exporting object. For example, this
might be re-cast as an integer by the exporter and used to store flags
@ -301,7 +301,7 @@ must be C-contiguous.
+-----------------------------------+-------+---------+------------+--------+
| .. c:macro:: PyBUF_ANY_CONTIGUOUS | yes | yes | NULL | C or F |
+-----------------------------------+-------+---------+------------+--------+
| .. c:macro:: PyBUF_ND | yes | NULL | NULL | C |
| :c:macro:`PyBUF_ND` | yes | NULL | NULL | C |
+-----------------------------------+-------+---------+------------+--------+
@ -438,12 +438,12 @@ Buffer-related functions
Send a request to *exporter* to fill in *view* as specified by *flags*.
If the exporter cannot provide a buffer of the exact type, it MUST raise
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to ``NULL`` and
:c:data:`PyExc_BufferError`, set ``view->obj`` to ``NULL`` and
return ``-1``.
On success, fill in *view*, set :c:member:`view->obj` to a new reference
On success, fill in *view*, set ``view->obj`` to a new reference
to *exporter* and return 0. In the case of chained buffer providers
that redirect requests to a single object, :c:member:`view->obj` MAY
that redirect requests to a single object, ``view->obj`` MAY
refer to this object instead of *exporter* (See :ref:`Buffer Object Structures <buffer-structs>`).
Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls
@ -455,7 +455,7 @@ Buffer-related functions
.. c:function:: void PyBuffer_Release(Py_buffer *view)
Release the buffer *view* and decrement the reference count for
:c:member:`view->obj`. This function MUST be called when the buffer
``view->obj``. This function MUST be called when the buffer
is no longer being used, otherwise reference leaks may occur.
It is an error to call this function on a buffer that was not obtained via
@ -516,9 +516,9 @@ Buffer-related functions
*view* as specified by flags, unless *buf* has been designated as read-only
and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
On success, set :c:member:`view->obj` to a new reference to *exporter* and
On success, set ``view->obj`` to a new reference to *exporter* and
return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
:c:member:`view->obj` to ``NULL`` and return ``-1``;
``view->obj`` to ``NULL`` and return ``-1``;
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
*exporter* MUST be set to the exporting object and *flags* must be passed

14
Doc/c-api/call.rst
View File

@ -84,7 +84,7 @@ This is a pointer to a function with the following signature:
and they must be unique.
If there are no keyword arguments, then *kwnames* can instead be *NULL*.
.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET
.. c:macro:: PY_VECTORCALL_ARGUMENTS_OFFSET
If this flag is set in a vectorcall *nargsf* argument, the callee is allowed
to temporarily change ``args[-1]``. In other words, *args* points to
@ -283,7 +283,7 @@ please see individual documentation for details.
This is the equivalent of the Python expression: ``callable(*args)``.
Note that if you only pass :c:type:`PyObject \*` args,
Note that if you only pass :c:type:`PyObject *` args,
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
.. versionchanged:: 3.4
@ -304,17 +304,17 @@ please see individual documentation for details.
This is the equivalent of the Python expression:
``obj.name(arg1, arg2, ...)``.
Note that if you only pass :c:type:`PyObject \*` args,
Note that if you only pass :c:type:`PyObject *` args,
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
.. versionchanged:: 3.4
The types of *name* and *format* were changed from ``char *``.
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...)
Call a callable Python object *callable*, with a variable number of
:c:type:`PyObject \*` arguments. The arguments are provided as a variable number
:c:type:`PyObject *` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*.
Return the result of the call on success, or raise an exception and return
@ -324,11 +324,11 @@ please see individual documentation for details.
``callable(arg1, arg2, ...)``.
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)
Call a method of the Python object *obj*, where the name of the method is given as a
Python string object in *name*. It is called with a variable number of
:c:type:`PyObject \*` arguments. The arguments are provided as a variable number
:c:type:`PyObject *` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*.
Return the result of the call on success, or raise an exception and return

2
Doc/c-api/capsule.rst
View File

@ -15,7 +15,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:type:: PyCapsule
This subtype of :c:type:`PyObject` represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a :c:type:`void\*`
extension modules who need to pass an opaque value (as a :c:type:`void*`
pointer) through Python code to other C code. It is often used to make a C
function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically

6
Doc/c-api/dict.rst
View File

@ -73,7 +73,7 @@ Dictionary Objects
.. index:: single: PyUnicode_FromString()
Insert *val* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`const char\*`. The key object is created using
be a :c:type:`const char*`. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure. This function *does not* steal a reference to *val*.
@ -112,7 +112,7 @@ Dictionary Objects
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
:c:type:`const char\*`, rather than a :c:type:`PyObject\*`.
:c:type:`const char*`, rather than a :c:type:`PyObject*`.
Note that exceptions which occur while calling :meth:`__hash__` and
:meth:`__eq__` methods and creating a temporary string object
@ -161,7 +161,7 @@ Dictionary Objects
prior to the first call to this function to start the iteration; the
function returns true for each pair in the dictionary, and false once all
pairs have been reported. The parameters *pkey* and *pvalue* should either
point to :c:type:`PyObject\*` variables that will be filled in with each key
point to :c:type:`PyObject*` variables that will be filled in with each key
and value, respectively, or may be ``NULL``. Any references returned through
them are borrowed. *ppos* should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and

4
Doc/c-api/exceptions.rst
View File

@ -783,7 +783,7 @@ Standard Exceptions
All standard Python exceptions are available as global variables whose names are
``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
:c:type:`PyObject*`; they are all class objects. For completeness, here are all
the variables:
.. index::
@ -1003,7 +1003,7 @@ Standard Warning Categories
All standard Python warning categories are available as global variables whose
names are ``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
:c:type:`PyObject*`; they are all class objects. For completeness, here are all
the variables:
.. index::

4
Doc/c-api/file.rst
View File

@ -8,7 +8,7 @@ File Objects
.. index:: object: file
These APIs are a minimal emulation of the Python 2 C API for built-in file
objects, which used to rely on the buffered I/O (:c:type:`FILE\*`) support
objects, which used to rely on the buffered I/O (:c:type:`FILE*`) support
from the C standard library. In Python 3, files and streams use the new
:mod:`io` module, which defines several layers over the low-level unbuffered
I/O of the operating system. The functions described below are
@ -17,7 +17,7 @@ error reporting in the interpreter; third-party code is advised to access
the :mod:`io` APIs instead.
.. c:function:: PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
.. c:function:: PyObject* PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
Create a Python file object from the file descriptor of an already
opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline*

48
Doc/c-api/init.rst
View File

@ -81,7 +81,7 @@ When a flag is set by an option, the value of the flag is the number of times
that the option was set. For example, ``-b`` sets :c:data:`Py_BytesWarningFlag`
to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. c:var:: Py_BytesWarningFlag
.. c:var:: int Py_BytesWarningFlag
Issue a warning when comparing :class:`bytes` or :class:`bytearray` with
:class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater
@ -89,7 +89,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-b` option.
.. c:var:: Py_DebugFlag
.. c:var:: int Py_DebugFlag
Turn on parser debugging output (for expert only, depending on compilation
options).
@ -97,7 +97,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
variable.
.. c:var:: Py_DontWriteBytecodeFlag
.. c:var:: int Py_DontWriteBytecodeFlag
If set to non-zero, Python won't try to write ``.pyc`` files on the
import of source modules.
@ -105,14 +105,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
environment variable.
.. c:var:: Py_FrozenFlag
.. c:var:: int Py_FrozenFlag
Suppress error messages when calculating the module search path in
:c:func:`Py_GetPath`.
Private flag used by ``_freeze_importlib`` and ``frozenmain`` programs.
.. c:var:: Py_HashRandomizationFlag
.. c:var:: int Py_HashRandomizationFlag
Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to
a non-empty string.
@ -120,14 +120,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
variable to initialize the secret hash seed.
.. c:var:: Py_IgnoreEnvironmentFlag
.. c:var:: int Py_IgnoreEnvironmentFlag
Ignore all :envvar:`PYTHON*` environment variables, e.g.
:envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
Set by the :option:`-E` and :option:`-I` options.
.. c:var:: Py_InspectFlag
.. c:var:: int Py_InspectFlag
When a script is passed as first argument or the :option:`-c` option is used,
enter interactive mode after executing the script or the command, even when
@ -136,11 +136,11 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
variable.
.. c:var:: Py_InteractiveFlag
.. c:var:: int Py_InteractiveFlag
Set by the :option:`-i` option.
.. c:var:: Py_IsolatedFlag
.. c:var:: int Py_IsolatedFlag
Run Python in isolated mode. In isolated mode :data:`sys.path` contains
neither the script's directory nor the user's site-packages directory.
@ -149,7 +149,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. versionadded:: 3.4
.. c:var:: Py_LegacyWindowsFSEncodingFlag
.. c:var:: int Py_LegacyWindowsFSEncodingFlag
If the flag is non-zero, use the ``mbcs`` encoding instead of the UTF-8
encoding for the filesystem encoding.
@ -161,7 +161,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. availability:: Windows.
.. c:var:: Py_LegacyWindowsStdioFlag
.. c:var:: int Py_LegacyWindowsStdioFlag
If the flag is non-zero, use :class:`io.FileIO` instead of
:class:`WindowsConsoleIO` for :mod:`sys` standard streams.
@ -173,7 +173,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. availability:: Windows.
.. c:var:: Py_NoSiteFlag
.. c:var:: int Py_NoSiteFlag
Disable the import of the module :mod:`site` and the site-dependent
manipulations of :data:`sys.path` that it entails. Also disable these
@ -182,7 +182,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-S` option.
.. c:var:: Py_NoUserSiteDirectory
.. c:var:: int Py_NoUserSiteDirectory
Don't add the :data:`user site-packages directory <site.USER_SITE>` to
:data:`sys.path`.
@ -190,12 +190,12 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-s` and :option:`-I` options, and the
:envvar:`PYTHONNOUSERSITE` environment variable.
.. c:var:: Py_OptimizeFlag
.. c:var:: int Py_OptimizeFlag
Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
variable.
.. c:var:: Py_QuietFlag
.. c:var:: int Py_QuietFlag
Don't display the copyright and version messages even in interactive mode.
@ -203,14 +203,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. versionadded:: 3.2
.. c:var:: Py_UnbufferedStdioFlag
.. c:var:: int Py_UnbufferedStdioFlag
Force the stdout and stderr streams to be unbuffered.
Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
environment variable.
.. c:var:: Py_VerboseFlag
.. c:var:: int Py_VerboseFlag
Print a message each time a module is initialized, showing the place
(filename or built-in module) from which it is loaded. If greater or equal
@ -830,7 +830,7 @@ code, or when embedding the Python interpreter:
.. c:type:: PyThreadState
This data structure represents the state of a single thread. The only public
data member is :c:type:`PyInterpreterState \*`:attr:`interp`, which points to
data member is :attr:`interp` (:c:type:`PyInterpreterState *`), which points to
this thread's interpreter state.
@ -1619,7 +1619,7 @@ The Python interpreter provides low-level support for thread-local storage
(TLS) which wraps the underlying native TLS implementation to support the
Python-level thread local storage API (:class:`threading.local`). The
CPython C level APIs are similar to those offered by pthreads and Windows:
use a thread key and functions to associate a :c:type:`void\*` value per
use a thread key and functions to associate a :c:type:`void*` value per
thread.
The GIL does *not* need to be held when calling these functions; they supply
@ -1630,8 +1630,8 @@ you need to include :file:`pythread.h` to use thread-local storage.
.. note::
None of these API functions handle memory management on behalf of the
:c:type:`void\*` values. You need to allocate and deallocate them yourself.
If the :c:type:`void\*` values happen to be :c:type:`PyObject\*`, these
:c:type:`void*` values. You need to allocate and deallocate them yourself.
If the :c:type:`void*` values happen to be :c:type:`PyObject*`, these
functions don't do refcount operations on them either.
.. _thread-specific-storage-api:
@ -1727,14 +1727,14 @@ undefined if the given :c:type:`Py_tss_t` has not been initialized by
.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value)
Return a zero value to indicate successfully associating a :c:type:`void\*`
Return a zero value to indicate successfully associating a :c:type:`void*`
value with a TSS key in the current thread. Each thread has a distinct
mapping of the key to a :c:type:`void\*` value.
mapping of the key to a :c:type:`void*` value.
.. c:function:: void* PyThread_tss_get(Py_tss_t *key)
Return the :c:type:`void\*` value associated with a TSS key in the current
Return the :c:type:`void*` value associated with a TSS key in the current
thread. This returns ``NULL`` if no value is associated with the key in the
current thread.

6
Doc/c-api/intro.rst
View File

@ -229,13 +229,13 @@ Objects, Types and Reference Counts
.. index:: object: type
Most Python/C API functions have one or more arguments as well as a return value
of type :c:type:`PyObject\*`. This type is a pointer to an opaque data type
of type :c:type:`PyObject*`. This type is a pointer to an opaque data type
representing an arbitrary Python object. Since all Python object types are
treated the same way by the Python language in most situations (e.g.,
assignments, scope rules, and argument passing), it is only fitting that they
should be represented by a single C type. Almost all Python objects live on the
heap: you never declare an automatic or static variable of type
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\*` can be
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject*` can be
declared. The sole exception are the type objects; since these must never be
deallocated, they are typically static :c:type:`PyTypeObject` objects.
@ -496,7 +496,7 @@ Types
There are few other data types that play a significant role in the Python/C
API; most are simple C types such as :c:type:`int`, :c:type:`long`,
:c:type:`double` and :c:type:`char\*`. A few structure types are used to
:c:type:`double` and :c:type:`char*`. A few structure types are used to
describe static tables used to list the functions exported by a module or the
data attributes of a new object type, and another is used to describe the value
of a complex number. These will be discussed together with the functions that

8
Doc/c-api/marshal.rst
View File

@ -43,7 +43,7 @@ The following functions allow marshalled values to be read back in.
.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
Return a C :c:type:`long` from the data stream in a :c:type:`FILE\*` opened
Return a C :c:type:`long` from the data stream in a :c:type:`FILE*` opened
for reading. Only a 32-bit value can be read in using this function,
regardless of the native size of :c:type:`long`.
@ -53,7 +53,7 @@ The following functions allow marshalled values to be read back in.
.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
Return a C :c:type:`short` from the data stream in a :c:type:`FILE\*` opened
Return a C :c:type:`short` from the data stream in a :c:type:`FILE*` opened
for reading. Only a 16-bit value can be read in using this function,
regardless of the native size of :c:type:`short`.
@ -63,7 +63,7 @@ The following functions allow marshalled values to be read back in.
.. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
Return a Python object from the data stream in a :c:type:`FILE*` opened for
reading.
On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
@ -72,7 +72,7 @@ The following functions allow marshalled values to be read back in.
.. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
Return a Python object from the data stream in a :c:type:`FILE*` opened for
reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function
assumes that no further objects will be read from the file, allowing it to
aggressively load file data into memory so that the de-serialization can

26
Doc/c-api/memory.rst
View File

@ -109,7 +109,7 @@ zero bytes.
.. c:function:: void* PyMem_RawMalloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the
allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
@ -120,7 +120,7 @@ zero bytes.
.. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void\*` to the allocated memory, or ``NULL`` if the
a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct
@ -180,7 +180,7 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
.. c:function:: void* PyMem_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the
allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
@ -191,7 +191,7 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
.. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void\*` to the allocated memory, or ``NULL`` if the
a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct
@ -233,14 +233,14 @@ The following type-oriented macros are provided for convenience. Note that
.. c:function:: TYPE* PyMem_New(TYPE, size_t n)
Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
memory. Returns a pointer cast to :c:type:`TYPE\*`. The memory will not have
memory. Returns a pointer cast to :c:type:`TYPE*`. The memory will not have
been initialized in any way.
.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE\*`. On return,
sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE*`. On return,
*p* will be a pointer to the new memory area, or ``NULL`` in the event of
failure.
@ -282,7 +282,7 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
.. c:function:: void* PyObject_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the
allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
@ -293,7 +293,7 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void\*` to the allocated memory, or ``NULL`` if the
a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct
@ -388,7 +388,7 @@ Customize Memory Allocators
Enum used to identify an allocator domain. Domains:
.. c:var:: PYMEM_DOMAIN_RAW
.. c:macro:: PYMEM_DOMAIN_RAW
Functions:
@ -397,7 +397,7 @@ Customize Memory Allocators
* :c:func:`PyMem_RawCalloc`
* :c:func:`PyMem_RawFree`
.. c:var:: PYMEM_DOMAIN_MEM
.. c:macro:: PYMEM_DOMAIN_MEM
Functions:
@ -406,7 +406,7 @@ Customize Memory Allocators
* :c:func:`PyMem_Calloc`
* :c:func:`PyMem_Free`
.. c:var:: PYMEM_DOMAIN_OBJ
.. c:macro:: PYMEM_DOMAIN_OBJ
Functions:
@ -519,11 +519,11 @@ Customize pymalloc Arena Allocator
| ``void free(void *ctx, size_t size, void *ptr)`` | free an arena |
+--------------------------------------------------+---------------------------------------+
.. c:function:: PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)
.. c:function:: void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)
Get the arena allocator.
.. c:function:: PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)
.. c:function:: void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)
Set the arena allocator.

4
Doc/c-api/module.rst
View File

@ -325,7 +325,7 @@ The *m_slots* array must be terminated by a slot with id 0.
The available slot types are:
.. c:var:: Py_mod_create
.. c:macro:: Py_mod_create
Specifies a function that is called to create the module object itself.
The *value* pointer of this slot must point to a function of the signature:
@ -357,7 +357,7 @@ The available slot types are:
``PyModuleDef`` has non-``NULL`` ``m_traverse``, ``m_clear``,
``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``.
.. c:var:: Py_mod_exec
.. c:macro:: Py_mod_exec
Specifies a function that is called to *execute* the module.
This is equivalent to executing the code of a Python module: typically,

2
Doc/c-api/object.rst
View File

@ -291,7 +291,7 @@ Object Protocol
is equivalent to the Python expression ``type(o)``. This function increments the
reference count of the return value. There's really no reason to use this
function instead of the common expression ``o->ob_type``, which returns a
pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
pointer of type :c:type:`PyTypeObject*`, except when the incremented reference
count is needed.

18
Doc/c-api/structures.rst
View File

@ -141,7 +141,7 @@ Implementing functions and methods
.. c:type:: PyCFunction
Type of the functions used to implement most Python callables in C.
Functions of this type take two :c:type:`PyObject\*` parameters and return
Functions of this type take two :c:type:`PyObject*` parameters and return
one such value. If the return value is ``NULL``, an exception shall have
been set. If not ``NULL``, the return value is interpreted as the return
value of the function as exposed in Python. The function must return a new
@ -220,10 +220,10 @@ Implementing functions and methods
+------------------+---------------+-------------------------------+
The :attr:`ml_meth` is a C function pointer. The functions may be of different
types, but they always return :c:type:`PyObject\*`. If the function is not of
types, but they always return :c:type:`PyObject*`. If the function is not of
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
Even though :c:type:`PyCFunction` defines the first parameter as
:c:type:`PyObject\*`, it is common that the method implementation uses the
:c:type:`PyObject*`, it is common that the method implementation uses the
specific C type of the *self* object.
The :attr:`ml_flags` field is a bitfield which can include the following flags.
@ -235,7 +235,7 @@ There are these calling conventions:
.. data:: METH_VARARGS
This is the typical calling convention, where the methods have the type
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject*` values.
The first one is the *self* object for methods; for module functions, it is
the module object. The second parameter (often called *args*) is a tuple
object representing all arguments. This parameter is typically processed
@ -256,7 +256,7 @@ There are these calling conventions:
Fast calling convention supporting only positional arguments.
The methods have the type :c:type:`_PyCFunctionFast`.
The first parameter is *self*, the second parameter is a C array
of :c:type:`PyObject\*` values indicating the arguments and the third
of :c:type:`PyObject*` values indicating the arguments and the third
parameter is the number of arguments (the length of the array).
This is not part of the :ref:`limited API <stable>`.
@ -270,7 +270,7 @@ There are these calling conventions:
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
Keyword arguments are passed the same way as in the
:ref:`vectorcall protocol <vectorcall>`:
there is an additional fourth :c:type:`PyObject\*` parameter
there is an additional fourth :c:type:`PyObject*` parameter
which is a tuple representing the names of the keyword arguments
(which are guaranteed to be strings)
or possibly ``NULL`` if there are no keywords. The values of the keyword
@ -308,7 +308,7 @@ There are these calling conventions:
Methods with a single object argument can be listed with the :const:`METH_O`
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
:c:type:`PyObject\*` parameter representing the single argument.
:c:type:`PyObject*` parameter representing the single argument.
These two constants are not used to indicate the calling convention but the
@ -459,7 +459,7 @@ Accessing attributes of extension types
| | | getter and setter |
+-------------+------------------+-----------------------------------+
The ``get`` function takes one :c:type:`PyObject\*` parameter (the
The ``get`` function takes one :c:type:`PyObject*` parameter (the
instance) and a function pointer (the associated ``closure``)::
typedef PyObject *(*getter)(PyObject *, void *);
@ -467,7 +467,7 @@ Accessing attributes of extension types
It should return a new reference on success or ``NULL`` with a set exception
on failure.
``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
``set`` functions take two :c:type:`PyObject*` parameters (the instance and
the value to be set) and a function pointer (the associated ``closure``)::
typedef int (*setter)(PyObject *, PyObject *, void *);

2
Doc/c-api/tuple.rst
View File

@ -161,7 +161,7 @@ type.
.. c:type:: PyStructSequence_Field
Describes a field of a struct sequence. As a struct sequence is modeled as a
tuple, all fields are typed as :c:type:`PyObject\*`. The index in the
tuple, all fields are typed as :c:type:`PyObject*`. The index in the
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
field of the struct sequence is described.

4
Doc/c-api/typeobj.rst
View File

@ -1348,7 +1348,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The following macro is defined to ease writing rich comparison functions:
.. c:function:: PyObject \*Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op)
.. c:macro:: Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, op)
Return ``Py_True`` or ``Py_False`` from the function, depending on the
result of a comparison.
@ -1386,7 +1386,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
than zero and contains the offset in the instance structure of the weak
reference list head (ignoring the GC header, if present); this offset is used by
:c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The
instance structure needs to include a field of type :c:type:`PyObject\*` which is
instance structure needs to include a field of type :c:type:`PyObject*` which is
initialized to ``NULL``.
Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for

37
Doc/c-api/unicode.rst
View File

@ -199,7 +199,7 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. c:function:: PyUnicode_MAX_CHAR_VALUE(PyObject *o)
.. c:macro:: PyUnicode_MAX_CHAR_VALUE(o)
Return the maximum code point that is suitable for creating another string
based on *o*, which must be in the "canonical" representation. This is
@ -1503,17 +1503,21 @@ These are the mapping codec APIs:
The following codec API is special in that maps Unicode to Unicode.
.. c:function:: PyObject* PyUnicode_Translate(PyObject *unicode, \
PyObject *mapping, const char *errors)
.. c:function:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
Translate a Unicode object using the given *mapping* object and return the
Translate a string by applying a character mapping table to it and return the
resulting Unicode object. Return ``NULL`` if an exception was raised by the
codec.
The *mapping* object must map Unicode ordinal integers to Unicode strings,
integers (which are then interpreted as Unicode ordinals) or ``None``
(causing deletion of the character). Unmapped character ordinals (ones
which cause a :exc:`LookupError`) are left untouched and are copied as-is.
The mapping table must map Unicode ordinal integers to Unicode ordinal integers
or ``None`` (causing deletion of the character).
Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
*errors* has the usual meaning for codecs. It may be ``NULL`` which indicates to
use the default error handling.
.. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, \
@ -1616,23 +1620,6 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
characters are not included in the resulting strings.
.. c:function:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, \
const char *errors)
Translate a string by applying a character mapping table to it and return the
resulting Unicode object.
The mapping table must map Unicode ordinal integers to Unicode ordinal integers
or ``None`` (causing deletion of the character).
Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
*errors* has the usual meaning for codecs. It may be ``NULL`` which indicates to
use the default error handling.
.. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
Join a sequence of strings using the given *separator* and return the resulting

4
Doc/c-api/veryhigh.rst
View File

@ -16,11 +16,11 @@ parameter. The available start symbols are :const:`Py_eval_input`,
:const:`Py_file_input`, and :const:`Py_single_input`. These are described
following the functions which accept them as parameters.
Note also that several of these functions take :c:type:`FILE\*` parameters. One
Note also that several of these functions take :c:type:`FILE*` parameters. One
particular issue which needs to be handled carefully is that the :c:type:`FILE`
structure for different C libraries can be different and incompatible. Under
Windows (at least), it is possible for dynamically linked extensions to actually
use different libraries, so care should be taken that :c:type:`FILE\*` parameters
use different libraries, so care should be taken that :c:type:`FILE*` parameters
are only passed to these functions if it is certain that they were created by
the same library that the Python runtime is using.

10
Doc/conf.py
View File

@ -228,3 +228,13 @@ linkcheck_ignore = [r'https://bugs.python.org/(issue)?\d+',
# Relative filename of the reference count data file.
refcount_file = 'data/refcounts.dat'
# Sphinx 2 and Sphinx 3 compatibility
# -----------------------------------
# bpo-40204: Allow Sphinx 2 syntax in the C domain
c_allow_pre_v3 = True
# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the
# documentation is built with -W (warnings treated as errors).
c_warn_on_allowed_pre_v3 = False

2
Doc/extending/newtypes_tutorial.rst
View File

@ -416,7 +416,7 @@ But this would be risky. Our type doesn't restrict the type of the
``first`` member, so it could be any kind of object. It could have a
destructor that causes code to be executed that tries to access the
``first`` member; or that destructor could release the
:term:`Global interpreter Lock` and let arbitrary code run in other
:term:`Global interpreter Lock <GIL>` and let arbitrary code run in other
threads that accesses and modifies our object.
To be paranoid and protect ourselves against this possibility, we almost

2
Doc/glossary.rst
View File

@ -587,7 +587,7 @@ Glossary
and :class:`tuple`) and some non-sequence types like :class:`dict`,
:term:`file objects <file object>`, and objects of any classes you define
with an :meth:`__iter__` method or with a :meth:`__getitem__` method
that implements :term:`Sequence` semantics.
that implements :term:`Sequence <sequence>` semantics.
Iterables can be
used in a :keyword:`for` loop and in many other places where a sequence is

24
Doc/howto/instrumentation.rst
View File

@ -272,9 +272,7 @@ should instead read:
Available static markers
------------------------
.. I'm reusing the "c:function" type for markers
.. c:function:: function__entry(str filename, str funcname, int lineno)
.. object:: function__entry(str filename, str funcname, int lineno)
This marker indicates that execution of a Python function has begun.
It is only triggered for pure-Python (bytecode) functions.
@ -290,7 +288,7 @@ Available static markers
* ``$arg3`` : ``int`` line number
.. c:function:: function__return(str filename, str funcname, int lineno)
.. object:: function__return(str filename, str funcname, int lineno)
This marker is the converse of :c:func:`function__entry`, and indicates that
execution of a Python function has ended (either via ``return``, or via an
@ -298,7 +296,7 @@ Available static markers
The arguments are the same as for :c:func:`function__entry`
.. c:function:: line(str filename, str funcname, int lineno)
.. object:: line(str filename, str funcname, int lineno)
This marker indicates a Python line is about to be executed. It is
the equivalent of line-by-line tracing with a Python profiler. It is
@ -306,24 +304,24 @@ Available static markers
The arguments are the same as for :c:func:`function__entry`.
.. c:function:: gc__start(int generation)
.. object:: gc__start(int generation)
Fires when the Python interpreter starts a garbage collection cycle.
``arg0`` is the generation to scan, like :func:`gc.collect()`.
.. c:function:: gc__done(long collected)
.. object:: gc__done(long collected)
Fires when the Python interpreter finishes a garbage collection
cycle. ``arg0`` is the number of collected objects.
.. c:function:: import__find__load__start(str modulename)
.. object:: import__find__load__start(str modulename)
Fires before :mod:`importlib` attempts to find and load the module.
``arg0`` is the module name.
.. versionadded:: 3.7
.. c:function:: import__find__load__done(str modulename, int found)
.. object:: import__find__load__done(str modulename, int found)
Fires after :mod:`importlib`'s find_and_load function is called.
``arg0`` is the module name, ``arg1`` indicates if module was
@ -332,7 +330,7 @@ Available static markers
.. versionadded:: 3.7
.. c:function:: audit(str event, void *tuple)
.. object:: audit(str event, void *tuple)
Fires when :func:`sys.audit` or :c:func:`PySys_Audit` is called.
``arg0`` is the event name as C string, ``arg1`` is a :c:type:`PyObject`
@ -375,14 +373,14 @@ If this file is installed in SystemTap's tapset directory (e.g.
``/usr/share/systemtap/tapset``), then these additional probepoints become
available:
.. c:function:: python.function.entry(str filename, str funcname, int lineno, frameptr)
.. object:: python.function.entry(str filename, str funcname, int lineno, frameptr)
This probe point indicates that execution of a Python function has begun.
It is only triggered for pure-Python (bytecode) functions.
.. c:function:: python.function.return(str filename, str funcname, int lineno, frameptr)
.. object:: python.function.return(str filename, str funcname, int lineno, frameptr)
This probe point is the converse of :c:func:`python.function.return`, and
This probe point is the converse of ``python.function.return``, and
indicates that execution of a Python function has ended (either via
``return``, or via an exception). It is only triggered for pure-Python
(bytecode) functions.

2
Doc/library/aifc.rst
View File

@ -208,6 +208,7 @@ number of frames must be filled in.
.. method:: aifc.tell()
:noindex:
Return the current write position in the output file. Useful in combination
with :meth:`setmark`.
@ -232,6 +233,7 @@ number of frames must be filled in.
.. method:: aifc.close()
:noindex:
Close the AIFF file. The header of the file is updated to reflect the actual
size of the audio data. After calling this method, the object can no longer be

2
Doc/library/collections.abc.rst
View File

@ -185,7 +185,7 @@ ABC Inherits from Abstract Methods Mixin
expressions. Custom implementations must provide the :meth:`__await__`
method.
:term:`Coroutine` objects and instances of the
:term:`Coroutine <coroutine>` objects and instances of the
:class:`~collections.abc.Coroutine` ABC are all instances of this ABC.
.. note::

3
Doc/library/concurrent.futures.rst
View File

@ -221,7 +221,8 @@ ProcessPoolExecutor
The :class:`ProcessPoolExecutor` class is an :class:`Executor` subclass that
uses a pool of processes to execute calls asynchronously.
:class:`ProcessPoolExecutor` uses the :mod:`multiprocessing` module, which
allows it to side-step the :term:`Global Interpreter Lock` but also means that
allows it to side-step the :term:`Global Interpreter Lock
<global interpreter lock>` but also means that
only picklable objects can be executed and returned.
The ``__main__`` module must be importable by worker subprocesses. This means

1
Doc/library/configparser.rst
View File

@ -696,6 +696,7 @@ be overridden by subclasses or by attribute assignment.
``enabled``/``disabled``.
.. method:: ConfigParser.optionxform(option)
:noindex:
This method transforms option names on every read, get, or set
operation. The default converts the name to lowercase. This also

2
Doc/library/difflib.rst
View File

@ -24,6 +24,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
.. class:: SequenceMatcher
:noindex:
This is a flexible class for comparing pairs of sequences of any type, so long
as the sequence elements are :term:`hashable`. The basic algorithm predates, and is a
@ -651,6 +652,7 @@ The :class:`Differ` class has this constructor:
.. class:: Differ(linejunk=None, charjunk=None)
:noindex:
Optional keyword parameters *linejunk* and *charjunk* are for filter functions
(or ``None``):

1
Doc/library/enum.rst
View File

@ -50,6 +50,7 @@ helper, :class:`auto`.
the bitwise operations without losing their :class:`Flag` membership.
.. function:: unique
:noindex:
Enum class decorator that ensures only one name is bound to any one value.

4
Doc/library/importlib.rst
View File

@ -1070,7 +1070,7 @@ find and load modules.
.. class:: WindowsRegistryFinder
:term:`Finder` for modules declared in the Windows registry. This class
:term:`Finder <finder>` for modules declared in the Windows registry. This class
implements the :class:`importlib.abc.MetaPathFinder` ABC.
Only class methods are defined by this class to alleviate the need for
@ -1085,7 +1085,7 @@ find and load modules.
.. class:: PathFinder
A :term:`Finder` for :data:`sys.path` and package ``__path__`` attributes.
A :term:`Finder <finder>` for :data:`sys.path` and package ``__path__`` attributes.
This class implements the :class:`importlib.abc.MetaPathFinder` ABC.
Only class methods are defined by this class to alleviate the need for

3
Doc/library/multiprocessing.rst
View File

@ -14,7 +14,8 @@ Introduction
:mod:`multiprocessing` is a package that supports spawning processes using an
API similar to the :mod:`threading` module. The :mod:`multiprocessing` package
offers both local and remote concurrency, effectively side-stepping the
:term:`Global Interpreter Lock` by using subprocesses instead of threads. Due
:term:`Global Interpreter Lock <global interpreter lock>` by using
subprocesses instead of threads. Due
to this, the :mod:`multiprocessing` module allows the programmer to fully
leverage multiple processors on a given machine. It runs on both Unix and
Windows.

2
Doc/library/pkgutil.rst
View File

@ -68,7 +68,7 @@ support.
.. class:: ImpLoader(fullname, file, filename, etc)
:term:`Loader` that wraps Python's "classic" import algorithm.
:term:`Loader <loader>` that wraps Python's "classic" import algorithm.
.. deprecated:: 3.3
This emulation is no longer needed, as the standard import mechanism

2
Doc/library/socket.rst
View File

@ -1695,7 +1695,9 @@ to sockets.
.. method:: socket.setsockopt(level, optname, value: int)
.. method:: socket.setsockopt(level, optname, value: buffer)
:noindex:
.. method:: socket.setsockopt(level, optname, None, optlen: int)
:noindex:
.. index:: module: struct

2
Doc/library/string.rst
View File

@ -308,7 +308,7 @@ non-empty format specification typically modifies the result.
The general form of a *standard format specifier* is:
.. productionlist:: sf
.. productionlist::
format_spec: [[`fill`]`align`][`sign`][#][0][`width`][`grouping_option`][.`precision`][`type`]
fill: <any character>
align: "<" | ">" | "=" | "^"

1
Doc/library/tarfile.rst
View File

@ -151,6 +151,7 @@ Some facts and figures:
.. class:: TarFile
:noindex:
Class for reading and writing tar archives. Do not use this class directly:
use :func:`tarfile.open` instead. See :ref:`tarfile-objects`.

3
Doc/library/threading.rst
View File

@ -395,7 +395,8 @@ since it is impossible to detect the termination of alien threads.
.. impl-detail::
In CPython, due to the :term:`Global Interpreter Lock`, only one thread
In CPython, due to the :term:`Global Interpreter Lock
<global interpreter lock>`, only one thread
can execute Python code at once (even though certain performance-oriented
libraries might overcome this limitation).
If you want your application to make better use of the computational

1
Doc/library/token.rst
View File

@ -70,6 +70,7 @@ the :mod:`tokenize` module.
.. data:: TYPE_COMMENT
:noindex:
Token value indicating that a type comment was recognized. Such
tokens are only produced when :func:`ast.parse()` is invoked with

3
Doc/library/turtle.rst
View File

@ -1069,6 +1069,7 @@ More drawing control
~~~~~~~~~~~~~~~~~~~~
.. function:: reset()
:noindex:
Delete the turtle's drawings from the screen, re-center the turtle and set
variables to the default values.
@ -1090,6 +1091,7 @@ More drawing control
.. function:: clear()
:noindex:
Delete the turtle's drawings from the screen. Do not move turtle. State and
position of the turtle as well as drawings of other turtles are not affected.
@ -1362,6 +1364,7 @@ Using events
------------
.. function:: onclick(fun, btn=1, add=None)
:noindex:
:param fun: a function with two arguments which will be called with the
coordinates of the clicked point on the canvas

2
Doc/library/urllib.request.rst
View File

@ -946,7 +946,7 @@ tracking URIs for which authentication credentials should always be sent.
If *is_authenticated* is specified as ``True``, *realm* is ignored.
.. method:: HTTPPasswordMgr.find_user_password(realm, authuri)
.. method:: HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)
Same as for :class:`HTTPPasswordMgrWithDefaultRealm` objects

4
Doc/reference/datamodel.rst
View File

@ -2601,7 +2601,7 @@ Awaitable Objects
-----------------
An :term:`awaitable` object generally implements an :meth:`__await__` method.
:term:`Coroutine` objects returned from :keyword:`async def` functions
:term:`Coroutine objects <coroutine>` returned from :keyword:`async def` functions
are awaitable.
.. note::
@ -2626,7 +2626,7 @@ are awaitable.
Coroutine Objects
-----------------
:term:`Coroutine` objects are :term:`awaitable` objects.
:term:`Coroutine objects <coroutine>` are :term:`awaitable` objects.
A coroutine's execution can be controlled by calling :meth:`__await__` and
iterating over the result. When the coroutine has finished executing and
returns, the iterator raises :exc:`StopIteration`, and the exception's

2
Doc/reference/introduction.rst
View File

@ -93,7 +93,7 @@ Notation
The descriptions of lexical analysis and syntax use a modified BNF grammar
notation. This uses the following style of definition:
.. productionlist:: *
.. productionlist::
name: `lc_letter` (`lc_letter` | "_")*
lc_letter: "a"..."z"

2
Doc/tutorial/classes.rst
View File

@ -849,7 +849,7 @@ defines :meth:`__next__`, then :meth:`__iter__` can just return ``self``::
Generators
==========
:term:`Generator`\s are a simple and powerful tool for creating iterators. They
:term:`Generators <generator>` are a simple and powerful tool for creating iterators. They
are written like regular functions but use the :keyword:`yield` statement
whenever they want to return data. Each time :func:`next` is called on it, the
generator resumes where it left off (it remembers all the data values and which

2
Doc/whatsnew/3.2.rst
View File

@ -2311,7 +2311,7 @@ Multi-threading
===============
* The mechanism for serializing execution of concurrently running Python threads
(generally known as the :term:`GIL` or :term:`Global Interpreter Lock`) has
(generally known as the :term:`GIL` or Global Interpreter Lock) has
been rewritten. Among the objectives were more predictable switching
intervals and reduced overhead due to lock contention and the number of
ensuing system calls. The notion of a "check interval" to allow thread

4
Doc/whatsnew/3.3.rst
View File

@ -2309,9 +2309,9 @@ Encoders:
:c:func:`PyUnicode_AsUTF8String`
* :c:func:`PyUnicode_EncodeUTF32`
* :c:func:`PyUnicode_EncodeUTF16`
* :c:func:`PyUnicode_EncodeUnicodeEscape:` use
* :c:func:`PyUnicode_EncodeUnicodeEscape` use
:c:func:`PyUnicode_AsUnicodeEscapeString`
* :c:func:`PyUnicode_EncodeRawUnicodeEscape:` use
* :c:func:`PyUnicode_EncodeRawUnicodeEscape` use
:c:func:`PyUnicode_AsRawUnicodeEscapeString`
* :c:func:`PyUnicode_EncodeLatin1`: use :c:func:`PyUnicode_AsLatin1String`
* :c:func:`PyUnicode_EncodeASCII`: use :c:func:`PyUnicode_AsASCIIString`

8
Doc/whatsnew/3.5.rst
View File

@ -412,7 +412,7 @@ uses were to provide type hints to function parameters and return values. It
became evident that it would be beneficial for Python users, if the
standard library included the base definitions and tools for type annotations.
:pep:`484` introduces a :term:`provisional module <provisional api>` to
:pep:`484` introduces a :term:`provisional module <provisional API>` to
provide these standard definitions and tools, along with some conventions
for situations where annotations are not available.
@ -726,7 +726,7 @@ New Modules
typing
------
The new :mod:`typing` :term:`provisional <provisional api>` module
The new :mod:`typing` :term:`provisional <provisional API>` module
provides standard definitions and tools for function type annotations.
See :ref:`Type Hints <whatsnew-pep-484>` for more information.
@ -772,7 +772,7 @@ Steven Bethard, paul j3 and Daniel Eriksson in :issue:`14910`.)
asyncio
-------
Since the :mod:`asyncio` module is :term:`provisional <provisional api>`,
Since the :mod:`asyncio` module is :term:`provisional <provisional API>`,
all changes introduced in Python 3.5 have also been backported to Python 3.4.x.
Notable changes in the :mod:`asyncio` module since Python 3.4.0:
@ -1867,7 +1867,7 @@ A new :func:`~sys.set_coroutine_wrapper` function allows setting a global
hook that will be called whenever a :term:`coroutine object <coroutine>`
is created by an :keyword:`async def` function. A corresponding
:func:`~sys.get_coroutine_wrapper` can be used to obtain a currently set
wrapper. Both functions are :term:`provisional <provisional api>`,
wrapper. Both functions are :term:`provisional <provisional API>`,
and are intended for debugging purposes only. (Contributed by Yury Selivanov
in :issue:`24017`.)

2
Doc/whatsnew/3.6.rst
View File

@ -1597,7 +1597,7 @@ to filter block traces by their address space (domain).
typing
------
Since the :mod:`typing` module is :term:`provisional <provisional api>`,
Since the :mod:`typing` module is :term:`provisional <provisional API>`,
all changes introduced in Python 3.6 have also been
backported to Python 3.5.x.

2
Doc/whatsnew/3.7.rst
View File

@ -636,7 +636,7 @@ The :mod:`asyncio` module has received many new features, usability and
:ref:`performance improvements <whatsnew37-asyncio-perf>`. Notable changes
include:
* The new :term:`provisional <provisional api>` :func:`asyncio.run` function can
* The new :term:`provisional <provisional API>` :func:`asyncio.run` function can
be used to run a coroutine from synchronous code by automatically creating and
destroying the event loop.
(Contributed by Yury Selivanov in :issue:`32314`.)

3
Misc/NEWS.d/next/Documentation/2020-08-12-18-35-40.bpo-40204.C8A_pe.rst Normal file
View File

@ -0,0 +1,3 @@
Enable Sphinx 3.2 ``c_allow_pre_v3`` option and disable
``c_warn_on_allowed_pre_v3`` option to make the documentation compatible
with Sphinx 2 and Sphinx 3.