Skip to content

Commit 0c500d3

Browse files
mattwang44mattwang44
committed
Deploying to gh-pages from @ 879b6b9 🚀
1 parent 61e0de0 commit 0c500d3

File tree

591 files changed

+9480
-7510
lines changed

Some content is hidden

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

591 files changed

+9480
-7510
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: bf1bf3e386dfa60dfb8561ec2bda0210
3+
config: eb6bdc9d353f28c7f5127594d7e4c00d
44
tags: 645f666f9bcd5a90fca523b33c5a78b7

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,8 +96,8 @@ bound into a function.
9696
Return the line number of the instruction that occurs on or before ``byte_offset`` and ends after it.
9797
If you just need the line number of a frame, use :c:func:`PyFrame_GetLineNumber` instead.
9898
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>`_.
99+
For efficiently iterating over the line numbers in a code object, use :pep:`the API described in PEP 626
100+
<0626#out-of-process-debuggers-and-profilers>`.
101101
102102
.. c:function:: int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)
103103

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1004,6 +1004,7 @@ the variables:
10041004
single: PyExc_OverflowError (C var)
10051005
single: PyExc_PermissionError (C var)
10061006
single: PyExc_ProcessLookupError (C var)
1007+
single: PyExc_PythonFinalizationError (C var)
10071008
single: PyExc_RecursionError (C var)
10081009
single: PyExc_ReferenceError (C var)
10091010
single: PyExc_RuntimeError (C var)
@@ -1096,6 +1097,8 @@ the variables:
10961097
+-----------------------------------------+---------------------------------+----------+
10971098
| :c:data:`PyExc_ProcessLookupError` | :exc:`ProcessLookupError` | |
10981099
+-----------------------------------------+---------------------------------+----------+
1100+
| :c:data:`PyExc_PythonFinalizationError` | :exc:`PythonFinalizationError` | |
1101+
+-----------------------------------------+---------------------------------+----------+
10991102
| :c:data:`PyExc_RecursionError` | :exc:`RecursionError` | |
11001103
+-----------------------------------------+---------------------------------+----------+
11011104
| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | |

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -452,6 +452,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
452452
Currently, ``-1`` corresponds to
453453
``Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER``.
454454
455+
.. c:namespace:: NULL
456+
455457
============================================= ======
456458
Flag Value
457459
============================================= ======

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

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -102,30 +102,38 @@ All allocating functions belong to one of three different "domains" (see also
102102
strategies and are optimized for different purposes. The specific details on
103103
how every domain allocates memory or what internal functions each domain calls
104104
is considered an implementation detail, but for debugging purposes a simplified
105-
table can be found at :ref:`here <default-memory-allocators>`. There is no hard
106-
requirement to use the memory returned by the allocation functions belonging to
107-
a given domain for only the purposes hinted by that domain (although this is the
108-
recommended practice). For example, one could use the memory returned by
109-
:c:func:`PyMem_RawMalloc` for allocating Python objects or the memory returned
110-
by :c:func:`PyObject_Malloc` for allocating memory for buffers.
105+
table can be found at :ref:`here <default-memory-allocators>`.
106+
The APIs used to allocate and free a block of memory must be from the same domain.
107+
For example, :c:func:`PyMem_Free` must be used to free memory allocated using :c:func:`PyMem_Malloc`.
111108

112109
The three allocation domains are:
113110

114111
* Raw domain: intended for allocating memory for general-purpose memory
115112
buffers where the allocation *must* go to the system allocator or where the
116113
allocator can operate without the :term:`GIL`. The memory is requested directly
117-
to the system.
114+
from the system. See :ref:`Raw Memory Interface <raw-memoryinterface>`.
118115

119116
* "Mem" domain: intended for allocating memory for Python buffers and
120117
general-purpose memory buffers where the allocation must be performed with
121118
the :term:`GIL` held. The memory is taken from the Python private heap.
119+
See :ref:`Memory Interface <memoryinterface>`.
122120

123-
* Object domain: intended for allocating memory belonging to Python objects. The
124-
memory is taken from the Python private heap.
121+
* Object domain: intended for allocating memory for Python objects. The
122+
memory is taken from the Python private heap. See :ref:`Object allocators <objectinterface>`.
125123

126-
When freeing memory previously allocated by the allocating functions belonging to a
127-
given domain,the matching specific deallocating functions must be used. For example,
128-
:c:func:`PyMem_Free` must be used to free memory allocated using :c:func:`PyMem_Malloc`.
124+
.. note::
125+
126+
The :term:`free-threaded <free threading>` build requires that only Python objects are allocated using the "object" domain
127+
and that all Python objects are allocated using that domain. This differs from the prior Python versions,
128+
where this was only a best practice and not a hard requirement.
129+
130+
For example, buffers (non-Python objects) should be allocated using :c:func:`PyMem_Malloc`,
131+
:c:func:`PyMem_RawMalloc`, or :c:func:`malloc`, but not :c:func:`PyObject_Malloc`.
132+
133+
See :ref:`Memory Allocation APIs <free-threaded-memory-allocation>`.
134+
135+
136+
.. _raw-memoryinterface:
129137

130138
Raw Memory Interface
131139
====================
@@ -299,6 +307,8 @@ versions and is therefore deprecated in extension modules.
299307
* ``PyMem_DEL(ptr)``
300308
301309
310+
.. _objectinterface:
311+
302312
Object allocators
303313
=================
304314

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -421,6 +421,8 @@ The available slot types are:
421421
422422
Specifies one of the following values:
423423
424+
.. c:namespace:: NULL
425+
424426
.. c:macro:: Py_MOD_GIL_USED
425427
426428
The module depends on the presence of the global interpreter lock (GIL),

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

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. highlight:: c
22

3-
.. _monitoring:
3+
.. _c-api-monitoring:
44

55
Monitoring C API
66
================
@@ -133,32 +133,60 @@ Managing the Monitoring State
133133
Monitoring states can be managed with the help of monitoring scopes. A scope
134134
would typically correspond to a python function.
135135
136-
.. :c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
136+
.. c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
137137
138138
Enter a monitored scope. ``event_types`` is an array of the event IDs for
139139
events that may be fired from the scope. For example, the ID of a ``PY_START``
140140
event is the value ``PY_MONITORING_EVENT_PY_START``, which is numerically equal
141141
to the base-2 logarithm of ``sys.monitoring.events.PY_START``.
142142
``state_array`` is an array with a monitoring state entry for each event in
143143
``event_types``, it is allocated by the user but populated by
144-
``PyMonitoring_EnterScope`` with information about the activation state of
144+
:c:func:`!PyMonitoring_EnterScope` with information about the activation state of
145145
the event. The size of ``event_types`` (and hence also of ``state_array``)
146146
is given in ``length``.
147147
148148
The ``version`` argument is a pointer to a value which should be allocated
149149
by the user together with ``state_array`` and initialized to 0,
150-
and then set only by ``PyMonitoring_EnterScope`` itelf. It allows this
150+
and then set only by :c:func:`!PyMonitoring_EnterScope` itelf. It allows this
151151
function to determine whether event states have changed since the previous call,
152152
and to return quickly if they have not.
153153
154154
The scopes referred to here are lexical scopes: a function, class or method.
155-
``PyMonitoring_EnterScope`` should be called whenever the lexical scope is
155+
:c:func:`!PyMonitoring_EnterScope` should be called whenever the lexical scope is
156156
entered. Scopes can be reentered, reusing the same *state_array* and *version*,
157157
in situations like when emulating a recursive Python function. When a code-like's
158158
execution is paused, such as when emulating a generator, the scope needs to
159159
be exited and re-entered.
160160
161-
162-
.. :c:function:: int PyMonitoring_ExitScope(void)
163-
164-
Exit the last scope that was entered with ``PyMonitoring_EnterScope``.
161+
The macros for *event_types* are:
162+
163+
.. c:namespace:: NULL
164+
165+
.. The table is here to make the docs searchable, and to allow automatic
166+
links to the identifiers.
167+
168+
================================================== =====================================
169+
Macro Event
170+
================================================== =====================================
171+
.. c:macro:: PY_MONITORING_EVENT_BRANCH :monitoring-event:`BRANCH`
172+
.. c:macro:: PY_MONITORING_EVENT_CALL :monitoring-event:`CALL`
173+
.. c:macro:: PY_MONITORING_EVENT_C_RAISE :monitoring-event:`C_RAISE`
174+
.. c:macro:: PY_MONITORING_EVENT_C_RETURN :monitoring-event:`C_RETURN`
175+
.. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED :monitoring-event:`EXCEPTION_HANDLED`
176+
.. c:macro:: PY_MONITORING_EVENT_INSTRUCTION :monitoring-event:`INSTRUCTION`
177+
.. c:macro:: PY_MONITORING_EVENT_JUMP :monitoring-event:`JUMP`
178+
.. c:macro:: PY_MONITORING_EVENT_LINE :monitoring-event:`LINE`
179+
.. c:macro:: PY_MONITORING_EVENT_PY_RESUME :monitoring-event:`PY_RESUME`
180+
.. c:macro:: PY_MONITORING_EVENT_PY_RETURN :monitoring-event:`PY_RETURN`
181+
.. c:macro:: PY_MONITORING_EVENT_PY_START :monitoring-event:`PY_START`
182+
.. c:macro:: PY_MONITORING_EVENT_PY_THROW :monitoring-event:`PY_THROW`
183+
.. c:macro:: PY_MONITORING_EVENT_PY_UNWIND :monitoring-event:`PY_UNWIND`
184+
.. c:macro:: PY_MONITORING_EVENT_PY_YIELD :monitoring-event:`PY_YIELD`
185+
.. c:macro:: PY_MONITORING_EVENT_RAISE :monitoring-event:`RAISE`
186+
.. c:macro:: PY_MONITORING_EVENT_RERAISE :monitoring-event:`RERAISE`
187+
.. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION :monitoring-event:`STOP_ITERATION`
188+
================================================== =====================================
189+
190+
.. c:function:: int PyMonitoring_ExitScope(void)
191+
192+
Exit the last scope that was entered with :c:func:`!PyMonitoring_EnterScope`.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ of Python objects.
6262
``NULL``, use :c:func:`Py_XINCREF`.
6363
6464
Do not expect this function to actually modify *o* in any way.
65-
For at least `some objects <https://peps.python.org/pep-0683/>`_,
65+
For at least :pep:`some objects <0683>`,
6666
this function has no effect.
6767
6868
.. versionchanged:: 3.12
@@ -130,7 +130,7 @@ of Python objects.
130130
use :c:func:`Py_XDECREF`.
131131
132132
Do not expect this function to actually modify *o* in any way.
133-
For at least `some objects <https://peps.python.org/pep-0683/>`_,
133+
For at least :pep:`some objects <683>`,
134134
this function has no effect.
135135
136136
.. warning::

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
.. highlight:: c
22

3+
.. _c-api-time:
4+
35
PyTime C API
46
============
57

‎_sources/deprecations/c-api-pending-removal-in-3.14.rst.txt

Lines changed: 51 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -9,38 +9,64 @@ Pending Removal in Python 3.14
99

1010
* Functions to configure Python's initialization, deprecated in Python 3.11:
1111

12-
* ``PySys_SetArgvEx()``: set :c:member:`PyConfig.argv` instead.
13-
* ``PySys_SetArgv()``: set :c:member:`PyConfig.argv` instead.
14-
* ``Py_SetProgramName()``: set :c:member:`PyConfig.program_name` instead.
15-
* ``Py_SetPythonHome()``: set :c:member:`PyConfig.home` instead.
12+
* :c:func:`!PySys_SetArgvEx()`:
13+
Set :c:member:`PyConfig.argv` instead.
14+
* :c:func:`!PySys_SetArgv()`:
15+
Set :c:member:`PyConfig.argv` instead.
16+
* :c:func:`!Py_SetProgramName()`:
17+
Set :c:member:`PyConfig.program_name` instead.
18+
* :c:func:`!Py_SetPythonHome()`:
19+
Set :c:member:`PyConfig.home` instead.
1620

1721
The :c:func:`Py_InitializeFromConfig` API should be used with
1822
:c:type:`PyConfig` instead.
1923

2024
* Global configuration variables:
2125

22-
* :c:var:`Py_DebugFlag`: use :c:member:`PyConfig.parser_debug` instead.
23-
* :c:var:`Py_VerboseFlag`: use :c:member:`PyConfig.verbose` instead.
24-
* :c:var:`Py_QuietFlag`: use :c:member:`PyConfig.quiet` instead.
25-
* :c:var:`Py_InteractiveFlag`: use :c:member:`PyConfig.interactive` instead.
26-
* :c:var:`Py_InspectFlag`: use :c:member:`PyConfig.inspect` instead.
27-
* :c:var:`Py_OptimizeFlag`: use :c:member:`PyConfig.optimization_level` instead.
28-
* :c:var:`Py_NoSiteFlag`: use :c:member:`PyConfig.site_import` instead.
29-
* :c:var:`Py_BytesWarningFlag`: use :c:member:`PyConfig.bytes_warning` instead.
30-
* :c:var:`Py_FrozenFlag`: use :c:member:`PyConfig.pathconfig_warnings` instead.
31-
* :c:var:`Py_IgnoreEnvironmentFlag`: use :c:member:`PyConfig.use_environment` instead.
32-
* :c:var:`Py_DontWriteBytecodeFlag`: use :c:member:`PyConfig.write_bytecode` instead.
33-
* :c:var:`Py_NoUserSiteDirectory`: use :c:member:`PyConfig.user_site_directory` instead.
34-
* :c:var:`Py_UnbufferedStdioFlag`: use :c:member:`PyConfig.buffered_stdio` instead.
35-
* :c:var:`Py_HashRandomizationFlag`: use :c:member:`PyConfig.use_hash_seed`
26+
* :c:var:`Py_DebugFlag`:
27+
Use :c:member:`PyConfig.parser_debug` instead.
28+
* :c:var:`Py_VerboseFlag`:
29+
Use :c:member:`PyConfig.verbose` instead.
30+
* :c:var:`Py_QuietFlag`:
31+
Use :c:member:`PyConfig.quiet` instead.
32+
* :c:var:`Py_InteractiveFlag`:
33+
Use :c:member:`PyConfig.interactive` instead.
34+
* :c:var:`Py_InspectFlag`:
35+
Use :c:member:`PyConfig.inspect` instead.
36+
* :c:var:`Py_OptimizeFlag`:
37+
Use :c:member:`PyConfig.optimization_level` instead.
38+
* :c:var:`Py_NoSiteFlag`:
39+
Use :c:member:`PyConfig.site_import` instead.
40+
* :c:var:`Py_BytesWarningFlag`:
41+
Use :c:member:`PyConfig.bytes_warning` instead.
42+
* :c:var:`Py_FrozenFlag`:
43+
Use :c:member:`PyConfig.pathconfig_warnings` instead.
44+
* :c:var:`Py_IgnoreEnvironmentFlag`:
45+
Use :c:member:`PyConfig.use_environment` instead.
46+
* :c:var:`Py_DontWriteBytecodeFlag`:
47+
Use :c:member:`PyConfig.write_bytecode` instead.
48+
* :c:var:`Py_NoUserSiteDirectory`:
49+
Use :c:member:`PyConfig.user_site_directory` instead.
50+
* :c:var:`Py_UnbufferedStdioFlag`:
51+
Use :c:member:`PyConfig.buffered_stdio` instead.
52+
* :c:var:`Py_HashRandomizationFlag`:
53+
Use :c:member:`PyConfig.use_hash_seed`
3654
and :c:member:`PyConfig.hash_seed` instead.
37-
* :c:var:`Py_IsolatedFlag`: use :c:member:`PyConfig.isolated` instead.
38-
* :c:var:`Py_LegacyWindowsFSEncodingFlag`: use :c:member:`PyPreConfig.legacy_windows_fs_encoding` instead.
39-
* :c:var:`Py_LegacyWindowsStdioFlag`: use :c:member:`PyConfig.legacy_windows_stdio` instead.
40-
* :c:var:`!Py_FileSystemDefaultEncoding`: use :c:member:`PyConfig.filesystem_encoding` instead.
41-
* :c:var:`!Py_HasFileSystemDefaultEncoding`: use :c:member:`PyConfig.filesystem_encoding` instead.
42-
* :c:var:`!Py_FileSystemDefaultEncodeErrors`: use :c:member:`PyConfig.filesystem_errors` instead.
43-
* :c:var:`!Py_UTF8Mode`: use :c:member:`PyPreConfig.utf8_mode` instead. (see :c:func:`Py_PreInitialize`)
55+
* :c:var:`Py_IsolatedFlag`:
56+
Use :c:member:`PyConfig.isolated` instead.
57+
* :c:var:`Py_LegacyWindowsFSEncodingFlag`:
58+
Use :c:member:`PyPreConfig.legacy_windows_fs_encoding` instead.
59+
* :c:var:`Py_LegacyWindowsStdioFlag`:
60+
Use :c:member:`PyConfig.legacy_windows_stdio` instead.
61+
* :c:var:`!Py_FileSystemDefaultEncoding`:
62+
Use :c:member:`PyConfig.filesystem_encoding` instead.
63+
* :c:var:`!Py_HasFileSystemDefaultEncoding`:
64+
Use :c:member:`PyConfig.filesystem_encoding` instead.
65+
* :c:var:`!Py_FileSystemDefaultEncodeErrors`:
66+
Use :c:member:`PyConfig.filesystem_errors` instead.
67+
* :c:var:`!Py_UTF8Mode`:
68+
Use :c:member:`PyPreConfig.utf8_mode` instead.
69+
(see :c:func:`Py_PreInitialize`)
4470

4571
The :c:func:`Py_InitializeFromConfig` API should be used with
4672
:c:type:`PyConfig` instead.

‎_sources/deprecations/c-api-pending-removal-in-3.15.rst.txt

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,26 @@ Pending Removal in Python 3.15
22
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
33

44
* The bundled copy of ``libmpdecimal``.
5-
* :c:func:`PyImport_ImportModuleNoBlock`: use :c:func:`PyImport_ImportModule` instead.
6-
* :c:func:`PyWeakref_GET_OBJECT`: use :c:func:`PyWeakref_GetRef` instead.
7-
* :c:func:`PyWeakref_GetObject`: use :c:func:`PyWeakref_GetRef` instead.
8-
* :c:type:`!Py_UNICODE_WIDE` type: use :c:type:`wchar_t` instead.
9-
* :c:type:`Py_UNICODE` type: use :c:type:`wchar_t` instead.
5+
* The :c:func:`PyImport_ImportModuleNoBlock`:
6+
Use :c:func:`PyImport_ImportModule` instead.
7+
* :c:func:`PyWeakref_GetObject` and :c:func:`PyWeakref_GET_OBJECT`:
8+
Use :c:func:`PyWeakref_GetRef` instead.
9+
* :c:type:`Py_UNICODE` type and the :c:macro:`!Py_UNICODE_WIDE` macro:
10+
Use :c:type:`wchar_t` instead.
1011
* Python initialization functions:
1112

12-
* :c:func:`PySys_ResetWarnOptions`: clear :data:`sys.warnoptions` and
13-
:data:`!warnings.filters` instead.
14-
* :c:func:`Py_GetExecPrefix`: get :data:`sys.exec_prefix` instead.
15-
* :c:func:`Py_GetPath`: get :data:`sys.path` instead.
16-
* :c:func:`Py_GetPrefix`: get :data:`sys.prefix` instead.
17-
* :c:func:`Py_GetProgramFullPath`: get :data:`sys.executable` instead.
18-
* :c:func:`Py_GetProgramName`: get :data:`sys.executable` instead.
19-
* :c:func:`Py_GetPythonHome`: get :c:member:`PyConfig.home` or
20-
the :envvar:`PYTHONHOME` environment variable instead.
13+
* :c:func:`PySys_ResetWarnOptions`:
14+
Clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead.
15+
* :c:func:`Py_GetExecPrefix`:
16+
Get :data:`sys.exec_prefix` instead.
17+
* :c:func:`Py_GetPath`:
18+
Get :data:`sys.path` instead.
19+
* :c:func:`Py_GetPrefix`:
20+
Get :data:`sys.prefix` instead.
21+
* :c:func:`Py_GetProgramFullPath`:
22+
Get :data:`sys.executable` instead.
23+
* :c:func:`Py_GetProgramName`:
24+
Get :data:`sys.executable` instead.
25+
* :c:func:`Py_GetPythonHome`:
26+
Get :c:member:`PyConfig.home`
27+
or the :envvar:`PYTHONHOME` environment variable instead.

0 commit comments

Comments
 (0)