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.

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

C API: mention the workgroup, and the need to be stricter than our public promises #1524

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

C API: mention the workgroup, and the need to be stricter than our public promises #1524

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4266d92
C API: mention the workgroup, and the need to be stricter than our pu…
encukou Feb 28, 2025
1f33341
Apply suggestions from code review
encukou Feb 28, 2025
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
20 changes: 18 additions & 2 deletions developer-workflow/c-api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,13 @@ The C API is divided into these tiers:
Each tier has different stability and maintenance requirements to consider
when you add or change definitions in it.

The compatibility guarantees for public C API are explained in the
user documentation, ``Doc/c-api/stable.rst`` (:ref:`python:stable`).
The public backwards compatibility guarantees for public C API are explained
in the user documentation, ``Doc/c-api/stable.rst`` (:ref:`python:stable`).
C language compatibility guarantees are in ``Doc/c-api/intro.rst``
(:ref:`python:api-intro`).

Internally, we need to be more careful about compatibility than what we promise
publicly. See :ref:`public-capi` for details.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand this paragraph. What do you mean by "internally"? The internal C API?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps "Within the core development group" is a better phrase than "internally"?

Comment on lines +27 to +28
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would this work?

Suggested change
Internally, we need to be more careful about compatibility than what we promise
publicly. See :ref:`public-capi` for details.
As core developers, we need to be more careful about compatibility than what
we promise publicly. See :ref:`public-capi` for details.



The internal API
Expand Down Expand Up @@ -93,6 +98,17 @@ CPython's public C API is available when ``Python.h`` is included normally
It should be defined in ``Include/cpython/`` (unless part of the Limited API,
see below).

Before adding new public API, please ask in the `decisions repo`_ of
the :pep:`C API workgroup <731>`.
This helps us ensure *newly added* API is consistent and maintainable.

Also check with the C API WG before requiring a C feature not present in C99.
While the *public* docs only promise compatibility with C11, in practice
we only intruduce C11 features individually as needed.

.. _decisions repo: https://github.com/capi-workgroup/decisions/issues


.. _public-api-guidelines:

Guidelines for expanding/changing the public API
Expand Down
Loading