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

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/

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.

“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.

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

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

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>

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

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

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>

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>

…PORTED_SYMBOL, Py_LOCAL_SYMBOL,Py_IMPORTED_SYMBOL) (pythonGH-143508) 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

Comment thread Doc/c-api/intro.rst Outdated

Comment thread Doc/c-api/intro.rst Outdated

Comment thread Doc/c-api/intro.rst Outdated

Comment thread Doc/c-api/intro.rst Outdated

Comment thread Doc/c-api/intro.rst

vstinner reviewed Jan 8, 2026

View reviewed changes

Comment thread Doc/c-api/intro.rst Outdated

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

Comment thread Doc/c-api/intro.rst Outdated

Comment thread Doc/c-api/intro.rst Outdated

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

Merged

+              .. 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.

		PyAPI_DATA(PyObject *) _Py_NoneStruct;


		.. c:macro:: Py_LOCAL_SYMBOL

+                 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.

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

Uh oh!

Uh oh!

gh-141004: Document symbol visibility macros (PyAPI_DATA, Py_EXPORTED_SYMBOL, Py_LOCAL_SYMBOL,Py_IMPORTED_SYMBOL) - #143508

gh-141004: Document symbol visibility macros (PyAPI_DATA, Py_EXPORTED_SYMBOL, Py_LOCAL_SYMBOL,Py_IMPORTED_SYMBOL)#143508encukou merged 11 commits intopython:mainpython/cpython:mainfrom Yashp002:doc-exportsYashp002/cpython:doc-exportsCopy head branch name to clipboard

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

gh-141004: Document symbol visibility macros (PyAPI_DATA, Py_EXPORTED_SYMBOL, Py_LOCAL_SYMBOL,Py_IMPORTED_SYMBOL)#143508
encukou merged 11 commits into
python:mainfrom
Yashp002:doc-exports

Yashp002 commented Jan 7, 2026 •
edited by github-actions Bot
Loading