Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 142cab9

Browse files
mattwang44mattwang44
committed
Deploying to gh-pages from @ 0c3a1c9 🚀
1 parent ca9fdd9 commit 142cab9

File tree

819 files changed

+43153
-37690
lines changed

Some content is hidden

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

819 files changed

+43153
-37690
lines changed

‎.buildinfo

Lines changed: 1 addition & 1 deletion
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: a106bc1aa0adf41da663be30441342a4
3+
config: 5f188cfea9b02bb2007eaf8ef703480f
44
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎_images/win_install_freethreaded.png

231 KB
Loading

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,3 @@ but whose items have not been set to some non-\ ``NULL`` value yet.
2424
mapping.rst
2525
iter.rst
2626
buffer.rst
27-
objbuffer.rst

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

Lines changed: 56 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,18 @@ unit; the entry in (round) parentheses is the Python object type that matches
2727
the format unit; and the entry in [square] brackets is the type of the C
2828
variable(s) whose address should be passed.
2929

30+
.. _arg-parsing-string-and-buffers:
31+
3032
Strings and buffers
3133
-------------------
3234

35+
.. note::
36+
37+
On Python 3.12 and older, the macro :c:macro:`!PY_SSIZE_T_CLEAN` must be
38+
defined before including :file:`Python.h` to use all ``#`` variants of
39+
formats (``s#``, ``y#``, etc.) explained below.
40+
This is not necessary on Python 3.13 and later.
41+
3342
These formats allow accessing an object as a contiguous chunk of memory.
3443
You don't have to provide raw storage for the returned unicode or bytes
3544
area.
@@ -68,15 +77,6 @@ There are three ways strings and buffers can be converted to C:
6877
whether the input object is immutable (e.g. whether it would honor a request
6978
for a writable buffer, or whether another thread can mutate the data).
7079

71-
.. note::
72-
73-
For all ``#`` variants of formats (``s#``, ``y#``, etc.), the macro
74-
:c:macro:`PY_SSIZE_T_CLEAN` must be defined before including
75-
:file:`Python.h`. On Python 3.9 and older, the type of the length argument
76-
is :c:type:`Py_ssize_t` if the :c:macro:`PY_SSIZE_T_CLEAN` macro is defined,
77-
or int otherwise.
78-
79-
8080
``s`` (:class:`str`) [const char \*]
8181
Convert a Unicode object to a C pointer to a character string.
8282
A pointer to an existing string is stored in the character pointer
@@ -413,21 +413,35 @@ API Functions
413413
than a variable number of arguments.
414414
415415
416-
.. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
416+
.. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char * const *keywords, ...)
417417
418418
Parse the parameters of a function that takes both positional and keyword
419-
parameters into local variables. The *keywords* argument is a
420-
``NULL``-terminated array of keyword parameter names. Empty names denote
419+
parameters into local variables.
420+
The *keywords* argument is a ``NULL``-terminated array of keyword parameter
421+
names specified as null-terminated ASCII or UTF-8 encoded C strings.
422+
Empty names denote
421423
:ref:`positional-only parameters <positional-only_parameter>`.
422424
Returns true on success; on failure, it returns false and raises the
423425
appropriate exception.
424426
427+
.. note::
428+
429+
The *keywords* parameter declaration is :c:expr:`char * const *` in C and
430+
:c:expr:`const char * const *` in C++.
431+
This can be overridden with the :c:macro:`PY_CXX_CONST` macro.
432+
425433
.. versionchanged:: 3.6
426434
Added support for :ref:`positional-only parameters
427435
<positional-only_parameter>`.
428436
437+
.. versionchanged:: 3.13
438+
The *keywords* parameter has now type :c:expr:`char * const *` in C and
439+
:c:expr:`const char * const *` in C++, instead of :c:expr:`char **`.
440+
Added support for non-ASCII keyword parameter names.
441+
429442
430-
.. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
443+
444+
.. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char * const *keywords, va_list vargs)
431445
432446
Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a
433447
va_list rather than a variable number of arguments.
@@ -442,16 +456,24 @@ API Functions
442456
.. versionadded:: 3.2
443457
444458
445-
.. XXX deprecated, will be removed
446459
.. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...)
447460
448-
Function used to deconstruct the argument lists of "old-style" functions ---
449-
these are functions which use the :const:`METH_OLDARGS` parameter parsing
450-
method, which has been removed in Python 3. This is not recommended for use
451-
in parameter parsing in new code, and most code in the standard interpreter
452-
has been modified to no longer use this for that purpose. It does remain a
453-
convenient way to decompose other tuples, however, and may continue to be
454-
used for that purpose.
461+
Parse the parameter of a function that takes a single positional parameter
462+
into a local variable. Returns true on success; on failure, it returns
463+
false and raises the appropriate exception.
464+
465+
Example::
466+
467+
// Function using METH_O calling convention
468+
static PyObject*
469+
my_function(PyObject *module, PyObject *arg)
470+
{
471+
int value;
472+
if (!PyArg_Parse(arg, "i:my_function", &value)) {
473+
return NULL;
474+
}
475+
// ... use value ...
476+
}
455477
456478
457479
.. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
@@ -492,6 +514,19 @@ API Functions
492514
493515
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
494516
517+
.. c:macro:: PY_CXX_CONST
518+
519+
The value to be inserted, if any, before :c:expr:`char * const *`
520+
in the *keywords* parameter declaration of
521+
:c:func:`PyArg_ParseTupleAndKeywords` and
522+
:c:func:`PyArg_VaParseTupleAndKeywords`.
523+
Default empty for C and ``const`` for C++
524+
(:c:expr:`const char * const *`).
525+
To override, define it to the desired value before including
526+
:file:`Python.h`.
527+
528+
.. versionadded:: 3.13
529+
495530
496531
---------------
497532
Building values

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,19 +26,19 @@ are available, however.
2626
.. c:var:: PyObject* Py_False
2727
2828
The Python ``False`` object. This object has no methods and is
29-
`immortal <https://peps.python.org/pep-0683/>`_.
29+
:term:`immortal`.
3030
31-
.. versionchanged:: 3.12
32-
:c:data:`Py_False` is immortal.
31+
.. versionchanged:: 3.12
32+
:c:data:`Py_False` is :term:`immortal`.
3333
3434
3535
.. c:var:: PyObject* Py_True
3636
3737
The Python ``True`` object. This object has no methods and is
38-
`immortal <https://peps.python.org/pep-0683/>`_.
38+
:term:`immortal`.
3939
40-
.. versionchanged:: 3.12
41-
:c:data:`Py_True` is immortal.
40+
.. versionchanged:: 3.12
41+
:c:data:`Py_True` is :term:`immortal`.
4242
4343
4444
.. c:macro:: Py_RETURN_FALSE

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -191,10 +191,10 @@ called with a non-bytes parameter.
191191
192192
.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
193193
194-
A way to resize a bytes object even though it is "immutable". Only use this
195-
to build up a brand new bytes object; don't use this if the bytes may already
196-
be known in other parts of the code. It is an error to call this function if
197-
the refcount on the input bytes object is not one. Pass the address of an
194+
Resize a bytes object. *newsize* will be the new length of the bytes object.
195+
You can think of it as creating a new bytes object and destroying the old
196+
one, only more efficiently.
197+
Pass the address of an
198198
existing bytes object as an lvalue (it may be written into), and the new size
199199
desired. On success, *\*bytes* holds the resized bytes object and ``0`` is
200200
returned; the address in *\*bytes* may differ from its input value. If the

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

Lines changed: 0 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -115,19 +115,6 @@ function as with any other callable.
115115
:c:func:`PyObject_Vectorcall` will usually be most efficient.
116116

117117

118-
.. note::
119-
120-
In CPython 3.8, the vectorcall API and related functions were available
121-
provisionally under names with a leading underscore:
122-
``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``,
123-
``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``,
124-
``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``,
125-
``_PyObject_CallMethodOneArg``.
126-
Additionally, ``PyObject_VectorcallDict`` was available as
127-
``_PyObject_FastCallDict``.
128-
The old names are still defined as aliases of the new, non-underscored names.
129-
130-
131118
Recursion Control
132119
.................
133120

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

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,16 @@ bound into a function.
3434
3535
Return the number of free variables in a code object.
3636
37-
.. c:function:: int PyCode_GetFirstFree(PyCodeObject *co)
37+
.. c:function:: int PyUnstable_Code_GetFirstFree(PyCodeObject *co)
3838
3939
Return the position of the first free variable in a code object.
4040
41+
.. versionchanged:: 3.13
42+
43+
Renamed from ``PyCode_GetFirstFree`` as part of :ref:`unstable-c-api`.
44+
The old name is deprecated, but will remain available until the
45+
signature changes again.
46+
4147
.. c:function:: PyCodeObject* PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
4248
4349
Return a new code object. If you need a dummy code object to create a frame,
@@ -90,8 +96,8 @@ bound into a function.
9096
Return the line number of the instruction that occurs on or before ``byte_offset`` and ends after it.
9197
If you just need the line number of a frame, use :c:func:`PyFrame_GetLineNumber` instead.
9298
93-
For efficiently iterating over the line numbers in a code object, use :pep:`the API described in PEP 626
94-
<0626#out-of-process-debuggers-and-profilers>`.
99+
For efficiently iterating over the line numbers in a code object, use `the API described in PEP 626
100+
<https://peps.python.org/pep-0626/#out-of-process-debuggers-and-profilers>`_.
95101
96102
.. c:function:: int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)
97103

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,14 +123,33 @@ Complex Numbers as Python Objects
123123
124124
Return the real part of *op* as a C :c:expr:`double`.
125125
126+
If *op* is not a Python complex number object but has a
127+
:meth:`~object.__complex__` method, this method will first be called to
128+
convert *op* to a Python complex number object. If :meth:`!__complex__` is
129+
not defined then it falls back to call :c:func:`PyFloat_AsDouble` and
130+
returns its result.
131+
126132
Upon failure, this method returns ``-1.0`` with an exception set, so one
127133
should call :c:func:`PyErr_Occurred` to check for errors.
128134
135+
.. versionchanged:: 3.13
136+
Use :meth:`~object.__complex__` if available.
129137
130138
.. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
131139
132140
Return the imaginary part of *op* as a C :c:expr:`double`.
133141
142+
If *op* is not a Python complex number object but has a
143+
:meth:`~object.__complex__` method, this method will first be called to
144+
convert *op* to a Python complex number object. If :meth:`!__complex__` is
145+
not defined then it falls back to call :c:func:`PyFloat_AsDouble` and
146+
returns ``0.0`` on success.
147+
148+
Upon failure, this method returns ``-1.0`` with an exception set, so one
149+
should call :c:func:`PyErr_Occurred` to check for errors.
150+
151+
.. versionchanged:: 3.13
152+
Use :meth:`~object.__complex__` if available.
134153
135154
.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
136155

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

Lines changed: 95 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,15 @@ Dictionary Objects
5555
This is equivalent to the Python expression ``key in p``.
5656
5757
58+
.. c:function:: int PyDict_ContainsString(PyObject *p, const char *key)
59+
60+
This is the same as :c:func:`PyDict_Contains`, but *key* is specified as a
61+
:c:expr:`const char*` UTF-8 encoded bytes string, rather than a
62+
:c:expr:`PyObject*`.
63+
64+
.. versionadded:: 3.13
65+
66+
5867
.. c:function:: PyObject* PyDict_Copy(PyObject *p)
5968
6069
Return a new dictionary that contains the same key-value pairs as *p*.
@@ -90,10 +99,26 @@ Dictionary Objects
9099
rather than a :c:expr:`PyObject*`.
91100
92101
102+
.. c:function:: int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)
103+
104+
Return a new :term:`strong reference` to the object from dictionary *p*
105+
which has a key *key*:
106+
107+
* If the key is present, set *\*result* to a new :term:`strong reference`
108+
to the value and return ``1``.
109+
* If the key is missing, set *\*result* to ``NULL`` and return ``0``.
110+
* On error, raise an exception and return ``-1``.
111+
112+
.. versionadded:: 3.13
113+
114+
See also the :c:func:`PyObject_GetItem` function.
115+
116+
93117
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
94118
95-
Return the object from dictionary *p* which has a key *key*. Return ``NULL``
96-
if the key *key* is not present, but *without* setting an exception.
119+
Return a :term:`borrowed reference` to the object from dictionary *p* which
120+
has a key *key*. Return ``NULL`` if the key *key* is missing *without*
121+
setting an exception.
97122
98123
.. note::
99124
@@ -129,6 +154,15 @@ Dictionary Objects
129154
:c:func:`PyUnicode_FromString` *key* instead.
130155
131156
157+
.. c:function:: int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)
158+
159+
Similar than :c:func:`PyDict_GetItemRef`, but *key* is specified as a
160+
:c:expr:`const char*` UTF-8 encoded bytes string, rather than a
161+
:c:expr:`PyObject*`.
162+
163+
.. versionadded:: 3.13
164+
165+
132166
.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
133167
134168
This is the same as the Python-level :meth:`dict.setdefault`. If present, it
@@ -139,6 +173,54 @@ Dictionary Objects
139173
140174
.. versionadded:: 3.4
141175
176+
177+
.. c:function:: int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)
178+
179+
Inserts *default_value* into the dictionary *p* with a key of *key* if the
180+
key is not already present in the dictionary. If *result* is not ``NULL``,
181+
then *\*result* is set to a :term:`strong reference` to either
182+
*default_value*, if the key was not present, or the existing value, if *key*
183+
was already present in the dictionary.
184+
Returns ``1`` if the key was present and *default_value* was not inserted,
185+
or ``0`` if the key was not present and *default_value* was inserted.
186+
On failure, returns ``-1``, sets an exception, and sets ``*result``
187+
to ``NULL``.
188+
189+
For clarity: if you have a strong reference to *default_value* before
190+
calling this function, then after it returns, you hold a strong reference
191+
to both *default_value* and *\*result* (if it's not ``NULL``).
192+
These may refer to the same object: in that case you hold two separate
193+
references to it.
194+
195+
.. versionadded:: 3.13
196+
197+
198+
.. c:function:: int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)
199+
200+
Remove *key* from dictionary *p* and optionally return the removed value.
201+
Do not raise :exc:`KeyError` if the key missing.
202+
203+
- If the key is present, set *\*result* to a new reference to the removed
204+
value if *result* is not ``NULL``, and return ``1``.
205+
- If the key is missing, set *\*result* to ``NULL`` if *result* is not
206+
``NULL``, and return ``0``.
207+
- On error, raise an exception and return ``-1``.
208+
209+
This is similar to :meth:`dict.pop`, but without the default value and
210+
not raising :exc:`KeyError` if the key missing.
211+
212+
.. versionadded:: 3.13
213+
214+
215+
.. c:function:: int PyDict_PopString(PyObject *p, const char *key, PyObject **result)
216+
217+
Similar to :c:func:`PyDict_Pop`, but *key* is specified as a
218+
:c:expr:`const char*` UTF-8 encoded bytes string, rather than a
219+
:c:expr:`PyObject*`.
220+
221+
.. versionadded:: 3.13
222+
223+
142224
.. c:function:: PyObject* PyDict_Items(PyObject *p)
143225
144226
Return a :c:type:`PyListObject` containing all the items from the dictionary.
@@ -208,6 +290,17 @@ Dictionary Objects
208290
Py_DECREF(o);
209291
}
210292
293+
The function is not thread-safe in the :term:`free-threaded <free threading>`
294+
build without external synchronization. You can use
295+
:c:macro:`Py_BEGIN_CRITICAL_SECTION` to lock the dictionary while iterating
296+
over it::
297+
298+
Py_BEGIN_CRITICAL_SECTION(self->dict);
299+
while (PyDict_Next(self->dict, &pos, &key, &value)) {
300+
...
301+
}
302+
Py_END_CRITICAL_SECTION();
303+
211304
212305
.. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
213306

0 commit comments

Comments
 (0)