From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Thu, 15 Jan 2026 12:34:27 +0000 (+0100)
Subject: [3.14] gh-141004: Document symbol visibility macros (PyAPI_DATA, Py_EXPORTED_SYMBOL... 
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=37c4a6551a5773971f15cf43475d36bd69f8bdf9;p=thirdparty%2FPython%2Fcpython.git

[3.14] gh-141004: Document symbol visibility macros (PyAPI_DATA, Py_EXPORTED_SYMBOL, Py_LOCAL_SYMBOL,Py_IMPORTED_SYMBOL) (GH-143508) (GH-143786)

(cherry picked from commit a7ba3b124f707f73b94b59f13908872f1a48e24f)

Co-authored-by: Yashraj <yashrajpala8@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
---

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 3a0c4c8e9606..c7520adc1214 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -182,6 +182,14 @@ complete listing.
    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``.
@@ -336,6 +344,38 @@ complete listing.
       sizeof(array) / sizeof((array)[0])
 
 
+.. c:macro:: Py_EXPORTED_SYMBOL
+
+   Macro used to declare a symbol (function or data) as exported.
+   On Windows, this expands to ``__declspec(dllexport)``.
+   On compatible versions of GCC/Clang, it
+   expands to ``__attribute__((visibility("default")))``.
+   This macro is for defining the C API itself; extension modules should not use it.
+
+
+.. c:macro:: Py_IMPORTED_SYMBOL
+
+   Macro used to declare a symbol as imported.
+   On Windows, this expands to ``__declspec(dllimport)``.
+   This macro is for defining the C API itself; extension modules should not use it.
+
+
+.. c:macro:: PyAPI_FUNC(type)
+
+   Macro used by CPython to declare a function as part of the C API.
+   Its expansion depends on the platform and build configuration.
+   This macro is intended for defining CPython's C API itself;
+   extension modules should not use it for their own symbols.
+
+
+.. c:macro:: PyAPI_DATA(type)
+
+   Macro used by CPython to declare a public global variable as part of the C API.
+   Its expansion depends on the platform and build configuration.
+   This macro is intended for defining CPython's C API itself;
+   extension modules should not use it for their own symbols.
+
+
 .. _api-objects:
 
 Objects, Types and Reference Counts
diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt
index 02b94cb0dc89..c23784d7e112 100644
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/Tools/check-c-api-docs/ignored_c_api.txt
@@ -18,11 +18,6 @@ Py_HasFileSystemDefaultEncoding
 Py_UTF8Mode
 # pyhash.h
 Py_HASH_EXTERNAL
-# exports.h
-PyAPI_DATA
-Py_EXPORTED_SYMBOL
-Py_IMPORTED_SYMBOL
-Py_LOCAL_SYMBOL
 # modsupport.h
 PyABIInfo_FREETHREADING_AGNOSTIC
 # moduleobject.h