From 44f9a3d3e4d49d81c685d6aeaeb6368cd288ee80 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 4 Feb 2026 14:01:22 +0100 Subject: [PATCH 1/5] Reorganize and reword the 'Useful macros' section - Group the macros - Roughly order them to put the most important ones first - Add expansions where it makes sense; especially if there's an equivalent in modern C or a common compiler --- Doc/c-api/intro.rst | 278 ++++++++++++++++++++++++-------------------- 1 file changed, 153 insertions(+), 125 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 6886cd85b09a7d..801825b40467cf 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -157,123 +157,37 @@ Others of a more general utility are defined here. This is not necessarily a 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 ` (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() @@ -286,8 +200,10 @@ complete listing. 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 @@ -297,18 +213,34 @@ complete listing. .. 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)); @@ -327,13 +259,42 @@ complete listing. .. 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:: @@ -345,13 +306,12 @@ complete listing. // ... } -.. 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 without docstrings, as specified in :pep:`7`. + Expands to the given input string, or an empty string + if docstrings are :option:`disabled <--without-doc-strings>`. Example:: @@ -363,26 +323,94 @@ complete listing. .. 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 ` (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 From abac586758f869f686a3f501091f2a770142ba6a Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 4 Feb 2026 15:35:51 +0100 Subject: [PATCH 2/5] Update Doc/c-api/intro.rst Co-authored-by: Victor Stinner --- Doc/c-api/intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 801825b40467cf..0a3ef79c58883a 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -383,7 +383,7 @@ to the C language. .. c:macro:: Py_DEPRECATED(version) - Use this to declare APIs that were deprecated in a specific CPYthon version. + Use this to declare APIs that were deprecated in a specific CPython version. The macro must be placed before the symbol name. Example:: From aa56752b497fe9201a1fc2425cadb2aabc786f51 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 4 Feb 2026 15:40:33 +0100 Subject: [PATCH 3/5] Avoid warning --- Doc/c-api/intro.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 801825b40467cf..9a9ed567b0ecfe 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -186,8 +186,8 @@ Utilities .. c:macro:: Py_GETENV(s) - Like :c:expr:`getenv(s)`, but returns ``NULL`` if :option:`-E` was passed on the - command line (see :c:member:`PyConfig.use_environment`). + Like :samp:`getenv({s})`, but returns ``NULL`` if :option:`-E` was passed + on the command line (see :c:member:`PyConfig.use_environment`). .. c:macro:: Py_UNREACHABLE() From 360333dffab5a7ac78db37c8dd175f30b7ece481 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 5 Feb 2026 13:49:24 +0100 Subject: [PATCH 4/5] Shuffle the macros around --- Doc/c-api/intro.rst | 229 +++++++++++++++++++++++--------------------- 1 file changed, 121 insertions(+), 108 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index a3ef4b693d64b3..36bdde5fadfa85 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -156,95 +156,23 @@ defined closer to where they are useful (for example, :c:macro:`Py_RETURN_NONE`, Others of a more general utility are defined here. This is not necessarily a complete listing. +.. c:macro:: Py_CAN_START_THREADS -Arithmetic 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. - - Corresponds roughly to :samp:`(({x}) < 0 ? -({x}) : ({x}))` - - .. versionadded:: 3.3 - -.. c:macro:: Py_MAX(x, y) - Py_MIN(x, y) - - Return the larger or smaller of the arguments, respectively. - Any arguments may be evaluated twice. - - :c:macro:`!Py_MAX` corresponds roughly to - :samp:`((({x}) > ({y})) ? ({x}) : ({y}))`. - - .. versionadded:: 3.3 - -.. c:macro:: Py_ARITHMETIC_RIGHT_SHIFT(type, integer, positions) - Similar to ``integer >> positions``, but forces sign extension, as the C - standard does not define whether a right-shift of a signed integer will - perform sign extension or a zero-fill. - - *integer* should be any signed integer type. - *positions* is the number of positions to shift to the right. - - Both *integer* and *positions* can be evaluated more than once; - consequently, avoid directly passing a function call or some other - operation with side-effects to this macro. Instead, store the result as a - variable and then pass it. - - *type* is unused and only kept for backwards compatibility. Historically, - *type* was used to cast *integer*. - - .. versionchanged:: 3.1 - - This macro is now valid for all signed integer types, not just those for - which ``unsigned type`` is legal. As a result, *type* is no longer - used. - -.. c:macro:: Py_SAFE_DOWNCAST(value, larger, smaller) - Cast *value* to type *smaller* from type *larger*, validating that no - information was lost. - - On release builds of Python, this is roughly equivalent to - ``(smaller) value`` (in C++, ``static_cast(value)`` will be - used instead). - - On debug builds (implying that :c:macro:`Py_DEBUG` is defined), this asserts - that no information was lost with the cast from *larger* to *smaller*. - - *value*, *larger*, and *smaller* may all be evaluated more than once in the - expression; consequently, do not pass an expression with side-effects - directly to this macro. - -.. 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``. + If this macro is defined, then the current system is able to start threads. + Currently, all systems supported by CPython (per :pep:`11`), with the + exception of some WebAssembly platforms, support starting threads. -Python-specific utilities -------------------------- + .. versionadded:: 3.13 .. c:macro:: Py_GETENV(s) Like :samp:`getenv({s})`, but returns ``NULL`` if :option:`-E` was passed on the command line (see :c:member:`PyConfig.use_environment`). -.. c:macro:: Py_CAN_START_THREADS - If this macro is defined, then the current system is able to start threads. - - Currently, all systems supported by CPython (per :pep:`11`), with the - exception of some WebAssembly platforms, support starting threads. - - .. versionadded:: 3.13 -Docstring utilities -^^^^^^^^^^^^^^^^^^^ +Docstring macros +---------------- .. c:macro:: PyDoc_STRVAR(name, str) @@ -288,8 +216,9 @@ Docstring utilities "A genus of constricting snakes in the Pythonidae family native " "to the tropics and subtropics of the Eastern Hemisphere."); -General Utilities ------------------ + +General utility macros +---------------------- The following macros common tasks not specific to Python. @@ -300,8 +229,79 @@ The following macros common tasks not specific to Python. .. versionadded:: 3.4 -Assertions -^^^^^^^^^^ +.. c:macro:: Py_GCC_ATTRIBUTE(name) + + Use a GCC attribute *name*, hiding it from compilers that don't support GCC + attributes (such as MSVC). + + This expands to :samp:`__attribute__(({name)})` on a GCC compiler, + and expands to nothing on compilers that don't support GCC attributes. + + +Numeric utilities +^^^^^^^^^^^^^^^^^ + +.. c:macro:: Py_ABS(x) + + Return the absolute value of ``x``. + + The argument may be evaluated more than once. + Consequently, do not pass an expression with side-effects directly + to this macro. + + 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. + + Corresponds roughly to :samp:`(({x}) < 0 ? -({x}) : ({x}))` + + .. versionadded:: 3.3 + +.. c:macro:: Py_MAX(x, y) + Py_MIN(x, y) + + Return the larger or smaller of the arguments, respectively. + + Any arguments may be evaluated more than once. + Consequently, do not pass an expression with side-effects directly + to this macro. + + :c:macro:`!Py_MAX` corresponds roughly to + :samp:`((({x}) > ({y})) ? ({x}) : ({y}))`. + + .. versionadded:: 3.3 + +.. c:macro:: Py_ARITHMETIC_RIGHT_SHIFT(type, integer, positions) + + Similar to :samp:`{integer} >> {positions{`, but forces sign extension, + as the C standard does not define whether a right-shift of a signed + integer will perform sign extension or a zero-fill. + + *integer* should be any signed integer type. + *positions* is the number of positions to shift to the right. + + Both *integer* and *positions* can be evaluated more than once; + consequently, avoid directly passing a function call or some other + operation with side-effects to this macro. Instead, store the result as a + variable and then pass it. + + *type* is unused and only kept for backwards compatibility. Historically, + *type* was used to cast *integer*. + + .. versionchanged:: 3.1 + + This macro is now valid for all signed integer types, not just those for + which ``unsigned type`` is legal. As a result, *type* is no longer + used. + +.. 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``. + + +Assertion utilities +^^^^^^^^^^^^^^^^^^^ .. c:macro:: Py_UNREACHABLE() @@ -314,7 +314,8 @@ Assertions 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`. + In debug mode, and on unsupported compilers, the macro expands 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 ``_Noreturn``. @@ -327,6 +328,22 @@ Assertions .. versionadded:: 3.7 +.. c:macro:: Py_SAFE_DOWNCAST(value, larger, smaller) + + Cast *value* to type *smaller* from type *larger*, validating that no + information was lost. + + On release builds of Python, this is roughly equivalent to + :samp:`(({smaller}) {value})` + (in C++, :samp:`static_cast<{smaller}>({value})` will be used instead). + + On debug builds (implying that :c:macro:`Py_DEBUG` is defined), this asserts + that no information was lost with the cast from *larger* to *smaller*. + + *value*, *larger*, and *smaller* may all be evaluated more than once in the + expression; consequently, do not pass an expression with side-effects + directly to this macro. + .. c:macro:: Py_BUILD_ASSERT(cond) Asserts a compile-time condition *cond*, as a statement. @@ -352,16 +369,9 @@ Assertions .. versionadded:: 3.3 -Size helpers -^^^^^^^^^^^^ - -.. c:macro:: Py_MEMBER_SIZE(type, member) - Return the size of a structure (*type*) *member* in bytes. - - Corresponds roughly to :samp:`sizeof((({type} *)NULL)->{member})`. - - .. versionadded:: 3.6 +Type size utilities +^^^^^^^^^^^^^^^^^^^ .. c:macro:: Py_ARRAY_LENGTH(array) @@ -376,27 +386,30 @@ Size helpers sizeof(array) / sizeof((array)[0]) -Macro helpers -^^^^^^^^^^^^^ +.. c:macro:: Py_MEMBER_SIZE(type, member) -.. c:macro:: Py_STRINGIFY(x) + Return the size of a structure (*type*) *member* in bytes. - Convert ``x`` to a C string. For example, ``Py_STRINGIFY(123)`` returns - ``"123"``. + Corresponds roughly to :samp:`sizeof((({type} *)NULL)->{member})`. - .. versionadded:: 3.4 + .. versionadded:: 3.6 + + +Macro definition utilities +^^^^^^^^^^^^^^^^^^^^^^^^^^ .. c:macro:: Py_FORCE_EXPANSION(X) - This is equivalent to ``X``, which is useful for token-pasting in + + This is equivalent to :samp:`{X}`, which is useful for token-pasting in macros, as macro expansions in *X* are forcefully evaluated by the preprocessor. -.. c:macro:: Py_GCC_ATTRIBUTE(name) - Use a GCC attribute *name*, hiding it from compilers that don't support GCC - attributes (such as MSVC). +.. c:macro:: Py_STRINGIFY(x) - This expands to ``__attribute__((name))`` on a GCC compiler, and expands - to nothing on compilers that don't support GCC attributes. + Convert ``x`` to a C string. For example, ``Py_STRINGIFY(123)`` returns + ``"123"``. + + .. versionadded:: 3.4 Declaration utilities @@ -515,9 +528,9 @@ Outdated macros The following macros have been used to features that have been standardized in C11. -They are still available for code that uses them. .. c:macro:: Py_ALIGNED(num) + Specify alignment to *num* bytes on compilers that support it. Consider using the C11 standard ``_Alignas`` specifier over this macro. @@ -528,10 +541,10 @@ They are still available for code that uses them. Use *number* as a ``long long`` or ``unsigned long long`` integer literal, respectively. - Expands to *number* followed by `LL`` or ``LLU``, respectively, but will + Expands to *number* followed by ``LL`` or ``LLU``, respectively, but will expand to some compiler-specific suffixes on some older compilers. - Consider using the C99 standard suffixes ``LL` and ``LLU`` directly. + Consider using the C99 standard suffixes ``LL`` and ``LLU`` directly. .. c:macro:: Py_MEMCPY(dest, src, n) From 9de0587faddeef7259965f7ccb83c236a1840e87 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 5 Feb 2026 15:59:38 +0100 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Peter Bierma --- Doc/c-api/intro.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 36bdde5fadfa85..e7ea5b9ba4016c 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -177,7 +177,7 @@ Docstring macros .. c:macro:: PyDoc_STRVAR(name, str) Creates a variable with name *name* that can be used in docstrings. - If Python is built :option:`without docstrings <--without-doc-strings>`, + If Python is built without docstrings (:option:`--without-doc-strings`), the value will be an empty string. Example:: @@ -195,7 +195,7 @@ Docstring macros .. c:macro:: PyDoc_STR(str) Expands to the given input string, or an empty string - if docstrings are :option:`disabled <--without-doc-strings>`. + if docstrings are disabled (:option:`--without-doc-strings`). Example:: @@ -273,7 +273,7 @@ Numeric utilities .. c:macro:: Py_ARITHMETIC_RIGHT_SHIFT(type, integer, positions) - Similar to :samp:`{integer} >> {positions{`, but forces sign extension, + Similar to :samp:`{integer} >> {positions}`, but forces sign extension, as the C standard does not define whether a right-shift of a signed integer will perform sign extension or a zero-fill.