From 6354f1a3b40363dae4a81a8786af771ee51f5d30 Mon Sep 17 00:00:00 2001 From: Sina Zel taat Date: Sat, 19 Jul 2025 16:23:16 +0200 Subject: [PATCH 1/6] Update documentation on excluded headers in Python.h --- Doc/extending/extending.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index fd63495674651b..09c59dab59db97 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -75,12 +75,13 @@ the module and a copyright notice if you like). See :ref:`arg-parsing-string-and-buffers` for a description of this macro. All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or -``PY``, except those defined in standard header files. For convenience, and -since they are used extensively by the Python interpreter, ``"Python.h"`` -includes a few standard header files: ````, ````, -````, and ````. If the latter header file does not exist on -your system, it declares the functions :c:func:`malloc`, :c:func:`free` and -:c:func:`realloc` directly. +``PY``, except those defined in standard header files. + +Note that :file:`Python.h` excludes ````, ````, ````, and ```` as they are not used by +Python anymore. For backward compatibility of existing third party C extensions, they will +be included if Py_LIMITED_API is not defined and for limited C API version 3.10 and older. +The ```` and ```` headers are also not included for limited C API version 3.13 and newer. + The next thing we add to our module file is the C function that will be called when the Python expression ``spam.system(string)`` is evaluated (we'll see From ea3c0132fe0a5f7ceca0a0b184784e9e6614b5c9 Mon Sep 17 00:00:00 2001 From: Sina Zel taat Date: Sat, 19 Jul 2025 17:14:56 +0200 Subject: [PATCH 2/6] fix line length. limit to 80 characters --- Doc/extending/extending.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 09c59dab59db97..facecd92e59af0 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -77,10 +77,13 @@ the module and a copyright notice if you like). All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or ``PY``, except those defined in standard header files. -Note that :file:`Python.h` excludes ````, ````, ````, and ```` as they are not used by -Python anymore. For backward compatibility of existing third party C extensions, they will -be included if Py_LIMITED_API is not defined and for limited C API version 3.10 and older. -The ```` and ```` headers are also not included for limited C API version 3.13 and newer. +Note that :file:`Python.h` excludes ````, ````, +````, and ```` as they are not used by Python anymore. +For backward compatibility of existing third party C extensions, they will be +included if Py_LIMITED_API is not defined and for limited C API version 3.10 +and older. +The ```` and ```` headers are also not included for limited +C API version 3.13 and newer. The next thing we add to our module file is the C function that will be called From 2cd4be1a14b31c52d6d5e4fad7a84165ce438e9e Mon Sep 17 00:00:00 2001 From: Sina Zel taat Date: Mon, 21 Jul 2025 18:00:03 +0200 Subject: [PATCH 3/6] apply suggestion from code review --- Doc/extending/extending.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index facecd92e59af0..2f07a4aa50f9f5 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -77,11 +77,9 @@ the module and a copyright notice if you like). All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or ``PY``, except those defined in standard header files. -Note that :file:`Python.h` excludes ````, ````, -````, and ```` as they are not used by Python anymore. -For backward compatibility of existing third party C extensions, they will be -included if Py_LIMITED_API is not defined and for limited C API version 3.10 -and older. +For backward compatibility of existing third party C extensions, :file:`Python.h` +includes ````, ````, ````, and ```` if +:c:macro:`Py_LIMITED_API` is not defined or for limited C API version 3.10 and older. The ```` and ```` headers are also not included for limited C API version 3.13 and newer. From cefc8f9c3d02c977bd0c28c664572c7a103d5997 Mon Sep 17 00:00:00 2001 From: Sina Zel taat <111974143+SZeltaat@users.noreply.github.com> Date: Mon, 4 Aug 2025 14:02:11 +0200 Subject: [PATCH 4/6] Update Doc/extending/extending.rst simplify the sentence and supress link Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/extending/extending.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 2f07a4aa50f9f5..709e7d4b729429 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -77,7 +77,7 @@ the module and a copyright notice if you like). All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or ``PY``, except those defined in standard header files. -For backward compatibility of existing third party C extensions, :file:`Python.h` +For backward compatibility, :file:`!Python.h` includes ````, ````, ````, and ```` if :c:macro:`Py_LIMITED_API` is not defined or for limited C API version 3.10 and older. The ```` and ```` headers are also not included for limited From 7e3b66fdaf7785879386814de1563fc3bc04f86c Mon Sep 17 00:00:00 2001 From: Sina Zel taat Date: Tue, 5 Aug 2025 20:16:30 +0200 Subject: [PATCH 5/6] apply suggestions from code review --- Doc/extending/extending.rst | 33 +++++++++++++++++++++++++++------ Include/Python.h | 4 ++++ 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 709e7d4b729429..c0b92d9571ce56 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -77,12 +77,33 @@ the module and a copyright notice if you like). All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or ``PY``, except those defined in standard header files. -For backward compatibility, :file:`!Python.h` -includes ````, ````, ````, and ```` if -:c:macro:`Py_LIMITED_API` is not defined or for limited C API version 3.10 and older. -The ```` and ```` headers are also not included for limited -C API version 3.13 and newer. - +For backward compatibility, :file:`Python.h` includes several standard header files. +C extensions should include the standard headers that they use, and should not rely +on these implicit includes. +If using the limited C API version 3.13 or newer, the implicit includes are: + +* ```` +* ```` (on Windows) +* ```` +* ```` +* ```` +* ```` +* ```` +* ```` (if present) + +If :c:macro:`Py_LIMITED_API` is not defined, or is set to version 3.12 or older, +the headers below are also included: + +* ```` +* ```` (on POSIX) + +If :c:macro:`Py_LIMITED_API` is not defined, or is set to version 3.10 or older, +the headers below are also included: + +* ```` +* ```` +* ```` +* ```` The next thing we add to our module file is the C function that will be called when the Python expression ``spam.system(string)`` is evaluated (we'll see diff --git a/Include/Python.h b/Include/Python.h index 19417df698c8e7..1c6cba6e3e12c3 100644 --- a/Include/Python.h +++ b/Include/Python.h @@ -2,6 +2,10 @@ // C extensions should only #include , and not include directly // the other Python header files included by . +// Note: If the included standard headers change, please update the documentation +// (including the documentation for C extensions) accordingly. + + #ifndef Py_PYTHON_H #define Py_PYTHON_H From 29d1c1685b71baaaf4bc503fef379306d85ae2d4 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Tue, 5 Aug 2025 21:26:38 +0100 Subject: [PATCH 6/6] cosmetics --- Doc/extending/extending.rst | 56 +++++++++++++++++++------------------ Include/Python.h | 5 +--- 2 files changed, 30 insertions(+), 31 deletions(-) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index c0b92d9571ce56..c0a7a3ac678a7f 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -77,33 +77,35 @@ the module and a copyright notice if you like). All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or ``PY``, except those defined in standard header files. -For backward compatibility, :file:`Python.h` includes several standard header files. -C extensions should include the standard headers that they use, and should not rely -on these implicit includes. -If using the limited C API version 3.13 or newer, the implicit includes are: - -* ```` -* ```` (on Windows) -* ```` -* ```` -* ```` -* ```` -* ```` -* ```` (if present) - -If :c:macro:`Py_LIMITED_API` is not defined, or is set to version 3.12 or older, -the headers below are also included: - -* ```` -* ```` (on POSIX) - -If :c:macro:`Py_LIMITED_API` is not defined, or is set to version 3.10 or older, -the headers below are also included: - -* ```` -* ```` -* ```` -* ```` +.. tip:: + + For backward compatibility, :file:`Python.h` includes several standard header files. + C extensions should include the standard headers that they use, + and should not rely on these implicit includes. + If using the limited C API version 3.13 or newer, the implicit includes are: + + * ```` + * ```` (on Windows) + * ```` + * ```` + * ```` + * ```` + * ```` + * ```` (if present) + + If :c:macro:`Py_LIMITED_API` is not defined, or is set to version 3.12 or older, + the headers below are also included: + + * ```` + * ```` (on POSIX) + + If :c:macro:`Py_LIMITED_API` is not defined, or is set to version 3.10 or older, + the headers below are also included: + + * ```` + * ```` + * ```` + * ```` The next thing we add to our module file is the C function that will be called when the Python expression ``spam.system(string)`` is evaluated (we'll see diff --git a/Include/Python.h b/Include/Python.h index 1c6cba6e3e12c3..23d744fed81ab8 100644 --- a/Include/Python.h +++ b/Include/Python.h @@ -2,10 +2,6 @@ // C extensions should only #include , and not include directly // the other Python header files included by . -// Note: If the included standard headers change, please update the documentation -// (including the documentation for C extensions) accordingly. - - #ifndef Py_PYTHON_H #define Py_PYTHON_H @@ -20,6 +16,7 @@ // Include standard header files +// When changing these files, remember to update Doc/extending/extending.rst. #include // assert() #include // uintptr_t #include // INT_MAX