gh-141004: Document symbol visibility macros (PyAPI_DATA, Py_EXPORTED_SYMBOL, Py_LOCAL_SYMBOL,Py_IMPORTED_SYMBOL) by Yashp002 · Pull Request #143508 · python/cpython

Yashp002 · 2026-01-07T07:21:57Z

This PR documents several symbol visibility macros that were identified as undocumented in issue #141004. These macros are defined in Include/exports.h and are used to control symbol visibility and linkage (dllexport/dllimport) across platforms.

Macros documented in Doc/c-api/intro.rst:

Py_EXPORTED_SYMBOL
Py_IMPORTED_SYMBOL
Py_LOCAL_SYMBOL
PyAPI_DATA

Issue: Document the entire C API #141004

📚 Documentation preview 📚: https://cpython-previews--143508.org.readthedocs.build/

encukou · 2026-01-07T08:04:14Z

Doc/c-api/intro.rst

+      PyAPI_DATA(PyObject *) _Py_NoneStruct;
+
+
+.. c:macro:: Py_LOCAL_SYMBOL


Could you move this next to the other Py_LOCAL macros, and ideally match their style?

I guess Py_ALWAYS_INLINE, Py_DEPRECATED, Py_LOCAL, Py_LOCAL_INLINE, all of these, and possibly Py_UNUSED, could be moved to a new section. But that can be in a new PR.

Doc/c-api/intro.rst

encukou · 2026-01-07T08:22:28Z

Doc/c-api/intro.rst

+.. c:macro:: Py_EXPORTED_SYMBOL
+
+   Macro used to declare a symbol (function or data) as exported from a shared library.
+   On Windows, this expands to ``__declspec(dllexport)``.
+   On other platforms with visibility support, it
+   expands to ``__attribute__((visibility("default")))``.
+
+
+.. c:macro:: Py_IMPORTED_SYMBOL
+
+   Macro used to declare a symbol as imported from a shared library.
+   On Windows, this expands to ``__declspec(dllimport)``.
+   On other platforms, it is usually empty or standard visibility.


“from a shared library” is not true: these depend on whether CPython's own C API is provided as a shared library.

The docs should say that these are for defining the C API itself; users shouldn't use them for their own symbols.

Yashp002 · 2026-01-07T19:12:22Z

@encukou I think I've done all the necessary changes you asked for, could you verify it.

Doc/c-api/intro.rst

Co-authored-by: Petr Viktorin <encukou@gmail.com>

vstinner · 2026-01-08T17:24:36Z

Doc/c-api/intro.rst

+
+   Macro used to declare a public global variable.
+   It expands to ``extern Py_EXPORTED_SYMBOL type`` or ``extern Py_IMPORTED_SYMBOL type``
+   depending on whether the core is being built or used.


I would also add:

"This macro is intended for defining CPython's C API itself; extension modules should not use it for their own symbols."

gonna push a PR for the manual changes in a bit yes, thank you for the corrections

Co-authored-by: Victor Stinner <vstinner@python.org>

Doc/c-api/intro.rst

Co-authored-by: Petr Viktorin <encukou@gmail.com>

miss-islington-app · 2026-01-13T12:15:06Z

Thanks @Yashp002 for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

bedevere-app · 2026-01-13T12:15:20Z

GH-143786 is a backport of this pull request to the 3.14 branch.

…PORTED_SYMBOL, Py_LOCAL_SYMBOL,Py_IMPORTED_SYMBOL) (pythonGH-143508) (cherry picked from commit a7ba3b1) Co-authored-by: Yashraj <yashrajpala8@gmail.com> Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Victor Stinner <vstinner@python.org>

bedevere-app · 2026-01-13T12:15:25Z

GH-143787 is a backport of this pull request to the 3.13 branch.

…XPORTED_SYMBOL, Py_LOCAL_SYMBOL,Py_IMPORTED_SYMBOL) (GH-143508) (GH-143786) (cherry picked from commit a7ba3b1) Co-authored-by: Yashraj <yashrajpala8@gmail.com> Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Victor Stinner <vstinner@python.org>

…XPORTED_SYMBOL, Py_LOCAL_SYMBOL,Py_IMPORTED_SYMBOL) (GH-143508) (GH-143787) (cherry picked from commit a7ba3b1) Co-authored-by: Yashraj <yashrajpala8@gmail.com> Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Victor Stinner <vstinner@python.org>

first exports

1cfd683

bedevere-app bot added docs Documentation in the Doc dir skip news labels Jan 7, 2026

github-project-automation bot added this to Docs PRs Jan 7, 2026

github-project-automation bot moved this to Todo in Docs PRs Jan 7, 2026

bedevere-app bot added the awaiting review label Jan 7, 2026

bedevere-app bot mentioned this pull request Jan 7, 2026

Document the entire C API #141004

Open

exports fix 1

0164c79

encukou reviewed Jan 7, 2026

View reviewed changes

ZeroIntensity added topic-C-API needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Jan 7, 2026

exports fix 2

d0c5c25

encukou reviewed Jan 8, 2026

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Doc/c-api/intro.rst Show resolved Hide resolved

vstinner reviewed Jan 8, 2026

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Yashp002 and others added 4 commits January 8, 2026 22:42

exports fix 3

d3e69b6

Co-authored-by: Petr Viktorin <encukou@gmail.com>

exports fix 4

68269d3

Co-authored-by: Petr Viktorin <encukou@gmail.com>

exports fix 5

113ff5e

Co-authored-by: Petr Viktorin <encukou@gmail.com>

exports fix 6

9eb597b

Co-authored-by: Petr Viktorin <encukou@gmail.com>

vstinner reviewed Jan 8, 2026

View reviewed changes

Yashp002 and others added 2 commits January 8, 2026 23:01

exports fix 7

6b9df7f

Co-authored-by: Victor Stinner <vstinner@python.org>

exports fix 8

26cffa2

Yashp002 requested a review from ZeroIntensity as a code owner January 8, 2026 17:37

encukou reviewed Jan 9, 2026

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Yashp002 and others added 2 commits January 9, 2026 16:43

exports fix 9

6c59e9b

Co-authored-by: Petr Viktorin <encukou@gmail.com>

exports fix 10

2f24241

Co-authored-by: Petr Viktorin <encukou@gmail.com>

encukou merged commit a7ba3b1 into python:main Jan 13, 2026
55 checks passed

github-project-automation bot moved this from Todo to Done in Docs PRs Jan 13, 2026

bedevere-app bot removed the awaiting review label Jan 13, 2026

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Jan 13, 2026

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Jan 13, 2026

encukou mentioned this pull request Feb 4, 2026

gh-141004: Reorganize and reword the 'Useful macros' section #144471

Open

		PyAPI_DATA(PyObject *) _Py_NoneStruct;


		.. c:macro:: Py_LOCAL_SYMBOL

Uh oh!

Conversation

Yashp002 commented Jan 7, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

encukou Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

encukou Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

encukou Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Yashp002 commented Jan 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vstinner Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Yashp002 Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

miss-islington-app bot commented Jan 13, 2026

Uh oh!

bedevere-app bot commented Jan 13, 2026

Uh oh!

bedevere-app bot commented Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Yashp002 commented Jan 7, 2026 •

edited by github-actions bot

Loading