https://github.com/python/cpython/commit/914fbec21458a0344468734489f29254033fafc5 commit: 914fbec21458a0344468734489f29254033fafc5 branch: main author: Peter Bierma <[email protected]> committer: ZeroIntensity <[email protected]> date: 2026-02-04T11:43:47-05:00 summary:
gh-141004: Document remaining `pyport.h` utility macros (GH-144279) Co-authored-by: Bénédikt Tran <[email protected]> Co-authored-by: Victor Stinner <[email protected]> files: M Doc/c-api/intro.rst M Tools/check-c-api-docs/ignored_c_api.txt diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 6886cd85b09a7d..9828e537a90654 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -167,6 +167,35 @@ complete listing. .. versionadded:: 3.3 +.. 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. + +.. 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_ALWAYS_INLINE Ask the compiler to always inline a static inline function. The compiler can @@ -189,6 +218,15 @@ complete listing. .. versionadded:: 3.11 +.. 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 + .. c:macro:: Py_CHARMASK(c) Argument must be a character or an integer in the range [-128, 127] or [0, @@ -206,11 +244,35 @@ complete listing. .. versionchanged:: 3.8 MSVC support was added. +.. c:macro:: Py_FORCE_EXPANSION(X) + + This is equivalent to ``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). + + This expands to ``__attribute__((name))`` on a GCC compiler, and expands + to nothing on compilers that don't support GCC attributes. + .. 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_LL(number) + + Use *number* as a ``long long`` integer literal. + + This usally expands to *number* followed by ``LL``, but will expand to some + compiler-specific suffixes (such as ``I64``) on older compilers. + + In modern versions of Python, this macro is not very useful, as C99 and + later require the ``LL`` suffix to be valid for an integer. + .. c:macro:: Py_LOCAL(type) Declare a function returning the specified *type* using a fast-calling @@ -268,6 +330,22 @@ complete listing. .. versionadded:: 3.11 +.. 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<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_STRINGIFY(x) Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns @@ -275,6 +353,14 @@ complete listing. .. versionadded:: 3.4 +.. c:macro:: Py_ULL(number) + + Similar to :c:macro:`Py_LL`, but *number* will be an ``unsigned long long`` + literal instead. This is done by appending ``U`` to the result of ``Py_LL``. + + In modern versions of Python, this macro is not very useful, as C99 and + later require the ``ULL``/``LLU`` suffixes to be valid for an integer. + .. c:macro:: Py_UNREACHABLE() Use this when you have a code path that cannot be reached by design. @@ -415,6 +501,16 @@ complete listing. This macro is intended for defining CPython's C API itself; extension modules should not use it for their own symbols. +.. c:macro:: Py_VA_COPY + + This is a :term:`soft deprecated` alias to the C99-standard ``va_copy`` + function. + + Historically, this would use a compiler-specific method to copy a ``va_list``. + + .. versionchanged:: 3.6 + This is now an alias to ``va_copy``. + .. _api-objects: diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index e0b2670808c79c..e628bdfebcbded 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -31,15 +31,6 @@ Py_TPFLAGS_IS_ABSTRACT PyExpat_CAPI_MAGIC PyExpat_CAPSULE_NAME # pyport.h -Py_ALIGNED -Py_ARITHMETIC_RIGHT_SHIFT -Py_CAN_START_THREADS -Py_FORCE_EXPANSION -Py_GCC_ATTRIBUTE -Py_LL -Py_SAFE_DOWNCAST -Py_ULL -Py_VA_COPY PYLONG_BITS_IN_DIGIT PY_DWORD_MAX PY_FORMAT_SIZE_T _______________________________________________ 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]
