From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sat, 8 Nov 2025 19:28:32 +0000 (+0100)
Subject: [3.13] gh-141004: Document `Py_BUILD_ASSERT*` macros (GH-141266) (GH-141270)
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=refs%2Fheads%2F3.13;p=thirdparty%2FPython%2Fcpython.git

[3.13] gh-141004: Document `Py_BUILD_ASSERT*` macros (GH-141266) (GH-141270)

gh-141004: Document `Py_BUILD_ASSERT*` macros (GH-141266)
(cherry picked from commit 0ac890bea79d3e0162c8909b0999f626f1141d89)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
---

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index b4a0fa74ffe..22ad080828b 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -245,6 +245,29 @@ complete listing.
 
    .. versionadded:: 3.4
 
+.. 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.
+
+   For example::
+
+      Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));
+
+   .. versionadded:: 3.3
+
+.. c:macro:: Py_BUILD_ASSERT_EXPR(cond)
+
+   Asserts a compile-time condition *cond*, as an expression that evaluates to ``0``.
+   The build will fail if the condition is false or cannot be evaluated at compile time.
+
+   For example::
+
+      #define foo_to_char(foo) \
+          ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))
+
+   .. versionadded:: 3.3
+
 .. c:macro:: PyDoc_STRVAR(name, str)
 
    Creates a variable with name *name* that can be used in docstrings.
diff --git a/Doc/conf.py b/Doc/conf.py
index 8d1d0821a7b..611e0dac7f9 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -225,9 +225,6 @@ nitpick_ignore = [
 # Temporary undocumented names.
 # In future this list must be empty.
 nitpick_ignore += [
-    # Undocumented public C macros
-    ('c:macro', 'Py_BUILD_ASSERT'),
-    ('c:macro', 'Py_BUILD_ASSERT_EXPR'),
     # Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
     # be resolved, as the method is currently undocumented. For context, see
     # https://github.com/python/cpython/pull/103289.