https://github.com/python/cpython/commit/01ff2e22e158674e68321f204cfb6dca631eda83 commit: 01ff2e22e158674e68321f204cfb6dca631eda83 branch: main author: Peter Bierma <[email protected]> committer: encukou <[email protected]> date: 2026-10-21T19:21:48+02:00 summary:
gh-141004: Document remaining parts of the public C API (GH-159892) Co-authored-by: Petr Viktorin <[email protected]> files: A Doc/c-api/pyexpat.rst M Doc/c-api/code.rst M Doc/c-api/conversion.rst M Doc/c-api/dict.rst M Doc/c-api/exceptions.rst M Doc/c-api/file.rst M Doc/c-api/function.rst M Doc/c-api/hash.rst M Doc/c-api/intro.rst M Doc/c-api/long.rst M Doc/c-api/monitoring.rst M Doc/c-api/profiling.rst M Doc/c-api/structures.rst M Doc/c-api/synchronization.rst M Doc/c-api/utilities.rst M Doc/c-api/veryhigh.rst M Doc/c-api/weakref.rst M Doc/conf.py M Doc/using/configure.rst M Include/cpython/code.h M Include/cpython/dictobject.h M Include/cpython/funcobject.h M Tools/check-c-api-docs/ignored_c_api.txt diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst index 57b77f92a7d2e6a..b34edb409da9a89 100644 --- a/Doc/c-api/code.rst +++ b/Doc/c-api/code.rst @@ -176,6 +176,14 @@ bound into a function. .. versionadded:: 3.12 +.. c:macro:: PY_FOREACH_CODE_EVENT(V) + + Apply the macro *V* to each suffix of :c:type:`PyCodeEvent` + constants. + Currently expands to ``V(CREATE) V(DESTROY)``. + The macro *V* must accept one event name and supply any punctuation + needed between expansions. + .. c:type:: int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject* co) Type of a code object watcher callback function. diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst index f7c8ef8b22b9556..0b176cdb118234e 100644 --- a/Doc/c-api/conversion.rst +++ b/Doc/c-api/conversion.rst @@ -258,3 +258,23 @@ The argument must be a signed or unsigned :c:expr:`char`. .. c:macro:: Py_TOUPPER(c) Return the uppercase equivalent of the character *c*. + + +Bit masks +--------- + +The following constants are bit masks used by the character classification +macros above: + +.. c:macro:: PY_CTF_ALNUM + PY_CTF_ALPHA + PY_CTF_DIGIT + PY_CTF_LOWER + PY_CTF_SPACE + PY_CTF_UPPER + PY_CTF_XDIGIT + + Values used internally by the ``Py_IS*`` classification macros above. + Exposed for backwards compatibility only. + + .. soft-deprecated:: next diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 87d09ad2412e405..4ac4445e25886c7 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -563,6 +563,15 @@ Dictionary objects .. versionadded:: 3.12 +.. c:macro:: PY_FOREACH_DICT_EVENT(V) + + Apply the macro *V* to each suffix of :c:type:`PyDict_WatchEvent` + constants. + Currently expands to ``V(ADDED) V(MODIFIED) V(DELETED) V(CLONED) + V(CLEARED) V(DEALLOCATED)``. + The macro *V* must accept one event name and supply any punctuation + needed between expansions. + .. c:type:: int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value) Type of a dict watcher callback function. diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 0c8d14dc134ebc1..7f4e1ecc2aba26d 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -407,6 +407,11 @@ an error value). documentation. There is no C API for warning control. +.. c:function:: int PyErr_Warn(PyObject *category, const char *message) + + Equivalent to :c:expr:`PyErr_WarnEx(category, message, 1)`. + + .. c:function:: int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry) Issue a warning message with explicit control over all warning attributes. This diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index 45f2d1a6f53c697..a6bfa8358e3aacc 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -162,18 +162,30 @@ the :mod:`io` APIs instead. Soft-deprecated API ^^^^^^^^^^^^^^^^^^^ -.. soft-deprecated:: 3.15 - These are APIs that were included in Python's C API by mistake. They are documented solely for completeness; use other ``PyFile*`` APIs instead. + .. c:function:: PyObject *PyFile_NewStdPrinter(int fd) Use :c:func:`PyFile_FromFd` with defaults (``fd, NULL, "w", -1, NULL, NULL, NULL, 0``) instead. + .. soft-deprecated:: 3.15 + + .. c:var:: PyTypeObject PyStdPrinter_Type Type of file-like objects used internally at Python startup when :py:mod:`io` is not yet available. Use Python :py:func:`open` or :c:func:`PyFile_FromFd` to create file objects instead. + + .. soft-deprecated:: 3.15 + + +.. c:macro:: PY_STDIOTEXTMODE + + The string literal ``"b"``, used to open files in binary mode. + Exposed for backwards compatibility only. + + .. soft-deprecated:: next diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst index 75a4adc810f90aa..a0ccde984effb16 100644 --- a/Doc/c-api/function.rst +++ b/Doc/c-api/function.rst @@ -197,6 +197,15 @@ There are a few functions specific to Python functions. .. versionadded:: 3.15 +.. c:macro:: PY_FOREACH_FUNC_EVENT(V) + + Apply the macro *V* to each suffix of :c:type:`PyFunction_WatchEvent` + constants. + Currently expands to ``V(CREATE) V(DESTROY) V(MODIFY_CODE) + V(MODIFY_DEFAULTS) V(MODIFY_KWDEFAULTS) V(MODIFY_QUALNAME)``. + The macro *V* must accept one event name and supply any punctuation + needed between expansions. + .. c:type:: int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value) Type of a function watcher callback function. diff --git a/Doc/c-api/hash.rst b/Doc/c-api/hash.rst index 1ad712b0ce4f2b1..7f1d3a656ebdd26 100644 --- a/Doc/c-api/hash.rst +++ b/Doc/c-api/hash.rst @@ -32,13 +32,19 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`. .. c:macro:: Py_HASH_FNV Py_HASH_SIPHASH24 Py_HASH_SIPHASH13 + Py_HASH_EXTERNAL Numerical values to compare to :c:macro:`Py_HASH_ALGORITHM` to determine - which algorithm is used for hashing. The hash algorithm can be configured - via the configure :option:`--with-hash-algorithm` option. + which algorithm is used for hashing. The built-in hash algorithm can be + configured via the configure :option:`--with-hash-algorithm` option. + + :c:macro:`!Py_HASH_EXTERNAL` has value ``0`` and indicates a hash + implementation supplied by the application embedding Python; see + :c:var:`PyHash_Func`. .. versionadded:: 3.4 - Add :c:macro:`!Py_HASH_FNV` and :c:macro:`!Py_HASH_SIPHASH24`. + Add :c:macro:`!Py_HASH_FNV`, :c:macro:`!Py_HASH_SIPHASH24`, and + :c:macro:`!Py_HASH_EXTERNAL`. .. versionadded:: 3.11 Add :c:macro:`!Py_HASH_SIPHASH13`. @@ -132,6 +138,19 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`. .. versionadded:: 3.4 +.. c:var:: PyHash_FuncDef PyHash_Func + + When Python is built with :c:macro:`Py_HASH_ALGORITHM` set to + :c:macro:`Py_HASH_EXTERNAL`, the application embedding Python must define + this variable to supply a hash implementation instead of using one of + Python's built-in hash algorithms. + + .. versionadded:: 3.4 + + .. deprecated-removed:: 3.15 3.19 + Use one of the built-in hash algorithms instead. + + .. c:function:: PyHash_FuncDef* PyHash_GetFuncDef(void) Get the hash function definition. diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 258135a234cc50d..8c63a108a78e5d8 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -924,6 +924,13 @@ use them. C99 doesn't define such a thing directly (size_t is an unsigned integral type). See :pep:`353` for details. + +.. c:macro:: Py_INVALID_SIZE + + A constant of type :c:type:`Py_ssize_t` with value ``-1``, representing an + invalid size. + + .. c:macro:: PY_SSIZE_T_MAX PY_SSIZE_T_MIN @@ -931,6 +938,12 @@ use them. respecitvely) of type :c:type:`Py_ssize_t`. +.. c:macro:: PY_DWORD_MAX + + The maximum value of the Windows ``DWORD`` type. + Expands to ``0xffffffff`` on all platforms. + + .. _api-exceptions: Exceptions diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 874e422d4701dd8..b25dec161cb6f1a 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -680,6 +680,21 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. .. versionadded:: 3.12 +Build configuration +^^^^^^^^^^^^^^^^^^^ + +.. c:macro:: PYLONG_BITS_IN_DIGIT + + The number of bits in each digit of CPython's native representation of + integers. + The value can currently be either ``30`` (the default) or ``15``, + selected with :option:`--enable-big-digits` when building Python. + + To access the native representation of integers, use + :c:func:`PyLong_GetNativeLayout` and its + :c:member:`~PyLongLayout.bits_per_digit` member instead. + + Export API ^^^^^^^^^^ diff --git a/Doc/c-api/monitoring.rst b/Doc/c-api/monitoring.rst index 4bfcb86abf58ed1..e0fa772309a2888 100644 --- a/Doc/c-api/monitoring.rst +++ b/Doc/c-api/monitoring.rst @@ -170,28 +170,56 @@ would typically correspond to a Python function. .. The table is here to make the docs searchable, and to allow automatic links to the identifiers. - ================================================== ===================================== - Macro Event - ================================================== ===================================== - .. c:macro:: PY_MONITORING_EVENT_BRANCH_LEFT :monitoring-event:`BRANCH_LEFT` - .. c:macro:: PY_MONITORING_EVENT_BRANCH_RIGHT :monitoring-event:`BRANCH_RIGHT` - .. c:macro:: PY_MONITORING_EVENT_CALL :monitoring-event:`CALL` - .. c:macro:: PY_MONITORING_EVENT_C_RAISE :monitoring-event:`C_RAISE` - .. c:macro:: PY_MONITORING_EVENT_C_RETURN :monitoring-event:`C_RETURN` - .. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED :monitoring-event:`EXCEPTION_HANDLED` - .. c:macro:: PY_MONITORING_EVENT_INSTRUCTION :monitoring-event:`INSTRUCTION` - .. c:macro:: PY_MONITORING_EVENT_JUMP :monitoring-event:`JUMP` - .. c:macro:: PY_MONITORING_EVENT_LINE :monitoring-event:`LINE` - .. c:macro:: PY_MONITORING_EVENT_PY_RESUME :monitoring-event:`PY_RESUME` - .. c:macro:: PY_MONITORING_EVENT_PY_RETURN :monitoring-event:`PY_RETURN` - .. c:macro:: PY_MONITORING_EVENT_PY_START :monitoring-event:`PY_START` - .. c:macro:: PY_MONITORING_EVENT_PY_THROW :monitoring-event:`PY_THROW` - .. c:macro:: PY_MONITORING_EVENT_PY_UNWIND :monitoring-event:`PY_UNWIND` - .. c:macro:: PY_MONITORING_EVENT_PY_YIELD :monitoring-event:`PY_YIELD` - .. c:macro:: PY_MONITORING_EVENT_RAISE :monitoring-event:`RAISE` - .. c:macro:: PY_MONITORING_EVENT_RERAISE :monitoring-event:`RERAISE` - .. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION :monitoring-event:`STOP_ITERATION` - ================================================== ===================================== + .. list-table:: + :header-rows: 1 + :widths: 50 37 + + * - Macro + - Event + * - .. c:macro:: PY_MONITORING_EVENT_BRANCH_LEFT + - :monitoring-event:`BRANCH_LEFT` + * - .. c:macro:: PY_MONITORING_EVENT_BRANCH_RIGHT + - :monitoring-event:`BRANCH_RIGHT` + * - .. c:macro:: PY_MONITORING_EVENT_CALL + - :monitoring-event:`CALL` + * - .. c:macro:: PY_MONITORING_EVENT_C_RAISE + - :monitoring-event:`C_RAISE` + * - .. c:macro:: PY_MONITORING_EVENT_C_RETURN + - :monitoring-event:`C_RETURN` + * - .. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED + - :monitoring-event:`EXCEPTION_HANDLED` + * - .. c:macro:: PY_MONITORING_EVENT_INSTRUCTION + - :monitoring-event:`INSTRUCTION` + * - .. c:macro:: PY_MONITORING_EVENT_JUMP + - :monitoring-event:`JUMP` + * - .. c:macro:: PY_MONITORING_EVENT_LINE + - :monitoring-event:`LINE` + * - .. c:macro:: PY_MONITORING_EVENT_PY_RESUME + - :monitoring-event:`PY_RESUME` + * - .. c:macro:: PY_MONITORING_EVENT_PY_RETURN + - :monitoring-event:`PY_RETURN` + * - .. c:macro:: PY_MONITORING_EVENT_PY_START + - :monitoring-event:`PY_START` + * - .. c:macro:: PY_MONITORING_EVENT_PY_THROW + - :monitoring-event:`PY_THROW` + * - .. c:macro:: PY_MONITORING_EVENT_PY_UNWIND + - :monitoring-event:`PY_UNWIND` + * - .. c:macro:: PY_MONITORING_EVENT_PY_YIELD + - :monitoring-event:`PY_YIELD` + * - .. c:macro:: PY_MONITORING_EVENT_RAISE + - :monitoring-event:`RAISE` + * - .. c:macro:: PY_MONITORING_EVENT_RERAISE + - :monitoring-event:`RERAISE` + * - .. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION + - :monitoring-event:`STOP_ITERATION` + * - .. c:macro:: PY_MONITORING_EVENT_BRANCH + + .. deprecated:: 3.14 + Use :c:macro:`PY_MONITORING_EVENT_BRANCH_LEFT` + and :c:macro:`PY_MONITORING_EVENT_BRANCH_RIGHT` instead. + + - :monitoring-event:`BRANCH_LEFT` and :monitoring-event:`BRANCH_RIGHT` + .. c:function:: int PyMonitoring_ExitScope(void) diff --git a/Doc/c-api/profiling.rst b/Doc/c-api/profiling.rst index 0200f2eac6d9086..8393858c827e2dd 100644 --- a/Doc/c-api/profiling.rst +++ b/Doc/c-api/profiling.rst @@ -237,3 +237,18 @@ Reference tracing There must be an :term:`attached thread state` when calling this function. .. versionadded:: 3.13 + + +Performance statistics +====================== + +.. c:macro:: PYSTATS_MAX_UOP_ID + + Largest micro-operation identifier for which CPython allocates performance + statistics counters. Available only in builds configured with + :option:`--enable-pystats`. + + This constant is intended for internal use only and is not useful to + extension modules. + + .. soft-deprecated:: next diff --git a/Doc/c-api/pyexpat.rst b/Doc/c-api/pyexpat.rst new file mode 100644 index 000000000000000..6f40bf5b7e70534 --- /dev/null +++ b/Doc/c-api/pyexpat.rst @@ -0,0 +1,99 @@ +.. highlight:: c + +Expat C API +=========== + +The :mod:`xml.parsers.expat` module exposes selected Expat functions +through its ``expat_CAPI`` capsule. This allows extension modules to use the +same Expat library as Python. The interface is declared in :file:`pyexpat.h`, +which must be included after Expat's :file:`expat.h` header. + +.. c:macro:: PyExpat_CAPSULE_NAME + + The name of the capsule containing the Expat C API: + ``"pyexpat.expat_CAPI"``. Pass this to :c:func:`PyCapsule_Import` to obtain + a pointer to a :c:struct:`PyExpat_CAPI`. + + +.. c:macro:: PyExpat_CAPI_MAGIC + + The string identifying the layout of :c:struct:`PyExpat_CAPI`. + Before using the function pointers in the structure, check that + its ``magic`` member compares equal to this string using ``strcmp()`` + and its ``size`` member is at least :c:expr:`sizeof(struct PyExpat_CAPI)`. + + +.. c:struct:: PyExpat_CAPI + + Table of function pointers exported by :mod:`xml.parsers.expat`. + The capsule owns this structure: treat it as read-only and do not free it. + Keep a strong reference to the capsule while using the table. + + Check the compatibility fields as described under + :c:macro:`PyExpat_CAPI_MAGIC` before using the function pointers. + + .. c:member:: char *magic + + Interface identifier, set to :c:macro:`PyExpat_CAPI_MAGIC`. + + .. c:member:: int size + + Size of the structure in bytes, set to ``sizeof(struct PyExpat_CAPI)`` + by the :mod:`xml.parsers.expat` module that created the capsule. + + .. c:member:: int MAJOR_VERSION + int MINOR_VERSION + int MICRO_VERSION + + Major, minor, and micro version numbers of the Expat library used by + :mod:`xml.parsers.expat`. + + .. c:member:: void (*SetUnknownEncodingHandler)(XML_Parser parser, XML_UnknownEncodingHandler handler, void *encodingHandlerData) + + Pointer to `XML_SetUnknownEncodingHandler + <https://libexpat.github.io/doc/api/latest/#XML_SetUnknownEncodingHandler>`_. + The handler may set a Python exception on failure. The caller must + check for a Python exception after parsing. + + .. c:member:: int (*DefaultUnknownEncodingHandler)(void *encodingHandlerData, const XML_Char *name, XML_Encoding *info) + + Python's unknown-encoding handler for Expat, used with + ``XML_SetUnknownEncodingHandler``. It uses Python's codec + registry to fill *info*. + The *encodingHandlerData* argument is unused. + Calling this handler requires an :term:`attached thread state`. + + Pointers to the corresponding Expat functions, or ``NULL`` if not + available in the Expat version used by :mod:`xml.parsers.expat`, are + listed below. + + Member names omit the ``XML_`` prefix; for example, ``SetHashSalt`` + exposes Expat's ``XML_SetHashSalt`` function. See the `Expat API reference + <https://libexpat.github.io/doc/api/latest/>`_ for their behavior + and the minimum Expat version they appear in. + + .. c:member:: const XML_LChar *(*ErrorString)(enum XML_Error code) + enum XML_Error (*GetErrorCode)(XML_Parser parser) + XML_Size (*GetErrorColumnNumber)(XML_Parser parser) + XML_Size (*GetErrorLineNumber)(XML_Parser parser) + enum XML_Status (*Parse)(XML_Parser parser, const char *s, int len, int isFinal) + XML_Parser (*ParserCreate_MM)(const XML_Char *encoding, const XML_Memory_Handling_Suite *memsuite, const XML_Char *namespaceSeparator) + void (*ParserFree)(XML_Parser parser) + void (*SetCharacterDataHandler)(XML_Parser parser, XML_CharacterDataHandler handler) + void (*SetCommentHandler)(XML_Parser parser, XML_CommentHandler handler) + void (*SetDefaultHandlerExpand)(XML_Parser parser, XML_DefaultHandler handler) + void (*SetElementHandler)(XML_Parser parser, XML_StartElementHandler start, XML_EndElementHandler end) + void (*SetNamespaceDeclHandler)(XML_Parser parser, XML_StartNamespaceDeclHandler start, XML_EndNamespaceDeclHandler end) + void (*SetProcessingInstructionHandler)(XML_Parser parser, XML_ProcessingInstructionHandler handler) + void (*SetUserData)(XML_Parser parser, void *userData) + void (*SetStartDoctypeDeclHandler)(XML_Parser parser, XML_StartDoctypeDeclHandler start) + enum XML_Status (*SetEncoding)(XML_Parser parser, const XML_Char *encoding) + int (*SetHashSalt)(XML_Parser parser, unsigned long hash_salt) + XML_Bool (*SetReparseDeferralEnabled)(XML_Parser parser, XML_Bool enabled) + XML_Bool (*SetAllocTrackerActivationThreshold)(XML_Parser parser, unsigned long long activationThresholdBytes) + XML_Bool (*SetAllocTrackerMaximumAmplification)(XML_Parser parser, float maxAmplificationFactor) + XML_Bool (*SetBillionLaughsAttackProtectionActivationThreshold)(XML_Parser parser, unsigned long long activationThresholdBytes) + XML_Bool (*SetBillionLaughsAttackProtectionMaximumAmplification)(XML_Parser parser, float maxAmplificationFactor) + XML_Bool (*SetHashSalt16Bytes)(XML_Parser parser, const uint8_t entropy[16]) + + See the `Expat API reference <https://libexpat.github.io/doc/api/latest/>`_. diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index f281f2e8328beac..d9557491bc93bde 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -610,6 +610,18 @@ definition with the same method name. type checking. +.. c:function:: PyTypeObject *PyCFunction_GET_CLASS(PyObject *func) + + Return a :term:`borrowed reference` to the defining class of *func* if + its :c:member:`~PyMethodDef.ml_flags` includes :c:macro:`METH_METHOD`. + Otherwise, return ``NULL`` without setting an exception. + + *func* must be a C function object and must not be ``NULL``. + This function does not perform error or type checking. + + .. versionadded:: 3.9 + + Accessing attributes of extension types --------------------------------------- @@ -774,6 +786,16 @@ The following flags can be used with :c:member:`PyMemberDef.flags`: .. soft-deprecated:: 3.12 Use :c:macro:`Py_AUDIT_READ` instead. + +.. c:macro:: PY_WRITE_RESTRICTED + + A member flag that has no effect, retained solely for backwards compatibility. + This is only available with ``#include "structmember.h"``. + + .. soft-deprecated:: next + Omit this flag instead. + + .. _PyMemberDef-types: Member types diff --git a/Doc/c-api/synchronization.rst b/Doc/c-api/synchronization.rst index 6f18c047a24a92f..a74a92ca7cfa24e 100644 --- a/Doc/c-api/synchronization.rst +++ b/Doc/c-api/synchronization.rst @@ -264,6 +264,22 @@ These APIs are obsolete since Python 3.13 with the introduction of A pointer to a mutual exclusion lock. +.. c:macro:: PY_TIMEOUT_T + + A :term:`soft deprecated` alias to :c:expr:`long long`, the integer + type used for the timeout argument of :c:func:`PyThread_acquire_lock_timed`. + + .. soft-deprecated:: next + +.. c:var:: const long long PY_TIMEOUT_MAX + + The maximum timeout, in microseconds, supported by + :c:func:`PyThread_acquire_lock_timed`. + + .. note:: + This differs from :data:`_thread.TIMEOUT_MAX`, which is expressed in seconds. + + .. c:type:: PyLockStatus The result of acquiring a lock with a timeout. diff --git a/Doc/c-api/utilities.rst b/Doc/c-api/utilities.rst index 9d0abf440f791d4..d3563ed990d7c26 100644 --- a/Doc/c-api/utilities.rst +++ b/Doc/c-api/utilities.rst @@ -22,3 +22,4 @@ and parsing function arguments and constructing Python values from C values. codec.rst time.rst perfmaps.rst + pyexpat.rst diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index bba5c7f8ecf7751..7c4ef80592e76b7 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -151,6 +151,8 @@ the same library that the Python runtime is using. event loops, as done in :file:`Modules/_tkinter.c` in the Python source code. + The function is called without an :term:`attached thread state`. + .. versionchanged:: 3.12 This function is only called from the :ref:`main interpreter <sub-interpreter-support>`. @@ -159,16 +161,27 @@ the same library that the Python runtime is using. .. c:var:: char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *) Can be set to point to a function with the prototype - ``char *func(FILE *stdin, FILE *stdout, char *prompt)``, + ``char *func(FILE *stdin, FILE *stdout, const char *prompt)``, overriding the default function used to read a single line of input at the interpreter's prompt. The function is expected to output the string *prompt* if it's not ``NULL``, and then read a line of input from the provided standard input file, returning the - resulting string. For example, The :mod:`readline` module sets + resulting string. For example, the :mod:`readline` module sets this hook to provide line-editing and tab-completion features. - The result must be a string allocated by :c:func:`PyMem_RawMalloc` or - :c:func:`PyMem_RawRealloc`, or ``NULL`` if an error occurred. + The function is called without an :term:`attached thread state`. + + If this pointer is ``NULL``, :c:func:`PyOS_Readline` sets it to the + default implementation, :c:func:`PyOS_Readline`, + before reading input. + + The returned string must be null-terminated and include the trailing + newline, if one was read. Return an empty string if the end of the file + is reached before any characters are read. Return ``NULL`` on failure + or interruption; a Python exception may be set. + + A non-``NULL`` result must be a string allocated by :c:func:`PyMem_RawMalloc` or + :c:func:`PyMem_RawRealloc`. .. versionchanged:: 3.4 The result must be allocated by :c:func:`PyMem_RawMalloc` or @@ -179,6 +192,23 @@ the same library that the Python runtime is using. This function is only called from the :ref:`main interpreter <sub-interpreter-support>`. + +.. c:function:: char *PyOS_Readline(FILE *sys_stdin, FILE *sys_stdout, const char *prompt) + + Display *prompt*, if it is not ``NULL``, and read a line from *sys_stdin*. + If both streams are terminals and the call is made from the + :ref:`main interpreter <sub-interpreter-support>`, use + :c:var:`PyOS_ReadlineFunctionPointer`. Otherwise, use the default + implementation, which flushes *sys_stdout* and writes *prompt* to the C + standard error stream. + + The returned string follows the contract of + :c:var:`PyOS_ReadlineFunctionPointer`, but the caller must free it with + :c:func:`PyMem_Free`. Return ``NULL`` on failure or interruption; a Python + exception may be set. + + + .. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals) This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving diff --git a/Doc/c-api/weakref.rst b/Doc/c-api/weakref.rst index f41a58e8e3cd696..83ca45ec251e2be 100644 --- a/Doc/c-api/weakref.rst +++ b/Doc/c-api/weakref.rst @@ -106,6 +106,17 @@ as much as it can. been attempted. +.. c:function:: PyObject **PyObject_GET_WEAKREFS_LISTPTR(PyObject *object) + + Return a pointer to an internal linked list of weak references to *object*. + *object* must support weak references and must not be ``NULL``. + + This function is intended for internal use only. Do not access or modify + the weak reference list through the returned pointer. + + .. soft-deprecated:: next + + .. c:function:: void PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *object) Clears the weakrefs for *object* without calling the callbacks. diff --git a/Doc/conf.py b/Doc/conf.py index 8791aba435f49ea..20971ec043bd1ab 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -180,6 +180,26 @@ ('c:type', 'unsigned __int64'), ('c:type', 'double'), ('c:type', '_Float16'), + # Expat types + ('c:type', 'XML_Bool'), + ('c:type', 'XML_Char'), + ('c:type', 'XML_CharacterDataHandler'), + ('c:type', 'XML_CommentHandler'), + ('c:type', 'XML_DefaultHandler'), + ('c:type', 'XML_Encoding'), + ('c:type', 'XML_EndElementHandler'), + ('c:type', 'XML_EndNamespaceDeclHandler'), + ('c:type', 'XML_Error'), + ('c:type', 'XML_LChar'), + ('c:type', 'XML_Memory_Handling_Suite'), + ('c:type', 'XML_Parser'), + ('c:type', 'XML_ProcessingInstructionHandler'), + ('c:type', 'XML_Size'), + ('c:type', 'XML_StartDoctypeDeclHandler'), + ('c:type', 'XML_StartElementHandler'), + ('c:type', 'XML_StartNamespaceDeclHandler'), + ('c:type', 'XML_Status'), + ('c:type', 'XML_UnknownEncodingHandler'), # Standard C structures ('c:struct', 'in6_addr'), ('c:struct', 'in_addr'), diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 0d420d80f8e261e..c36328ca6f79723 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -247,7 +247,7 @@ General Options By default, the digit size is 30. - Define the ``PYLONG_BITS_IN_DIGIT`` to ``15`` or ``30``. + Define :c:macro:`PYLONG_BITS_IN_DIGIT` to ``15`` or ``30``. See :data:`sys.int_info.bits_per_digit <sys.int_info>`. diff --git a/Include/cpython/code.h b/Include/cpython/code.h index 1be47e42ed62bfb..5238447070ee548 100644 --- a/Include/cpython/code.h +++ b/Include/cpython/code.h @@ -232,9 +232,9 @@ PyAPI_FUNC(int) PyCode_Addr2Location(PyCodeObject *, int, int *, int *, int *, i V(DESTROY) typedef enum { - #define PY_DEF_EVENT(op) PY_CODE_EVENT_##op, - PY_FOREACH_CODE_EVENT(PY_DEF_EVENT) - #undef PY_DEF_EVENT + #define _Py_DEF_EVENT(op) PY_CODE_EVENT_##op, + PY_FOREACH_CODE_EVENT(_Py_DEF_EVENT) + #undef _Py_DEF_EVENT } PyCodeEvent; diff --git a/Include/cpython/dictobject.h b/Include/cpython/dictobject.h index 5e7811416aba63f..2b139a1e7db1818 100644 --- a/Include/cpython/dictobject.h +++ b/Include/cpython/dictobject.h @@ -86,9 +86,9 @@ Py_DEPRECATED(3.14) PyAPI_FUNC(PyObject *) _PyDict_Pop( V(DEALLOCATED) typedef enum { - #define PY_DEF_EVENT(EVENT) PyDict_EVENT_##EVENT, - PY_FOREACH_DICT_EVENT(PY_DEF_EVENT) - #undef PY_DEF_EVENT + #define _Py_DEF_EVENT(EVENT) PyDict_EVENT_##EVENT, + PY_FOREACH_DICT_EVENT(_Py_DEF_EVENT) + #undef _Py_DEF_EVENT } PyDict_WatchEvent; // Callback to be invoked when a watched dict is cleared, dealloced, or modified. diff --git a/Include/cpython/funcobject.h b/Include/cpython/funcobject.h index bcdd9df561def38..78a4ed41162924f 100644 --- a/Include/cpython/funcobject.h +++ b/Include/cpython/funcobject.h @@ -148,9 +148,9 @@ PyAPI_FUNC(PyObject *) PyStaticMethod_New(PyObject *); V(MODIFY_QUALNAME) typedef enum { - #define PY_DEF_EVENT(EVENT) PyFunction_EVENT_##EVENT, - PY_FOREACH_FUNC_EVENT(PY_DEF_EVENT) - #undef PY_DEF_EVENT + #define _Py_DEF_EVENT(EVENT) PyFunction_EVENT_##EVENT, + PY_FOREACH_FUNC_EVENT(_Py_DEF_EVENT) + #undef _Py_DEF_EVENT } PyFunction_WatchEvent; /* diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index aa57d70df25494c..c2003dff7b6b6bb 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -1,68 +1,4 @@ -# pydtrace_probes.h -PyDTrace_AUDIT -PyDTrace_FUNCTION_ENTRY -PyDTrace_FUNCTION_RETURN -PyDTrace_GC_DONE -PyDTrace_GC_START -PyDTrace_IMPORT_FIND_LOAD_DONE -PyDTrace_IMPORT_FIND_LOAD_START -PyDTrace_INSTANCE_DELETE_DONE -PyDTrace_INSTANCE_DELETE_START -PyDTrace_INSTANCE_NEW_DONE -PyDTrace_INSTANCE_NEW_START -PyDTrace_LINE -# fileobject.h -Py_FileSystemDefaultEncodeErrors -Py_FileSystemDefaultEncoding -Py_HasFileSystemDefaultEncoding -Py_UTF8Mode -# pyhash.h -Py_HASH_EXTERNAL -# object.h -Py_INVALID_SIZE -# pyexpat.h -PyExpat_CAPI_MAGIC -PyExpat_CAPSULE_NAME -# pyport.h -PYLONG_BITS_IN_DIGIT -PY_DWORD_MAX -# cpython/methodobject.h -PyCFunction_GET_CLASS # cpython/descrobject.h PyDescr_NAME PyDescr_TYPE PyWrapperFlag_KEYWORDS -# cpython/objimpl.h -PyObject_GET_WEAKREFS_LISTPTR -# cpython/pythonrun.h -PyOS_Readline -# cpython/warnings.h -PyErr_Warn -# fileobject.h -PY_STDIOTEXTMODE -# structmember.h -PY_WRITE_RESTRICTED -# pythread.h -PY_TIMEOUT_T -PY_TIMEOUT_MAX -# cpython/pyctype.h -PY_CTF_ALNUM -PY_CTF_ALPHA -PY_CTF_DIGIT -PY_CTF_LOWER -PY_CTF_SPACE -PY_CTF_UPPER -PY_CTF_XDIGIT -# cpython/code.h -PY_DEF_EVENT -PY_FOREACH_CODE_EVENT -# cpython/funcobject.h -PY_DEF_EVENT -PY_FOREACH_FUNC_EVENT -# cpython/monitoring.h -PY_MONITORING_EVENT_BRANCH -# cpython/dictobject.h -PY_DEF_EVENT -PY_FOREACH_DICT_EVENT -# cpython/pystats.h -PYSTATS_MAX_UOP_ID _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
