aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/Doc/c-api
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/c-api')
-rw-r--r--Doc/c-api/arg.rst6
-rw-r--r--Doc/c-api/capsule.rst10
-rw-r--r--Doc/c-api/exceptions.rst10
-rw-r--r--Doc/c-api/extension-modules.rst4
-rw-r--r--Doc/c-api/function.rst20
-rw-r--r--Doc/c-api/init.rst2
-rw-r--r--Doc/c-api/long.rst2
-rw-r--r--Doc/c-api/refcounting.rst2
-rw-r--r--Doc/c-api/type.rst4
9 files changed, 55 insertions, 5 deletions
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 49dbc8d71cc..ab9f9c4539a 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -686,6 +686,12 @@ Building values
``p`` (:class:`bool`) [int]
Convert a C :c:expr:`int` to a Python :class:`bool` object.
+ Be aware that this format requires an ``int`` argument.
+ Unlike most other contexts in C, variadic arguments are not coerced to
+ a suitable type automatically.
+ You can convert another type (for example, a pointer or a float) to a
+ suitable ``int`` value using ``(x) ? 1 : 0`` or ``!!x``.
+
.. versionadded:: 3.14
``c`` (:class:`bytes` of length 1) [char]
diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst
index cdb8aa33e9f..64dc4f5275b 100644
--- a/Doc/c-api/capsule.rst
+++ b/Doc/c-api/capsule.rst
@@ -105,9 +105,19 @@ Refer to :ref:`using-capsules` for more information on using these objects.
``module.attribute``. The *name* stored in the capsule must match this
string exactly.
+ This function splits *name* on the ``.`` character, and imports the first
+ element. It then processes further elements using attribute lookups.
+
Return the capsule's internal *pointer* on success. On failure, set an
exception and return ``NULL``.
+ .. note::
+
+ If *name* points to an attribute of some submodule or subpackage, this
+ submodule or subpackage must be previously imported using other means
+ (for example, by using :c:func:`PyImport_ImportModule`) for the
+ attribute lookups to succeed.
+
.. versionchanged:: 3.3
*no_block* has no effect anymore.
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 885dbeb7530..a750cda3e2d 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -749,6 +749,16 @@ Exception Classes
.. versionadded:: 3.2
+.. c:function:: int PyExceptionClass_Check(PyObject *ob)
+
+ Return non-zero if *ob* is an exception class, zero otherwise. This function always succeeds.
+
+
+.. c:function:: const char *PyExceptionClass_Name(PyObject *ob)
+
+ Return :c:member:`~PyTypeObject.tp_name` of the exception class *ob*.
+
+
Exception Objects
=================
diff --git a/Doc/c-api/extension-modules.rst b/Doc/c-api/extension-modules.rst
index 4c8212f2f5e..3d331e6ec12 100644
--- a/Doc/c-api/extension-modules.rst
+++ b/Doc/c-api/extension-modules.rst
@@ -242,6 +242,6 @@ in the following ways:
* Single-phase modules support module lookup functions like
:c:func:`PyState_FindModule`.
-.. [#testsinglephase] ``_testsinglephase`` is an internal module used \
- in CPython's self-test suite; your installation may or may not \
+.. [#testsinglephase] ``_testsinglephase`` is an internal module used
+ in CPython's self-test suite; your installation may or may not
include it.
diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst
index 63b78f67767..5fb8567ef8c 100644
--- a/Doc/c-api/function.rst
+++ b/Doc/c-api/function.rst
@@ -95,6 +95,13 @@ There are a few functions specific to Python functions.
.. versionadded:: 3.12
+
+.. c:function:: PyObject* PyFunction_GetKwDefaults(PyObject *op)
+
+ Return the keyword-only argument default values of the function object *op*. This can be a
+ dictionary of arguments or ``NULL``.
+
+
.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
Return the closure associated with the function object *op*. This can be ``NULL``
@@ -123,6 +130,19 @@ There are a few functions specific to Python functions.
Raises :exc:`SystemError` and returns ``-1`` on failure.
+.. c:function:: PyObject *PyFunction_GET_CODE(PyObject *op)
+ PyObject *PyFunction_GET_GLOBALS(PyObject *op)
+ PyObject *PyFunction_GET_MODULE(PyObject *op)
+ PyObject *PyFunction_GET_DEFAULTS(PyObject *op)
+ PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)
+ PyObject *PyFunction_GET_CLOSURE(PyObject *op)
+ PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)
+
+ These functions are similar to their ``PyFunction_Get*`` counterparts, but
+ do not do type checking. Passing anything other than an instance of
+ :c:data:`PyFunction_Type` is undefined behavior.
+
+
.. c:function:: int PyFunction_AddWatcher(PyFunction_WatchCallback callback)
Register *callback* as a function watcher for the current interpreter.
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 3106bf9808f..41fd4ea14ef 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1250,7 +1250,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: void PyInterpreterState_Clear(PyInterpreterState *interp)
Reset all information in an interpreter state object. There must be
- an :term:`attached thread state` for the the interpreter.
+ an :term:`attached thread state` for the interpreter.
.. audit-event:: cpython.PyInterpreterState_Clear "" c.PyInterpreterState_Clear
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 25d9e62e387..2d0bda76697 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -439,7 +439,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
All *n_bytes* of the buffer are written: large buffers are padded with
zeroes.
- If the returned value is greater than than *n_bytes*, the value was
+ If the returned value is greater than *n_bytes*, the value was
truncated: as many of the lowest bits of the value as could fit are written,
and the higher bits are ignored. This matches the typical behavior
of a C-style downcast.
diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst
index b23f016f9b0..57a0728d4e9 100644
--- a/Doc/c-api/refcounting.rst
+++ b/Doc/c-api/refcounting.rst
@@ -210,7 +210,7 @@ of Python objects.
Py_SETREF(dst, src);
- That arranges to set *dst* to *src* _before_ releasing the reference
+ That arranges to set *dst* to *src* *before* releasing the reference
to the old value of *dst*, so that any code triggered as a side-effect
of *dst* getting torn down no longer believes *dst* points
to a valid object.
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index 2176b8e492f..5bdbff4e0ad 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -282,6 +282,10 @@ Type Objects
and other places where a method's defining class cannot be passed using the
:c:type:`PyCMethod` calling convention.
+ The returned reference is :term:`borrowed <borrowed reference>` from *type*,
+ and will be valid as long as you hold a reference to *type*.
+ Do not release it with :c:func:`Py_DECREF` or similar.
+
.. versionadded:: 3.11
.. c:function:: int PyType_GetBaseByToken(PyTypeObject *type, void *token, PyTypeObject **result)