openharmony/third_party_python
1
0
Fork 0
mirror of https://gitee.com/openharmony/third_party_python synced 2024-11-23 07:19:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

updated Python version

Browse Source 
Signed-off-by: oumeng <oumeng@huawei.com>
This commit is contained in:
oumeng 2022-03-30 17:17:39 +08:00
parent 7319d2fc39
commit 3af129a1d0
1730 changed files with 265744 additions and 142213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doc/Makefile
View File

@ -143,7 +143,7 @@ clean:
venv:
$(PYTHON) -m venv $(VENVDIR)
$(VENVDIR)/bin/python3 -m pip install -U pip setuptools
$(VENVDIR)/bin/python3 -m pip install -U Sphinx==2.3.1 blurb python-docs-theme
$(VENVDIR)/bin/python3 -m pip install -r requirements.txt
@echo "The venv has been created in the $(VENVDIR) directory"
dist:

1
Doc/c-api/abstract.rst
View File

@ -18,6 +18,7 @@ but whose items have not been set to some non-\ ``NULL`` value yet.
.. toctree::
object.rst
call.rst
number.rst
sequence.rst
mapping.rst

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*]

3
Doc/c-api/bool.rst
View File

@ -13,7 +13,8 @@ are available, however.
.. c:function:: int PyBool_Check(PyObject *o)
Return true if *o* is of type :c:data:`PyBool_Type`.
Return true if *o* is of type :c:data:`PyBool_Type`. This function always
succeeds.
.. c:var:: PyObject* Py_False

34
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,17 +455,19 @@ 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
:c:func:`PyObject_GetBuffer`.
.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *format)
Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
This function is not yet implemented.
On error, raise an exception and return -1.
.. versionadded:: 3.9
.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
@ -514,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

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

@ -25,13 +25,13 @@ Type check macros
.. c:function:: int PyByteArray_Check(PyObject *o)
Return true if the object *o* is a bytearray object or an instance of a
subtype of the bytearray type.
subtype of the bytearray type. This function always succeeds.
.. c:function:: int PyByteArray_CheckExact(PyObject *o)
Return true if the object *o* is a bytearray object, but not an instance of a
subtype of the bytearray type.
subtype of the bytearray type. This function always succeeds.
Direct API functions

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

@ -25,13 +25,13 @@ called with a non-bytes parameter.
.. c:function:: int PyBytes_Check(PyObject *o)
Return true if the object *o* is a bytes object or an instance of a subtype
of the bytes type.
of the bytes type. This function always succeeds.
.. c:function:: int PyBytes_CheckExact(PyObject *o)
Return true if the object *o* is a bytes object, but not an instance of a
subtype of the bytes type.
subtype of the bytes type. This function always succeeds.
.. c:function:: PyObject* PyBytes_FromString(const char *v)

424
Doc/c-api/call.rst Normal file
View File

@ -0,0 +1,424 @@
.. highlight:: c
.. _call:
Call Protocol
=============
CPython supports two different calling protocols:
*tp_call* and vectorcall.
The *tp_call* Protocol
----------------------
Instances of classes that set :c:member:`~PyTypeObject.tp_call` are callable.
The signature of the slot is::
PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);
A call is made using a tuple for the positional arguments
and a dict for the keyword arguments, similarly to
``callable(*args, **kwargs)`` in Python code.
*args* must be non-NULL (use an empty tuple if there are no arguments)
but *kwargs* may be *NULL* if there are no keyword arguments.
This convention is not only used by *tp_call*:
:c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_init`
also pass arguments this way.
To call an object, use :c:func:`PyObject_Call` or other
:ref:`call API <capi-call>`.
.. _vectorcall:
The Vectorcall Protocol
-----------------------
.. versionadded:: 3.9
The vectorcall protocol was introduced in :pep:`590` as an additional protocol
for making calls more efficient.
As rule of thumb, CPython will prefer the vectorcall for internal calls
if the callable supports it. However, this is not a hard rule.
Additionally, some third-party extensions use *tp_call* directly
(rather than using :c:func:`PyObject_Call`).
Therefore, a class supporting vectorcall must also implement
:c:member:`~PyTypeObject.tp_call`.
Moreover, the callable must behave the same
regardless of which protocol is used.
The recommended way to achieve this is by setting
:c:member:`~PyTypeObject.tp_call` to :c:func:`PyVectorcall_Call`.
This bears repeating:
.. warning::
A class supporting vectorcall **must** also implement
:c:member:`~PyTypeObject.tp_call` with the same semantics.
A class should not implement vectorcall if that would be slower
than *tp_call*. For example, if the callee needs to convert
the arguments to an args tuple and kwargs dict anyway, then there is no point
in implementing vectorcall.
Classes can implement the vectorcall protocol by enabling the
:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
:c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the
object structure where a *vectorcallfunc* appears.
This is a pointer to a function with the following signature:
.. c:type:: PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
- *callable* is the object being called.
- *args* is a C array consisting of the positional arguments followed by the
values of the keyword arguments.
This can be *NULL* if there are no arguments.
- *nargsf* is the number of positional arguments plus possibly the
:const:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
To get the actual number of positional arguments from *nargsf*,
use :c:func:`PyVectorcall_NARGS`.
- *kwnames* is a tuple containing the names of the keyword arguments;
in other words, the keys of the kwargs dict.
These names must be strings (instances of ``str`` or a subclass)
and they must be unique.
If there are no keyword arguments, then *kwnames* can instead be *NULL*.
.. 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
argument 1 (not 0) in the allocated vector.
The callee must restore the value of ``args[-1]`` before returning.
For :c:func:`PyObject_VectorcallMethod`, this flag means instead that
``args[0]`` may be changed.
Whenever they can do so cheaply (without additional allocation), callers
are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
Doing so will allow callables such as bound methods to make their onward
calls (which include a prepended *self* argument) very efficiently.
To call an object that implements vectorcall, use a :ref:`call API <capi-call>`
function as with any other callable.
:c:func:`PyObject_Vectorcall` will usually be most efficient.
.. note::
In CPython 3.8, the vectorcall API and related functions were available
provisionally under names with a leading underscore:
``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``,
``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``,
``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``,
``_PyObject_CallMethodOneArg``.
Additionally, ``PyObject_VectorcallDict`` was available as
``_PyObject_FastCallDict``.
The old names are still defined as aliases of the new, non-underscored names.
Recursion Control
.................
When using *tp_call*, callees do not need to worry about
:ref:`recursion <recursion>`: CPython uses
:c:func:`Py_EnterRecursiveCall` and :c:func:`Py_LeaveRecursiveCall`
for calls made using *tp_call*.
For efficiency, this is not the case for calls done using vectorcall:
the callee should use *Py_EnterRecursiveCall* and *Py_LeaveRecursiveCall*
if needed.
Vectorcall Support API
......................
.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf)
Given a vectorcall *nargsf* argument, return the actual number of
arguments.
Currently equivalent to::
(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)
However, the function ``PyVectorcall_NARGS`` should be used to allow
for future extensions.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.8
.. c:function:: vectorcallfunc PyVectorcall_Function(PyObject *op)
If *op* does not support the vectorcall protocol (either because the type
does not or because the specific instance does not), return *NULL*.
Otherwise, return the vectorcall function pointer stored in *op*.
This function never raises an exception.
This is mostly useful to check whether or not *op* supports vectorcall,
which can be done by checking ``PyVectorcall_Function(op) != NULL``.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.8
.. c:function:: PyObject* PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)
Call *callable*'s :c:type:`vectorcallfunc` with positional and keyword
arguments given in a tuple and dict, respectively.
This is a specialized function, intended to be put in the
:c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
and it does not fall back to ``tp_call``.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.8
.. _capi-call:
Object Calling API
------------------
Various functions are available for calling a Python object.
Each converts its arguments to a convention supported by the called object –
either *tp_call* or vectorcall.
In order to do as litle conversion as possible, pick one that best fits
the format of data you have available.
The following table summarizes the available functions;
please see individual documentation for details.
+------------------------------------------+------------------+--------------------+---------------+
| Function | callable | args | kwargs |
+==========================================+==================+====================+===============+
| :c:func:`PyObject_Call` | ``PyObject *`` | tuple | dict/``NULL`` |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallNoArgs` | ``PyObject *`` | --- | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallObject` | ``PyObject *`` | tuple/``NULL`` | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallFunction` | ``PyObject *`` | format | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethod` | obj + ``char*`` | format | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallFunctionObjArgs` | ``PyObject *`` | variadic | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethodObjArgs` | obj + name | variadic | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethodNoArgs` | obj + name | --- | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethodOneArg` | obj + name | 1 object | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_VectorcallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall |
+------------------------------------------+------------------+--------------------+---------------+
.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
Call a callable Python object *callable*, with arguments given by the
tuple *args*, and named arguments given by the dictionary *kwargs*.
*args* must not be *NULL*; use an empty tuple if no arguments are needed.
If no named arguments are needed, *kwargs* can be *NULL*.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This is the equivalent of the Python expression:
``callable(*args, **kwargs)``.
.. c:function:: PyObject* PyObject_CallNoArgs(PyObject *callable)
Call a callable Python object *callable* without any arguments. It is the
most efficient way to call a callable Python object without any argument.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
.. versionadded:: 3.9
.. c:function:: PyObject* PyObject_CallOneArg(PyObject *callable, PyObject *arg)
Call a callable Python object *callable* with exactly 1 positional argument
*arg* and no keyword arguments.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.9
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
Call a callable Python object *callable*, with arguments given by the
tuple *args*. If no arguments are needed, then *args* can be *NULL*.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This is the equivalent of the Python expression: ``callable(*args)``.
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
Call a callable Python object *callable*, with a variable number of C arguments.
The C arguments are described using a :c:func:`Py_BuildValue` style format
string. The format can be *NULL*, indicating that no arguments are provided.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This is the equivalent of the Python expression: ``callable(*args)``.
Note that if you only pass :c:type:`PyObject *` args,
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
.. versionchanged:: 3.4
The type of *format* was changed from ``char *``.
.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
Call the method named *name* of object *obj* with a variable number of C
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
string that should produce a tuple.
The format can be *NULL*, indicating that no arguments are provided.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This is the equivalent of the Python expression:
``obj.name(arg1, arg2, ...)``.
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, ...)
Call a callable Python object *callable*, with a variable number of
: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
*NULL* on failure.
This is the equivalent of the Python expression:
``callable(arg1, arg2, ...)``.
.. 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
of parameters followed by *NULL*.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
.. c:function:: PyObject* PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
Call a method of the Python object *obj* without arguments,
where the name of the method is given as a Python string object in *name*.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.9
.. c:function:: PyObject* PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
Call a method of the Python object *obj* with a single positional argument
*arg*, where the name of the method is given as a Python string object in
*name*.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.9
.. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
Call a callable Python object *callable*.
The arguments are the same as for :c:type:`vectorcallfunc`.
If *callable* supports vectorcall_, this directly calls
the vectorcall function stored in *callable*.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.9
.. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol,
but with keyword arguments passed as a dictionary *kwdict*.
The *args* array contains only the positional arguments.
Regardless of which protocol is used internally,
a conversion of arguments needs to be done.
Therefore, this function should only be used if the caller
already has a dictionary ready to use for the keyword arguments,
but not a tuple for the positional arguments.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.9
.. c:function:: PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
Call a method using the vectorcall calling convention. The name of the method
is given as a Python string *name*. The object whose method is called is
*args[0]*, and the *args* array starting at *args[1]* represents the arguments
of the call. There must be at least one positional argument.
*nargsf* is the number of positional arguments including *args[0]*,
plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
temporarily be changed. Keyword arguments can be passed just like in
:c:func:`PyObject_Vectorcall`.
If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
this will call the unbound method object with the full
*args* vector as arguments.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.9
Call Support API
----------------
.. c:function:: int PyCallable_Check(PyObject *o)
Determine if the object *o* is callable. Return ``1`` if the object is callable
and ``0`` otherwise. This function always succeeds.

5
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
@ -34,7 +34,8 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:function:: int PyCapsule_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyCapsule`.
Return true if its argument is a :c:type:`PyCapsule`. This function always
succeeds.
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

3
Doc/c-api/cell.rst
View File

@ -27,7 +27,8 @@ Cell objects are not likely to be useful elsewhere.
.. c:function:: int PyCell_Check(ob)
Return true if *ob* is a cell object; *ob* must not be ``NULL``.
Return true if *ob* is a cell object; *ob* must not be ``NULL``. This
function always succeeds.
.. c:function:: PyObject* PyCell_New(PyObject *ob)

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

@ -27,7 +27,7 @@ bound into a function.
.. c:function:: int PyCode_Check(PyObject *co)
Return true if *co* is a :class:`code` object.
Return true if *co* is a :class:`code` object. This function always succeeds.
.. c:function:: int PyCode_GetNumFree(PyCodeObject *co)

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

@ -94,13 +94,13 @@ Complex Numbers as Python Objects
.. c:function:: int PyComplex_Check(PyObject *p)
Return true if its argument is a :c:type:`PyComplexObject` or a subtype of
:c:type:`PyComplexObject`.
:c:type:`PyComplexObject`. This function always succeeds.
.. c:function:: int PyComplex_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of
:c:type:`PyComplexObject`.
:c:type:`PyComplexObject`. This function always succeeds.
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)

5
Doc/c-api/contextvars.rst
View File

@ -101,11 +101,6 @@ Context object management functions:
current context for the current thread. Returns ``0`` on success,
and ``-1`` on error.
.. c:function:: int PyContext_ClearFreeList()
Clear the context variable free list. Return the total number of
freed items. This function always succeeds.
Context variable functions:

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

@ -11,14 +11,14 @@ Functions for number conversion and formatted string output.
.. c:function:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)
Output not more than *size* bytes to *str* according to the format string
*format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
*format* and the extra arguments. See the Unix man page :manpage:`snprintf(3)`.
.. c:function:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
Output not more than *size* bytes to *str* according to the format string
*format* and the variable argument list *va*. Unix man page
:manpage:`vsnprintf(2)`.
:manpage:`vsnprintf(3)`.
:c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C library
functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose is to

1
Doc/c-api/coro.rst
View File

@ -24,6 +24,7 @@ return.
.. c:function:: int PyCoro_CheckExact(PyObject *ob)
Return true if *ob*'s type is :c:type:`PyCoro_Type`; *ob* must not be ``NULL``.
This function always succeeds.
.. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)

25
Doc/c-api/datetime.rst
View File

@ -28,61 +28,66 @@ Type-check macros:
.. c:function:: int PyDate_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
:c:data:`PyDateTime_DateType`. *ob* must not be ``NULL``.
:c:data:`PyDateTime_DateType`. *ob* must not be ``NULL``. This function always
succeeds.
.. c:function:: int PyDate_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
``NULL``.
``NULL``. This function always succeeds.
.. c:function:: int PyDateTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
:c:data:`PyDateTime_DateTimeType`. *ob* must not be ``NULL``.
:c:data:`PyDateTime_DateTimeType`. *ob* must not be ``NULL``. This function always
succeeds.
.. c:function:: int PyDateTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
be ``NULL``.
be ``NULL``. This function always succeeds.
.. c:function:: int PyTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
:c:data:`PyDateTime_TimeType`. *ob* must not be ``NULL``.
:c:data:`PyDateTime_TimeType`. *ob* must not be ``NULL``. This function always
succeeds.
.. c:function:: int PyTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
``NULL``.
``NULL``. This function always succeeds.
.. c:function:: int PyDelta_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
:c:data:`PyDateTime_DeltaType`. *ob* must not be ``NULL``.
:c:data:`PyDateTime_DeltaType`. *ob* must not be ``NULL``. This function always
succeeds.
.. c:function:: int PyDelta_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
``NULL``.
``NULL``. This function always succeeds.
.. c:function:: int PyTZInfo_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
:c:data:`PyDateTime_TZInfoType`. *ob* must not be ``NULL``.
:c:data:`PyDateTime_TZInfoType`. *ob* must not be ``NULL``. This function always
succeeds.
.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
``NULL``.
``NULL``. This function always succeeds.
Macros to create objects:

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

@ -22,13 +22,13 @@ Dictionary Objects
.. c:function:: int PyDict_Check(PyObject *p)
Return true if *p* is a dict object or an instance of a subtype of the dict
type.
type. This function always succeeds.
.. c:function:: int PyDict_CheckExact(PyObject *p)
Return true if *p* is a dict object, but not an instance of a subtype of
the dict type.
the dict type. This function always succeeds.
.. c:function:: PyObject* PyDict_New()
@ -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*.
@ -81,14 +81,16 @@ Dictionary Objects
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``
on failure.
if it isn't, :exc:`TypeError` is raised.
If *key* is not in the dictionary, :exc:`KeyError` is raised.
Return ``0`` on success or ``-1`` on failure.
.. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
Remove the entry in dictionary *p* which has a key specified by the string
*key*. Return ``0`` on success or ``-1`` on failure.
Remove the entry in dictionary *p* which has a key specified by the string *key*.
If *key* is not in the dictionary, :exc:`KeyError` is raised.
Return ``0`` on success or ``-1`` on failure.
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
@ -112,7 +114,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 +163,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
@ -232,10 +234,3 @@ Dictionary Objects
for key, value in seq2:
if override or key not in a:
a[key] = value
.. c:function:: int PyDict_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 3.3

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

@ -374,6 +374,8 @@ Querying the error indicator
own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
it.
The caller must hold the GIL.
.. note::
Do not compare the return value to a specific exception; use
@ -635,11 +637,21 @@ The following functions are used to create and modify Unicode exceptions from C.
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
UTF-8 encoded strings.
.. deprecated:: 3.3 3.11
``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
``PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...)``.
.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeTranslateError` object with the attributes *object*,
*length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string.
.. deprecated:: 3.3 3.11
``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
``PyObject_CallFunction(PyExc_UnicodeTranslateError, "Onns", ...)``.
.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
@ -695,6 +707,8 @@ The following functions are used to create and modify Unicode exceptions from C.
``0`` on success, ``-1`` on failure.
.. _recursion:
Recursion Control
=================
@ -702,6 +716,8 @@ These two functions provide a way to perform safe recursive calls at the C
level, both in the core and in extension modules. They are needed if the
recursive code does not necessarily invoke Python code (which tracks its
recursion depth automatically).
They are also not needed for *tp_call* implementations
because the :ref:`call protocol <call>` takes care of recursion handling.
.. c:function:: int Py_EnterRecursiveCall(const char *where)
@ -715,15 +731,21 @@ recursion depth automatically).
case, a :exc:`RecursionError` is set and a nonzero value is returned.
Otherwise, zero is returned.
*where* should be a string such as ``" in instance check"`` to be
concatenated to the :exc:`RecursionError` message caused by the recursion
*where* should be a UTF-8 encoded string such as ``" in instance check"`` to
be concatenated to the :exc:`RecursionError` message caused by the recursion
depth limit.
.. c:function:: void Py_LeaveRecursiveCall()
.. versionchanged:: 3.9
This function is now also available in the limited API.
.. c:function:: void Py_LeaveRecursiveCall(void)
Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
*successful* invocation of :c:func:`Py_EnterRecursiveCall`.
.. versionchanged:: 3.9
This function is now also available in the limited API.
Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
special recursion handling. In addition to protecting the stack,
:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles. The
@ -761,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::
@ -981,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::

6
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*
@ -82,6 +82,8 @@ the :mod:`io` APIs instead.
This function is safe to call before :c:func:`Py_Initialize`.
.. audit-event:: setopencodehook "" c.PyFile_SetOpenCodeHook
.. versionadded:: 3.8

9
Doc/c-api/float.rst
View File

@ -22,13 +22,13 @@ Floating Point Objects
.. c:function:: int PyFloat_Check(PyObject *p)
Return true if its argument is a :c:type:`PyFloatObject` or a subtype of
:c:type:`PyFloatObject`.
:c:type:`PyFloatObject`. This function always succeeds.
.. c:function:: int PyFloat_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of
:c:type:`PyFloatObject`.
:c:type:`PyFloatObject`. This function always succeeds.
.. c:function:: PyObject* PyFloat_FromString(PyObject *str)
@ -76,8 +76,3 @@ Floating Point Objects
.. c:function:: double PyFloat_GetMin()
Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
.. c:function:: int PyFloat_ClearFreeList()
Clear the float free list. Return the number of items that could not
be freed.

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

@ -26,7 +26,7 @@ There are a few functions specific to Python functions.
.. c:function:: int PyFunction_Check(PyObject *o)
Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
The parameter must not be ``NULL``.
The parameter must not be ``NULL``. This function always succeeds.
.. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)

27
Doc/c-api/gcsupport.rst
View File

@ -61,6 +61,33 @@ Constructors for container types must conform to two rules:
end of the constructor.
.. c:function:: int PyObject_IS_GC(PyObject *obj)
Returns non-zero if the object implements the garbage collector protocol,
otherwise returns 0.
The object cannot be tracked by the garbage collector if this function returns 0.
.. c:function:: int PyObject_GC_IsTracked(PyObject *op)
Returns 1 if the object type of *op* implements the GC protocol and *op* is being
currently tracked by the garbage collector and 0 otherwise.
This is analogous to the Python function :func:`gc.is_tracked`.
.. versionadded:: 3.9
.. c:function:: int PyObject_GC_IsFinalized(PyObject *op)
Returns 1 if the object type of *op* implements the GC protocol and *op* has been
already finalized by the garbage collector and 0 otherwise.
This is analogous to the Python function :func:`gc.is_finalized`.
.. versionadded:: 3.9
Similarly, the deallocator for the object must conform to a similar pair of
rules:

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

@ -22,12 +22,14 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
.. c:function:: int PyGen_Check(PyObject *ob)
Return true if *ob* is a generator object; *ob* must not be ``NULL``.
Return true if *ob* is a generator object; *ob* must not be ``NULL``. This
function always succeeds.
.. c:function:: int PyGen_CheckExact(PyObject *ob)
Return true if *ob*'s type is :c:type:`PyGen_Type`; *ob* must not be ``NULL``.
Return true if *ob*'s type is :c:type:`PyGen_Type`; *ob* must not be
``NULL``. This function always succeeds.
.. c:function:: PyObject* PyGen_New(PyFrameObject *frame)

15
Doc/c-api/import.rst
View File

@ -223,21 +223,6 @@ Importing Modules
Return a new reference to the finder object.
.. c:function:: void _PyImport_Init()
Initialize the import mechanism. For internal use only.
.. c:function:: void PyImport_Cleanup()
Empty the module table. For internal use only.
.. c:function:: void _PyImport_Fini()
Finalize the import mechanism. For internal use only.
.. c:function:: int PyImport_ImportFrozenModuleObject(PyObject *name)
Load a frozen module named *name*. Return ``1`` for success, ``0`` if the

165
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.
@ -842,12 +842,12 @@ code, or when embedding the Python interpreter:
single: PyEval_SaveThread()
single: PyEval_RestoreThread()
Initialize and acquire the global interpreter lock. It should be called in the
main thread before creating a second thread or engaging in any other thread
operations such as ``PyEval_ReleaseThread(tstate)``. It is not needed before
calling :c:func:`PyEval_SaveThread` or :c:func:`PyEval_RestoreThread`.
Deprecated function which does nothing.
This is a no-op when called for a second time.
In Python 3.6 and older, this function created the GIL if it didn't exist.
.. versionchanged:: 3.9
The function now does nothing.
.. versionchanged:: 3.7
This function is now called by :c:func:`Py_Initialize()`, so you don't
@ -856,6 +856,8 @@ code, or when embedding the Python interpreter:
.. versionchanged:: 3.2
This function cannot be called before :c:func:`Py_Initialize()` anymore.
.. deprecated-removed:: 3.9 3.11
.. index:: module: _thread
@ -868,6 +870,8 @@ code, or when embedding the Python interpreter:
.. versionchanged:: 3.7
The :term:`GIL` is now initialized by :c:func:`Py_Initialize()`.
.. deprecated-removed:: 3.9 3.11
.. c:function:: PyThreadState* PyEval_SaveThread()
@ -1048,6 +1052,10 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
Reset all information in a thread state object. The global interpreter lock
must be held.
.. versionchanged:: 3.9
This function now calls the :c:member:`PyThreadState.on_delete` callback.
Previously, that happened in :c:func:`PyThreadState_Delete`.
.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
@ -1056,11 +1064,65 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
:c:func:`PyThreadState_Clear`.
.. c:function:: PY_INT64_T PyInterpreterState_GetID(PyInterpreterState *interp)
.. c:function:: void PyThreadState_DeleteCurrent(void)
Destroy the current thread state and release the global interpreter lock.
Like :c:func:`PyThreadState_Delete`, the global interpreter lock need not
be held. The thread state must have been reset with a previous call
to :c:func:`PyThreadState_Clear`.
.. c:function:: PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)
Get the current frame of the Python thread state *tstate*.
Return a strong reference. Return ``NULL`` if no frame is currently
executing.
See also :c:func:`PyEval_GetFrame`.
*tstate* must not be ``NULL``.
.. versionadded:: 3.9
.. c:function:: uint64_t PyThreadState_GetID(PyThreadState *tstate)
Get the unique thread state identifier of the Python thread state *tstate*.
*tstate* must not be ``NULL``.
.. versionadded:: 3.9
.. c:function:: PyInterpreterState* PyThreadState_GetInterpreter(PyThreadState *tstate)
Get the interpreter of the Python thread state *tstate*.
*tstate* must not be ``NULL``.
.. versionadded:: 3.9
.. c:function:: PyInterpreterState* PyInterpreterState_Get(void)
Get the current interpreter.
Issue a fatal error if there no current Python thread state or no current
interpreter. It cannot return NULL.
The caller must hold the GIL.
.. versionadded:: 3.9
.. c:function:: int64_t PyInterpreterState_GetID(PyInterpreterState *interp)
Return the interpreter's unique ID. If there was any error in doing
so then ``-1`` is returned and an error is set.
The caller must hold the GIL.
.. versionadded:: 3.7
@ -1075,6 +1137,32 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. versionadded:: 3.8
.. c:type:: PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, PyFrameObject *frame, int throwflag)
Type of a frame evaluation function.
The *throwflag* parameter is used by the ``throw()`` method of generators:
if non-zero, handle the current exception.
.. versionchanged:: 3.9
The function now takes a *tstate* parameter.
.. c:function:: _PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
Get the frame evaluation function.
See the :pep:`523` "Adding a frame evaluation API to CPython".
.. versionadded:: 3.9
.. c:function:: void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)
Set the frame evaluation function.
See the :pep:`523` "Adding a frame evaluation API to CPython".
.. versionadded:: 3.9
.. c:function:: PyObject* PyThreadState_GetDict()
@ -1102,7 +1190,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
Acquire the global interpreter lock and set the current thread state to
*tstate*, which should not be ``NULL``. The lock must have been created earlier.
*tstate*, which must not be ``NULL``. The lock must have been created earlier.
If this thread already has the lock, deadlock ensues.
.. note::
@ -1326,6 +1414,10 @@ pointer and a void pointer argument.
This function doesn't need a current thread state to run, and it doesn't
need the global interpreter lock.
To call this function in a subinterpreter, the caller must hold the GIL.
Otherwise, the function *func* can be scheduled to be called from the wrong
interpreter.
.. warning::
This is a low-level function, only useful for very special cases.
There is no guarantee that *func* will be called as quick as
@ -1334,6 +1426,12 @@ pointer and a void pointer argument.
function is generally **not** suitable for calling Python code from
arbitrary C threads. Instead, use the :ref:`PyGILState API<gilstate>`.
.. versionchanged:: 3.9
If this function is called in a subinterpreter, the function *func* is
now scheduled to be called from the subinterpreter, rather than being
called from the main interpreter. Each subinterpreter now has its own
list of scheduled calls.
.. versionadded:: 3.1
.. _profiling:
@ -1456,6 +1554,8 @@ Python-level trace functions in previous versions.
profile function is called for all monitored events except :const:`PyTrace_LINE`
:const:`PyTrace_OPCODE` and :const:`PyTrace_EXCEPTION`.
The caller must hold the :term:`GIL`.
.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
@ -1466,6 +1566,9 @@ Python-level trace functions in previous versions.
will not receive :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or
:const:`PyTrace_C_RETURN` as a value for the *what* parameter.
The caller must hold the :term:`GIL`.
.. _advanced-debugging:
Advanced Debugger Support
@ -1516,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
@ -1527,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:
@ -1624,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.

46
Doc/c-api/init_config.rst
View File

@ -43,6 +43,7 @@ Functions:
* :c:func:`Py_PreInitializeFromArgs`
* :c:func:`Py_PreInitializeFromBytesArgs`
* :c:func:`Py_RunMain`
* :c:func:`Py_GetArgcArgv`
The preconfiguration (``PyPreConfig`` type) is stored in
``_PyRuntime.preconfig`` and the configuration (``PyConfig`` type) is stored in
@ -436,6 +437,14 @@ PyConfig
:data:`sys.base_prefix`.
.. c:member:: wchar_t* platlibdir
:data:`sys.platlibdir`: platform library directory name, set at configure time
by ``--with-platlibdir``, overrideable by the ``PYTHONPLATLIBDIR``
environment variable.
.. versionadded:: 3.9
.. c:member:: int buffered_stdio
If equals to 0, enable unbuffered mode, making the stdout and stderr
@ -466,13 +475,13 @@ PyConfig
.. c:member:: int dev_mode
Development mode: see :option:`-X dev <-X>`.
If non-zero, enable the :ref:`Python Development Mode <devmode>`.
.. c:member:: int dump_refs
If non-zero, dump all objects which are still alive at exit.
Require a debug build of Python (``Py_REF_DEBUG`` macro must be defined).
``Py_TRACE_REFS`` macro must be defined in build.
.. c:member:: wchar_t* exec_prefix
@ -627,14 +636,6 @@ PyConfig
``python3 -m MODULE`` argument. Used by :c:func:`Py_RunMain`.
.. c:member:: int show_alloc_count
Show allocation counts at exit?
Set to 1 by :option:`-X showalloccount <-X>` command line option.
Need a special Python build with ``COUNT_ALLOCS`` macro defined.
.. c:member:: int show_ref_count
Show total reference count at exit?
@ -694,6 +695,16 @@ PyConfig
:data:`sys._xoptions`.
.. c:member:: int _use_peg_parser
Enable PEG parser? Default: 1.
Set to 0 by :option:`-X oldparser <-X>` and :envvar:`PYTHONOLDPARSER`.
See also :pep:`617`.
.. deprecated-removed:: 3.9 3.10
If ``parse_argv`` is non-zero, ``argv`` arguments are parsed the same
way the regular Python parses command line arguments, and Python
arguments are stripped from ``argv``: see :ref:`Command Line Arguments
@ -702,6 +713,10 @@ arguments are stripped from ``argv``: see :ref:`Command Line Arguments
The ``xoptions`` options are parsed to set other options: see :option:`-X`
option.
.. versionchanged:: 3.9
The ``show_alloc_count`` field has been removed.
Initialization with PyConfig
----------------------------
@ -878,6 +893,7 @@ Path Configuration
* Path configuration inputs:
* :c:member:`PyConfig.home`
* :c:member:`PyConfig.platlibdir`
* :c:member:`PyConfig.pathconfig_warnings`
* :c:member:`PyConfig.program_name`
* :c:member:`PyConfig.pythonpath_env`
@ -969,6 +985,14 @@ customized Python always running in isolated mode using
:c:func:`Py_RunMain`.
Py_GetArgcArgv()
----------------
.. c:function:: void Py_GetArgcArgv(int *argc, wchar_t ***argv)
Get the original command line arguments, before Python modified them.
Multi-Phase Initialization Private Provisional API
--------------------------------------------------
@ -998,6 +1022,8 @@ Private provisional API:
* :c:member:`PyConfig._init_main`: if set to 0,
:c:func:`Py_InitializeFromConfig` stops at the "Core" initialization phase.
* :c:member:`PyConfig._isolated_interpreter`: if non-zero,
disallow threads, subprocesses and fork.
.. c:function:: PyStatus _Py_InitializeMain(void)

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

@ -107,11 +107,24 @@ complete listing.
.. c:macro:: Py_UNREACHABLE()
Use this when you have a code path that you do not expect to be reached.
Use this when you have a code path that cannot be reached by design.
For example, in the ``default:`` clause in a ``switch`` statement for which
all possible values are covered in ``case`` statements. Use this in places
where you might be tempted to put an ``assert(0)`` or ``abort()`` call.
In release mode, the macro helps the compiler to optimize the code, and
avoids a warning about unreachable code. For example, the macro is
implemented with ``__builtin_unreachable()`` on GCC in release mode.
A use for ``Py_UNREACHABLE()`` is following a call a function that
never returns but that is not declared :c:macro:`_Py_NO_RETURN`.
If a code path is very unlikely code but can be reached under exceptional
case, this macro must not be used. For example, under low memory condition
or if a system call returns a value out of the expected range. In this
case, it's better to report the error to the caller. If the error cannot
be reported to caller, :c:func:`Py_FatalError` can be used.
.. versionadded:: 3.7
.. c:macro:: Py_ABS(x)
@ -216,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.
@ -483,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

3
Doc/c-api/iter.rst
View File

@ -9,7 +9,8 @@ There are two functions specifically for working with iterators.
.. c:function:: int PyIter_Check(PyObject *o)
Return true if the object *o* supports the iterator protocol.
Return true if the object *o* supports the iterator protocol. This
function always succeeds.
.. c:function:: PyObject* PyIter_Next(PyObject *o)

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

@ -21,7 +21,8 @@ sentinel value is returned.
.. c:function:: int PySeqIter_Check(op)
Return true if the type of *op* is :c:data:`PySeqIter_Type`.
Return true if the type of *op* is :c:data:`PySeqIter_Type`. This function
always succeeds.
.. c:function:: PyObject* PySeqIter_New(PyObject *seq)
@ -39,7 +40,8 @@ sentinel value is returned.
.. c:function:: int PyCallIter_Check(op)
Return true if the type of *op* is :c:data:`PyCallIter_Type`.
Return true if the type of *op* is :c:data:`PyCallIter_Type`. This
function always succeeds.
.. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)

11
Doc/c-api/list.rst
View File

@ -22,13 +22,13 @@ List Objects
.. c:function:: int PyList_Check(PyObject *p)
Return true if *p* is a list object or an instance of a subtype of the list
type.
type. This function always succeeds.
.. c:function:: int PyList_CheckExact(PyObject *p)
Return true if *p* is a list object, but not an instance of a subtype of
the list type.
the list type. This function always succeeds.
.. c:function:: PyObject* PyList_New(Py_ssize_t len)
@ -142,10 +142,3 @@ List Objects
Return a new tuple object containing the contents of *list*; equivalent to
``tuple(list)``.
.. c:function:: int PyList_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 3.3

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

@ -27,13 +27,13 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: int PyLong_Check(PyObject *p)
Return true if its argument is a :c:type:`PyLongObject` or a subtype of
:c:type:`PyLongObject`.
:c:type:`PyLongObject`. This function always succeeds.
.. c:function:: int PyLong_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of
:c:type:`PyLongObject`.
:c:type:`PyLongObject`. This function always succeeds.
.. c:function:: PyObject* PyLong_FromLong(long v)
@ -42,9 +42,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
The current implementation keeps an array of integer objects for all integers
between ``-5`` and ``256``, when you create an int in that range you actually
just get back a reference to the existing object. So it should be possible to
change the value of ``1``. I suspect the behaviour of Python in this case is
undefined. :-)
just get back a reference to the existing object.
.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
@ -193,8 +191,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
:meth:`__int__` method (if present) to convert it to a
:c:type:`PyLongObject`.
If the value of *obj* is greater than :const:`PY_LLONG_MAX` or less than
:const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
If the value of *obj* is greater than :const:`LLONG_MAX` or less than
:const:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
and return ``-1``; otherwise, set *\*overflow* to ``0``. If any other
exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
@ -302,7 +300,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
it to a :c:type:`PyLongObject`.
If the value of *obj* is out of range for an :c:type:`unsigned long long`,
return the reduction of that value modulo ``PY_ULLONG_MAX + 1``.
return the reduction of that value modulo ``ULLONG_MAX + 1``.
Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred`
to disambiguate.

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.

3
Doc/c-api/memoryview.rst
View File

@ -45,7 +45,8 @@ any other object.
.. c:function:: int PyMemoryView_Check(PyObject *obj)
Return true if the object *obj* is a memoryview object. It is not
currently allowed to create subclasses of :class:`memoryview`.
currently allowed to create subclasses of :class:`memoryview`. This
function always succeeds.
.. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview)

9
Doc/c-api/method.rst
View File

@ -22,6 +22,7 @@ to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
Return true if *o* is an instance method object (has type
:c:data:`PyInstanceMethod_Type`). The parameter must not be ``NULL``.
This function always succeeds.
.. c:function:: PyObject* PyInstanceMethod_New(PyObject *func)
@ -64,7 +65,7 @@ no longer available.
.. c:function:: int PyMethod_Check(PyObject *o)
Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). The
parameter must not be ``NULL``.
parameter must not be ``NULL``. This function always succeeds.
.. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self)
@ -92,9 +93,3 @@ no longer available.
.. c:function:: PyObject* PyMethod_GET_SELF(PyObject *meth)
Macro version of :c:func:`PyMethod_Self` which avoids error checking.
.. c:function:: int PyMethod_ClearFreeList()
Clear the free list. Return the total number of freed items.

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

@ -19,12 +19,13 @@ Module Objects
.. c:function:: int PyModule_Check(PyObject *p)
Return true if *p* is a module object, or a subtype of a module object.
This function always succeeds.
.. c:function:: int PyModule_CheckExact(PyObject *p)
Return true if *p* is a module object, but not a subtype of
:c:data:`PyModule_Type`.
:c:data:`PyModule_Type`. This function always succeeds.
.. c:function:: PyObject* PyModule_NewObject(PyObject *name)
@ -196,23 +197,47 @@ or request "multi-phase initialization" by returning the definition struct itsel
.. c:member:: traverseproc m_traverse
A traversal function to call during GC traversal of the module object, or
``NULL`` if not needed. This function may be called before module state
is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
and before the :c:member:`Py_mod_exec` function is executed.
``NULL`` if not needed.
This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if :c:member:`m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
.. versionchanged:: 3.9
No longer called before the module state is allocated.
.. c:member:: inquiry m_clear
A clear function to call during GC clearing of the module object, or
``NULL`` if not needed. This function may be called before module state
is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
and before the :c:member:`Py_mod_exec` function is executed.
``NULL`` if not needed.
This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if :c:member:`m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
.. versionchanged:: 3.9
No longer called before the module state is allocated.
.. c:member:: freefunc m_free
A function to call during deallocation of the module object, or ``NULL`` if
not needed. This function may be called before module state
is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
and before the :c:member:`Py_mod_exec` function is executed.
A function to call during deallocation of the module object, or ``NULL``
if not needed.
This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if :c:member:`m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
.. versionchanged:: 3.9
No longer called before the module state is allocated.
Single-phase initialization
...........................
@ -301,7 +326,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:
@ -333,7 +358,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,
@ -417,7 +442,7 @@ state:
Add an object to *module* as *name*. This is a convenience function which can
be used from the module's initialization function. This steals a reference to
*value* on success. Return ``-1`` on error, ``0`` on success.
*value* on success. Return ``-1`` on error, ``0`` on success.
.. note::
@ -460,6 +485,16 @@ state:
Add a string constant to *module*.
.. c:function:: int PyModule_AddType(PyObject *module, PyTypeObject *type)
Add a type object to *module*.
The type object is finalized by calling internally :c:func:`PyType_Ready`.
The name of the type object is taken from the last component of
:c:member:`~PyTypeObject.tp_name` after dot.
Return ``-1`` on error, ``0`` on success.
.. versionadded:: 3.9
Module lookup
^^^^^^^^^^^^^
@ -493,6 +528,8 @@ since multiple such modules can be created from a single definition.
mechanisms (either by calling it directly, or by referring to its
implementation for details of the required state updates).
The caller must hold the GIL.
Return 0 on success or -1 on failure.
.. versionadded:: 3.3
@ -502,4 +539,6 @@ since multiple such modules can be created from a single definition.
Removes the module object created from *def* from the interpreter state.
Return 0 on success or -1 on failure.
The caller must hold the GIL.
.. versionadded:: 3.3

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

@ -196,6 +196,7 @@ Object Protocol
This function now includes a debug assertion to help ensure that it
does not silently discard an active exception.
.. c:function:: PyObject* PyObject_Bytes(PyObject *o)
.. index:: builtin: bytes
@ -247,179 +248,6 @@ Object Protocol
of base classes).
.. c:function:: int PyCallable_Check(PyObject *o)
Determine if the object *o* is callable. Return ``1`` if the object is callable
and ``0`` otherwise. This function always succeeds.
.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
Call a callable Python object *callable*, with arguments given by the
tuple *args*, and named arguments given by the dictionary *kwargs*.
*args* must not be ``NULL``, use an empty tuple if no arguments are needed.
If no named arguments are needed, *kwargs* can be ``NULL``.
Return the result of the call on success, or raise an exception and return
``NULL`` on failure.
This is the equivalent of the Python expression:
``callable(*args, **kwargs)``.
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
Call a callable Python object *callable*, with arguments given by the
tuple *args*. If no arguments are needed, then *args* can be ``NULL``.
Return the result of the call on success, or raise an exception and return
``NULL`` on failure.
This is the equivalent of the Python expression: ``callable(*args)``.
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
Call a callable Python object *callable*, with a variable number of C arguments.
The C arguments are described using a :c:func:`Py_BuildValue` style format
string. The format can be ``NULL``, indicating that no arguments are provided.
Return the result of the call on success, or raise an exception and return
``NULL`` on failure.
This is the equivalent of the Python expression: ``callable(*args)``.
Note that if you only pass :c:type:`PyObject \*` args,
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
.. versionchanged:: 3.4
The type of *format* was changed from ``char *``.
.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
Call the method named *name* of object *obj* with a variable number of C
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
string that should produce a tuple.
The format can be ``NULL``, indicating that no arguments are provided.
Return the result of the call on success, or raise an exception and return
``NULL`` on failure.
This is the equivalent of the Python expression:
``obj.name(arg1, arg2, ...)``.
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)
Call a callable Python object *callable*, with a variable number of
: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
``NULL`` on failure.
This is the equivalent of the Python expression:
``callable(arg1, arg2, ...)``.
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)
Calls 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
of parameters followed by ``NULL``.
Return the result of the call on success, or raise an exception and return
``NULL`` on failure.
.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
Call a callable Python object *callable*, using
:c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>` if possible.
*args* is a C array with the positional arguments.
*nargsf* is the number of positional arguments plus optionally the flag
:const:`PY_VECTORCALL_ARGUMENTS_OFFSET` (see below).
To get actual number of arguments, use
:c:func:`PyVectorcall_NARGS(nargsf) <PyVectorcall_NARGS>`.
*kwnames* can be either ``NULL`` (no keyword arguments) or a tuple of keyword
names. In the latter case, the values of the keyword arguments are stored
in *args* after the positional arguments.
The number of keyword arguments does not influence *nargsf*.
*kwnames* must contain only objects of type ``str`` (not a subclass),
and all keys must be unique.
Return the result of the call on success, or raise an exception and return
``NULL`` on failure.
This uses the vectorcall protocol if the callable supports it;
otherwise, the arguments are converted to use
:c:member:`~PyTypeObject.tp_call`.
.. note::
This function is provisional and expected to become public in Python 3.9,
with a different name and, possibly, changed semantics.
If you use the function, plan for updating your code for Python 3.9.
.. versionadded:: 3.8
.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET
If set in a vectorcall *nargsf* argument, the callee is allowed to
temporarily change ``args[-1]``. In other words, *args* points to
argument 1 (not 0) in the allocated vector.
The callee must restore the value of ``args[-1]`` before returning.
Whenever they can do so cheaply (without additional allocation), callers
are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
Doing so will allow callables such as bound methods to make their onward
calls (which include a prepended *self* argument) cheaply.
.. versionadded:: 3.8
.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf)
Given a vectorcall *nargsf* argument, return the actual number of
arguments.
Currently equivalent to ``nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET``.
.. versionadded:: 3.8
.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
Same as :c:func:`_PyObject_Vectorcall` except that the keyword arguments
are passed as a dictionary in *kwdict*. This may be ``NULL`` if there
are no keyword arguments.
For callables supporting :c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>`,
the arguments are internally converted to the vectorcall convention.
Therefore, this function adds some overhead compared to
:c:func:`_PyObject_Vectorcall`.
It should only be used if the caller already has a dictionary ready to use.
.. note::
This function is provisional and expected to become public in Python 3.9,
with a different name and, possibly, changed semantics.
If you use the function, plan for updating your code for Python 3.9.
.. versionadded:: 3.8
.. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
.. index:: builtin: hash
@ -463,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.

34
Doc/c-api/reflection.rst
View File

@ -5,34 +5,60 @@
Reflection
==========
.. c:function:: PyObject* PyEval_GetBuiltins()
.. c:function:: PyObject* PyEval_GetBuiltins(void)
Return a dictionary of the builtins in the current execution frame,
or the interpreter of the thread state if no frame is currently executing.
.. c:function:: PyObject* PyEval_GetLocals()
.. c:function:: PyObject* PyEval_GetLocals(void)
Return a dictionary of the local variables in the current execution frame,
or ``NULL`` if no frame is currently executing.
.. c:function:: PyObject* PyEval_GetGlobals()
.. c:function:: PyObject* PyEval_GetGlobals(void)
Return a dictionary of the global variables in the current execution frame,
or ``NULL`` if no frame is currently executing.
.. c:function:: PyFrameObject* PyEval_GetFrame()
.. c:function:: PyFrameObject* PyEval_GetFrame(void)
Return the current thread state's frame, which is ``NULL`` if no frame is
currently executing.
See also :c:func:`PyThreadState_GetFrame`.
.. c:function:: int PyFrame_GetBack(PyFrameObject *frame)
Get the *frame* next outer frame.
Return a strong reference, or ``NULL`` if *frame* has no outer frame.
*frame* must not be ``NULL``.
.. versionadded:: 3.9
.. c:function:: int PyFrame_GetCode(PyFrameObject *frame)
Get the *frame* code.
Return a strong reference.
*frame* must not be ``NULL``. The result (frame code) cannot be ``NULL``.
.. versionadded:: 3.9
.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
Return the line number that *frame* is currently executing.
*frame* must not be ``NULL``.
.. c:function:: const char* PyEval_GetFuncName(PyObject *func)

16
Doc/c-api/set.rst
View File

@ -53,28 +53,29 @@ the constructor functions work with any iterable Python object.
.. c:function:: int PySet_Check(PyObject *p)
Return true if *p* is a :class:`set` object or an instance of a subtype.
This function always succeeds.
.. c:function:: int PyFrozenSet_Check(PyObject *p)
Return true if *p* is a :class:`frozenset` object or an instance of a
subtype.
subtype. This function always succeeds.
.. c:function:: int PyAnySet_Check(PyObject *p)
Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
instance of a subtype.
instance of a subtype. This function always succeeds.
.. c:function:: int PyAnySet_CheckExact(PyObject *p)
Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
not an instance of a subtype.
not an instance of a subtype. This function always succeeds.
.. c:function:: int PyFrozenSet_CheckExact(PyObject *p)
Return true if *p* is a :class:`frozenset` object but not an instance of a
subtype.
subtype. This function always succeeds.
.. c:function:: PyObject* PySet_New(PyObject *iterable)
@ -157,10 +158,3 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
.. c:function:: int PySet_Clear(PyObject *set)
Empty an existing set of all elements.
.. c:function:: int PySet_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 3.3

3
Doc/c-api/slice.rst
View File

@ -14,7 +14,8 @@ Slice Objects
.. c:function:: int PySlice_Check(PyObject *ob)
Return true if *ob* is a slice object; *ob* must not be ``NULL``.
Return true if *ob* is a slice object; *ob* must not be ``NULL``. This
function always succeeds.
.. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)

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

@ -9,6 +9,10 @@ There are a large number of structures which are used in the definition of
object types for Python. This section describes these structures and how they
are used.
Base object types and macros
----------------------------
All Python objects ultimately share a small number of fields at the beginning
of the object's representation in memory. These are represented by the
:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn,
@ -66,6 +70,21 @@ the definition of all other Python objects.
(((PyObject*)(o))->ob_type)
.. c:function:: int Py_IS_TYPE(PyObject *o, PyTypeObject *type)
Return non-zero if the object *o* type is *type*. Return zero otherwise.
Equivalent to: ``Py_TYPE(o) == type``.
.. versionadded:: 3.9
.. c:function:: void Py_SET_TYPE(PyObject *o, PyTypeObject *type)
Set the object *o* type to *type*.
.. versionadded:: 3.9
.. c:macro:: Py_REFCNT(o)
This macro is used to access the :attr:`ob_refcnt` member of a Python
@ -75,6 +94,13 @@ the definition of all other Python objects.
(((PyObject*)(o))->ob_refcnt)
.. c:function:: void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)
Set the object *o* reference counter to *refcnt*.
.. versionadded:: 3.9
.. c:macro:: Py_SIZE(o)
This macro is used to access the :attr:`ob_size` member of a Python object.
@ -83,6 +109,13 @@ the definition of all other Python objects.
(((PyVarObject*)(o))->ob_size)
.. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
Set the object *o* size to *size*.
.. versionadded:: 3.9
.. c:macro:: PyObject_HEAD_INIT(type)
This is a macro which expands to initialization values for a new
@ -102,32 +135,68 @@ the definition of all other Python objects.
1, type, size,
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
reference.
The function signature is::
PyObject *PyCFunction(PyObject *self,
PyObject *args);
.. c:type:: PyCFunctionWithKeywords
Type of the functions used to implement Python callables in C
with signature :const:`METH_VARARGS | METH_KEYWORDS`.
The function signature is::
PyObject *PyCFunctionWithKeywords(PyObject *self,
PyObject *args,
PyObject *kwargs);
.. c:type:: _PyCFunctionFast
Type of the functions used to implement Python callables in C
with signature :const:`METH_FASTCALL`.
The function signature is::
PyObject *_PyCFunctionFast(PyObject *self,
PyObject *const *args,
Py_ssize_t nargs);
.. c:type:: _PyCFunctionFastWithKeywords
Type of the functions used to implement Python callables in C
with signature :const:`METH_FASTCALL | METH_KEYWORDS`.
The function signature is::
PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
PyObject *const *args,
Py_ssize_t nargs,
PyObject *kwnames);
.. c:type:: PyCMethod
Type of the functions used to implement Python callables in C
with signature :const:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`.
The function signature is::
PyObject *PyCMethod(PyObject *self,
PyTypeObject *defining_class,
PyObject *const *args,
Py_ssize_t nargs,
PyObject *kwnames)
.. versionadded:: 3.9
.. c:type:: PyMethodDef
@ -151,24 +220,22 @@ the definition of all other Python objects.
+------------------+---------------+-------------------------------+
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.
The individual flags indicate either a calling convention or a binding
convention.
There are four basic calling conventions for positional arguments
and two of them can be combined with :const:`METH_KEYWORDS` to support
also keyword arguments. So there are a total of 6 calling conventions:
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
@ -189,7 +256,7 @@ also keyword arguments. So there are a total of 6 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>`.
@ -201,9 +268,11 @@ also keyword arguments. So there are a total of 6 calling conventions:
Extension of :const:`METH_FASTCALL` supporting also keyword arguments,
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
Keyword arguments are passed the same way as in the vectorcall protocol:
there is an additional fourth :c:type:`PyObject\*` parameter
Keyword arguments are passed the same way as in the
:ref:`vectorcall protocol <vectorcall>`:
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
arguments are stored in the *args* array, after the positional arguments.
@ -212,6 +281,19 @@ also keyword arguments. So there are a total of 6 calling conventions:
.. versionadded:: 3.7
.. data:: METH_METHOD | METH_FASTCALL | METH_KEYWORDS
Extension of :const:`METH_FASTCALL | METH_KEYWORDS` supporting the *defining
class*, that is, the class that contains the method in question.
The defining class might be a superclass of ``Py_TYPE(self)``.
The method needs to be of type :c:type:`PyCMethod`, the same as for
``METH_FASTCALL | METH_KEYWORDS`` with ``defining_class`` argument added after
``self``.
.. versionadded:: 3.9
.. data:: METH_NOARGS
Methods without parameters don't need to check whether arguments are given if
@ -226,7 +308,7 @@ also keyword arguments. So there are a total of 6 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
@ -270,6 +352,9 @@ definition with the same method name.
than wrapper object calls.
Accessing attributes of extension types
---------------------------------------
.. c:type:: PyMemberDef
Structure which describes an attribute of a type which corresponds to a C
@ -335,6 +420,21 @@ definition with the same method name.
Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
members can be deleted. (They are set to ``NULL``).
.. _pymemberdef-offsets:
Heap allocated types (created using :c:func:`PyType_FromSpec` or similar),
``PyMemberDef`` may contain definitions for the special members
``__dictoffset__``, ``__weaklistoffset__`` and ``__vectorcalloffset__``,
corresponding to
:c:member:`~PyTypeObject.tp_dictoffset`,
:c:member:`~PyTypeObject.tp_weaklistoffset` and
:c:member:`~PyTypeObject.tp_vectorcall_offset` in type objects.
These must be defined with ``T_PYSSIZET`` and ``READONLY``, for example::
static PyMemberDef spam_type_members[] = {
{"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY},
{NULL} /* Sentinel */
};
.. c:type:: PyGetSetDef
@ -359,7 +459,7 @@ definition with the same method name.
| | | 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 *);
@ -367,7 +467,7 @@ definition with the same method name.
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 *);

7
Doc/c-api/sys.rst
View File

@ -388,6 +388,13 @@ Process Control
function :c:func:`abort` is called which will attempt to produce a :file:`core`
file.
The ``Py_FatalError()`` function is replaced with a macro which logs
automatically the name of the current function, unless the
``Py_LIMITED_API`` macro is defined.
.. versionchanged:: 3.9
Log the function name automatically.
.. c:function:: void Py_Exit(int status)

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

@ -21,14 +21,14 @@ Tuple Objects
.. c:function:: int PyTuple_Check(PyObject *p)
Return true if *p* is a tuple object or an instance of a subtype of the tuple
type.
Return true if *p* is a tuple object or an instance of a subtype of the
tuple type. This function always succeeds.
.. c:function:: int PyTuple_CheckExact(PyObject *p)
Return true if *p* is a tuple object, but not an instance of a subtype of the
tuple type.
tuple type. This function always succeeds.
.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
@ -111,11 +111,6 @@ Tuple Objects
raises :exc:`MemoryError` or :exc:`SystemError`.
.. c:function:: int PyTuple_ClearFreeList()
Clear the free list. Return the total number of freed items.
Struct Sequence Objects
-----------------------
@ -166,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.
@ -182,10 +177,13 @@ type.
+-----------+------------------+-----------------------------------------+
.. c:var:: char* PyStructSequence_UnnamedField
.. c:var:: const char * const PyStructSequence_UnnamedField
Special value for a field name to leave it unnamed.
.. versionchanged:: 3.9
The type was changed from ``char *``.
.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type)

83
Doc/c-api/type.rst
View File

@ -21,14 +21,16 @@ Type Objects
.. c:function:: int PyType_Check(PyObject *o)
Return true if the object *o* is a type object, including instances of types
derived from the standard type object. Return false in all other cases.
Return non-zero if the object *o* is a type object, including instances of
types derived from the standard type object. Return 0 in all other cases.
This function always succeeds.
.. c:function:: int PyType_CheckExact(PyObject *o)
Return true if the object *o* is a type object, but not a subtype of the
standard type object. Return false in all other cases.
Return non-zero if the object *o* is a type object, but not a subtype of
the standard type object. Return 0 in all other cases. This function
always succeeds.
.. c:function:: unsigned int PyType_ClearCache()
@ -57,8 +59,8 @@ Type Objects
.. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature)
Return true if the type object *o* sets the feature *feature*. Type features
are denoted by single bit flags.
Return non-zero if the type object *o* sets the feature *feature*.
Type features are denoted by single bit flags.
.. c:function:: int PyType_IS_GC(PyTypeObject *o)
@ -109,6 +111,37 @@ Type Objects
.. versionadded:: 3.4
.. c:function:: PyObject* PyType_GetModule(PyTypeObject *type)
Return the module object associated with the given type when the type was
created using :c:func:`PyType_FromModuleAndSpec`.
If no module is associated with the given type, sets :py:class:`TypeError`
and returns ``NULL``.
This function is usually used to get the module in which a method is defined.
Note that in such a method, ``PyType_GetModule(Py_TYPE(self))``
may not return the intended result.
``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
are not necessarily defined in the same module as their superclass.
See :c:type:`PyCMethod` to get the class that defines the method.
.. versionadded:: 3.9
.. c:function:: void* PyType_GetModuleState(PyTypeObject *type)
Return the state of the module object associated with the given type.
This is a shortcut for calling :c:func:`PyModule_GetState()` on the result
of :c:func:`PyType_GetModule`.
If no module is associated with the given type, sets :py:class:`TypeError`
and returns ``NULL``.
If the *type* has an associated module but its state is ``NULL``,
returns ``NULL`` without setting an exception.
.. versionadded:: 3.9
Creating Heap-Allocated Types
.............................
@ -116,7 +149,7 @@ Creating Heap-Allocated Types
The following functions and structs are used to create
:ref:`heap types <heap-types>`.
.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
.. c:function:: PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
Creates and returns a heap type object from the *spec*
(:const:`Py_TPFLAGS_HEAPTYPE`).
@ -124,11 +157,25 @@ The following functions and structs are used to create
If *bases* is a tuple, the created heap type contains all types contained
in it as base types.
If *bases* is ``NULL``, the *Py_tp_base* slot is used instead.
If *bases* is ``NULL``, the *Py_tp_bases* slot is used instead.
If that also is ``NULL``, the *Py_tp_base* slot is used instead.
If that also is ``NULL``, the new type derives from :class:`object`.
The *module* argument can be used to record the module in which the new
class is defined. It must be a module object or ``NULL``.
If not ``NULL``, the module is associated with the new type and can later be
retreived with :c:func:`PyType_GetModule`.
The associated module is not inherited by subclasses; it must be specified
for each class individually.
This function calls :c:func:`PyType_Ready` on the new type.
.. versionadded:: 3.9
.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
Equivalent to ``PyType_FromModuleAndSpec(NULL, spec, bases)``.
.. versionadded:: 3.3
.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
@ -181,23 +228,37 @@ The following functions and structs are used to create
* ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add`
* ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length`
The following fields cannot be set using :c:type:`PyType_Spec` and :c:type:`PyType_Slot`:
The following fields cannot be set at all using :c:type:`PyType_Spec` and
:c:type:`PyType_Slot`:
* :c:member:`~PyTypeObject.tp_dict`
* :c:member:`~PyTypeObject.tp_mro`
* :c:member:`~PyTypeObject.tp_cache`
* :c:member:`~PyTypeObject.tp_subclasses`
* :c:member:`~PyTypeObject.tp_weaklist`
* :c:member:`~PyTypeObject.tp_print`
* :c:member:`~PyTypeObject.tp_vectorcall`
* :c:member:`~PyTypeObject.tp_weaklistoffset`
(see :ref:`PyMemberDef <pymemberdef-offsets>`)
* :c:member:`~PyTypeObject.tp_dictoffset`
(see :ref:`PyMemberDef <pymemberdef-offsets>`)
* :c:member:`~PyTypeObject.tp_vectorcall_offset`
(see :ref:`PyMemberDef <pymemberdef-offsets>`)
The following fields cannot be set using :c:type:`PyType_Spec` and
:c:type:`PyType_Slot` under the limited API:
* :c:member:`~PyBufferProcs.bf_getbuffer`
* :c:member:`~PyBufferProcs.bf_releasebuffer`
Setting :c:data:`Py_tp_bases` may be problematic on some platforms.
Setting :c:data:`Py_tp_bases` or :c:data:`Py_tp_base` may be
problematic on some platforms.
To avoid issues, use the *bases* argument of
:py:func:`PyType_FromSpecWithBases` instead.
.. versionchanged:: 3.9
Slots in :c:type:`PyBufferProcs` in may be set in the unlimited API.
.. c:member:: void *PyType_Slot.pfunc
The desired value of the slot. In most cases, this is a pointer

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

@ -49,7 +49,7 @@ Quick Reference
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
| :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | | X | X | | X |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
| :c:member:`~PyTypeObject.tp_vectorcall_offset` | Py_ssize_t | | | | | ? |
| :c:member:`~PyTypeObject.tp_vectorcall_offset` | Py_ssize_t | | | X | | X |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
| (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | __getattribute__, | | | | G |
| | | __getattr__ | | | | |
@ -145,15 +145,8 @@ Quick Reference
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
| :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | __del__ | | | | X |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
If :const:`COUNT_ALLOCS` is defined then the following (internal-only)
fields exist as well:
* :c:member:`~PyTypeObject.tp_allocs`
* :c:member:`~PyTypeObject.tp_frees`
* :c:member:`~PyTypeObject.tp_maxalloc`
* :c:member:`~PyTypeObject.tp_prev`
* :c:member:`~PyTypeObject.tp_next`
| :c:member:`~PyTypeObject.tp_vectorcall` | :c:type:`vectorcallfunc` | | | | | |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
.. [#slots]
A slot name in parentheses indicates it is (effectively) deprecated.
@ -180,7 +173,7 @@ fields exist as well:
.. code-block:: none
X - type slot is inherited via PyType_Ready if defined with a NULL value
X - type slot is inherited via *PyType_Ready* if defined with a *NULL* value
% - the slots of the sub-struct are inherited individually
G - inherited, but only in combination with other slots; see the slot's description
? - it's complicated; see the slot's description
@ -687,42 +680,29 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: Py_ssize_t PyTypeObject.tp_vectorcall_offset
An optional offset to a per-instance function that implements calling
the object using the *vectorcall* protocol, a more efficient alternative
the object using the :ref:`vectorcall protocol <vectorcall>`,
a more efficient alternative
of the simpler :c:member:`~PyTypeObject.tp_call`.
This field is only used if the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL`
This field is only used if the flag :const:`Py_TPFLAGS_HAVE_VECTORCALL`
is set. If so, this must be a positive integer containing the offset in the
instance of a :c:type:`vectorcallfunc` pointer.
The signature is the same as for :c:func:`_PyObject_Vectorcall`::
PyObject *vectorcallfunc(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
The *vectorcallfunc* pointer may be zero, in which case the instance behaves
as if :const:`_Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
The *vectorcallfunc* pointer may be ``NULL``, in which case the instance behaves
as if :const:`Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
falls back to :c:member:`~PyTypeObject.tp_call`.
Any class that sets ``_Py_TPFLAGS_HAVE_VECTORCALL`` must also set
Any class that sets ``Py_TPFLAGS_HAVE_VECTORCALL`` must also set
:c:member:`~PyTypeObject.tp_call` and make sure its behaviour is consistent
with the *vectorcallfunc* function.
This can be done by setting *tp_call* to ``PyVectorcall_Call``:
This can be done by setting *tp_call* to :c:func:`PyVectorcall_Call`.
.. c:function:: PyObject *PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)
Call *callable*'s *vectorcallfunc* with positional and keyword
arguments given in a tuple and dict, respectively.
This function is intended to be used in the ``tp_call`` slot.
It does not fall back to ``tp_call`` and it currently does not check the
``_Py_TPFLAGS_HAVE_VECTORCALL`` flag.
To call an object, use one of the :c:func:`PyObject_Call <PyObject_Call>`
functions instead.
.. note::
.. warning::
It is not recommended for :ref:`heap types <heap-types>` to implement
the vectorcall protocol.
When a user sets ``__call__`` in Python code, only ``tp_call`` is updated,
possibly making it inconsistent with the vectorcall function.
When a user sets :attr:`__call__` in Python code, only *tp_call* is updated,
likely making it inconsistent with the vectorcall function.
.. note::
@ -732,18 +712,19 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionchanged:: 3.8
This slot was used for print formatting in Python 2.x.
In Python 3.0 to 3.7, it was reserved and named ``tp_print``.
Before version 3.8, this slot was named ``tp_print``.
In Python 2.x, it was used for printing to a file.
In Python 3.0 to 3.7, it was unused.
**Inheritance:**
This field is inherited by subtypes together with
:c:member:`~PyTypeObject.tp_call`: a subtype inherits
:c:member:`~PyTypeObject.tp_vectorcall_offset` from its base type when
the subtype’s :c:member:`~PyTypeObject.tp_call` is ``NULL``.
Note that `heap types`_ (including subclasses defined in Python) do not
inherit the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag.
This field is always inherited.
However, the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is not
always inherited. If it's not, then the subclass won't use
:ref:`vectorcall <vectorcall>`, except when
:c:func:`PyVectorcall_Call` is explicitly called.
This is in particular the case for `heap types`_
(including subclasses defined in Python).
.. c:member:: getattrfunc PyTypeObject.tp_getattr
@ -965,7 +946,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The signature is the same as for :c:func:`PyObject_SetAttr`::
PyObject *tp_setattro(PyObject *self, PyObject *attr, PyObject *value);
int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);
In addition, setting *value* to ``NULL`` to delete an attribute must be
supported. It is usually convenient to set this field to
@ -1171,27 +1152,20 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:c:member:`~PyTypeObject.tp_finalize` slot is always present in the
type structure.
.. data:: _Py_TPFLAGS_HAVE_VECTORCALL
This bit is set when the class implements the vectorcall protocol.
.. data:: Py_TPFLAGS_HAVE_VECTORCALL
This bit is set when the class implements
the :ref:`vectorcall protocol <vectorcall>`.
See :c:member:`~PyTypeObject.tp_vectorcall_offset` for details.
**Inheritance:**
This bit is set on *static* subtypes if ``tp_flags`` is not overridden:
a subtype inherits ``_Py_TPFLAGS_HAVE_VECTORCALL`` from its base type
when the subtype’s :c:member:`~PyTypeObject.tp_call` is ``NULL``
and the subtype's ``Py_TPFLAGS_HEAPTYPE`` is not set.
This bit is inherited for *static* subtypes if
:c:member:`~PyTypeObject.tp_call` is also inherited.
`Heap types`_ do not inherit ``Py_TPFLAGS_HAVE_VECTORCALL``.
`Heap types`_ do not inherit ``_Py_TPFLAGS_HAVE_VECTORCALL``.
.. note::
This flag is provisional and expected to become public in Python 3.9,
with a different name and, possibly, changed semantics.
If you use vectorcall, plan for updating your code for Python 3.9.
.. versionadded:: 3.8
.. versionadded:: 3.9
.. c:member:: const char* PyTypeObject.tp_doc
@ -1249,11 +1223,25 @@ and :c:type:`PyType_Type` effectively act as defaults.)
but the instance has no strong reference to the elements inside it, as they
are allowed to be removed even if the instance is still alive).
Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to
:c:func:`local_traverse` to have these specific names; don't name them just
anything.
Heap-allocated types (:const:`Py_TPFLAGS_HEAPTYPE`, such as those created
with :c:func:`PyType_FromSpec` and similar APIs) hold a reference to their
type. Their traversal function must therefore either visit
:c:func:`Py_TYPE(self) <Py_TYPE>`, or delegate this responsibility by
calling ``tp_traverse`` of another heap-allocated type (such as a
heap-allocated superclass).
If they do not, the type object may not be garbage-collected.
.. versionchanged:: 3.9
Heap-allocated types are expected to visit ``Py_TYPE(self)`` in
``tp_traverse``. In earlier versions of Python, due to
`bug 40217 <https://bugs.python.org/issue40217>`_, doing this
may lead to crashes in subclasses.
**Inheritance:**
Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
@ -1360,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.
@ -1398,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
@ -1727,9 +1715,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);
The subtype argument is the type of the object being created; the *args* and
The *subtype* argument is the type of the object being created; the *args* and
*kwds* arguments represent positional and keyword arguments of the call to the
type. Note that subtype doesn't have to equal the type whose :c:member:`~PyTypeObject.tp_new`
type. Note that *subtype* doesn't have to equal the type whose :c:member:`~PyTypeObject.tp_new`
function is called; it may be a subtype of that type (but not an unrelated
type).
@ -1912,30 +1900,20 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. seealso:: "Safe object finalization" (:pep:`442`)
The remaining fields are only defined if the feature test macro
:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
documented here for completeness. None of these fields are inherited by
subtypes.
.. c:member:: vectorcallfunc PyTypeObject.tp_vectorcall
.. c:member:: Py_ssize_t PyTypeObject.tp_allocs
Vectorcall function to use for calls of this type object.
In other words, it is used to implement
:ref:`vectorcall <vectorcall>` for ``type.__call__``.
If ``tp_vectorcall`` is ``NULL``, the default call implementation
using :attr:`__new__` and :attr:`__init__` is used.
Number of allocations.
**Inheritance:**
.. c:member:: Py_ssize_t PyTypeObject.tp_frees
This field is never inherited.
Number of frees.
.. versionadded:: 3.9 (the field exists since 3.8 but it's only used since 3.9)
.. c:member:: Py_ssize_t PyTypeObject.tp_maxalloc
Maximum simultaneously allocated objects.
.. c:member:: PyTypeObject* PyTypeObject.tp_prev
Pointer to the previous type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field.
.. c:member:: PyTypeObject* PyTypeObject.tp_next
Pointer to the next type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field.
Also, note that, in a garbage collected Python, :c:member:`~PyTypeObject.tp_dealloc` may be called from
any Python thread, not just the thread which created the object (if the object
@ -2381,14 +2359,6 @@ Slot Type typedefs
.. c:type:: void (*destructor)(PyObject *)
.. c:type:: PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
See :c:member:`~PyTypeObject.tp_vectorcall_offset`.
Arguments to ``vectorcallfunc`` are the same as for :c:func:`_PyObject_Vectorcall`.
.. versionadded:: 3.8
.. c:type:: void (*freefunc)(void *)
See :c:member:`~PyTypeObject.tp_free`.

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

@ -34,6 +34,11 @@ can internally be in two states depending on how they were created:
:c:type:`Py_UNICODE*` representation; you will have to call
:c:func:`PyUnicode_READY` on them before calling any other API.
.. note::
The "legacy" Unicode object will be removed in Python 3.12 with deprecated
APIs. All Unicode objects will be "canonical" since then. See :pep:`623`
for more information.
Unicode Type
""""""""""""
@ -86,13 +91,13 @@ access internal read-only data of Unicode objects:
.. c:function:: int PyUnicode_Check(PyObject *o)
Return true if the object *o* is a Unicode object or an instance of a Unicode
subtype.
subtype. This function always succeeds.
.. c:function:: int PyUnicode_CheckExact(PyObject *o)
Return true if the object *o* is a Unicode object, but not an instance of a
subtype.
subtype. This function always succeeds.
.. c:function:: int PyUnicode_READY(PyObject *o)
@ -107,6 +112,9 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. deprecated-removed:: 3.10 3.12
This API will be removed with :c:func:`PyUnicode_FromUnicode`.
.. c:function:: Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)
@ -138,6 +146,9 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. deprecated-removed:: 3.10 3.12
``PyUnicode_WCHAR_KIND`` is deprecated.
.. c:function:: int PyUnicode_KIND(PyObject *o)
@ -188,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
@ -197,18 +208,13 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. c:function:: int PyUnicode_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. c:function:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
Return the size of the deprecated :c:type:`Py_UNICODE` representation, in
code units (this includes surrogate pairs as 2 units). *o* has to be a
Unicode object (not checked).
.. deprecated-removed:: 3.3 4.0
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_GET_LENGTH`.
@ -218,7 +224,7 @@ access internal read-only data of Unicode objects:
Return the size of the deprecated :c:type:`Py_UNICODE` representation in
bytes. *o* has to be a Unicode object (not checked).
.. deprecated-removed:: 3.3 4.0
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_GET_LENGTH`.
@ -240,11 +246,21 @@ access internal read-only data of Unicode objects:
code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use
:c:func:`PyUnicode_WRITE` or :c:func:`PyUnicode_READ`.
.. deprecated-removed:: 3.3 4.0
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using the
:c:func:`PyUnicode_nBYTE_DATA` family of macros.
.. c:function:: int PyUnicode_IsIdentifier(PyObject *o)
Return ``1`` if the string is a valid identifier according to the language
definition, section :ref:`identifiers`. Return ``0`` otherwise.
.. versionchanged:: 3.9
The function does not call :c:func:`Py_FatalError` anymore if the string
is not ready.
Unicode Character Properties
""""""""""""""""""""""""""""
@ -682,8 +698,10 @@ Extension modules can continue using them, as they will not be removed in Python
string content has been filled before using any of the access macros such as
:c:func:`PyUnicode_KIND`.
Please migrate to using :c:func:`PyUnicode_FromKindAndData`,
:c:func:`PyUnicode_FromWideChar` or :c:func:`PyUnicode_New`.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_FromKindAndData`, :c:func:`PyUnicode_FromWideChar`, or
:c:func:`PyUnicode_New`.
.. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
@ -696,9 +714,10 @@ Extension modules can continue using them, as they will not be removed in Python
embedded null code points, which would cause the string to be truncated when
used in most C functions.
Please migrate to using :c:func:`PyUnicode_AsUCS4`,
:c:func:`PyUnicode_AsWideChar`, :c:func:`PyUnicode_ReadChar` or similar new
APIs.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_AsUCS4`, :c:func:`PyUnicode_AsWideChar`,
:c:func:`PyUnicode_ReadChar` or similar new APIs.
.. deprecated-removed:: 3.3 3.10
@ -720,6 +739,11 @@ Extension modules can continue using them, as they will not be removed in Python
.. versionadded:: 3.3
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_AsUCS4`, :c:func:`PyUnicode_AsWideChar`,
:c:func:`PyUnicode_ReadChar` or similar new APIs.
.. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)
@ -740,7 +764,9 @@ Extension modules can continue using them, as they will not be removed in Python
Return the size of the deprecated :c:type:`Py_UNICODE` representation, in
code units (this includes surrogate pairs as 2 units).
Please migrate to using :c:func:`PyUnicode_GetLength`.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_GET_LENGTH`.
.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
@ -985,7 +1011,7 @@ have the same semantics as the ones of the built-in :func:`str` string object
constructor.
Setting encoding to ``NULL`` causes the default encoding to be used
which is ASCII. The file system calls should use
which is UTF-8. The file system calls should use
:c:func:`PyUnicode_FSConverter` for encoding file names. This uses the
variable :c:data:`Py_FileSystemDefaultEncoding` internally. This
variable should be treated as read-only: on some systems, it will be a
@ -1477,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, \
@ -1590,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
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.
@ -117,7 +117,7 @@ the same library that the Python runtime is using.
closed before PyRun_SimpleFileExFlags returns.
.. note::
On Windows, *fp* should be opened as binary mode (e.g. ``fopen(filename, "rb")``.
On Windows, *fp* should be opened as binary mode (e.g. ``fopen(filename, "rb")``).
Otherwise, Python may not handle script file with LF line ending correctly.
@ -193,6 +193,8 @@ the same library that the Python runtime is using.
:c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
to ``NULL`` and *flags* set to ``0``.
.. deprecated-removed:: 3.9 3.10
.. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)
@ -200,6 +202,8 @@ the same library that the Python runtime is using.
:c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
to ``NULL``.
.. deprecated-removed:: 3.9 3.10
.. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)
@ -209,18 +213,24 @@ the same library that the Python runtime is using.
many times. *filename* is decoded from the filesystem encoding
(:func:`sys.getfilesystemencoding`).
.. deprecated-removed:: 3.9 3.10
.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below,
leaving *flags* set to ``0``.
.. deprecated-removed:: 3.9 3.10
.. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python
source code is read from *fp* instead of an in-memory string.
.. deprecated-removed:: 3.9 3.10
.. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

7
Doc/c-api/weakref.rst
View File

@ -13,17 +13,18 @@ as much as it can.
.. c:function:: int PyWeakref_Check(ob)
Return true if *ob* is either a reference or proxy object.
Return true if *ob* is either a reference or proxy object. This function
always succeeds.
.. c:function:: int PyWeakref_CheckRef(ob)
Return true if *ob* is a reference object.
Return true if *ob* is a reference object. This function always succeeds.
.. c:function:: int PyWeakref_CheckProxy(ob)
Return true if *ob* is a proxy object.
Return true if *ob* is a proxy object. This function always succeeds.
.. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)

14
Doc/conf.py
View File

@ -14,7 +14,8 @@ sys.path.append(os.path.abspath('includes'))
# ---------------------
extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',
'pyspecific', 'c_annotations', 'escape4chm']
'pyspecific', 'c_annotations', 'escape4chm',
'asdl_highlight', 'peg_highlight']
doctest_global_setup = '''
@ -127,6 +128,7 @@ latex_elements['preamble'] = r'''
}
\let\Verbatim=\OriginalVerbatim
\let\endVerbatim=\endOriginalVerbatim
\setcounter{tocdepth}{2}
'''
# The paper size ('letter' or 'a4').
@ -226,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/copyright.rst
View File

@ -4,7 +4,7 @@ Copyright
Python and this documentation is:
Copyright © 2001-2020 Python Software Foundation. All rights reserved.
Copyright © 2001-2021 Python Software Foundation. All rights reserved.
Copyright © 2000 BeOpen.com. All rights reserved.

7
Doc/data/refcounts.dat
View File

@ -2306,6 +2306,11 @@ PyType_CheckExact:PyObject*:o:0:
PyType_FromSpec:PyObject*::+1:
PyType_FromSpec:PyType_Spec*:spec::
PyType_FromModuleAndSpec:PyObject*::+1:
PyType_FromModuleAndSpec:PyObject*:module:+1:
PyType_FromModuleAndSpec:PyType_Spec*:spec::
PyType_FromModuleAndSpec:PyObject*:bases:0:
PyType_FromSpecWithBases:PyObject*::+1:
PyType_FromSpecWithBases:PyType_Spec*:spec::
PyType_FromSpecWithBases:PyObject*:bases:0:
@ -3046,8 +3051,6 @@ Py_XINCREF:PyObject*:o:+1:if o is not NULL
_PyImport_Fini:void:::
_PyImport_Init:void:::
_PyObject_New:PyObject*::+1:
_PyObject_New:PyTypeObject*:type:0:

21
Doc/distutils/apiref.rst
View File

@ -1142,6 +1142,24 @@ other utility module.
* ``macosx-10.6-intel``
For AIX, Python 3.9 and later return a string starting with "aix", followed
by additional fields (separated by ``'-'``) that represent the combined
values of AIX Version, Release and Technology Level (first field), Build Date
(second field), and bit-size (third field). Python 3.8 and earlier returned
only a single additional field with the AIX Version and Release.
Examples of returned values on AIX:
* ``aix-5307-0747-32`` # 32-bit build on AIX ``oslevel -s``: 5300-07-00-0000
* ``aix-7105-1731-64`` # 64-bit build on AIX ``oslevel -s``: 7100-05-01-1731
* ``aix-7.2`` # Legacy form reported in Python 3.8 and earlier
.. versionchanged:: 3.9
The AIX platform string format now also includes the technology level,
build date, and ABI bit-size.
.. function:: convert_path(pathname)
@ -1837,6 +1855,9 @@ Subclasses of :class:`Command` must define the following methods.
.. class:: bdist_msi
.. deprecated:: 3.9
Use bdist_wheel (wheel packages) instead.
Builds a `Windows Installer`_ (.msi) binary package.
.. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx

9
Doc/distutils/builtdist.rst
View File

@ -149,6 +149,9 @@ generated by each, are:
.. note::
bdist_wininst is deprecated since Python 3.8.
.. note::
bdist_msi is deprecated since Python 3.9.
The following sections give details on the individual :command:`bdist_\*`
commands.
@ -304,6 +307,9 @@ Creating Windows Installers
.. warning::
bdist_wininst is deprecated since Python 3.8.
.. warning::
bdist_msi is deprecated since Python 3.9.
Executable installers are the natural format for binary distributions on
Windows. They display a nice graphical user interface, display some information
about the module distribution to be installed taken from the metadata in the
@ -468,3 +474,6 @@ installed for all users) and 'force' (meaning always prompt for elevation).
.. note::
bdist_wininst is deprecated since Python 3.8.
.. note::
bdist_msi is deprecated since Python 3.9.

2
Doc/distutils/examples.rst
View File

@ -255,7 +255,7 @@ Running the ``check`` command will display some warnings:
running check
warning: check: missing required meta-data: version, url
warning: check: missing meta-data: either (author and author_email) or
(maintainer and maintainer_email) must be supplied
(maintainer and maintainer_email) should be supplied
If you use the reStructuredText syntax in the ``long_description`` field and

2
Doc/extending/newtypes.rst
View File

@ -104,7 +104,7 @@ done. This can be done using the :c:func:`PyErr_Fetch` and
/* This saves the current exception state */
PyErr_Fetch(&err_type, &err_value, &err_traceback);
cbresult = PyObject_CallObject(self->my_callback, NULL);
cbresult = PyObject_CallNoArgs(self->my_callback);
if (cbresult == NULL)
PyErr_WriteUnraisable(self->my_callback);
else

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

25
Doc/faq/design.rst
View File

@ -24,14 +24,16 @@ programmers will encounter a fragment of code like this::
z++;
Only the ``x++`` statement is executed if the condition is true, but the
indentation leads you to believe otherwise. Even experienced C programmers will
sometimes stare at it a long time wondering why ``y`` is being decremented even
indentation leads many to believe otherwise. Even experienced C programmers will
sometimes stare at it a long time wondering as to why ``y`` is being decremented even
for ``x > y``.
Because there are no begin/end brackets, Python is much less prone to
coding-style conflicts. In C there are many different ways to place the braces.
If you're used to reading and writing code that uses one style, you will feel at
least slightly uneasy when reading (or being required to write) another style.
After becoming used to reading and writing code using a particular style,
it is normal to feel somewhat uneasy when reading (or being required to write)
in a different one.
Many coding styles place begin/end brackets on a line by themselves. This makes
programs considerably longer and wastes valuable screen space, making it harder
@ -571,8 +573,7 @@ whether an instance or a class implements a particular ABC. The
:class:`~collections.abc.MutableMapping`.
For Python, many of the advantages of interface specifications can be obtained
by an appropriate test discipline for components. There is also a tool,
PyChecker, which can be used to find problems due to subclassing.
by an appropriate test discipline for components.
A good test suite for a module can both provide a regression test and serve as a
module interface specification and a set of examples. Many Python modules can
@ -590,11 +591,11 @@ to the end of some internal list; an interface specification cannot test that
your :meth:`append` implementation will actually do this correctly, but it's
trivial to check this property in a test suite.
Writing test suites is very helpful, and you might want to design your code with
an eye to making it easily tested. One increasingly popular technique,
test-directed development, calls for writing parts of the test suite first,
before you write any of the actual code. Of course Python allows you to be
sloppy and not write test cases at all.
Writing test suites is very helpful, and you might want to design your code to
make it easily tested. One increasingly popular technique, test-driven
development, calls for writing parts of the test suite first, before you write
any of the actual code. Of course Python allows you to be sloppy and not write
test cases at all.
Why is there no goto?
@ -649,7 +650,7 @@ Why doesn't Python have a "with" statement for attribute assignments?
---------------------------------------------------------------------
Python has a 'with' statement that wraps the execution of a block, calling code
on the entrance and exit from the block. Some language have a construct that
on the entrance and exit from the block. Some languages have a construct that
looks like this::
with obj:

8
Doc/faq/general.rst
View File

@ -142,9 +142,9 @@ to fix critical bugs.
Alpha, beta and release candidate versions have an additional suffix. The
suffix for an alpha version is "aN" for some small number N, the suffix for a
beta version is "bN" for some small number N, and the suffix for a release
candidate version is "cN" for some small number N. In other words, all versions
candidate version is "rcN" for some small number N. In other words, all versions
labeled 2.0aN precede the versions labeled 2.0bN, which precede versions labeled
2.0cN, and *those* precede 2.0.
2.0rcN, and *those* precede 2.0.
You may also find version numbers with a "+" suffix, e.g. "2.2+". These are
unreleased versions, built directly from the CPython development repository. In
@ -309,8 +309,8 @@ releases.
The latest stable releases can always be found on the `Python download page
<https://www.python.org/downloads/>`_. There are two production-ready versions
of Python: 2.x and 3.x. The recommended version is 3.x, which is supported by
most widely used libraries. Although 2.x is still widely used, `it will not
be maintained after January 1, 2020 <https://www.python.org/dev/peps/pep-0373/>`_.
most widely used libraries. Although 2.x is still widely used, `it is not
maintained anymore <https://www.python.org/dev/peps/pep-0373/>`_.
How many people are using Python?
---------------------------------

29
Doc/faq/library.rst
View File

@ -125,7 +125,7 @@ argument list. It is called as ::
handler(signum, frame)
so it should be declared with two arguments::
so it should be declared with two parameters::
def handler(signum, frame):
...
@ -159,9 +159,9 @@ The "global main logic" of your program may be as simple as ::
at the bottom of the main module of your program.
Once your program is organized as a tractable collection of functions and class
behaviours you should write test functions that exercise the behaviours. A test
suite that automates a sequence of tests can be associated with each module.
Once your program is organized as a tractable collection of function and class
behaviours, you should write test functions that exercise the behaviours. A
test suite that automates a sequence of tests can be associated with each module.
This sounds like a lot of work, but since Python is so terse and flexible it's
surprisingly easy. You can make coding much more pleasant and fun by writing
your test functions in parallel with the "production code", since this makes it
@ -295,7 +295,7 @@ queue as there are threads.
How do I parcel out work among a bunch of worker threads?
---------------------------------------------------------
The easiest way is to use the new :mod:`concurrent.futures` module,
The easiest way is to use the :mod:`concurrent.futures` module,
especially the :mod:`~concurrent.futures.ThreadPoolExecutor` class.
Or, if you want fine control over the dispatching algorithm, you can write
@ -679,7 +679,7 @@ How can I mimic CGI form submission (METHOD=POST)?
I would like to retrieve web pages that are the result of POSTing a form. Is
there existing code that would let me do this easily?
Yes. Here's a simple example that uses urllib.request::
Yes. Here's a simple example that uses :mod:`urllib.request`::
#!/usr/local/bin/python
@ -765,20 +765,21 @@ The :mod:`select` module is commonly used to help with asynchronous I/O on
sockets.
To prevent the TCP connect from blocking, you can set the socket to non-blocking
mode. Then when you do the ``connect()``, you will either connect immediately
mode. Then when you do the :meth:`socket.connect`, you will either connect immediately
(unlikely) or get an exception that contains the error number as ``.errno``.
``errno.EINPROGRESS`` indicates that the connection is in progress, but hasn't
finished yet. Different OSes will return different values, so you're going to
have to check what's returned on your system.
You can use the ``connect_ex()`` method to avoid creating an exception. It will
just return the errno value. To poll, you can call ``connect_ex()`` again later
You can use the :meth:`socket.connect_ex` method to avoid creating an exception. It will
just return the errno value. To poll, you can call :meth:`socket.connect_ex` again later
-- ``0`` or ``errno.EISCONN`` indicate that you're connected -- or you can pass this
socket to select to check if it's writable.
socket to :meth:`select.select` to check if it's writable.
.. note::
The :mod:`asyncore` module presents a framework-like approach to the problem
of writing non-blocking networking code.
The :mod:`asyncio` module provides a general purpose single-threaded and
concurrent asynchronous library, which can be used for writing non-blocking
network code.
The third-party `Twisted <https://twistedmatrix.com/trac/>`_ library is
a popular and feature-rich alternative.
@ -832,8 +833,8 @@ There are also many other specialized generators in this module, such as:
Some higher-level functions operate on sequences directly, such as:
* ``choice(S)`` chooses random element from a given sequence
* ``shuffle(L)`` shuffles a list in-place, i.e. permutes it randomly
* ``choice(S)`` chooses a random element from a given sequence.
* ``shuffle(L)`` shuffles a list in-place, i.e. permutes it randomly.
There's also a ``Random`` class you can instantiate to create independent
multiple random number generators.

158
Doc/faq/programming.rst
View File

@ -35,12 +35,6 @@ for Windows Extensions <https://sourceforge.net/projects/pywin32/>`__ project an
as a part of the ActivePython distribution (see
https://www.activestate.com/activepython\ ).
`Boa Constructor <http://boa-constructor.sourceforge.net/>`_ is an IDE and GUI
builder that uses wxWidgets. It offers visual frame creation and manipulation,
an object inspector, many views on the source like object browsers, inheritance
hierarchies, doc string generated html documentation, an advanced debugger,
integrated help, and Zope support.
`Eric <http://eric-ide.python-projects.org/>`_ is an IDE built on PyQt
and the Scintilla editing component.
@ -57,22 +51,14 @@ They include:
* PyCharm (https://www.jetbrains.com/pycharm/)
Is there a tool to help find bugs or perform static analysis?
Are there tools to help find bugs or perform static analysis?
-------------------------------------------------------------
Yes.
PyChecker is a static analysis tool that finds bugs in Python source code and
warns about code complexity and style. You can get PyChecker from
http://pychecker.sourceforge.net/.
`Pylint <https://www.pylint.org/>`_ is another tool that checks
if a module satisfies a coding standard, and also makes it possible to write
plug-ins to add a custom feature. In addition to the bug checking that
PyChecker performs, Pylint offers some additional features such as checking line
length, whether variable names are well-formed according to your coding
standard, whether declared interfaces are fully implemented, and more.
https://docs.pylint.org/ provides a full list of Pylint's features.
`Pylint <https://www.pylint.org/>`_ and
`Pyflakes <https://github.com/PyCQA/pyflakes>`_ do basic checking that will
help you catch bugs sooner.
Static type checkers such as `Mypy <http://mypy-lang.org/>`_,
`Pyre <https://pyre-check.org/>`_, and
@ -518,14 +504,14 @@ desired effect in a number of ways.
1) By returning a tuple of the results::
def func2(a, b):
a = 'new-value' # a and b are local names
b = b + 1 # assigned to new objects
return a, b # return new values
x, y = 'old-value', 99
x, y = func2(x, y)
print(x, y) # output: new-value 100
>>> def func1(a, b):
... a = 'new-value' # a and b are local names
... b = b + 1 # assigned to new objects
... return a, b # return new values
...
>>> x, y = 'old-value', 99
>>> func1(x, y)
('new-value', 100)
This is almost always the clearest solution.
@ -533,38 +519,41 @@ desired effect in a number of ways.
3) By passing a mutable (changeable in-place) object::
def func1(a):
a[0] = 'new-value' # 'a' references a mutable list
a[1] = a[1] + 1 # changes a shared object
args = ['old-value', 99]
func1(args)
print(args[0], args[1]) # output: new-value 100
>>> def func2(a):
... a[0] = 'new-value' # 'a' references a mutable list
... a[1] = a[1] + 1 # changes a shared object
...
>>> args = ['old-value', 99]
>>> func2(args)
>>> args
['new-value', 100]
4) By passing in a dictionary that gets mutated::
def func3(args):
args['a'] = 'new-value' # args is a mutable dictionary
args['b'] = args['b'] + 1 # change it in-place
args = {'a': 'old-value', 'b': 99}
func3(args)
print(args['a'], args['b'])
>>> def func3(args):
... args['a'] = 'new-value' # args is a mutable dictionary
... args['b'] = args['b'] + 1 # change it in-place
...
>>> args = {'a': 'old-value', 'b': 99}
>>> func3(args)
>>> args
{'a': 'new-value', 'b': 100}
5) Or bundle up values in a class instance::
class callByRef:
def __init__(self, /, **args):
for key, value in args.items():
setattr(self, key, value)
def func4(args):
args.a = 'new-value' # args is a mutable callByRef
args.b = args.b + 1 # change object in-place
args = callByRef(a='old-value', b=99)
func4(args)
print(args.a, args.b)
>>> class Namespace:
... def __init__(self, /, **args):
... for key, value in args.items():
... setattr(self, key, value)
...
>>> def func4(args):
... args.a = 'new-value' # args is a mutable Namespace
... args.b = args.b + 1 # change object in-place
...
>>> args = Namespace(a='old-value', b=99)
>>> func4(args)
>>> vars(args)
{'a': 'new-value', 'b': 100}
There's almost never a good reason to get this complicated.
@ -851,10 +840,11 @@ For integers, use the built-in :func:`int` type constructor, e.g. ``int('144')
e.g. ``float('144') == 144.0``.
By default, these interpret the number as decimal, so that ``int('0144') ==
144`` and ``int('0x144')`` raises :exc:`ValueError`. ``int(string, base)`` takes
the base to convert from as a second optional argument, so ``int('0x144', 16) ==
324``. If the base is specified as 0, the number is interpreted using Python's
rules: a leading '0o' indicates octal, and '0x' indicates a hex number.
144`` holds true, and ``int('0x144')`` raises :exc:`ValueError`. ``int(string,
base)`` takes the base to convert from as a second optional argument, so ``int(
'0x144', 16) == 324``. If the base is specified as 0, the number is interpreted
using Python's rules: a leading '0o' indicates octal, and '0x' indicates a hex
number.
Do not use the built-in function :func:`eval` if all you need is to convert
strings to numbers. :func:`eval` will be significantly slower and it presents a
@ -952,7 +942,7 @@ There are various techniques.
f()
* Use :func:`locals` or :func:`eval` to resolve the function name::
* Use :func:`locals` to resolve the function name::
def myFunc():
print("hello")
@ -962,12 +952,6 @@ There are various techniques.
f = locals()[fname]
f()
f = eval(fname)
f()
Note: Using :func:`eval` is slow and dangerous. If you don't have absolute
control over the contents of the string, someone could pass a string that
resulted in an arbitrary function being executed.
Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?
-------------------------------------------------------------------------------------
@ -1132,7 +1116,7 @@ trailing newline from a string.
How do I iterate over a sequence in reverse order?
--------------------------------------------------
Use the :func:`reversed` built-in function, which is new in Python 2.4::
Use the :func:`reversed` built-in function::
for x in reversed(sequence):
... # do something with x ...
@ -1140,11 +1124,6 @@ Use the :func:`reversed` built-in function, which is new in Python 2.4::
This won't touch your original sequence, but build a new copy with reversed
order to iterate over.
With Python 2.3, you can use an extended slice syntax::
for x in sequence[::-1]:
... # do something with x ...
How do you remove duplicates from a list?
-----------------------------------------
@ -1174,6 +1153,21 @@ This converts the list into a set, thereby removing duplicates, and then back
into a list.
How do you remove multiple items from a list
--------------------------------------------
As with removing duplicates, explicitly iterating in reverse with a
delete condition is one possibility. However, it is easier and faster
to use slice replacement with an implicit or explicit forward iteration.
Here are three variations.::
mylist[:] = filter(keep_function, mylist)
mylist[:] = (x for x in mylist if keep_condition)
mylist[:] = [x for x in mylist if keep_condition]
The list comprehension may be fastest.
How do you make an array in Python?
-----------------------------------
@ -1376,20 +1370,6 @@ out the element you want. ::
['else', 'sort', 'to', 'something']
An alternative for the last step is::
>>> result = []
>>> for p in pairs: result.append(p[1])
If you find this more legible, you might prefer to use this instead of the final
list comprehension. However, it is almost twice as slow for long lists. Why?
First, the ``append()`` operation has to reallocate memory, and while it uses
some tricks to avoid doing that each time, it still has to do it occasionally,
and that costs quite a bit. Second, the expression "result.append" requires an
extra attribute lookup, and third, there's a speed reduction from having to make
all those function calls.
Objects
=======
@ -1533,18 +1513,18 @@ provide the ``self`` argument.
How can I organize my code to make it easier to change the base class?
----------------------------------------------------------------------
You could define an alias for the base class, assign the real base class to it
before your class definition, and use the alias throughout your class. Then all
You could assign the base class to an alias and derive from the alias. Then all
you have to change is the value assigned to the alias. Incidentally, this trick
is also handy if you want to decide dynamically (e.g. depending on availability
of resources) which base class to use. Example::
BaseAlias = <real base class>
class Base:
...
BaseAlias = Base
class Derived(BaseAlias):
def meth(self):
BaseAlias.meth(self)
...
...
How do I create static class data and static class methods?

4
Doc/faq/windows.rst
View File

@ -140,7 +140,7 @@ offender.
How do I make an executable from a Python script?
-------------------------------------------------
See `cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_ for a distutils extension
See `cx_Freeze <https://cx-freeze.readthedocs.io/en/latest/>`_ for a distutils extension
that allows you to create console and GUI executables from Python code.
`py2exe <http://www.py2exe.org/>`_, the most popular extension for building
Python 2.x-based executables, does not yet support Python 3 but a version that
@ -279,7 +279,7 @@ in batch mode.
How do I check for a keypress without blocking?
-----------------------------------------------
Use the msvcrt module. This is a standard Windows-specific extension module.
Use the :mod:`msvcrt` module. This is a standard Windows-specific extension module.
It defines a function ``kbhit()`` which checks whether a keyboard hit is
present, and ``getch()`` which gets one character without echoing it.

36
Doc/glossary.rst
View File

@ -301,13 +301,20 @@ Glossary
including functions, methods, properties, class methods, static methods,
and reference to super classes.
For more information about descriptors' methods, see :ref:`descriptors`.
For more information about descriptors' methods, see :ref:`descriptors`
or the :ref:`Descriptor How To Guide <descriptorhowto>`.
dictionary
An associative array, where arbitrary keys are mapped to values. The
keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
Called a hash in Perl.
dictionary comprehension
A compact way to process all or part of the elements in an iterable and
return a dictionary with the results. ``results = {n: n ** 2 for n in
range(10)}`` generates a dictionary containing key ``n`` mapped to
value ``n ** 2``. See :ref:`comprehensions`.
dictionary view
The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
:meth:`dict.items` are called dictionary views. They provide a dynamic
@ -476,6 +483,13 @@ Glossary
See also the :term:`single dispatch` glossary entry, the
:func:`functools.singledispatch` decorator, and :pep:`443`.
generic type
A :term:`type` that can be parameterized; typically a container like
:class:`list`. Used for :term:`type hints <type hint>` and
:term:`annotations <annotation>`.
See :pep:`483` for more details, and :mod:`typing` or
:ref:`generic alias type <types-genericalias>` for its uses.
GIL
See :term:`global interpreter lock`.
@ -587,7 +601,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
@ -1024,7 +1038,13 @@ Glossary
:meth:`index`, :meth:`__contains__`, and
:meth:`__reversed__`. Types that implement this expanded
interface can be registered explicitly using
:func:`~abc.register`.
:func:`~abc.ABCMeta.register`.
set comprehension
A compact way to process all or part of the elements in an iterable and
return a set with the results. ``results = {c for c in 'abracadabra' if
c not in 'abc'}`` generates the set of strings ``{'r', 'd'}``. See
:ref:`comprehensions`.
single dispatch
A form of :term:`generic function` dispatch where the implementation is
@ -1084,19 +1104,15 @@ Glossary
Type aliases are useful for simplifying :term:`type hints <type hint>`.
For example::
from typing import List, Tuple
def remove_gray_shades(
colors: List[Tuple[int, int, int]]) -> List[Tuple[int, int, int]]:
colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:
pass
could be made more readable like this::
from typing import List, Tuple
Color = tuple[int, int, int]
Color = Tuple[int, int, int]
def remove_gray_shades(colors: List[Color]) -> List[Color]:
def remove_gray_shades(colors: list[Color]) -> list[Color]:
pass
See :mod:`typing` and :pep:`484`, which describe this functionality.

1511
Doc/howto/descriptor.rst
View File

File diff suppressed because it is too large Load Diff

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.

4
Doc/howto/logging-cookbook.rst
View File

@ -1368,7 +1368,7 @@ An example dictionary-based configuration
-----------------------------------------
Below is an example of a logging configuration dictionary - it's taken from
the `documentation on the Django project <https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-logging>`_.
the `documentation on the Django project <https://docs.djangoproject.com/en/stable/topics/logging/#configuring-logging>`_.
This dictionary is passed to :func:`~config.dictConfig` to put the configuration into effect::
LOGGING = {
@ -1424,7 +1424,7 @@ This dictionary is passed to :func:`~config.dictConfig` to put the configuration
}
For more information about this configuration, you can see the `relevant
section <https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-logging>`_
section <https://docs.djangoproject.com/en/stable/topics/logging/#configuring-logging>`_
of the Django documentation.
.. _cookbook-rotator-namer:

14
Doc/howto/logging.rst
View File

@ -128,10 +128,18 @@ look at that next. Be sure to try the following in a newly-started Python
interpreter, and don't just continue from the session described above::
import logging
logging.basicConfig(filename='example.log',level=logging.DEBUG)
logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG)
logging.debug('This message should go to the log file')
logging.info('So should this')
logging.warning('And this, too')
logging.error('And non-ASCII stuff, too, like Øresund and Malmö')
.. versionchanged:: 3.9
The *encoding* argument was added. In earlier Python versions, or if not
specified, the encoding used is the default value used by :func:`open`. While
not shown in the above example, an *errors* argument can also now be passed,
which determines how encoding errors are handled. For available values and
the default, see the documentation for :func:`open`.
And now if we open the file and look at what we have, we should find the log
messages:
@ -141,6 +149,7 @@ messages:
DEBUG:root:This message should go to the log file
INFO:root:So should this
WARNING:root:And this, too
ERROR:root:And non-ASCII stuff, too, like Øresund and Malmö
This example also shows how you can set the logging level which acts as the
threshold for tracking. In this case, because we set the threshold to
@ -1077,8 +1086,7 @@ need:
| | :func:`sys._getframe`, which may help |
| | to speed up your code in environments |
| | like PyPy (which can't speed up code |
| | that uses :func:`sys._getframe`), if |
| | and when PyPy supports Python 3.x. |
| | that uses :func:`sys._getframe`). |
+-----------------------------------------------+----------------------------------------+
| Threading information. | Set ``logging.logThreads`` to ``0``. |
+-----------------------------------------------+----------------------------------------+

20
Doc/howto/pyporting.rst
View File

@ -31,20 +31,26 @@ are:
#. Only worry about supporting Python 2.7
#. Make sure you have good test coverage (coverage.py_ can help;
``pip install coverage``)
``python -m pip install coverage``)
#. Learn the differences between Python 2 & 3
#. Use Futurize_ (or Modernize_) to update your code (e.g. ``pip install future``)
#. Use Futurize_ (or Modernize_) to update your code (e.g. ``python -m pip install future``)
#. Use Pylint_ to help make sure you don't regress on your Python 3 support
(``pip install pylint``)
(``python -m pip install pylint``)
#. Use caniusepython3_ to find out which of your dependencies are blocking your
use of Python 3 (``pip install caniusepython3``)
use of Python 3 (``python -m pip install caniusepython3``)
#. Once your dependencies are no longer blocking you, use continuous integration
to make sure you stay compatible with Python 2 & 3 (tox_ can help test
against multiple versions of Python; ``pip install tox``)
against multiple versions of Python; ``python -m pip install tox``)
#. Consider using optional static type checking to make sure your type usage
works in both Python 2 & 3 (e.g. use mypy_ to check your typing under both
Python 2 & Python 3).
Python 2 & Python 3; ``python -m pip install mypy``).
.. note::
Note: Using ``python -m pip install`` guarantees that the ``pip`` you invoke
is the one installed for the Python currently in use, whether it be
a system-wide ``pip`` or one installed within a
:ref:`virtual environment <tut-venv>`.
Details
=======
@ -71,7 +77,7 @@ Drop support for Python 2.6 and older
While you can make Python 2.5 work with Python 3, it is **much** easier if you
only have to work with Python 2.7. If dropping Python 2.5 is not an
option then the six_ project can help you support Python 2.5 & 3 simultaneously
(``pip install six``). Do realize, though, that nearly all the projects listed
(``python -m pip install six``). Do realize, though, that nearly all the projects listed
in this HOWTO will not be available to you.
If you are able to skip Python 2.5 and older, then the required changes

2
Doc/howto/sockets.rst
View File

@ -317,7 +317,7 @@ know about the mechanics of using sockets. You'll still use the same calls, in
much the same ways. It's just that, if you do it right, your app will be almost
inside-out.
In Python, you use ``socket.setblocking(0)`` to make it non-blocking. In C, it's
In Python, you use ``socket.setblocking(False)`` to make it non-blocking. In C, it's
more complex, (for one thing, you'll need to choose between the BSD flavor
``O_NONBLOCK`` and the almost indistinguishable POSIX flavor ``O_NDELAY``, which
is completely different from ``TCP_NODELAY``), but it's the exact same idea. You

10
Doc/howto/sorting.rst
View File

@ -43,16 +43,18 @@ Key Functions
=============
Both :meth:`list.sort` and :func:`sorted` have a *key* parameter to specify a
function to be called on each list element prior to making comparisons.
function (or other callable) to be called on each list element prior to making
comparisons.
For example, here's a case-insensitive string comparison:
>>> sorted("This is a test string from Andrew".split(), key=str.lower)
['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']
The value of the *key* parameter should be a function that takes a single argument
and returns a key to use for sorting purposes. This technique is fast because
the key function is called exactly once for each input record.
The value of the *key* parameter should be a function (or other callable) that
takes a single argument and returns a key to use for sorting purposes. This
technique is fast because the key function is called exactly once for each
input record.
A common pattern is to sort complex objects using some of the object's indices
as keys. For example:

11
Doc/howto/unicode.rst
View File

@ -41,8 +41,9 @@ but these are two different characters that have different meanings.
The Unicode standard describes how characters are represented by
**code points**. A code point value is an integer in the range 0 to
0x10FFFF (about 1.1 million values, with some 110 thousand assigned so
far). In the standard and in this document, a code point is written
0x10FFFF (about 1.1 million values, the
`actual number assigned <https://www.unicode.org/versions/latest/#Summary>`_
is less than that). In the standard and in this document, a code point is written
using the notation ``U+265E`` to mean the character with value
``0x265e`` (9,822 in decimal).
@ -156,9 +157,9 @@ UTF-8 has several convenient properties:
References
----------
The `Unicode Consortium site <http://www.unicode.org>`_ has character charts, a
The `Unicode Consortium site <https://www.unicode.org>`_ has character charts, a
glossary, and PDF versions of the Unicode specification. Be prepared for some
difficult reading. `A chronology <http://www.unicode.org/history/>`_ of the
difficult reading. `A chronology <https://www.unicode.org/history/>`_ of the
origin and development of Unicode is also available on the site.
On the Computerphile Youtube channel, Tom Scott briefly
@ -393,7 +394,7 @@ These are grouped into categories such as "Letter", "Number", "Punctuation", or
from the above output, ``'Ll'`` means 'Letter, lowercase', ``'No'`` means
"Number, other", ``'Mn'`` is "Mark, nonspacing", and ``'So'`` is "Symbol,
other". See
`the General Category Values section of the Unicode Character Database documentation <http://www.unicode.org/reports/tr44/#General_Category_Values>`_ for a
`the General Category Values section of the Unicode Character Database documentation <https://www.unicode.org/reports/tr44/#General_Category_Values>`_ for a
list of category codes.

2
Doc/howto/urllib2.rst
View File

@ -97,7 +97,7 @@ schemes. For example, you can make an FTP request like so::
In the case of HTTP, there are two extra things that Request objects allow you
to do: First, you can pass data to be sent to the server. Second, you can pass
extra information ("metadata") *about* the data or the about request itself, to
extra information ("metadata") *about* the data or about the request itself, to
the server - this information is sent as HTTP "headers". Let's look at each of
these in turn.

3
Doc/install/index.rst
View File

@ -1064,8 +1064,7 @@ normal libraries do.
.. [#] This also means you could replace all existing COFF-libraries with OMF-libraries
of the same name.
.. [#] Check https://www.sourceware.org/cygwin/ and http://www.mingw.org/ for more
information
.. [#] Check https://www.sourceware.org/cygwin/ for more information
.. [#] Then you have no POSIX emulation available, but you also don't need
:file:`cygwin1.dll`.

16
Doc/library/2to3.rst
View File

@ -9,9 +9,7 @@
of *fixers* to transform it into valid Python 3.x code. The standard library
contains a rich set of fixers that will handle almost all code. 2to3 supporting
library :mod:`lib2to3` is, however, a flexible and generic library, so it is
possible to write your own fixers for 2to3. :mod:`lib2to3` could also be
adapted to custom applications in which Python code needs to be edited
automatically.
possible to write your own fixers for 2to3.
.. _2to3-using:
@ -102,7 +100,7 @@ presence of the ``from __future__ import print_function`` compiler directive, it
modifies its internal grammar to interpret :func:`print` as a function. This
change can also be enabled manually with the :option:`!-p` flag. Use
:option:`!-p` to run fixers on code that already has had its print statements
converted.
converted. Also :option:`!-e` can be used to make :func:`exec` a function.
The :option:`!-o` or :option:`!--output-dir` option allows specification of an
alternate directory for processed output files to be written to. The
@ -466,9 +464,17 @@ and off individually. They are described here in more detail.
--------------
.. deprecated:: 3.10
Python 3.9 will switch to a PEG parser (see :pep:`617`), and Python 3.10 may
include new language syntax that is not parsable by lib2to3's LL(1) parser.
The ``lib2to3`` module may be removed from the standard library in a future
Python version. Consider third-party alternatives such as `LibCST`_ or
`parso`_.
.. note::
The :mod:`lib2to3` API should be considered unstable and may change
drastically in the future.
.. XXX What is the public interface anyway?
.. _LibCST: https://libcst.readthedocs.io/
.. _parso: https://parso.readthedocs.io/

2
Doc/library/__future__.rst
View File

@ -90,7 +90,7 @@ language using this mechanism:
| generator_stop | 3.5.0b1 | 3.7 | :pep:`479`: |
| | | | *StopIteration handling inside generators* |
+------------------+-------------+--------------+---------------------------------------------+
| annotations | 3.7.0b1 | 4.0 | :pep:`563`: |
| annotations | 3.7.0b1 | 3.10 | :pep:`563`: |
| | | | *Postponed evaluation of annotations* |
+------------------+-------------+--------------+---------------------------------------------+

22
Doc/library/_dummy_thread.rst
View File

@ -1,22 +0,0 @@
:mod:`_dummy_thread` --- Drop-in replacement for the :mod:`_thread` module
==========================================================================
.. module:: _dummy_thread
:synopsis: Drop-in replacement for the _thread module.
**Source code:** :source:`Lib/_dummy_thread.py`
.. deprecated:: 3.7
Python now always has threading enabled. Please use :mod:`_thread`
(or, better, :mod:`threading`) instead.
--------------
This module provides a duplicate interface to the :mod:`_thread` module.
It was meant to be imported when the :mod:`_thread` module was not provided
on a platform.
Be careful to not use this module where deadlock might occur from a thread being
created that blocks waiting for another thread to be created. This often occurs
with blocking I/O.

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

185
Doc/library/argparse.rst
View File

@ -142,7 +142,7 @@ ArgumentParser objects
formatter_class=argparse.HelpFormatter, \
prefix_chars='-', fromfile_prefix_chars=None, \
argument_default=None, conflict_handler='error', \
add_help=True, allow_abbrev=True)
add_help=True, allow_abbrev=True, exit_on_error=True)
Create a new :class:`ArgumentParser` object. All parameters should be passed
as keyword arguments. Each parameter has its own more detailed description
@ -179,6 +179,9 @@ ArgumentParser objects
* allow_abbrev_ - Allows long options to be abbreviated if the
abbreviation is unambiguous. (default: ``True``)
* exit_on_error_ - Determines whether or not ArgumentParser exits with
error info when an error occurs. (default: ``True``)
.. versionchanged:: 3.5
*allow_abbrev* parameter was added.
@ -186,6 +189,9 @@ ArgumentParser objects
In previous versions, *allow_abbrev* also disabled grouping of short
flags such as ``-vv`` to mean ``-v -v``.
.. versionchanged:: 3.9
*exit_on_error* parameter was added.
The following sections describe how each of these are used.
@ -443,7 +449,7 @@ default values to each of the argument help messages::
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar [bar ...]]
usage: PROG [-h] [--foo FOO] [bar ...]
positional arguments:
bar BAR! (default: [1, 2, 3])
@ -647,6 +653,28 @@ the help options::
+h, ++help show this help message and exit
exit_on_error
^^^^^^^^^^^^^
Normally, when you pass an invalid argument list to the :meth:`~ArgumentParser.parse_args`
method of an :class:`ArgumentParser`, it will exit with error info.
If the user would like catch errors manually, the feature can be enable by setting
``exit_on_error`` to ``False``::
>>> parser = argparse.ArgumentParser(exit_on_error=False)
>>> parser.add_argument('--integers', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
>>> try:
... parser.parse_args('--integers a'.split())
... except argparse.ArgumentError:
... print('Catching an argumentError')
...
Catching an argumentError
.. versionadded:: 3.9
The add_argument() method
-------------------------
@ -668,7 +696,7 @@ The add_argument() method
* const_ - A constant value required by some action_ and nargs_ selections.
* default_ - The value produced if the argument is absent from the
command line.
command line and if it is absent from the namespace object.
* type_ - The type to which the command-line argument should be converted.
@ -815,9 +843,19 @@ how the command-line arguments should be handled. The supplied actions are:
.. versionadded:: 3.8
You may also specify an arbitrary action by passing an Action subclass or
other object that implements the same interface. The recommended way to do
this is to extend :class:`Action`, overriding the ``__call__`` method
and optionally the ``__init__`` method.
other object that implements the same interface. The ``BooleanOptionalAction``
is available in ``argparse`` and adds support for boolean actions such as
``--foo`` and ``--no-foo``::
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)
The recommended way to create a custom action is to extend :class:`Action`,
overriding the ``__call__`` method and optionally the ``__init__`` and
``format_usage`` methods.
An example of a custom action::
@ -923,19 +961,6 @@ values are:
usage: PROG [-h] foo [foo ...]
PROG: error: the following arguments are required: foo
.. _`argparse.REMAINDER`:
* ``argparse.REMAINDER``. All the remaining command-line arguments are gathered
into a list. This is commonly useful for command line utilities that dispatch
to other command line utilities::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo')
>>> parser.add_argument('command')
>>> parser.add_argument('args', nargs=argparse.REMAINDER)
>>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()))
Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
If the ``nargs`` keyword argument is not provided, the number of arguments consumed
is determined by the action_. Generally this means a single command-line argument
will be consumed and a single item (not a list) will be produced.
@ -981,6 +1006,14 @@ was not present at the command line::
>>> parser.parse_args([])
Namespace(foo=42)
If the target namespace already has an attribute set, the action *default*
will not over write it::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)
If the ``default`` value is a string, the parser parses the value as if it
were a command-line argument. In particular, the parser applies any type_
conversion argument, if provided, before setting the attribute on the
@ -1017,63 +1050,70 @@ command-line argument was not present::
type
^^^^
By default, :class:`ArgumentParser` objects read command-line arguments in as simple
By default, the parser reads command-line arguments in as simple
strings. However, quite often the command-line string should instead be
interpreted as another type, like a :class:`float` or :class:`int`. The
``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any
necessary type-checking and type conversions to be performed. Common built-in
types and functions can be used directly as the value of the ``type`` argument::
interpreted as another type, such as a :class:`float` or :class:`int`. The
``type`` keyword for :meth:`~ArgumentParser.add_argument` allows any
necessary type-checking and type conversions to be performed.
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=open)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
If the type_ keyword is used with the default_ keyword, the type converter
is only applied if the default is a string.
See the section on the default_ keyword argument for information on when the
``type`` argument is applied to default arguments.
The argument to ``type`` can be any callable that accepts a single string.
If the function raises :exc:`ArgumentTypeError`, :exc:`TypeError`, or
:exc:`ValueError`, the exception is caught and a nicely formatted error
message is displayed. No other exception types are handled.
To ease the use of various types of files, the argparse module provides the
factory FileType which takes the ``mode=``, ``bufsize=``, ``encoding=`` and
``errors=`` arguments of the :func:`open` function. For example,
``FileType('w')`` can be used to create a writable file::
Common built-in types and functions can be used as type converters:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)
.. testcode::
``type=`` can take any callable that takes a single string argument and returns
the converted value::
import argparse
import pathlib
>>> def perfect_square(string):
... value = int(string)
... sqrt = math.sqrt(value)
... if sqrt != int(sqrt):
... msg = "%r is not a perfect square" % string
... raise argparse.ArgumentTypeError(msg)
... return value
parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)
User defined functions can be used as well:
.. doctest::
>>> def hyphenated(string):
... return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')
The choices_ keyword argument may be more convenient for type checkers that
simply check against a range of values::
The :func:`bool` function is not recommended as a type converter. All it does
is convert empty strings to ``False`` and non-empty strings to ``True``.
This is usually not what is desired.
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=range(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
In general, the ``type`` keyword is a convenience that should only be used for
simple conversions that can only raise one of the three supported exceptions.
Anything with more interesting error-handling or resource management should be
done downstream after the arguments are parsed.
See the choices_ section for more details.
For example, JSON or YAML conversions have complex error cases that require
better reporting than can be given by the ``type`` keyword. An
:exc:`~json.JSONDecodeError` would not be well formatted and a
:exc:`FileNotFound` exception would not be handled at all.
Even :class:`~argparse.FileType` has its limitations for use with the ``type``
keyword. If one argument uses *FileType* and then a subsequent argument fails,
an error is reported but the file is not automatically closed. In this case, it
would be better to wait until after the parser has run and then use the
:keyword:`with`-statement to manage the files.
For type checkers that simply check against a fixed set of values, consider
using the choices_ keyword instead.
choices
@ -1109,6 +1149,14 @@ container should match the type_ specified::
Any container can be passed as the *choices* value, so :class:`list` objects,
:class:`set` objects, and custom containers are all supported.
Use of :class:`enum.Enum` is not recommended because it is difficult to
control its appearance in usage, help, and error messages.
Formatted choices overrides the default *metavar* which is normally derived
from *dest*. This is usually what you want because the user never sees the
*dest* parameter. If this display isn't desirable (perhaps because there are
many choices), just specify an explicit metavar_.
required
^^^^^^^^
@ -1123,8 +1171,8 @@ keyword argument to :meth:`~ArgumentParser.add_argument`::
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required
usage: [-h] --foo FOO
: error: the following arguments are required: --foo
As the example shows, if an option is marked as ``required``,
:meth:`~ArgumentParser.parse_args` will report an error if that option is not
@ -1337,6 +1385,9 @@ Action instances should be callable, so subclasses must override the
The ``__call__`` method may perform arbitrary actions, but will typically set
attributes on the ``namespace`` based on ``dest`` and ``values``.
Action subclasses can define a ``format_usage`` method that takes no argument
and return a string which will be used when printing the usage of the program.
If such method is not provided, a sensible default will be used.
The parse_args() method
-----------------------

27
Doc/library/array.rst
View File

@ -22,7 +22,7 @@ defined:
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'B'`` | unsigned char | int | 1 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'u'`` | Py_UNICODE | Unicode character | 2 | \(1) |
| ``'u'`` | wchar_t | Unicode character | 2 | \(1) |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'h'`` | signed short | int | 2 | |
+-----------+--------------------+-------------------+-----------------------+-------+
@ -48,15 +48,16 @@ defined:
Notes:
(1)
The ``'u'`` type code corresponds to Python's obsolete unicode character
(:c:type:`Py_UNICODE` which is :c:type:`wchar_t`). Depending on the
platform, it can be 16 bits or 32 bits.
It can be 16 bits or 32 bits depending on the platform.
``'u'`` will be removed together with the rest of the :c:type:`Py_UNICODE`
API.
.. versionchanged:: 3.9
``array('u')`` now uses ``wchar_t`` as C type instead of deprecated
``Py_UNICODE``. This change doesn't affect to its behavior because
``Py_UNICODE`` is alias of ``wchar_t`` since Python 3.3.
.. deprecated-removed:: 3.3 4.0
The actual representation of values is determined by the machine architecture
(strictly speaking, by the C implementation). The actual size can be accessed
through the :attr:`itemsize` attribute.
@ -169,13 +170,6 @@ The following data items and methods are also supported:
a.append(x)`` except that if there is a type error, the array is unchanged.
.. method:: array.fromstring()
Deprecated alias for :meth:`frombytes`.
.. deprecated-removed:: 3.2 3.9
.. method:: array.fromunicode(s)
Extends this array with data from the given unicode string. The array must
@ -233,13 +227,6 @@ The following data items and methods are also supported:
Convert the array to an ordinary list with the same items.
.. method:: array.tostring()
Deprecated alias for :meth:`tobytes`.
.. deprecated-removed:: 3.2 3.9
.. method:: array.tounicode()
Convert the array to a unicode string. The array must be a type ``'u'`` array;

1533
Doc/library/ast.rst
View File

File diff suppressed because it is too large Load Diff

3
Doc/library/asyncio-api-index.rst
View File

@ -48,6 +48,9 @@ await on multiple things with timeouts.
* - :class:`Task`
- Task object.
* - :func:`to_thread`
- Asychronously run a function in a separate OS thread.
* - :func:`run_coroutine_threadsafe`
- Schedule a coroutine from another OS thread.

12
Doc/library/asyncio-dev.rst
View File

@ -25,7 +25,7 @@ There are several ways to enable asyncio debug mode:
* Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``.
* Using the :option:`-X` ``dev`` Python command line option.
* Using the :ref:`Python Development Mode <devmode>`.
* Passing ``debug=True`` to :func:`asyncio.run`.
@ -107,6 +107,16 @@ The :meth:`loop.run_in_executor` method can be used with a
blocking code in a different OS thread without blocking the OS thread
that the event loop runs in.
There is currently no way to schedule coroutines or callbacks directly
from a different process (such as one started with
:mod:`multiprocessing`). The :ref:`Event Loop Methods <asyncio-event-loop>`
section lists APIs that can read from pipes and watch file descriptors
without blocking the event loop. In addition, asyncio's
:ref:`Subprocess <asyncio-subprocess>` APIs provide a way to start a
process and communicate with it from the event loop. Lastly, the
aforementioned :meth:`loop.run_in_executor` method can also be used
with a :class:`concurrent.futures.ProcessPoolExecutor` to execute
code in a different process.
.. _asyncio-handle-blocking:

50
Doc/library/asyncio-eventloop.rst
View File

@ -173,6 +173,18 @@ Running and stopping the loop
.. versionadded:: 3.6
.. coroutinemethod:: loop.shutdown_default_executor()
Schedule the closure of the default executor and wait for it to join all of
the threads in the :class:`ThreadPoolExecutor`. After calling this method, a
:exc:`RuntimeError` will be raised if :meth:`loop.run_in_executor` is called
while using the default executor.
Note that there is no need to call this function when
:func:`asyncio.run` is used.
.. versionadded:: 3.9
Scheduling callbacks
^^^^^^^^^^^^^^^^^^^^
@ -309,7 +321,7 @@ Creating Futures and Tasks
.. versionadded:: 3.5.2
.. method:: loop.create_task(coro, \*, name=None)
.. method:: loop.create_task(coro, *, name=None)
Schedule the execution of a :ref:`coroutine`.
Return a :class:`Task` object.
@ -344,7 +356,7 @@ Opening network connections
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. coroutinemethod:: loop.create_connection(protocol_factory, \
host=None, port=None, \*, ssl=None, \
host=None, port=None, *, ssl=None, \
family=0, proto=0, flags=0, sock=None, \
local_addr=None, server_hostname=None, \
ssl_handshake_timeout=None, \
@ -470,7 +482,7 @@ Opening network connections
that can be used directly in async/await code.
.. coroutinemethod:: loop.create_datagram_endpoint(protocol_factory, \
local_addr=None, remote_addr=None, \*, \
local_addr=None, remote_addr=None, *, \
family=0, proto=0, flags=0, \
reuse_address=None, reuse_port=None, \
allow_broadcast=None, sock=None)
@ -547,7 +559,7 @@ Opening network connections
Added support for Windows.
.. coroutinemethod:: loop.create_unix_connection(protocol_factory, \
path=None, \*, ssl=None, sock=None, \
path=None, *, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
Create a Unix connection.
@ -580,7 +592,7 @@ Creating network servers
^^^^^^^^^^^^^^^^^^^^^^^^
.. coroutinemethod:: loop.create_server(protocol_factory, \
host=None, port=None, \*, \
host=None, port=None, *, \
family=socket.AF_UNSPEC, \
flags=socket.AI_PASSIVE, \
sock=None, backlog=100, ssl=None, \
@ -671,7 +683,7 @@ Creating network servers
.. coroutinemethod:: loop.create_unix_server(protocol_factory, path=None, \
\*, sock=None, backlog=100, ssl=None, \
*, sock=None, backlog=100, ssl=None, \
ssl_handshake_timeout=None, start_serving=True)
Similar to :meth:`loop.create_server` but works with the
@ -696,7 +708,7 @@ Creating network servers
The *path* parameter can now be a :class:`~pathlib.Path` object.
.. coroutinemethod:: loop.connect_accepted_socket(protocol_factory, \
sock, \*, ssl=None, ssl_handshake_timeout=None)
sock, *, ssl=None, ssl_handshake_timeout=None)
Wrap an already accepted connection into a transport/protocol pair.
@ -761,7 +773,7 @@ TLS Upgrade
^^^^^^^^^^^
.. coroutinemethod:: loop.start_tls(transport, protocol, \
sslcontext, \*, server_side=False, \
sslcontext, *, server_side=False, \
server_hostname=None, ssl_handshake_timeout=None)
Upgrade an existing transport-based connection to TLS.
@ -794,7 +806,7 @@ TLS Upgrade
Watching file descriptors
^^^^^^^^^^^^^^^^^^^^^^^^^
.. method:: loop.add_reader(fd, callback, \*args)
.. method:: loop.add_reader(fd, callback, *args)
Start monitoring the *fd* file descriptor for read availability and
invoke *callback* with the specified arguments once *fd* is available for
@ -804,7 +816,7 @@ Watching file descriptors
Stop monitoring the *fd* file descriptor for read availability.
.. method:: loop.add_writer(fd, callback, \*args)
.. method:: loop.add_writer(fd, callback, *args)
Start monitoring the *fd* file descriptor for write availability and
invoke *callback* with the specified arguments once *fd* is available for
@ -918,7 +930,7 @@ convenient.
:meth:`loop.create_server` and :func:`start_server`.
.. coroutinemethod:: loop.sock_sendfile(sock, file, offset=0, count=None, \
\*, fallback=True)
*, fallback=True)
Send a file using high-performance :mod:`os.sendfile` if possible.
Return the total number of bytes sent.
@ -952,7 +964,7 @@ convenient.
DNS
^^^
.. coroutinemethod:: loop.getaddrinfo(host, port, \*, family=0, \
.. coroutinemethod:: loop.getaddrinfo(host, port, *, family=0, \
type=0, proto=0, flags=0)
Asynchronous version of :meth:`socket.getaddrinfo`.
@ -1017,7 +1029,7 @@ Working with pipes
Unix signals
^^^^^^^^^^^^
.. method:: loop.add_signal_handler(signum, callback, \*args)
.. method:: loop.add_signal_handler(signum, callback, *args)
Set *callback* as the handler for the *signum* signal.
@ -1052,7 +1064,7 @@ Unix signals
Executing code in thread or process pools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. awaitablemethod:: loop.run_in_executor(executor, func, \*args)
.. awaitablemethod:: loop.run_in_executor(executor, func, *args)
Arrange for *func* to be called in the specified executor.
@ -1200,7 +1212,7 @@ Enabling debug mode
.. versionchanged:: 3.7
The new ``-X dev`` command line option can now also be used
The new :ref:`Python Development Mode <devmode>` can now also be used
to enable the debug mode.
.. seealso::
@ -1222,9 +1234,9 @@ async/await code consider using the high-level
subprocesses. See :ref:`Subprocess Support on Windows
<asyncio-windows-subprocess>` for details.
.. coroutinemethod:: loop.subprocess_exec(protocol_factory, \*args, \
.. coroutinemethod:: loop.subprocess_exec(protocol_factory, *args, \
stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
stderr=subprocess.PIPE, \*\*kwargs)
stderr=subprocess.PIPE, **kwargs)
Create a subprocess from one or more string arguments specified by
*args*.
@ -1304,9 +1316,9 @@ async/await code consider using the high-level
conforms to the :class:`asyncio.SubprocessTransport` base class and
*protocol* is an object instantiated by the *protocol_factory*.
.. coroutinemethod:: loop.subprocess_shell(protocol_factory, cmd, \*, \
.. coroutinemethod:: loop.subprocess_shell(protocol_factory, cmd, *, \
stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
stderr=subprocess.PIPE, \*\*kwargs)
stderr=subprocess.PIPE, **kwargs)
Create a subprocess from *cmd*, which can be a :class:`str` or a
:class:`bytes` string encoded to the

14
Doc/library/asyncio-future.rst
View File

@ -31,7 +31,7 @@ Future Functions
.. versionadded:: 3.5
.. function:: ensure_future(obj, \*, loop=None)
.. function:: ensure_future(obj, *, loop=None)
Return:
@ -58,7 +58,7 @@ Future Functions
The function accepts any :term:`awaitable` object.
.. function:: wrap_future(future, \*, loop=None)
.. function:: wrap_future(future, *, loop=None)
Wrap a :class:`concurrent.futures.Future` object in a
:class:`asyncio.Future` object.
@ -67,7 +67,7 @@ Future Functions
Future Object
=============
.. class:: Future(\*, loop=None)
.. class:: Future(*, loop=None)
A Future represents an eventual result of an asynchronous
operation. Not thread-safe.
@ -170,7 +170,7 @@ Future Object
Returns the number of callbacks removed, which is typically 1,
unless a callback was added more than once.
.. method:: cancel()
.. method:: cancel(msg=None)
Cancel the Future and schedule callbacks.
@ -178,6 +178,9 @@ Future Object
Otherwise, change the Future's state to *cancelled*,
schedule the callbacks, and return ``True``.
.. versionchanged:: 3.9
Added the ``msg`` parameter.
.. method:: exception()
Return the exception that was set on this Future.
@ -255,3 +258,6 @@ the Future has a result::
- asyncio Future is not compatible with the
:func:`concurrent.futures.wait` and
:func:`concurrent.futures.as_completed` functions.
- :meth:`asyncio.Future.cancel` accepts an optional ``msg`` argument,
but :func:`concurrent.futures.cancel` does not.

18
Doc/library/asyncio-policy.rst
View File

@ -159,7 +159,7 @@ implementation used by the asyncio event loop:
.. class:: AbstractChildWatcher
.. method:: add_child_handler(pid, callback, \*args)
.. method:: add_child_handler(pid, callback, *args)
Register a new child handler.
@ -209,7 +209,7 @@ implementation used by the asyncio event loop:
It works reliably even when the asyncio event loop is run in a non-main OS thread.
There is no noticeable overhead when handling a big number of children (*O(1)* each
time a child terminates), but stating a thread per process requires extra memory.
time a child terminates), but starting a thread per process requires extra memory.
This watcher is used by default.
@ -219,7 +219,7 @@ implementation used by the asyncio event loop:
This implementation registers a :py:data:`SIGCHLD` signal handler on
instantiation. That can break third-party code that installs a custom handler for
`SIGCHLD`. signal).
:py:data:`SIGCHLD` signal.
The watcher avoids disrupting other code spawning processes
by polling every process explicitly on a :py:data:`SIGCHLD` signal.
@ -257,6 +257,18 @@ implementation used by the asyncio event loop:
This solution requires a running event loop in the main thread to work, as
:class:`SafeChildWatcher`.
.. class:: PidfdChildWatcher
This implementation polls process file descriptors (pidfds) to await child
process termination. In some respects, :class:`PidfdChildWatcher` is a
"Goldilocks" child watcher implementation. It doesn't require signals or
threads, doesn't interfere with any processes launched outside the event
loop, and scales linearly with the number of subprocesses launched by the
event loop. The main disadvantage is that pidfds are specific to Linux, and
only work on recent (5.3+) kernels.
.. versionadded:: 3.9
Custom Policies
===============

3
Doc/library/asyncio-protocol.rst
View File

@ -588,9 +588,6 @@ Buffered Streaming Protocols
----------------------------
.. versionadded:: 3.7
**Important:** this has been added to asyncio in Python 3.7
*on a provisional basis*! This is as an experimental API that
might be changed or removed completely in Python 3.8.
Buffered Protocols can be used with any event loop method
that supports `Streaming Protocols`_.

8
Doc/library/asyncio-stream.rst
View File

@ -48,7 +48,7 @@ The following top-level asyncio functions can be used to create
and work with streams:
.. coroutinefunction:: open_connection(host=None, port=None, \*, \
.. coroutinefunction:: open_connection(host=None, port=None, *, \
loop=None, limit=None, ssl=None, family=0, \
proto=0, flags=0, sock=None, local_addr=None, \
server_hostname=None, ssl_handshake_timeout=None)
@ -74,7 +74,7 @@ and work with streams:
The *ssl_handshake_timeout* parameter.
.. coroutinefunction:: start_server(client_connected_cb, host=None, \
port=None, \*, loop=None, limit=None, \
port=None, *, loop=None, limit=None, \
family=socket.AF_UNSPEC, \
flags=socket.AI_PASSIVE, sock=None, \
backlog=100, ssl=None, reuse_address=None, \
@ -109,7 +109,7 @@ and work with streams:
.. rubric:: Unix Sockets
.. coroutinefunction:: open_unix_connection(path=None, \*, loop=None, \
.. coroutinefunction:: open_unix_connection(path=None, *, loop=None, \
limit=None, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
@ -132,7 +132,7 @@ and work with streams:
.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \
\*, loop=None, limit=None, sock=None, \
*, loop=None, limit=None, sock=None, \
backlog=100, ssl=None, ssl_handshake_timeout=None, \
start_serving=True)

12
Doc/library/asyncio-subprocess.rst
View File

@ -61,9 +61,9 @@ See also the `Examples`_ subsection.
Creating Subprocesses
=====================
.. coroutinefunction:: create_subprocess_exec(program, \*args, stdin=None, \
.. coroutinefunction:: create_subprocess_exec(program, *args, stdin=None, \
stdout=None, stderr=None, loop=None, \
limit=None, \*\*kwds)
limit=None, **kwds)
Create a subprocess.
@ -82,7 +82,7 @@ Creating Subprocesses
.. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, \
stdout=None, stderr=None, loop=None, \
limit=None, \*\*kwds)
limit=None, **kwds)
Run the *cmd* shell command.
@ -110,10 +110,8 @@ Creating Subprocesses
.. note::
The default asyncio event loop implementation on **Windows** does not
support subprocesses. Subprocesses are available for Windows if a
:class:`ProactorEventLoop` is used.
See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
Subprocesses are available for Windows if a :class:`ProactorEventLoop` is
used. See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
for details.
.. seealso::

14
Doc/library/asyncio-sync.rst
View File

@ -104,8 +104,8 @@ Event
that some event has happened.
An Event object manages an internal flag that can be set to *true*
with the :meth:`set` method and reset to *false* with the
:meth:`clear` method. The :meth:`wait` method blocks until the
with the :meth:`~Event.set` method and reset to *false* with the
:meth:`clear` method. The :meth:`~Event.wait` method blocks until the
flag is set to *true*. The flag is set to *false* initially.
@ -142,7 +142,7 @@ Event
Wait until the event is set.
If the event is set, return ``True`` immediately.
Otherwise block until another task calls :meth:`set`.
Otherwise block until another task calls :meth:`~Event.set`.
.. method:: set()
@ -155,8 +155,8 @@ Event
Clear (unset) the event.
Tasks awaiting on :meth:`wait` will now block until the
:meth:`set` method is called again.
Tasks awaiting on :meth:`~Event.wait` will now block until the
:meth:`~Event.set` method is called again.
.. method:: is_set()
@ -347,8 +347,8 @@ BoundedSemaphore
---------
.. deprecated:: 3.7
.. versionchanged:: 3.9
Acquiring a lock using ``await lock`` or ``yield from lock`` and/or
:keyword:`with` statement (``with await lock``, ``with (yield from
lock)``) is deprecated. Use ``async with lock`` instead.
lock)``) was removed. Use ``async with lock`` instead.

130
Doc/library/asyncio-task.rst
View File

@ -210,13 +210,13 @@ is :meth:`loop.run_in_executor`.
Running an asyncio Program
==========================
.. function:: run(coro, \*, debug=False)
.. function:: run(coro, *, debug=False)
Execute the :term:`coroutine` *coro* and return the result.
This function runs the passed coroutine, taking care of
managing the asyncio event loop and *finalizing asynchronous
generators*.
managing the asyncio event loop, *finalizing asynchronous
generators*, and closing the threadpool.
This function cannot be called when another asyncio event loop is
running in the same thread.
@ -237,6 +237,8 @@ Running an asyncio Program
.. versionadded:: 3.7
.. versionchanged:: 3.9
Updated to use :meth:`loop.shutdown_default_executor`.
.. note::
The source code for ``asyncio.run()`` can be found in
@ -245,7 +247,7 @@ Running an asyncio Program
Creating Tasks
==============
.. function:: create_task(coro, \*, name=None)
.. function:: create_task(coro, *, name=None)
Wrap the *coro* :ref:`coroutine <coroutine>` into a :class:`Task`
and schedule its execution. Return the Task object.
@ -281,7 +283,7 @@ Creating Tasks
Sleeping
========
.. coroutinefunction:: sleep(delay, result=None, \*, loop=None)
.. coroutinefunction:: sleep(delay, result=None, *, loop=None)
Block for *delay* seconds.
@ -317,7 +319,7 @@ Sleeping
Running Tasks Concurrently
==========================
.. awaitablefunction:: gather(\*aws, loop=None, return_exceptions=False)
.. awaitablefunction:: gather(*aws, loop=None, return_exceptions=False)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
sequence *concurrently*.
@ -401,7 +403,7 @@ Running Tasks Concurrently
Shielding From Cancellation
===========================
.. awaitablefunction:: shield(aw, \*, loop=None)
.. awaitablefunction:: shield(aw, *, loop=None)
Protect an :ref:`awaitable object <asyncio-awaitables>`
from being :meth:`cancelled <Task.cancel>`.
@ -441,7 +443,7 @@ Shielding From Cancellation
Timeouts
========
.. coroutinefunction:: wait_for(aw, timeout, \*, loop=None)
.. coroutinefunction:: wait_for(aw, timeout, *, loop=None)
Wait for the *aw* :ref:`awaitable <asyncio-awaitables>`
to complete with a timeout.
@ -459,7 +461,8 @@ Timeouts
wrap it in :func:`shield`.
The function will wait until the future is actually cancelled,
so the total wait time may exceed the *timeout*.
so the total wait time may exceed the *timeout*. If an exception
happens during cancellation, it is propagated.
If the wait is cancelled, the future *aw* is also cancelled.
@ -497,13 +500,15 @@ Timeouts
Waiting Primitives
==================
.. coroutinefunction:: wait(aws, \*, loop=None, timeout=None,\
.. coroutinefunction:: wait(aws, *, loop=None, timeout=None,\
return_when=ALL_COMPLETED)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
set concurrently and block until the condition specified
iterable concurrently and block until the condition specified
by *return_when*.
The *aws* iterable must not be empty.
Returns two sets of Tasks/Futures: ``(done, pending)``.
Usage::
@ -579,18 +584,18 @@ Waiting Primitives
if task in done:
# Everything will work as expected now.
.. deprecated:: 3.8
.. deprecated-removed:: 3.8 3.11
Passing coroutine objects to ``wait()`` directly is
deprecated.
.. function:: as_completed(aws, \*, loop=None, timeout=None)
.. function:: as_completed(aws, *, loop=None, timeout=None)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
set concurrently. Return an iterator of coroutines.
iterable concurrently. Return an iterator of coroutines.
Each coroutine returned can be awaited to get the earliest next
result from the set of the remaining awaitables.
result from the iterable of the remaining awaitables.
Raises :exc:`asyncio.TimeoutError` if the timeout occurs before
all Futures are done.
@ -605,6 +610,65 @@ Waiting Primitives
# ...
Running in Threads
==================
.. coroutinefunction:: to_thread(func, /, *args, **kwargs)
Asynchronously run function *func* in a separate thread.
Any \*args and \*\*kwargs supplied for this function are directly passed
to *func*. Also, the current :class:`contextvars.Context` is propagated,
allowing context variables from the event loop thread to be accessed in the
separate thread.
Return a coroutine that can be awaited to get the eventual result of *func*.
This coroutine function is primarily intended to be used for executing
IO-bound functions/methods that would otherwise block the event loop if
they were ran in the main thread. For example::
def blocking_io():
print(f"start blocking_io at {time.strftime('%X')}")
# Note that time.sleep() can be replaced with any blocking
# IO-bound operation, such as file operations.
time.sleep(1)
print(f"blocking_io complete at {time.strftime('%X')}")
async def main():
print(f"started main at {time.strftime('%X')}")
await asyncio.gather(
asyncio.to_thread(blocking_io),
asyncio.sleep(1))
print(f"finished main at {time.strftime('%X')}")
asyncio.run(main())
# Expected output:
#
# started main at 19:50:53
# start blocking_io at 19:50:53
# blocking_io complete at 19:50:54
# finished main at 19:50:54
Directly calling `blocking_io()` in any coroutine would block the event loop
for its duration, resulting in an additional 1 second of run time. Instead,
by using `asyncio.to_thread()`, we can run it in a separate thread without
blocking the event loop.
.. note::
Due to the :term:`GIL`, `asyncio.to_thread()` can typically only be used
to make IO-bound functions non-blocking. However, for extension modules
that release the GIL or alternative Python implementations that don't
have one, `asyncio.to_thread()` can also be used for CPU-bound functions.
.. versionadded:: 3.9
Scheduling From Other Threads
=============================
@ -679,7 +743,7 @@ Introspection
Task Object
===========
.. class:: Task(coro, \*, loop=None, name=None)
.. class:: Task(coro, *, loop=None, name=None)
A :class:`Future-like <Future>` object that runs a Python
:ref:`coroutine <coroutine>`. Not thread-safe.
@ -727,7 +791,7 @@ Task Object
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. method:: cancel()
.. method:: cancel(msg=None)
Request the Task to be cancelled.
@ -742,6 +806,9 @@ Task Object
suppressing cancellation completely is not common and is actively
discouraged.
.. versionchanged:: 3.9
Added the ``msg`` parameter.
.. _asyncio_example_task_cancel:
The following example illustrates how coroutines can intercept
@ -842,7 +909,7 @@ Task Object
See the documentation of :meth:`Future.remove_done_callback`
for more details.
.. method:: get_stack(\*, limit=None)
.. method:: get_stack(*, limit=None)
Return the list of stack frames for this Task.
@ -863,7 +930,7 @@ Task Object
stack are returned, but the oldest frames of a traceback are
returned. (This matches the behavior of the traceback module.)
.. method:: print_stack(\*, limit=None, file=None)
.. method:: print_stack(*, limit=None, file=None)
Print the stack or traceback for this Task.
@ -903,31 +970,6 @@ Task Object
.. versionadded:: 3.8
.. classmethod:: all_tasks(loop=None)
Return a set of all tasks for an event loop.
By default all tasks for the current event loop are returned.
If *loop* is ``None``, the :func:`get_event_loop` function
is used to get the current loop.
.. deprecated-removed:: 3.7 3.9
Do not call this as a task method. Use the :func:`asyncio.all_tasks`
function instead.
.. classmethod:: current_task(loop=None)
Return the currently running task or ``None``.
If *loop* is ``None``, the :func:`get_event_loop` function
is used to get the current loop.
.. deprecated-removed:: 3.7 3.9
Do not call this as a task method. Use the
:func:`asyncio.current_task` function instead.
.. _asyncio_generator_based_coro:

26
Doc/library/audit_events.rst
View File

@ -19,3 +19,29 @@ information on handling these events.
specific documentation for actual events raised.
.. audit-event-table::
The following events are raised internally and do not correspond to any
public API of CPython:
+--------------------------+-------------------------------------------+
| Audit event | Arguments |
+==========================+===========================================+
| _winapi.CreateFile | ``file_name``, ``desired_access``, |
| | ``share_mode``, ``creation_disposition``, |
| | ``flags_and_attributes`` |
+--------------------------+-------------------------------------------+
| _winapi.CreateJunction | ``src_path``, ``dst_path`` |
+--------------------------+-------------------------------------------+
| _winapi.CreateNamedPipe | ``name``, ``open_mode``, ``pipe_mode`` |
+--------------------------+-------------------------------------------+
| _winapi.CreatePipe | |
+--------------------------+-------------------------------------------+
| _winapi.CreateProcess | ``application_name``, ``command_line``, |
| | ``current_directory`` |
+--------------------------+-------------------------------------------+
| _winapi.OpenProcess | ``process_id``, ``desired_access`` |
+--------------------------+-------------------------------------------+
| _winapi.TerminateProcess | ``handle``, ``exit_code`` |
+--------------------------+-------------------------------------------+
| ctypes.PyObj_FromPtr | ``obj`` |
+--------------------------+-------------------------------------------+

12
Doc/library/base64.rst
View File

@ -235,12 +235,6 @@ The legacy interface:
.. versionadded:: 3.1
.. function:: decodestring(s)
Deprecated alias of :func:`decodebytes`.
.. deprecated:: 3.1
.. function:: encode(input, output)
@ -261,12 +255,6 @@ The legacy interface:
.. versionadded:: 3.1
.. function:: encodestring(s)
Deprecated alias of :func:`encodebytes`.
.. deprecated:: 3.1
An example usage of the module:

2
Doc/library/bdb.rst
View File

@ -343,7 +343,7 @@ The :mod:`bdb` module also defines two classes:
For backwards compatibility. Calls the :meth:`run` method.
.. method:: runcall(func, *args, **kwds)
.. method:: runcall(func, /, *args, **kwds)
Debug a single function call, and return its result.

8
Doc/library/binascii.rst
View File

@ -92,6 +92,8 @@ The :mod:`binascii` module defines the following functions:
The string should contain a complete number of binary bytes, or (in case of the
last portion of the binhex4 data) have the remaining bits zero.
.. deprecated:: 3.9
.. function:: rledecode_hqx(data)
@ -104,11 +106,15 @@ The :mod:`binascii` module defines the following functions:
.. versionchanged:: 3.2
Accept only bytestring or bytearray objects as input.
.. deprecated:: 3.9
.. function:: rlecode_hqx(data)
Perform binhex4 style RLE-compression on *data* and return the result.
.. deprecated:: 3.9
.. function:: b2a_hqx(data)
@ -116,6 +122,8 @@ The :mod:`binascii` module defines the following functions:
argument should already be RLE-coded, and have a length divisible by 3 (except
possibly the last fragment).
.. deprecated:: 3.9
.. function:: crc_hqx(data, value)

2
Doc/library/binhex.rst
View File

@ -6,6 +6,8 @@
**Source code:** :source:`Lib/binhex.py`
.. deprecated:: 3.9
--------------
This module encodes and decodes files in binhex4 format, a format allowing

24
Doc/library/bz2.rst
View File

@ -31,7 +31,7 @@ All of the classes in this module may safely be accessed from multiple threads.
(De)compression of files
------------------------
.. function:: open(filename, mode='r', compresslevel=9, encoding=None, errors=None, newline=None)
.. function:: open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)
Open a bzip2-compressed file in binary or text mode, returning a :term:`file
object`.
@ -65,7 +65,7 @@ All of the classes in this module may safely be accessed from multiple threads.
Accepts a :term:`path-like object`.
.. class:: BZ2File(filename, mode='r', buffering=None, compresslevel=9)
.. class:: BZ2File(filename, mode='r', *, compresslevel=9)
Open a bzip2-compressed file in binary mode.
@ -81,8 +81,6 @@ All of the classes in this module may safely be accessed from multiple threads.
If *filename* is a file object (rather than an actual file name), a mode of
``'w'`` does not truncate the file, and is instead equivalent to ``'a'``.
The *buffering* argument is ignored. Its use is deprecated since Python 3.0.
If *mode* is ``'w'`` or ``'a'``, *compresslevel* can be an integer between
``1`` and ``9`` specifying the level of compression: ``1`` produces the
least compression, and ``9`` (default) produces the most compression.
@ -110,9 +108,6 @@ All of the classes in this module may safely be accessed from multiple threads.
.. versionadded:: 3.3
.. deprecated:: 3.0
The keyword argument *buffering* was deprecated and is now ignored.
.. versionchanged:: 3.1
Support for the :keyword:`with` statement was added.
@ -138,6 +133,13 @@ All of the classes in this module may safely be accessed from multiple threads.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
.. versionchanged:: 3.9
The *buffering* parameter has been removed. It was ignored and deprecated
since Python 3.0. Pass an open file object to control how the file is
opened.
The *compresslevel* parameter became keyword-only.
Incremental (de)compression
---------------------------
@ -264,7 +266,6 @@ Below are some examples of typical usage of the :mod:`bz2` module.
Using :func:`compress` and :func:`decompress` to demonstrate round-trip compression:
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
@ -273,11 +274,9 @@ Using :func:`compress` and :func:`decompress` to demonstrate round-trip compress
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c) # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d # Check equality to original object after round-trip
True
@ -285,7 +284,6 @@ Using :func:`compress` and :func:`decompress` to demonstrate round-trip compress
Using :class:`BZ2Compressor` for incremental compression:
>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
... """Yield incremental blocks of chunksize bytes."""
... for _ in range(chunks):
@ -308,7 +306,6 @@ while ordered, repetitive data usually yields a high compression ratio.
Writing and reading a bzip2-compressed file in binary mode:
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
@ -317,14 +314,11 @@ Writing and reading a bzip2-compressed file in binary mode:
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
... # Write compressed data to file
... unused = f.write(data)
>>> with bz2.open("myfile.bz2", "rb") as f:
... # Decompress data from file
... content = f.read()
>>> content == data # Check equality to original object after round-trip
True

9
Doc/library/cgi.rst
View File

@ -277,14 +277,14 @@ These are useful if you want more control, or if you want to employ some of the
algorithms implemented in this module in other circumstances.
.. function:: parse(fp=None, environ=os.environ, keep_blank_values=False, strict_parsing=False)
.. function:: parse(fp=None, environ=os.environ, keep_blank_values=False, strict_parsing=False, separator="&")
Parse a query in the environment or from a file (the file defaults to
``sys.stdin``). The *keep_blank_values* and *strict_parsing* parameters are
``sys.stdin``). The *keep_blank_values*, *strict_parsing* and *separator* parameters are
passed to :func:`urllib.parse.parse_qs` unchanged.
.. function:: parse_multipart(fp, pdict, encoding="utf-8", errors="replace")
.. function:: parse_multipart(fp, pdict, encoding="utf-8", errors="replace", separator="&")
Parse input of type :mimetype:`multipart/form-data` (for file uploads).
Arguments are *fp* for the input file, *pdict* for a dictionary containing
@ -303,6 +303,9 @@ algorithms implemented in this module in other circumstances.
Added the *encoding* and *errors* parameters. For non-file fields, the
value is now a list of strings, not bytes.
.. versionchanged:: 3.9.2
Added the *separator* parameter.
.. function:: parse_header(string)

7
Doc/library/codecs.rst
View File

@ -694,7 +694,7 @@ compatible with the Python codec registry.
.. method:: reset()
Flushes and resets the codec buffers used for keeping state.
Resets the codec buffers used for keeping internal state.
Calling this method should ensure that the data on the output is put into
a clean state that allows appending of new fresh data without having to
@ -789,7 +789,7 @@ compatible with the Python codec registry.
.. method:: reset()
Resets the codec buffers used for keeping state.
Resets the codec buffers used for keeping internal state.
Note that no stream repositioning should take place. This method is
primarily intended to be able to recover from decoding errors.
@ -1198,7 +1198,8 @@ particular, the following variants typically exist:
+-----------------+--------------------------------+--------------------------------+
| mac_iceland | maciceland | Icelandic |
+-----------------+--------------------------------+--------------------------------+
| mac_latin2 | maclatin2, maccentraleurope | Central and Eastern Europe |
| mac_latin2 | maclatin2, maccentraleurope, | Central and Eastern Europe |
| | mac_centeuro | |
+-----------------+--------------------------------+--------------------------------+
| mac_roman | macroman, macintosh | Western Europe |
+-----------------+--------------------------------+--------------------------------+

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

@ -98,12 +98,20 @@ ABC Inherits from Abstract Methods Mixin
.. class:: Container
Hashable
Sized
Callable
ABCs for classes that provide respectively the methods :meth:`__contains__`,
:meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`.
ABC for classes that provide the :meth:`__contains__` method.
.. class:: Hashable
ABC for classes that provide the :meth:`__hash__` method.
.. class:: Sized
ABC for classes that provide the :meth:`__len__` method.
.. class:: Callable
ABC for classes that provide the :meth:`__call__` method.
.. class:: Iterable
@ -185,7 +193,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::
@ -283,7 +291,7 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
:meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
If the :class:`Set` mixin is being used in a class with a different
constructor signature, you will need to override :meth:`_from_iterable`
with a classmethod that can construct new instances from
with a classmethod or regular method that can construct new instances from
an iterable argument.
(2)

14
Doc/library/collections.rst
View File

@ -116,6 +116,9 @@ The class can be used to simulate nested scopes and is useful in templating.
>>> list(combined)
['music', 'art', 'opera']
.. versionchanged:: 3.9
Added support for ``|`` and ``|=`` operators, specified in :pep:`584`.
.. seealso::
* The `MultiContext class
@ -729,6 +732,10 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
initialized from the first argument to the constructor, if present, or to
``None``, if absent.
.. versionchanged:: 3.9
Added merge (``|``) and update (``|=``) operators, specified in
:pep:`584`.
:class:`defaultdict` Examples
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -842,6 +849,9 @@ they add the ability to access fields by name instead of position index.
Named tuple instances do not have per-instance dictionaries, so they are
lightweight and require no more memory than regular tuples.
To support pickling, the named tuple class should be assigned to a variable
that matches *typename*.
.. versionchanged:: 3.1
Added support for *rename*.
@ -1119,6 +1129,10 @@ anywhere a regular dictionary is used.
passed to the :class:`OrderedDict` constructor and its :meth:`update`
method.
.. versionchanged:: 3.9
Added merge (``|``) and update (``|=``) operators, specified in :pep:`584`.
:class:`OrderedDict` Examples and Recipes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

2
Doc/library/colorsys.rst
View File

@ -21,7 +21,7 @@ spaces, the coordinates are all between 0 and 1.
.. seealso::
More information about color spaces can be found at
http://poynton.ca/ColorFAQ.html and
https://poynton.ca/ColorFAQ.html and
https://www.cambridgeincolour.com/tutorials/color-spaces.htm.
The :mod:`colorsys` module defines the following functions:

Some files were not shown because too many files have changed in this diff Show More