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.
Doc/c-api/intro.rst
Outdated
| .. 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. |
| 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.
Co-authored-by: Petr Viktorin <[email protected]>
Co-authored-by: Petr Viktorin <[email protected]>
Co-authored-by: Petr Viktorin <[email protected]>
Co-authored-by: Petr Viktorin <[email protected]>
| 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. |
There was a problem hiding this comment.
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."
There was a problem hiding this comment.
gonna push a PR for the manual changes in a bit yes, thank you for the corrections
Co-authored-by: Victor Stinner <[email protected]>
4 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/