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 1 commit
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
Next Next commit
first exports
  • Loading branch information
@Yashp002
Yashp002 committed Jan 7, 2026
commit 1cfd6837e6d580ac62d4fa860b32bdd79743c48d
33 changes: 33 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,39 @@ 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.
Outdated
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.
Comment thread
Yashp002 marked this conversation as resolved.
Outdated


.. c:macro:: PyAPI_DATA(type)
Comment thread
encukou marked this conversation as 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.
Outdated

Example usage::

PyAPI_DATA(PyObject *) _Py_NoneStruct;


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