gh-141004: Document symbol visibility macros (PyAPI_DATA, Py_EXPORTED_SYMBOL, Py_LOCAL_SYMBOL,Py_IMPORTED_SYMBOL) #143508
Conversation
Doc/c-api/intro.rst
Outdated
| PyAPI_DATA(PyObject *) _Py_NoneStruct; | ||
|
|
||
|
|
||
| .. c:macro:: Py_LOCAL_SYMBOL |
There was a problem hiding this comment.
Could you move this next to the other Py_LOCAL macros, and ideally match their style?
There was a problem hiding this comment.
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.
| On other platforms, it is usually empty or standard visibility. | ||
|
|
||
|
|
||
| .. c:macro:: PyAPI_DATA(type) |
There was a problem hiding this comment.
If we document this, we should also document PyAPI_FUNC.
Again, this is for defining the C API itself; users shouldn't use it for their own data.
There was a problem hiding this comment.
This should be similar to the docs for PyAPI_FUNC.
| .. 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. |
There was a problem hiding this comment.
“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
added
topic-C-API
needs backport to 3.13
|
@encukou I think I've done all the necessary changes you asked for, could you verify it. |
| It ensures the symbol is not exported. | ||
| On platforms with visibility support, it | ||
| expands to ``__attribute__((visibility("hidden")))``. |
There was a problem hiding this comment.
This is platform-specific, and not really guaranteed everywhere.
| It ensures the symbol is not exported. | |
| On platforms with visibility support, it | |
| expands to ``__attribute__((visibility("hidden")))``. | |
| On supported platforms, it ensures the symbol is not exported. | |
| On compatible versions of GCC/Clang, it | |
| expands to ``__attribute__((visibility("hidden")))``. |
| Macro used to declare a symbol (function or data) as exported. | ||
| On Windows, this expands to ``__declspec(dllexport)``. | ||
| On other platforms with visibility support, it |
There was a problem hiding this comment.
Not sure what you mean “platforms with visibility support”. Would it work to mention the compiler directly?
| On other platforms with visibility support, it | |
| On compatible versions of GCC/Clang, it |
(same below)
| Macro used to declare a symbol as imported. | ||
| On Windows, this expands to ``__declspec(dllimport)``. | ||
| On other platforms, it is usually empty or standard visibility. |
There was a problem hiding this comment.
I think we can remove this.
| On other platforms, it is usually empty or standard visibility. |
As I see it, the main reason for the expansions is so that the reader can look up the behaviour in compiler docs.
| Macro used by CPython to declare a function as part of the C API. | ||
| Its expansion depends on the platform and build configuration. | ||
| This macro is intended for defining CPython's C API itself; | ||
| extension modulesshould not use it for their own symbols. |
There was a problem hiding this comment.
| extension modulesshould not use it for their own symbols. | |
| extension modules should not use it for their own symbols. |
| On other platforms, it is usually empty or standard visibility. | ||
|
|
||
|
|
||
| .. c:macro:: PyAPI_DATA(type) |
There was a problem hiding this comment.
This should be similar to the docs for PyAPI_FUNC.
3 participants
This PR documents several symbol visibility macros that were identified as undocumented in issue #141004. These macros are defined in
Include/exports.hand are used to control symbol visibility and linkage (dllexport/dllimport) across platforms.Macros documented in
Doc/c-api/intro.rst:Py_EXPORTED_SYMBOLPy_IMPORTED_SYMBOLPy_LOCAL_SYMBOLPyAPI_DATA📚 Documentation preview 📚: https://cpython-previews--143508.org.readthedocs.build/