Skip to content

Commit 37f67c4

Browse files
mattwang44mattwang44
committed
Deploying to gh-pages from @ 64f8366 🚀
1 parent c9868d7 commit 37f67c4

File tree

604 files changed

+10432
-9680
lines changed

Some content is hidden

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

604 files changed

+10432
-9680
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 records the configuration used when building these files. When it is not found, a full rebuild will be done.
3-
config: f9142bea56443272670326d4d54066fd
3+
config: c9ddeb59dab60e7bd89cb228c5129b61
44
tags: 645f666f9bcd5a90fca523b33c5a78b7

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,6 @@ Allocating Objects on the Heap
7676
7777
.. seealso::
7878
79-
:c:func:`PyModule_Create`
79+
:ref:`moduleobjects`
8080
To allocate and create extension modules.
8181

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -749,6 +749,16 @@ Exception Classes
749749
.. versionadded:: 3.2
750750
751751
752+
.. c:function:: int PyExceptionClass_Check(PyObject *ob)
753+
754+
Return non-zero if *ob* is an exception class, zero otherwise. This function always succeeds.
755+
756+
757+
.. c:function:: const char *PyExceptionClass_Name(PyObject *ob)
758+
759+
Return :c:member:`~PyTypeObject.tp_name` of the exception class *ob*.
760+
761+
752762
Exception Objects
753763
=================
754764
@@ -970,6 +980,7 @@ the variables:
970980
971981
.. index::
972982
single: PyExc_BaseException (C var)
983+
single: PyExc_BaseExceptionGroup (C var)
973984
single: PyExc_Exception (C var)
974985
single: PyExc_ArithmeticError (C var)
975986
single: PyExc_AssertionError (C var)
@@ -1029,6 +1040,8 @@ the variables:
10291040
+=========================================+=================================+==========+
10301041
| :c:data:`PyExc_BaseException` | :exc:`BaseException` | [1]_ |
10311042
+-----------------------------------------+---------------------------------+----------+
1043+
| :c:data:`PyExc_BaseExceptionGroup` | :exc:`BaseExceptionGroup` | [1]_ |
1044+
+-----------------------------------------+---------------------------------+----------+
10321045
| :c:data:`PyExc_Exception` | :exc:`Exception` | [1]_ |
10331046
+-----------------------------------------+---------------------------------+----------+
10341047
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | [1]_ |
@@ -1152,6 +1165,9 @@ the variables:
11521165
.. versionadded:: 3.6
11531166
:c:data:`PyExc_ModuleNotFoundError`.
11541167
1168+
.. versionadded:: 3.11
1169+
:c:data:`PyExc_BaseExceptionGroup`.
1170+
11551171
These are compatibility aliases to :c:data:`PyExc_OSError`:
11561172
11571173
.. index::
@@ -1195,6 +1211,7 @@ the variables:
11951211
single: PyExc_Warning (C var)
11961212
single: PyExc_BytesWarning (C var)
11971213
single: PyExc_DeprecationWarning (C var)
1214+
single: PyExc_EncodingWarning (C var)
11981215
single: PyExc_FutureWarning (C var)
11991216
single: PyExc_ImportWarning (C var)
12001217
single: PyExc_PendingDeprecationWarning (C var)
@@ -1213,6 +1230,8 @@ the variables:
12131230
+------------------------------------------+---------------------------------+----------+
12141231
| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | |
12151232
+------------------------------------------+---------------------------------+----------+
1233+
| :c:data:`PyExc_EncodingWarning` | :exc:`EncodingWarning` | |
1234+
+------------------------------------------+---------------------------------+----------+
12161235
| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | |
12171236
+------------------------------------------+---------------------------------+----------+
12181237
| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | |
@@ -1233,6 +1252,9 @@ the variables:
12331252
.. versionadded:: 3.2
12341253
:c:data:`PyExc_ResourceWarning`.
12351254
1255+
.. versionadded:: 3.10
1256+
:c:data:`PyExc_EncodingWarning`.
1257+
12361258
Notes:
12371259
12381260
.. [3]

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

Lines changed: 8 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -488,17 +488,8 @@ Initializing and finalizing the interpreter
488488
strings other than those passed in (however, the contents of the strings
489489
pointed to by the argument list are not modified).
490490
491-
The return value will be ``0`` if the interpreter exits normally (i.e.,
492-
without an exception), ``1`` if the interpreter exits due to an exception,
493-
or ``2`` if the argument list does not represent a valid Python command
494-
line.
495-
496-
Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
497-
function will not return ``1``, but exit the process, as long as
498-
``Py_InspectFlag`` is not set. If ``Py_InspectFlag`` is set, execution will
499-
drop into the interactive Python prompt, at which point a second otherwise
500-
unhandled :exc:`SystemExit` will still exit the process, while any other
501-
means of exiting will set the return value as described above.
491+
The return value is ``2`` if the argument list does not represent a valid
492+
Python command line, and otherwise the same as :c:func:`Py_RunMain`.
502493
503494
In terms of the CPython runtime configuration APIs documented in the
504495
:ref:`runtime configuration <init-config>` section (and without accounting
@@ -535,23 +526,18 @@ Initializing and finalizing the interpreter
535526
536527
If :c:member:`PyConfig.inspect` is not set (the default), the return value
537528
will be ``0`` if the interpreter exits normally (that is, without raising
538-
an exception), or ``1`` if the interpreter exits due to an exception. If an
539-
otherwise unhandled :exc:`SystemExit` is raised, the function will immediately
540-
exit the process instead of returning ``1``.
529+
an exception), the exit status of an unhandled :exc:`SystemExit`, or ``1``
530+
for any other unhandled exception.
541531
542532
If :c:member:`PyConfig.inspect` is set (such as when the :option:`-i` option
543533
is used), rather than returning when the interpreter exits, execution will
544534
instead resume in an interactive Python prompt (REPL) using the ``__main__``
545535
module's global namespace. If the interpreter exited with an exception, it
546536
is immediately raised in the REPL session. The function return value is
547-
then determined by the way the *REPL session* terminates: returning ``0``
548-
if the session terminates without raising an unhandled exception, exiting
549-
immediately for an unhandled :exc:`SystemExit`, and returning ``1`` for
550-
any other unhandled exception.
551-
552-
This function always finalizes the Python interpreter regardless of whether
553-
it returns a value or immediately exits the process due to an unhandled
554-
:exc:`SystemExit` exception.
537+
then determined by the way the *REPL session* terminates: ``0``, ``1``, or
538+
the status of a :exc:`SystemExit`, as specified above.
539+
540+
This function always finalizes the Python interpreter before it returns.
555541
556542
See :ref:`Python Configuration <init-python-config>` for an example of a
557543
customized Python that always runs in isolated mode using

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

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,15 +117,15 @@ complete listing.
117117
item defined in the module file. Example::
118118

119119
static struct PyModuleDef spam_module = {
120-
PyModuleDef_HEAD_INIT,
120+
.m_base = PyModuleDef_HEAD_INIT,
121121
.m_name = "spam",
122122
...
123123
};
124124

125125
PyMODINIT_FUNC
126126
PyInit_spam(void)
127127
{
128-
return PyModule_Create(&spam_module);
128+
return PyModuleDef_Init(&spam_module);
129129
}
130130

131131

@@ -834,3 +834,41 @@ after every statement run by the interpreter.)
834834

835835
Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution
836836
for more detailed information.
837+
838+
839+
.. _c-api-tools:
840+
841+
Recommended third party tools
842+
=============================
843+
844+
The following third party tools offer both simpler and more sophisticated
845+
approaches to creating C, C++ and Rust extensions for Python:
846+
847+
* `Cython <https://cython.org/>`_
848+
* `cffi <https://cffi.readthedocs.io>`_
849+
* `HPy <https://hpyproject.org/>`_
850+
* `nanobind <https://github.com/wjakob/nanobind>`_ (C++)
851+
* `Numba <https://numba.pydata.org/>`_
852+
* `pybind11 <https://pybind11.readthedocs.io/>`_ (C++)
853+
* `PyO3 <https://pyo3.rs/>`_ (Rust)
854+
* `SWIG <https://www.swig.org>`_
855+
856+
Using tools such as these can help avoid writing code that is tightly bound to
857+
a particular version of CPython, avoid reference counting errors, and focus
858+
more on your own code than on using the CPython API. In general, new versions
859+
of Python can be supported by updating the tool, and your code will often use
860+
newer and more efficient APIs automatically. Some tools also support compiling
861+
for other implementations of Python from a single set of sources.
862+
863+
These projects are not supported by the same people who maintain Python, and
864+
issues need to be raised with the projects directly. Remember to check that the
865+
project is still maintained and supported, as the list above may become
866+
outdated.
867+
868+
.. seealso::
869+
870+
`Python Packaging User Guide: Binary Extensions <https://packaging.python.org/guides/packaging-binary-extensions/>`_
871+
The Python Packaging User Guide not only covers several available
872+
tools that simplify the creation of binary extensions, but also
873+
discusses the various reasons why creating an extension module may be
874+
desirable in the first place.

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

Lines changed: 30 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -288,22 +288,40 @@ An alternate way to specify extensions is to request "multi-phase initialization
288288
Extension modules created this way behave more like Python modules: the
289289
initialization is split between the *creation phase*, when the module object
290290
is created, and the *execution phase*, when it is populated.
291-
The distinction is similar to the :py:meth:`!__new__` and :py:meth:`!__init__` methods
292-
of classes.
291+
The distinction is similar to the :py:meth:`~object.__new__` and
292+
:py:meth:`~object.__init__` methods of classes.
293293
294294
Unlike modules created using single-phase initialization, these modules are not
295-
singletons: if the *sys.modules* entry is removed and the module is re-imported,
296-
a new module object is created, and the old module is subject to normal garbage
297-
collection -- as with Python modules.
298-
By default, multiple modules created from the same definition should be
299-
independent: changes to one should not affect the others.
300-
This means that all state should be specific to the module object (using e.g.
301-
using :c:func:`PyModule_GetState`), or its contents (such as the module's
302-
:attr:`~object.__dict__` or individual classes created with :c:func:`PyType_FromSpec`).
295+
singletons.
296+
For example, if the :py:attr:`sys.modules` entry is removed and the module
297+
is re-imported, a new module object is created, and typically populated with
298+
fresh method and type objects.
299+
The old module is subject to normal garbage collection.
300+
This mirrors the behavior of pure-Python modules.
301+
302+
Additional module instances may be created in
303+
:ref:`sub-interpreters <sub-interpreter-support>`
304+
or after after Python runtime reinitialization
305+
(:c:func:`Py_Finalize` and :c:func:`Py_Initialize`).
306+
In these cases, sharing Python objects between module instances would likely
307+
cause crashes or undefined behavior.
308+
309+
To avoid such issues, each instance of an extension module should
310+
be *isolated*: changes to one instance should not implicitly affect the others,
311+
and all state, including references to Python objects, should be specific to
312+
a particular module instance.
313+
See :ref:`isolating-extensions-howto` for more details and a practical guide.
314+
315+
A simpler way to avoid these issues is
316+
:ref:`raising an error on repeated initialization <isolating-extensions-optout>`.
303317
304318
All modules created using multi-phase initialization are expected to support
305-
:ref:`sub-interpreters <sub-interpreter-support>`. Making sure multiple modules
306-
are independent is typically enough to achieve this.
319+
:ref:`sub-interpreters <sub-interpreter-support>`, or otherwise explicitly
320+
signal a lack of support.
321+
This is usually achieved by isolation or blocking repeated initialization,
322+
as above.
323+
A module may also be limited to the main interpreter using
324+
the :c:data:`Py_mod_multiple_interpreters` slot.
307325
308326
To request multi-phase initialization, the initialization function
309327
(PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ of Python objects.
201201
202202
Py_SETREF(dst, src);
203203
204-
That arranges to set *dst* to *src* _before_ releasing the reference
204+
That arranges to set *dst* to *src* *before* releasing the reference
205205
to the old value of *dst*, so that any code triggered as a side-effect
206206
of *dst* getting torn down no longer believes *dst* points
207207
to a valid object.

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,10 @@ Type Objects
267267
and other places where a method's defining class cannot be passed using the
268268
:c:type:`PyCMethod` calling convention.
269269
270+
The returned reference is :term:`borrowed <borrowed reference>` from *type*,
271+
and will be valid as long as you hold a reference to *type*.
272+
Do not release it with :c:func:`Py_DECREF` or similar.
273+
270274
.. versionadded:: 3.11
271275
272276
.. c:function:: int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)

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

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1403,10 +1403,6 @@ the user settings on the machine running the codec.
14031403
.. versionadded:: 3.3
14041404
14051405
1406-
Methods & Slots
1407-
"""""""""""""""
1408-
1409-
14101406
.. _unicodemethodsandslots:
14111407
14121408
Methods and Slot Functions
@@ -1643,8 +1639,4 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
16431639
from user input, prefer calling :c:func:`PyUnicode_FromString` and
16441640
:c:func:`PyUnicode_InternInPlace` directly.
16451641
1646-
.. impl-detail::
1647-
1648-
Strings interned this way are made :term:`immortal`.
1649-
16501642

‎_sources/extending/building.rst.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,10 @@ instance. See :ref:`initializing-modules` for details.
2323
.. highlight:: python
2424
2525
For modules with ASCII-only names, the function must be named
26-
``PyInit_<modulename>``, with ``<modulename>`` replaced by the name of the
27-
module. When using :ref:`multi-phase-initialization`, non-ASCII module names
26+
:samp:`PyInit_{<name>}`, with ``<name>`` replaced by the name of the module.
27+
When using :ref:`multi-phase-initialization`, non-ASCII module names
2828
are allowed. In this case, the initialization function name is
29-
``PyInitU_<modulename>``, with ``<modulename>`` encoded using Python's
29+
:samp:`PyInitU_{<name>}`, with ``<name>`` encoded using Python's
3030
*punycode* encoding with hyphens replaced by underscores. In Python::
3131

3232
def initfunc_name(name):

‎_sources/extending/embedding.rst.txt

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -245,21 +245,23 @@ Python extension. For example::
245245
return PyLong_FromLong(numargs);
246246
}
247247

248-
static PyMethodDef EmbMethods[] = {
248+
static PyMethodDef emb_module_methods[] = {
249249
{"numargs", emb_numargs, METH_VARARGS,
250250
"Return the number of arguments received by the process."},
251251
{NULL, NULL, 0, NULL}
252252
};
253253

254-
static PyModuleDef EmbModule = {
255-
PyModuleDef_HEAD_INIT, "emb", NULL, -1, EmbMethods,
256-
NULL, NULL, NULL, NULL
254+
static struct PyModuleDef emb_module = {
255+
.m_base = PyModuleDef_HEAD_INIT,
256+
.m_name = "emb",
257+
.m_size = 0,
258+
.m_methods = emb_module_methods,
257259
};
258260

259261
static PyObject*
260262
PyInit_emb(void)
261263
{
262-
return PyModule_Create(&EmbModule);
264+
return PyModuleDef_Init(&emb_module);
263265
}
264266

265267
Insert the above code just above the :c:func:`main` function. Also, insert the

0 commit comments

Comments
 (0)