Search code, repositories, users, issues, pull requests...

Copy link

Contributor

@Yashp002 Yashp002 commented Jan 7, 2026 •

edited by github-actions bot

Loading

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/


 first exports

1cfd683

@bedevere-app bedevere-app bot added docs skip news labels

@github-project-automation github-project-automation bot added this to Docs PRs

@github-project-automation github-project-automation bot moved this to Todo in Docs PRs

@bedevere-app bedevere-app bot added the awaiting review label

@bedevere-app bedevere-app bot mentioned this pull request

Document the entire C API #141004

Open


 exports fix 1

0164c79

encukou

encukou reviewed

Doc/c-api/intro.rst Outdated

PyAPI_DATA(PyObject *) _Py_NoneStruct;

.. c:macro:: Py_LOCAL_SYMBOL

Copy link

Member

@encukou encukou Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Member

@encukou encukou Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Show resolved Hide resolved

Doc/c-api/intro.rst Outdated

Comment on lines 379 to 391

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

Copy link

Member

@encukou encukou Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@ZeroIntensity ZeroIntensity added topic-C-API needs backport to 3.13 needs backport to 3.14 labels


 exports fix 2

d0c5c25

Copy link

Contributor Author

Yashp002 commented Jan 7, 2026

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

encukou

encukou reviewed

Jan 8, 2026

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

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

vstinner

vstinner reviewed

Jan 8, 2026

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

vstinner reviewed

Jan 8, 2026

Doc/c-api/intro.rst Outdated

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.

Copy link

Member

@vstinner vstinner Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Contributor Author

@Yashp002 Yashp002 Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Yashp002 and others added 2 commits

January 8, 2026 23:01

@Yashp002 @vstinner


 exports fix 7

6b9df7f

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


 exports fix 8

26cffa2

@Yashp002 Yashp002 requested a review from ZeroIntensity as a code owner

January 8, 2026 17:37

encukou

encukou reviewed

Jan 9, 2026

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 encukou merged commit a7ba3b1 into python:main

55 checks passed

@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs

@miss-islington-app

Copy link

miss-islington-app bot commented Jan 13, 2026

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 bedevere-app bot removed the awaiting review label

@bedevere-app

Copy link

bedevere-app bot commented Jan 13, 2026

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

@bedevere-app bedevere-app bot removed the needs backport to 3.14 label

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request

@Yashp002 @encukou @vstinner @miss-islington


 pythongh-141004 : Document symbol visibility macros (PyAPI_DATA, Py_EX...

2f9fc90

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request

@Yashp002 @encukou @vstinner @miss-islington


 pythongh-141004 : Document symbol visibility macros (PyAPI_DATA, Py_EX...

9d63266

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

Copy link

bedevere-app bot commented Jan 13, 2026

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

@bedevere-app bedevere-app bot removed the needs backport to 3.13 label