Skip to content

Add guidelines for C API return values #1123

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

Merged
merged 4 commits into from
Jun 26, 2023
Merged

Add guidelines for C API return values #1123

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
91c2a05
Add guidelines for C API return values
erlend-aasland Jun 23, 2023
e4959a3
Be explicit about what a return value is
erlend-aasland Jun 23, 2023
1baa415
Wording
erlend-aasland Jun 23, 2023
8458b6f
Apply suggestions from CAM's review
erlend-aasland Jun 23, 2023
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
26 changes: 25 additions & 1 deletion developer-workflow/c-api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,10 @@ 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).

Guidelines for expanding/changing the public API:
.. _public-api-guidelines:

Guidelines for expanding/changing the public API
------------------------------------------------

- Make sure the new API follows reference counting conventions.
(Following them makes the API easier to reason about, and easier use
Expand All @@ -106,6 +109,24 @@ Guidelines for expanding/changing the public API:
- Make sure the ownership rules and lifetimes of all applicable struct
fields, arguments and return values are well defined.

- Functions returning ``PyObject *`` must return a valid pointer on success,
and ``NULL`` with an exception raised on error.
Most other API must return ``-1`` with an exception raised on error,
and ``0`` on success.

- APIs with lesser and greater results must return ``0`` for the lesser result,
and ``1`` for the greater result.
Consider a lookup function with a three-way return:

- ``return -1``: internal error or API misuse; exception raised
- ``return 0``: lookup succeeded; no item was found
- ``return 1``: lookup succeeded; item was found

Please start a public discussion if these guidelines won't work for your API.

.. note::

By *return value*, we mean the value returned by the *C return statement*.

C API Tests
-----------
Expand Down Expand Up @@ -292,10 +313,13 @@ It is possible to remove items marked as part of the Stable ABI, but only
if there was no way to use them in any past version of the Limited API.


.. _limited-api-guidelines:

Guidelines for adding to the Limited API
----------------------------------------

- Guidelines for the general :ref:`public-capi` apply.
See :ref:`public-api-guidelines`.

- New Limited API should only be defined if ``Py_LIMITED_API`` is set
to the version the API was added in or higher.
Expand Down