[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 commit423e77d6de) * 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 commit43577c01a2) * 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 commit46d10b1237) * 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 commitd3ded08048) * 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 commit474652fe93) * 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 commitbb0b08540c) * 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 commit1abeda80f7)
This commit is contained in:
Victor Stinner
GitHub
parent
e3cafebb5c
commit
8f88190af5
|
|
@ -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*]
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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 *);
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
resulting Unicode object. Return ``NULL`` if an exception was raised by 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
|
||||
|
|
|
|||
|
|
@ -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
10
Doc/conf.py
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -674,97 +674,98 @@ be overridden by subclasses or by attribute assignment.
|
|||
|
||||
.. attribute:: ConfigParser.BOOLEAN_STATES
|
||||
|
||||
By default when using :meth:`~ConfigParser.getboolean`, config parsers
|
||||
consider the following values ``True``: ``'1'``, ``'yes'``, ``'true'``,
|
||||
``'on'`` and the following values ``False``: ``'0'``, ``'no'``, ``'false'``,
|
||||
``'off'``. You can override this by specifying a custom dictionary of strings
|
||||
and their Boolean outcomes. For example:
|
||||
By default when using :meth:`~ConfigParser.getboolean`, config parsers
|
||||
consider the following values ``True``: ``'1'``, ``'yes'``, ``'true'``,
|
||||
``'on'`` and the following values ``False``: ``'0'``, ``'no'``, ``'false'``,
|
||||
``'off'``. You can override this by specifying a custom dictionary of strings
|
||||
and their Boolean outcomes. For example:
|
||||
|
||||
.. doctest::
|
||||
.. doctest::
|
||||
|
||||
>>> custom = configparser.ConfigParser()
|
||||
>>> custom['section1'] = {'funky': 'nope'}
|
||||
>>> custom['section1'].getboolean('funky')
|
||||
Traceback (most recent call last):
|
||||
...
|
||||
ValueError: Not a boolean: nope
|
||||
>>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
|
||||
>>> custom['section1'].getboolean('funky')
|
||||
False
|
||||
>>> custom = configparser.ConfigParser()
|
||||
>>> custom['section1'] = {'funky': 'nope'}
|
||||
>>> custom['section1'].getboolean('funky')
|
||||
Traceback (most recent call last):
|
||||
...
|
||||
ValueError: Not a boolean: nope
|
||||
>>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
|
||||
>>> custom['section1'].getboolean('funky')
|
||||
False
|
||||
|
||||
Other typical Boolean pairs include ``accept``/``reject`` or
|
||||
``enabled``/``disabled``.
|
||||
Other typical Boolean pairs include ``accept``/``reject`` or
|
||||
``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
|
||||
means that when a configuration file gets written, all keys will be
|
||||
lowercase. Override this method if that's unsuitable.
|
||||
For example:
|
||||
This method transforms option names on every read, get, or set
|
||||
operation. The default converts the name to lowercase. This also
|
||||
means that when a configuration file gets written, all keys will be
|
||||
lowercase. Override this method if that's unsuitable.
|
||||
For example:
|
||||
|
||||
.. doctest::
|
||||
.. doctest::
|
||||
|
||||
>>> config = """
|
||||
... [Section1]
|
||||
... Key = Value
|
||||
...
|
||||
... [Section2]
|
||||
... AnotherKey = Value
|
||||
... """
|
||||
>>> typical = configparser.ConfigParser()
|
||||
>>> typical.read_string(config)
|
||||
>>> list(typical['Section1'].keys())
|
||||
['key']
|
||||
>>> list(typical['Section2'].keys())
|
||||
['anotherkey']
|
||||
>>> custom = configparser.RawConfigParser()
|
||||
>>> custom.optionxform = lambda option: option
|
||||
>>> custom.read_string(config)
|
||||
>>> list(custom['Section1'].keys())
|
||||
['Key']
|
||||
>>> list(custom['Section2'].keys())
|
||||
['AnotherKey']
|
||||
>>> config = """
|
||||
... [Section1]
|
||||
... Key = Value
|
||||
...
|
||||
... [Section2]
|
||||
... AnotherKey = Value
|
||||
... """
|
||||
>>> typical = configparser.ConfigParser()
|
||||
>>> typical.read_string(config)
|
||||
>>> list(typical['Section1'].keys())
|
||||
['key']
|
||||
>>> list(typical['Section2'].keys())
|
||||
['anotherkey']
|
||||
>>> custom = configparser.RawConfigParser()
|
||||
>>> custom.optionxform = lambda option: option
|
||||
>>> custom.read_string(config)
|
||||
>>> list(custom['Section1'].keys())
|
||||
['Key']
|
||||
>>> list(custom['Section2'].keys())
|
||||
['AnotherKey']
|
||||
|
||||
.. note::
|
||||
The optionxform function transforms option names to a canonical form.
|
||||
This should be an idempotent function: if the name is already in
|
||||
canonical form, it should be returned unchanged.
|
||||
.. note::
|
||||
The optionxform function transforms option names to a canonical form.
|
||||
This should be an idempotent function: if the name is already in
|
||||
canonical form, it should be returned unchanged.
|
||||
|
||||
|
||||
.. attribute:: ConfigParser.SECTCRE
|
||||
|
||||
A compiled regular expression used to parse section headers. The default
|
||||
matches ``[section]`` to the name ``"section"``. Whitespace is considered
|
||||
part of the section name, thus ``[ larch ]`` will be read as a section of
|
||||
name ``" larch "``. Override this attribute if that's unsuitable. For
|
||||
example:
|
||||
A compiled regular expression used to parse section headers. The default
|
||||
matches ``[section]`` to the name ``"section"``. Whitespace is considered
|
||||
part of the section name, thus ``[ larch ]`` will be read as a section of
|
||||
name ``" larch "``. Override this attribute if that's unsuitable. For
|
||||
example:
|
||||
|
||||
.. doctest::
|
||||
.. doctest::
|
||||
|
||||
>>> import re
|
||||
>>> config = """
|
||||
... [Section 1]
|
||||
... option = value
|
||||
...
|
||||
... [ Section 2 ]
|
||||
... another = val
|
||||
... """
|
||||
>>> typical = configparser.ConfigParser()
|
||||
>>> typical.read_string(config)
|
||||
>>> typical.sections()
|
||||
['Section 1', ' Section 2 ']
|
||||
>>> custom = configparser.ConfigParser()
|
||||
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
|
||||
>>> custom.read_string(config)
|
||||
>>> custom.sections()
|
||||
['Section 1', 'Section 2']
|
||||
>>> import re
|
||||
>>> config = """
|
||||
... [Section 1]
|
||||
... option = value
|
||||
...
|
||||
... [ Section 2 ]
|
||||
... another = val
|
||||
... """
|
||||
>>> typical = configparser.ConfigParser()
|
||||
>>> typical.read_string(config)
|
||||
>>> typical.sections()
|
||||
['Section 1', ' Section 2 ']
|
||||
>>> custom = configparser.ConfigParser()
|
||||
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
|
||||
>>> custom.read_string(config)
|
||||
>>> custom.sections()
|
||||
['Section 1', 'Section 2']
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
While ConfigParser objects also use an ``OPTCRE`` attribute for recognizing
|
||||
option lines, it's not recommended to override it because that would
|
||||
interfere with constructor options *allow_no_value* and *delimiters*.
|
||||
While ConfigParser objects also use an ``OPTCRE`` attribute for recognizing
|
||||
option lines, it's not recommended to override it because that would
|
||||
interfere with constructor options *allow_no_value* and *delimiters*.
|
||||
|
||||
|
||||
Legacy API Examples
|
||||
|
|
|
|||
|
|
@ -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``):
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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: "<" | ">" | "=" | "^"
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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`.)
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue