Feb 4, 2026 · Feb 4, 2026 · Feb 4, 2026 · Feb 4, 2026
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
 complete listing.


 Utilities
 ---------

 .. c:macro:: Py_ABS(x)

   Return the absolute value of ``x``.
   The argument may be evaluated twice.

   If the result cannot be represented (for example, if ``x`` has
   :c:macro:`!INT_MIN` value for :c:expr:`int` type), the behavior is
   undefined.

   .. versionadded:: 3.3

 .. c:macro:: Py_ALWAYS_INLINE

   Ask the compiler to always inline a static inline function. The compiler can
   ignore it and decide to not inline the function.

   It can be used to inline performance critical static inline functions when
   building Python in debug mode with function inlining disabled. For example,
   MSC disables function inlining when building in debug mode.

   Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
   worse performances (due to increased code size for example). The compiler is
   usually smarter than the developer for the cost/benefit analysis.

   If Python is :ref:`built in debug mode <debug-build>` (if the :c:macro:`Py_DEBUG`
   macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing.

   It must be specified before the function return type. Usage::

       static inline Py_ALWAYS_INLINE int random(void) { return 4; }

   .. versionadded:: 3.11

 .. c:macro:: Py_CHARMASK(c)

   Argument must be a character or an integer in the range [-128, 127] or [0,
   255].  This macro returns ``c`` cast to an ``unsigned char``.

 .. c:macro:: Py_DEPRECATED(version)

   Use this for deprecated declarations.  The macro must be placed before the
   symbol name.

   Example::

      Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

   .. versionchanged:: 3.8
      MSVC support was added.

 .. c:macro:: Py_GETENV(s)

   Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the
   command line (see :c:member:`PyConfig.use_environment`).

 .. c:macro:: Py_LOCAL(type)

   Declare a function returning the specified *type* using a fast-calling
   qualifier for functions that are local to the current file.
   Semantically, this is equivalent to ``static type``.

 .. c:macro:: Py_LOCAL_INLINE(type)

   Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function
   be inlined.

 .. c:macro:: Py_LOCAL_SYMBOL

   Macro used to declare a symbol as local to the shared library (hidden).
   On supported platforms, it ensures the symbol is not exported.

   On compatible versions of GCC/Clang, it
   expands to ``__attribute__((visibility("hidden")))``.

 .. c:macro:: Py_MAX(x, y)

   Return the maximum value between ``x`` and ``y``.
   Corresponds roughly to :samp:`(({x}) < 0 ? -({x}) : ({x}))`

   .. versionadded:: 3.3

 .. c:macro:: Py_MEMBER_SIZE(type, member)

   Return the size of a structure (``type``) ``member`` in bytes.

   .. versionadded:: 3.6

 .. c:macro:: Py_MEMCPY(dest, src, n)

   This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
   Use :c:func:`!memcpy` directly instead.

   .. deprecated:: 3.14
      The macro is :term:`soft deprecated`.
 .. c:macro:: Py_MAX(x, y)
             Py_MIN(x, y)

 .. c:macro:: Py_MIN(x, y)
   Return the larger or smaller of the arguments, respectively.
   Any arguments may be evaluated twice.

   Return the minimum value between ``x`` and ``y``.
   :c:macro:`!Py_MAX` corresponds roughly to
   :samp:`((({x}) > ({y})) ? ({x}) : ({y}))`.

   .. versionadded:: 3.3

 .. c:macro:: Py_NO_INLINE

   Disable inlining on a function. For example, it reduces the C stack
   consumption: useful on LTO+PGO builds which heavily inline code (see
   :issue:`33720`).

   Usage::

       Py_NO_INLINE static int random(void) { return 4; }

   .. versionadded:: 3.11

 .. c:macro:: Py_STRINGIFY(x)

   Convert ``x`` to a C string.  E.g. ``Py_STRINGIFY(123)`` returns
   ``"123"``.
 .. c:macro:: Py_GETENV(s)

   .. versionadded:: 3.4
   Like :c:expr:`getenv(s)`, but returns ``NULL`` if :option:`-E` was passed on the
   command line (see :c:member:`PyConfig.use_environment`).

 .. c:macro:: Py_UNREACHABLE()

   avoids a warning about unreachable code.  For example, the macro is
   implemented with ``__builtin_unreachable()`` on GCC in release mode.

   In debug mode, the macro compiles to a call to :c:func:`Py_FatalError`.

   A use for ``Py_UNREACHABLE()`` is following a call a function that
   never returns but that is not declared:c:macro:`_Py_NO_RETURN`.
   never returns but that is not declared``_Noreturn``.

   If a code path is very unlikely code but can be reached under exceptional
   case, this macro must not be used.  For example, under low memory condition

   .. versionadded:: 3.7

 .. c:macro::Py_UNUSED(arg)
 .. c:macro::Py_MEMBER_SIZE(type, member)

   Use this for unused arguments in a function definition to silence compiler
   warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``.
   Return the size of a structure (*type*) *member* in bytes.

   .. versionadded:: 3.4
   Corresponds roughly to :samp:`sizeof((({type} *)NULL)->{member})`.

   .. versionadded:: 3.6

 .. c:macro:: Py_ARRAY_LENGTH(array)

   Compute the length of a statically allocated C array at compile time.

   The *array* argument must be a C array with a size known at compile time.
   Passing an array with an unknown size, such as a heap-allocated array,
   will result in a compilation error on some compilers, or otherwise produce
   incorrect results.

   This is roughly equivalent to::

      sizeof(array) / sizeof((array)[0])

 .. c:macro:: Py_BUILD_ASSERT(cond)

   Asserts a compile-time condition *cond*, as a statement.
   The build will fail if the condition is false or cannot be evaluated at compile time.

   Corresponds roughly to :samp:`static_assert({cond})` on C23 and above.

   For example::

      Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));

   .. versionadded:: 3.3

 .. c:macro:: Py_STRINGIFY(x)

   Convert ``x`` to a C string.  For example, ``Py_STRINGIFY(123)`` returns
   ``"123"``.

   .. versionadded:: 3.4

 .. c:macro:: Py_UNUSED(arg)

   Use this for unused arguments in a function definition to silence compiler
   warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``.

   .. versionadded:: 3.4

 .. c:macro:: Py_CHARMASK(c)

   Argument must be a character or an integer in the range [-128, 127] or [0,
   255].  This macro returns ``c`` cast to an ``unsigned char``.

 .. c:macro:: Py_MEMCPY(dest, src, n)

   This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
   Use :c:func:`!memcpy` directly instead.

   .. deprecated:: 3.14
      The macro is :term:`soft deprecated`.


 Docstring utilities
 -------------------

 .. c:macro:: PyDoc_STRVAR(name, str)

   Creates a variable with name *name* that can be used in docstrings.
   If Python is built without docstrings, the value will be empty.

   Use :c:macro:`PyDoc_STRVAR` for docstrings to support building
   Python without docstrings, as specified in :pep:`7`.
   If Python is built :option:`without docstrings <--without-doc-strings>`,
   the value will be an empty string.

   Example::

          // ...
      }

 .. c:macro::PyDoc_STR(str)
   Expands to :samp:`PyDoc_VAR({name}) =PyDoc_STR({str})`.

   Creates a docstring for the given input string or an empty string
   if docstrings are disabled.
 .. c:macro:: PyDoc_STR(str)

 Use :c:macro:`PyDoc_STR` in specifying docstrings to support
 building Python withoutdocstrings, as specified in :pep:`7`.
 Expands to the given input string, or an empty string
 ifdocstrings are :option:`disabled <--without-doc-strings>`.

   Example::


 .. c:macro:: PyDoc_VAR(name)

   Declares a static character array variable with the given name *name*.
   Declares a static character array variable with the given *name*.
   Expands to :samp:`static const char {name}[]`

   For example::

      PyDoc_VAR(python_doc) = PyDoc_STR("A genus of constricting snakes in the Pythonidae family native "
                                        "to the tropics and subtropics of the Eastern Hemisphere.");
      PyDoc_VAR(python_doc) = PyDoc_STR(
         "A genus of constricting snakes in the Pythonidae family native "
         "to the tropics and subtropics of the Eastern Hemisphere.");

 .. c:macro:: Py_ARRAY_LENGTH(array)

   Compute the length of a statically allocated C array at compile time.
 Declaration utilities
 ---------------------

   The *array* argument must be a C array with a size known at compile time.
   Passing an array with an unknown size, such as a heap-allocated array,
   will result in a compilation error on some compilers, or otherwise produce
   incorrect results.
 The following macros can be used in declarations.
 They are most useful for defining the C API itself, and have limited use
 for extension authors.
 Most of them expand to compiler-specific spellings of common extensions
 to the C language.

   This is roughly equivalent to::
 .. c:macro:: Py_ALWAYS_INLINE

      sizeof(array) / sizeof((array)[0])
   Ask the compiler to always inline a static inline function. The compiler can
   ignore it and decide to not inline the function.

   Corresponds to ``always_inline`` attribute in GCC and ``__forceinline``
   in MSVC.

   It can be used to inline performance critical static inline functions when
   building Python in debug mode with function inlining disabled. For example,
   MSC disables function inlining when building in debug mode.

   Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
   worse performances (due to increased code size for example). The compiler is
   usually smarter than the developer for the cost/benefit analysis.

   If Python is :ref:`built in debug mode <debug-build>` (if the :c:macro:`Py_DEBUG`
   macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing.

   It must be specified before the function return type. Usage::

       static inline Py_ALWAYS_INLINE int random(void) { return 4; }

   .. versionadded:: 3.11

 .. c:macro:: Py_NO_INLINE

   Disable inlining on a function. For example, it reduces the C stack
   consumption: useful on LTO+PGO builds which heavily inline code (see
   :issue:`33720`).

   Corresponds to the ``noinline`` attribute/specification on GCC and MSVC.

   Usage::

       Py_NO_INLINE static int random(void) { return 4; }

   .. versionadded:: 3.11

 .. c:macro:: Py_DEPRECATED(version)

   Use this to declare APIs that were deprecated in a specific CPython version.
   The macro must be placed before the symbol name.

   Example::

      Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

   .. versionchanged:: 3.8
      MSVC support was added.

 .. c:macro:: Py_LOCAL(type)

   Declare a function returning the specified *type* using a fast-calling
   qualifier for functions that are local to the current file.
   Semantically, this is equivalent to :samp:`static {type}`.

 .. c:macro:: Py_LOCAL_INLINE(type)

   Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function
   be inlined.

 .. c:macro:: Py_LOCAL_SYMBOL

   Macro used to declare a symbol as local to the shared library (hidden).
   On supported platforms, it ensures the symbol is not exported.

   On compatible versions of GCC/Clang, it
   expands to ``__attribute__((visibility("hidden")))``.

 .. c:macro:: Py_EXPORTED_SYMBOL
Original file line number	Diff line number	Diff line change
Expand Up		@@ -157,123 +157,37 @@
		complete listing.


		Utilities
		---------

		.. c:macro:: Py_ABS(x)

		Return the absolute value of ``x``.
		The argument may be evaluated twice.

		If the result cannot be represented (for example, if ``x`` has
		:c:macro:`!INT_MIN` value for :c:expr:`int` type), the behavior is
		undefined.

		.. versionadded:: 3.3

		.. c:macro:: Py_ALWAYS_INLINE

		Ask the compiler to always inline a static inline function. The compiler can
		ignore it and decide to not inline the function.

		It can be used to inline performance critical static inline functions when
		building Python in debug mode with function inlining disabled. For example,
		MSC disables function inlining when building in debug mode.

		Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
		worse performances (due to increased code size for example). The compiler is
		usually smarter than the developer for the cost/benefit analysis.

		If Python is :ref:`built in debug mode <debug-build>` (if the :c:macro:`Py_DEBUG`
		macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing.

		It must be specified before the function return type. Usage::

		static inline Py_ALWAYS_INLINE int random(void) { return 4; }

		.. versionadded:: 3.11

		.. c:macro:: Py_CHARMASK(c)

		Argument must be a character or an integer in the range [-128, 127] or [0,
		255]. This macro returns ``c`` cast to an ``unsigned char``.

		.. c:macro:: Py_DEPRECATED(version)

		Use this for deprecated declarations. The macro must be placed before the
		symbol name.

		Example::

		Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

		.. versionchanged:: 3.8
		MSVC support was added.

		.. c:macro:: Py_GETENV(s)

		Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the
		command line (see :c:member:`PyConfig.use_environment`).

		.. c:macro:: Py_LOCAL(type)

		Declare a function returning the specified type using a fast-calling
		qualifier for functions that are local to the current file.
		Semantically, this is equivalent to ``static type``.

		.. c:macro:: Py_LOCAL_INLINE(type)

		Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function
		be inlined.

		.. c:macro:: Py_LOCAL_SYMBOL

		Macro used to declare a symbol as local to the shared library (hidden).
		On supported platforms, it ensures the symbol is not exported.

		On compatible versions of GCC/Clang, it
		expands to ``__attribute__((visibility("hidden")))``.

		.. c:macro:: Py_MAX(x, y)

		Return the maximum value between ``x`` and ``y``.
		Corresponds roughly to :samp:`(({x}) < 0 ? -({x}) : ({x}))`

		.. versionadded:: 3.3

		.. c:macro:: Py_MEMBER_SIZE(type, member)

		Return the size of a structure (``type``) ``member`` in bytes.

		.. versionadded:: 3.6

		.. c:macro:: Py_MEMCPY(dest, src, n)

		This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
		Use :c:func:`!memcpy` directly instead.

		.. deprecated:: 3.14
		The macro is :term:`soft deprecated`.
		.. c:macro:: Py_MAX(x, y)
		Py_MIN(x, y)

		.. c:macro:: Py_MIN(x, y)
		Return the larger or smaller of the arguments, respectively.
		Any arguments may be evaluated twice.

		Return the minimum value between ``x`` and ``y``.
		:c:macro:`!Py_MAX` corresponds roughly to
		:samp:`((({x}) > ({y})) ? ({x}) : ({y}))`.

		.. versionadded:: 3.3

		.. c:macro:: Py_NO_INLINE

		Disable inlining on a function. For example, it reduces the C stack
		consumption: useful on LTO+PGO builds which heavily inline code (see
		:issue:`33720`).

		Usage::

		Py_NO_INLINE static int random(void) { return 4; }

		.. versionadded:: 3.11

		.. c:macro:: Py_STRINGIFY(x)

		Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns
		``"123"``.
		.. c:macro:: Py_GETENV(s)

		.. versionadded:: 3.4
		Like :c:expr:`getenv(s)`, but returns ``NULL`` if :option:`-E` was passed on the
Check warning on line 189 in Doc/c-api/intro.rst View workflow job for this annotation GitHub Actions/ Docs / Docs `c:identifier reference target not found: s [ref.identifier]` Check warning on line 189 in Doc/c-api/intro.rst View workflow job for this annotation GitHub Actions/ Docs / Docs `c:identifier reference target not found: getenv [ref.identifier]`
		command line (see :c:member:`PyConfig.use_environment`).

		.. c:macro:: Py_UNREACHABLE()

Expand All		@@ -286,8 +200,10 @@
		avoids a warning about unreachable code. For example, the macro is
		implemented with ``__builtin_unreachable()`` on GCC in release mode.

		In debug mode, the macro compiles to a call to :c:func:`Py_FatalError`.

		A use for ``Py_UNREACHABLE()`` is following a call a function that
		never returns but that is not declared:c:macro:`_Py_NO_RETURN`.
		never returns but that is not declared``_Noreturn``.
Copy link Member vstinnerFeb 4, 2026 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Note: C11 added`_Noreturn`, but C23 adds`[[noreturn]]` and deprecates`_Noreturn`. Copy link MemberAuthor encukouFeb 4, 2026 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I'm aware, but don't want to get in the details too much. We require C11, and as far as I know, deprecations in the C standard don't mean planned removal.

		If a code path is very unlikely code but can be reached under exceptional
		case, this macro must not be used. For example, under low memory condition
Expand All		@@ -297,18 +213,34 @@

		.. versionadded:: 3.7

		.. c:macro::Py_UNUSED(arg)
		.. c:macro::Py_MEMBER_SIZE(type, member)

		Use this for unused arguments in a function definition to silence compiler
		warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``.
		Return the size of a structure (type) member in bytes.

		.. versionadded:: 3.4
		Corresponds roughly to :samp:`sizeof((({type} *)NULL)->{member})`.

		.. versionadded:: 3.6

		.. c:macro:: Py_ARRAY_LENGTH(array)

		Compute the length of a statically allocated C array at compile time.

		The array argument must be a C array with a size known at compile time.
		Passing an array with an unknown size, such as a heap-allocated array,
		will result in a compilation error on some compilers, or otherwise produce
		incorrect results.

		This is roughly equivalent to::

		sizeof(array) / sizeof((array)[0])

		.. c:macro:: Py_BUILD_ASSERT(cond)

		Asserts a compile-time condition cond, as a statement.
		The build will fail if the condition is false or cannot be evaluated at compile time.

		Corresponds roughly to :samp:`static_assert({cond})` on C23 and above.

		For example::

		Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));
Expand All		@@ -327,13 +259,42 @@

		.. versionadded:: 3.3

		.. c:macro:: Py_STRINGIFY(x)

		Convert ``x`` to a C string. For example, ``Py_STRINGIFY(123)`` returns
		``"123"``.

		.. versionadded:: 3.4

		.. c:macro:: Py_UNUSED(arg)

		Use this for unused arguments in a function definition to silence compiler
		warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``.

		.. versionadded:: 3.4

		.. c:macro:: Py_CHARMASK(c)

		Argument must be a character or an integer in the range [-128, 127] or [0,
		255]. This macro returns ``c`` cast to an ``unsigned char``.

		.. c:macro:: Py_MEMCPY(dest, src, n)

		This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
		Use :c:func:`!memcpy` directly instead.

		.. deprecated:: 3.14
		The macro is :term:`soft deprecated`.


		Docstring utilities
		-------------------

		.. c:macro:: PyDoc_STRVAR(name, str)

		Creates a variable with name name that can be used in docstrings.
		If Python is built without docstrings, the value will be empty.

		Use :c:macro:`PyDoc_STRVAR` for docstrings to support building
		Python without docstrings, as specified in :pep:`7`.
		If Python is built :option:`without docstrings <--without-doc-strings>`,
		the value will be an empty string.

		Example::

Expand All		@@ -345,13 +306,12 @@
		// ...
		}

		.. c:macro::PyDoc_STR(str)
		Expands to :samp:`PyDoc_VAR({name}) =PyDoc_STR({str})`.

		Creates a docstring for the given input string or an empty string
		if docstrings are disabled.
		.. c:macro:: PyDoc_STR(str)

		Use :c:macro:`PyDoc_STR` in specifying docstrings to support
		building Python withoutdocstrings, as specified in :pep:`7`.
		Expands to the given input string, or an empty string
		ifdocstrings are :option:`disabled <--without-doc-strings>`.

		Example::

Expand All		@@ -363,26 +323,94 @@

		.. c:macro:: PyDoc_VAR(name)

		Declares a static character array variable with the given name name.
		Declares a static character array variable with the given name.
		Expands to :samp:`static const char {name}[]`

		For example::

		PyDoc_VAR(python_doc) = PyDoc_STR("A genus of constricting snakes in the Pythonidae family native "
		"to the tropics and subtropics of the Eastern Hemisphere.");
		PyDoc_VAR(python_doc) = PyDoc_STR(
		"A genus of constricting snakes in the Pythonidae family native "
		"to the tropics and subtropics of the Eastern Hemisphere.");

		.. c:macro:: Py_ARRAY_LENGTH(array)

		Compute the length of a statically allocated C array at compile time.
		Declaration utilities
		---------------------

		The array argument must be a C array with a size known at compile time.
		Passing an array with an unknown size, such as a heap-allocated array,
		will result in a compilation error on some compilers, or otherwise produce
		incorrect results.
		The following macros can be used in declarations.
		They are most useful for defining the C API itself, and have limited use
		for extension authors.
		Most of them expand to compiler-specific spellings of common extensions
		to the C language.

		This is roughly equivalent to::
		.. c:macro:: Py_ALWAYS_INLINE

		sizeof(array) / sizeof((array)[0])
		Ask the compiler to always inline a static inline function. The compiler can
		ignore it and decide to not inline the function.

		Corresponds to ``always_inline`` attribute in GCC and ``__forceinline``
		in MSVC.

		It can be used to inline performance critical static inline functions when
		building Python in debug mode with function inlining disabled. For example,
		MSC disables function inlining when building in debug mode.

		Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
		worse performances (due to increased code size for example). The compiler is
		usually smarter than the developer for the cost/benefit analysis.

		If Python is :ref:`built in debug mode <debug-build>` (if the :c:macro:`Py_DEBUG`
		macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing.

		It must be specified before the function return type. Usage::

		static inline Py_ALWAYS_INLINE int random(void) { return 4; }

		.. versionadded:: 3.11

		.. c:macro:: Py_NO_INLINE

		Disable inlining on a function. For example, it reduces the C stack
		consumption: useful on LTO+PGO builds which heavily inline code (see
		:issue:`33720`).

		Corresponds to the ``noinline`` attribute/specification on GCC and MSVC.

		Usage::

		Py_NO_INLINE static int random(void) { return 4; }

		.. versionadded:: 3.11

		.. c:macro:: Py_DEPRECATED(version)

		Use this to declare APIs that were deprecated in a specific CPython version.
		The macro must be placed before the symbol name.

		Example::

		Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

		.. versionchanged:: 3.8
		MSVC support was added.

		.. c:macro:: Py_LOCAL(type)

		Declare a function returning the specified type using a fast-calling
		qualifier for functions that are local to the current file.
		Semantically, this is equivalent to :samp:`static {type}`.

		.. c:macro:: Py_LOCAL_INLINE(type)

		Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function
		be inlined.

		.. c:macro:: Py_LOCAL_SYMBOL

		Macro used to declare a symbol as local to the shared library (hidden).
		On supported platforms, it ensures the symbol is not exported.

		On compatible versions of GCC/Clang, it
		expands to ``__attribute__((visibility("hidden")))``.

		.. c:macro:: Py_EXPORTED_SYMBOL

Expand Down