Skip to content

Commit 048b3cc

Browse files
github-actions[bot]github-actions[bot]
committed
deploy: a0aef16 
1 parent 9a955f8 commit 048b3cc

File tree

849 files changed

+122615
-63503
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

849 files changed

+122615
-63503
lines changed

‎.buildinfo

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# Sphinx build info version 1
22
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3-
config: ca58daa7f9eaf2fe9b9976d62f82e969
3+
config: 6945e7653596070102fe8892a1eb13f9
44
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎_sources/c-api/allocation.rst.txt

+16-12
Original file line numberDiff line numberDiff line change
@@ -27,31 +27,35 @@ Allocating Objects on the Heap
2727
length information for a variable-size object.
2828
2929
30-
.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
30+
.. c:macro:: PyObject_New(TYPE, typeobj)
3131
32-
Allocate a new Python object using the C structure type *TYPE* and the
33-
Python type object *type*. Fields not defined by the Python object header
34-
are not initialized; the object's reference count will be one. The size of
35-
the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
36-
the type object.
32+
Allocate a new Python object using the C structure type *TYPE*
33+
and the Python type object *typeobj* (``PyTypeObject*``).
34+
Fields not defined by the Python object header are not initialized.
35+
The caller will own the only reference to the object
36+
(i.e. its reference count will be one).
37+
The size of the memory allocation is determined from the
38+
:c:member:`~PyTypeObject.tp_basicsize` field of the type object.
3739
3840
39-
.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
41+
.. c:macro:: PyObject_NewVar(TYPE, typeobj, size)
4042
4143
Allocate a new Python object using the C structure type *TYPE* and the
42-
Python type object *type*. Fields not defined by the Python object header
44+
Python type object *typeobj* (``PyTypeObject*``).
45+
Fields not defined by the Python object header
4346
are not initialized. The allocated memory allows for the *TYPE* structure
44-
plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
45-
*type*. This is useful for implementing objects like tuples, which are
47+
plus *size* (``Py_ssize_t``) fields of the size
48+
given by the :c:member:`~PyTypeObject.tp_itemsize` field of
49+
*typeobj*. This is useful for implementing objects like tuples, which are
4650
able to determine their size at construction time. Embedding the array of
4751
fields into the same allocation decreases the number of allocations,
4852
improving the memory management efficiency.
4953
5054
5155
.. c:function:: void PyObject_Del(void *op)
5256
53-
Releases memory allocated to an object using :c:func:`PyObject_New` or
54-
:c:func:`PyObject_NewVar`. This is normally called from the
57+
Releases memory allocated to an object using :c:macro:`PyObject_New` or
58+
:c:macro:`PyObject_NewVar`. This is normally called from the
5559
:c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type. The fields of
5660
the object should not be accessed after this call as the memory is no
5761
longer a valid Python object.

‎_sources/c-api/apiabiversion.rst.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
6060

6161
Use this for numeric comparisons, e.g. ``#if PY_VERSION_HEX >= ...``.
6262

63-
This version is also available via the symbol :data:`Py_Version`.
63+
This version is also available via the symbol :c:var:`Py_Version`.
6464

6565
.. c:var:: const unsigned long Py_Version
6666

‎_sources/c-api/arg.rst.txt

+15-10
Original file line numberDiff line numberDiff line change
@@ -330,8 +330,10 @@ Other objects
330330

331331
``O`` (object) [PyObject \*]
332332
Store a Python object (without any conversion) in a C object pointer. The C
333-
program thus receives the actual object that was passed. The object's reference
334-
count is not increased. The pointer stored is not ``NULL``.
333+
program thus receives the actual object that was passed. A new
334+
:term:`strong reference` to the object is not created
335+
(i.e. its reference count is not increased).
336+
The pointer stored is not ``NULL``.
335337

336338
``O!`` (object) [*typeobject*, PyObject \*]
337339
Store a Python object in a C object pointer. This is similar to ``O``, but
@@ -380,7 +382,7 @@ Other objects
380382
*items*. Format units for sequences may be nested.
381383

382384
It is possible to pass "long" integers (integers whose value exceeds the
383-
platform's :const:`LONG_MAX`) however no proper range checking is done --- the
385+
platform's :c:macro:`LONG_MAX`) however no proper range checking is done --- the
384386
most significant bits are silently truncated when the receiving field is too
385387
small to receive the value (actually, the semantics are inherited from downcasts
386388
in C --- your mileage may vary).
@@ -415,7 +417,8 @@ inside nested parentheses. They are:
415417
mutually exclude each other.
416418

417419
Note that any Python object references which are provided to the caller are
418-
*borrowed* references; do not decrement their reference count!
420+
*borrowed* references; do not release them
421+
(i.e. do not decrement their reference count)!
419422

420423
Additional arguments passed to these functions must be addresses of variables
421424
whose type is determined by the format string; these are used to store values
@@ -492,7 +495,7 @@ API Functions
492495
493496
A simpler form of parameter retrieval which does not use a format string to
494497
specify the types of the arguments. Functions which use this method to retrieve
495-
their parameters should be declared as :const:`METH_VARARGS` in function or
498+
their parameters should be declared as :c:macro:`METH_VARARGS` in function or
496499
method tables. The tuple containing the actual parameters should be passed as
497500
*args*; it must actually be a tuple. The length of the tuple must be at least
498501
*min* and no more than *max*; *min* and *max* may be equal. Additional
@@ -506,7 +509,7 @@ API Functions
506509
will be set if there was a failure.
507510
508511
This is an example of the use of this function, taken from the sources for the
509-
:mod:`_weakref` helper module for weak references::
512+
:mod:`!_weakref` helper module for weak references::
510513
511514
static PyObject *
512515
weakref_ref(PyObject *self, PyObject *args)
@@ -584,7 +587,7 @@ Building values
584587
Same as ``s#``.
585588
586589
``u`` (:class:`str`) [const wchar_t \*]
587-
Convert a null-terminated :c:expr:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
590+
Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
588591
data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``,
589592
``None`` is returned.
590593
@@ -650,8 +653,10 @@ Building values
650653
Convert a C :c:type:`Py_complex` structure to a Python complex number.
651654
652655
``O`` (object) [PyObject \*]
653-
Pass a Python object untouched (except for its reference count, which is
654-
incremented by one). If the object passed in is a ``NULL`` pointer, it is assumed
656+
Pass a Python object untouched but create a new
657+
:term:`strong reference` to it
658+
(i.e. its reference count is incremented by one).
659+
If the object passed in is a ``NULL`` pointer, it is assumed
655660
that this was caused because the call producing the argument found an error and
656661
set an exception. Therefore, :c:func:`Py_BuildValue` will return ``NULL`` but won't
657662
raise an exception. If no exception has been raised yet, :exc:`SystemError` is
@@ -661,7 +666,7 @@ Building values
661666
Same as ``O``.
662667
663668
``N`` (object) [PyObject \*]
664-
Same as ``O``, except it doesn't increment the reference count on the object.
669+
Same as ``O``, except it doesn't create a new :term:`strong reference`.
665670
Useful when the object is created by a call to an object constructor in the
666671
argument list.
667672

‎_sources/c-api/bool.rst.txt

+6
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ creation and deletion functions don't apply to booleans. The following macros
1111
are available, however.
1212

1313

14+
.. c:var:: PyTypeObject PyBool_Type
15+
16+
This instance of :c:type:`PyTypeObject` represents the Python boolean type; it
17+
is the same object as :class:`bool` in the Python layer.
18+
19+
1420
.. c:function:: int PyBool_Check(PyObject *o)
1521
1622
Return true if *o* is of type :c:data:`PyBool_Type`. This function always

‎_sources/c-api/buffer.rst.txt

+23-12
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ the elements exposed by an :class:`array.array` can be multi-byte values.
4444

4545
An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
4646
method of file objects: any object that can export a series of bytes through
47-
the buffer interface can be written to a file. While :meth:`write` only
47+
the buffer interface can be written to a file. While :meth:`!write` only
4848
needs read-only access to the internal contents of the object passed to it,
4949
other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
5050
to the contents of their argument. The buffer interface allows objects to
@@ -102,7 +102,9 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
102102
.. c:member:: PyObject *obj
103103
104104
A new reference to the exporting object. The reference is owned by
105-
the consumer and automatically decremented and set to ``NULL`` by
105+
the consumer and automatically released
106+
(i.e. reference count decremented)
107+
and set to ``NULL`` by
106108
:c:func:`PyBuffer_Release`. The field is the equivalent of the return
107109
value of any standard C-API function.
108110

@@ -159,10 +161,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
159161
If it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing
160162
a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
161163
and :c:member:`~Py_buffer.suboffsets` MUST be ``NULL``.
162-
163-
The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions
164-
to 64. Exporters MUST respect this limit, consumers of multi-dimensional
165-
buffers SHOULD be able to handle up to :c:macro:`PyBUF_MAX_NDIM` dimensions.
164+
The maximum number of dimensions is given by :c:macro:`PyBUF_MAX_NDIM`.
166165

167166
.. c:member:: Py_ssize_t *shape
168167
@@ -215,6 +214,17 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
215214
freed when the buffer is released. The consumer MUST NOT alter this
216215
value.
217216

217+
218+
Constants:
219+
220+
.. c:macro:: PyBUF_MAX_NDIM
221+
222+
The maximum number of dimensions the memory represents.
223+
Exporters MUST respect this limit, consumers of multi-dimensional
224+
buffers SHOULD be able to handle up to :c:macro:`!PyBUF_MAX_NDIM` dimensions.
225+
Currently set to 64.
226+
227+
218228
.. _buffer-request-types:
219229

220230
Buffer request types
@@ -225,7 +235,7 @@ object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical
225235
structure of the memory can vary drastically, the consumer uses the *flags*
226236
argument to specify the exact buffer type it can handle.
227237

228-
All :c:data:`Py_buffer` fields are unambiguously defined by the request
238+
All :c:type:`Py_buffer` fields are unambiguously defined by the request
229239
type.
230240

231241
request-independent fields
@@ -438,7 +448,7 @@ Buffer-related functions
438448
439449
Send a request to *exporter* to fill in *view* as specified by *flags*.
440450
If the exporter cannot provide a buffer of the exact type, it MUST raise
441-
:c:data:`PyExc_BufferError`, set ``view->obj`` to ``NULL`` and
451+
:exc:`BufferError`, set ``view->obj`` to ``NULL`` and
442452
return ``-1``.
443453
444454
On success, fill in *view*, set ``view->obj`` to a new reference
@@ -454,7 +464,8 @@ Buffer-related functions
454464
455465
.. c:function:: void PyBuffer_Release(Py_buffer *view)
456466
457-
Release the buffer *view* and decrement the reference count for
467+
Release the buffer *view* and release the :term:`strong reference`
468+
(i.e. decrement the reference count) to the view's supporting object,
458469
``view->obj``. This function MUST be called when the buffer
459470
is no longer being used, otherwise reference leaks may occur.
460471
@@ -464,7 +475,7 @@ Buffer-related functions
464475
465476
.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *format)
466477
467-
Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
478+
Return the implied :c:member:`~Py_buffer.itemsize` from :c:member:`~Py_buffer.format`.
468479
On error, raise an exception and return -1.
469480
470481
.. versionadded:: 3.9
@@ -499,7 +510,7 @@ Buffer-related functions
499510
This function fails if *len* != *src->len*.
500511
501512
502-
.. c:function:: int PyObject_CopyData(Py_buffer *dest, Py_buffer *src)
513+
.. c:function:: int PyObject_CopyData(PyObject *dest, PyObject *src)
503514
504515
Copy data from *src* to *dest* buffer. Can convert between C-style and
505516
or Fortran-style buffers.
@@ -524,7 +535,7 @@ Buffer-related functions
524535
and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
525536
526537
On success, set ``view->obj`` to a new reference to *exporter* and
527-
return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
538+
return 0. Otherwise, raise :exc:`BufferError`, set
528539
``view->obj`` to ``NULL`` and return ``-1``;
529540
530541
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,

‎_sources/c-api/bytearray.rst.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
Byte Array Objects
66
------------------
77

8-
.. index:: object: bytearray
8+
.. index:: pair: object; bytearray
99

1010

1111
.. c:type:: PyByteArrayObject

‎_sources/c-api/bytes.rst.txt

+15-15
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Bytes Objects
88
These functions raise :exc:`TypeError` when expecting a bytes parameter and
99
called with a non-bytes parameter.
1010

11-
.. index:: object: bytes
11+
.. index:: pair: object; bytes
1212

1313

1414
.. c:type:: PyBytesObject
@@ -67,39 +67,39 @@ called with a non-bytes parameter.
6767
+-------------------+---------------+--------------------------------+
6868
| Format Characters | Type | Comment |
6969
+===================+===============+================================+
70-
| :attr:`%%` | *n/a* | The literal % character. |
70+
| ``%%`` | *n/a* | The literal % character. |
7171
+-------------------+---------------+--------------------------------+
72-
| :attr:`%c` | int | A single byte, |
72+
| ``%c`` | int | A single byte, |
7373
| | | represented as a C int. |
7474
+-------------------+---------------+--------------------------------+
75-
| :attr:`%d` | int | Equivalent to |
75+
| ``%d`` | int | Equivalent to |
7676
| | | ``printf("%d")``. [1]_ |
7777
+-------------------+---------------+--------------------------------+
78-
| :attr:`%u` | unsigned int | Equivalent to |
78+
| ``%u`` | unsigned int | Equivalent to |
7979
| | | ``printf("%u")``. [1]_ |
8080
+-------------------+---------------+--------------------------------+
81-
| :attr:`%ld` | long | Equivalent to |
81+
| ``%ld`` | long | Equivalent to |
8282
| | | ``printf("%ld")``. [1]_ |
8383
+-------------------+---------------+--------------------------------+
84-
| :attr:`%lu` | unsigned long | Equivalent to |
84+
| ``%lu`` | unsigned long | Equivalent to |
8585
| | | ``printf("%lu")``. [1]_ |
8686
+-------------------+---------------+--------------------------------+
87-
| :attr:`%zd` | :c:type:`\ | Equivalent to |
87+
| ``%zd`` | :c:type:`\ | Equivalent to |
8888
| | Py_ssize_t` | ``printf("%zd")``. [1]_ |
8989
+-------------------+---------------+--------------------------------+
90-
| :attr:`%zu` | size_t | Equivalent to |
90+
| ``%zu`` | size_t | Equivalent to |
9191
| | | ``printf("%zu")``. [1]_ |
9292
+-------------------+---------------+--------------------------------+
93-
| :attr:`%i` | int | Equivalent to |
93+
| ``%i`` | int | Equivalent to |
9494
| | | ``printf("%i")``. [1]_ |
9595
+-------------------+---------------+--------------------------------+
96-
| :attr:`%x` | int | Equivalent to |
96+
| ``%x`` | int | Equivalent to |
9797
| | | ``printf("%x")``. [1]_ |
9898
+-------------------+---------------+--------------------------------+
99-
| :attr:`%s` | const char\* | A null-terminated C character |
99+
| ``%s`` | const char\* | A null-terminated C character |
100100
| | | array. |
101101
+-------------------+---------------+--------------------------------+
102-
| :attr:`%p` | const void\* | The hex representation of a C |
102+
| ``%p`` | const void\* | The hex representation of a C |
103103
| | | pointer. Mostly equivalent to |
104104
| | | ``printf("%p")`` except that |
105105
| | | it is guaranteed to start with |
@@ -187,8 +187,8 @@ called with a non-bytes parameter.
187187
.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
188188
189189
Create a new bytes object in *\*bytes* containing the contents of *newpart*
190-
appended to *bytes*. This version decrements the reference count of
191-
*newpart*.
190+
appended to *bytes*. This version releases the :term:`strong reference`
191+
to *newpart* (i.e. decrements its reference count).
192192
193193
194194
.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

0 commit comments

Comments
 (0)