Skip to content
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.

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

Explain why the current state of the API is inconsistent #30

Open
vstinner opened this issue Oct 14, 2023 · 3 comments
Open

Explain why the current state of the API is inconsistent #30

vstinner opened this issue Oct 14, 2023 · 3 comments

Comments

@vstinner
Copy link
Contributor

Example: in PR python/cpython#110848 Antoine is surprised that the PyThread_start_new_thread() function is part of the limited C API but is not documented.

We should explain that in the past, we didn't pay much attention to document and tests all limited C API functions, and that some functions were added to the limited C API by mistake. The limited c API was even "the default", before there was a clear cut between limited and non-limited, by creating Include/cpython/ sub-directory.

While the API can be inconsistent, it cannot be changed all sudden. We are not going to remove undocumented functions just because they are undocumented. Documentation can be written. Functions can be removed, but following PEP 387 deprecation process.

The only exception that I saw is when a function is part of the limited C API but cannot be used in the limited C API since it's broken: in that case, it can be removed immediately. I did that for the "trash can" API which was always broken. Same for PyWeakref_GET_OBJECT(): the implementation uses a member of structure whereas the structure is not part of the limited C API.

@vstinner vstinner added the guideline To be included in guidelines PEP label Oct 14, 2023
@gvanrossum
Copy link
Contributor

You can’t remove 100% broken functions from the Stable ABI though. Code may link with them but never call them, or handle an exception gracefully. Right?

@vstinner
Copy link
Contributor Author

I don't think that we removed any stable ABI function so far, the functions only kept as "ABI only" just works. For immortal unicode, it's implemented by leaking memory (Py_INCREF) if i recall correctly. Maybe it could be modified to use immortal ref count now.

I was only talking about the public C API and the limited API, so at the API level.

@encukou
Copy link
Contributor

encukou commented Oct 17, 2023

The guideline label is for the PEP that will list guidelines for new API. The PEP should just say that API should be documented and tested: #31
I'll remove the label from here.

@encukou encukou removed the guideline To be included in guidelines PEP label Oct 17, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants