Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
encukou merged 11 commits into from
Jan 13, 2026
Merged

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

Changes from 2 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
1cfd683
first exports
Yashp002 Jan 7, 2026
0164c79
exports fix 1
Yashp002 Jan 7, 2026
d0c5c25
exports fix 2
Yashp002 Jan 7, 2026
d3e69b6
exports fix 3
Yashp002 Jan 8, 2026
68269d3
exports fix 4
Yashp002 Jan 8, 2026
113ff5e
exports fix 5
Yashp002 Jan 8, 2026
9eb597b
exports fix 6
Yashp002 Jan 8, 2026
6b9df7f
exports fix 7
Yashp002 Jan 8, 2026
26cffa2
exports fix 8
Yashp002 Jan 8, 2026
6c59e9b
exports fix 9
Yashp002 Jan 9, 2026
2f24241
exports fix 10
Yashp002 Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions Doc/c-api/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -376,6 +376,40 @@ complete listing.
sizeof(array) / sizeof((array)[0])


.. 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
Comment thread
Yashp002 marked this conversation as resolved.
Resolved
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.

@encukou encukou Jan 7, 2026

Copy link
Copy Markdown
Member

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.

Comment thread
Yashp002 marked this conversation as resolved.
Resolved


.. c:macro:: PyAPI_DATA(type)
Comment thread
encukou marked this conversation as resolved.
Resolved

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.

@vstinner vstinner Jan 8, 2026

Copy link
Copy Markdown
Member

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

@Yashp002 Yashp002 Jan 8, 2026

Copy link
Copy Markdown
Contributor Author

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

Comment thread
Yashp002 marked this conversation as resolved.
Resolved

Example usage::

PyAPI_DATA(PyObject *) _Py_NoneStruct;
Comment thread
Yashp002 marked this conversation as resolved.
Resolved


.. c:macro:: Py_LOCAL_SYMBOL

@encukou encukou Jan 7, 2026

Copy link
Copy Markdown
Member

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?

@encukou encukou Jan 7, 2026

Copy link
Copy Markdown
Member

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.


Macro used to declare a symbol as local to the shared library (hidden).
It ensures the symbol is not exported.
On platforms with visibility support, it
expands to ``__attribute__((visibility("hidden")))``.


.. _api-objects:

Objects, Types and Reference Counts
Expand Down
Loading