classification
Title: Add README files in Include/cpython and Include/internal
Type: enhancement Stage: resolved
Components: Documentation, Interpreter Core Versions: Python 3.10
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, erlendaasland, serhiy.storchaka, vstinner
Priority: normal Keywords: patch

Created on 2021-03-06 08:44 by serhiy.storchaka, last changed 2021-03-25 16:35 by vstinner. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 24884 merged erlendaasland, 2021-03-15 21:02
Messages (3)
msg388196 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2021-03-06 08:44
I always hesitate in what subdirectory of Include/ to add a declaration of new private API. What is more "private"? It would be nice to add README files in these directories which describe what API should be declared here and what is the difference between Include/cpython and Include/internal.
msg388280 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2021-03-08 18:41
* Include/internal/ with extern: C API which must not and can not be used outside CPython code base, only stdlib extensions built as built-in extensions can use it.

* Include/internal/ with PyAPI_FUNC/PyAPI_DATA: API which should be be used outside CPython, but exposed for specific use cases like debuggers and profilers. Structures are exposed for debuggers and profilers which don't want to execute code to avoid the risk of any unwanted side effect.

* Include/cpython/: Public C API excluded from the limited C API (Py_LIMITED_API macro) and the stable ABI (PEP 384).

* Include/: Public limited C API and the stable ABI (PEP 384).

In case of doubt, new C API must be added to the internal C API using extern.

I would suggest a public discussion before adding any new C API to Include/cpython/ or Include/

No new functions stealing references or returning borrowed references must be added to public C API (limited or not). A strong reference must be returned.
msg389507 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2021-03-25 16:16
New changeset 929c9039fe0468cb37e0811ddfb7b67c98353ea8 by Erlend Egeberg Aasland in branch 'master':
bpo-43416: Add Include/README.rst (GH-24884)
https://github.com/python/cpython/commit/929c9039fe0468cb37e0811ddfb7b67c98353ea8
History
Date User Action Args
2021-03-25 16:35:39vstinnersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2021-03-25 16:16:38vstinnersetmessages: + msg389507
2021-03-15 21:02:44erlendaaslandsetkeywords: + patch
nosy: + erlendaasland

pull_requests: + pull_request23643
stage: patch review
2021-03-08 18:41:00vstinnersetmessages: + msg388280
2021-03-06 08:44:25serhiy.storchakacreate