8000 Add guidelines for C API return values (#1123) · python/devguide@3f08d25 · GitHub
[go: up one dir, main page]

Skip to content

Commit 3f08d25

Browse files
Add guidelines for C API return values (#1123)
1 parent 13dc964 commit 3f08d25

File tree

1 file changed

+25
-1
lines changed

1 file changed

+25
-1
lines changed

developer-workflow/c-api.rst

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,10 @@ CPython's public C API is available when ``Python.h`` is included normally
9393
It should be defined in ``Include/cpython/`` (unless part of the Limited API,
9494
see below).
9595

96-
Guidelines for expanding/changing the public API:
96+
.. _public-api-guidelines:
97+
98+
Guidelines for expanding/changing the public API
99+
------------------------------------------------
97100

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

112+
- Functions returning ``PyObject *`` must return a valid pointer on success,
113+
and ``NULL`` with an exception raised on error.
114+
Most other API must return ``-1`` with an exception raised on error,
115+
and ``0`` on success.
116+
117+
- APIs with lesser and greater results must return ``0`` for the lesser result,
118+
and ``1`` for the greater result.
119+
Consider a lookup function with a three-way return:
120+
121+
- ``return -1``: internal error or API misuse; exception raised
122+
- ``return 0``: lookup succeeded; no item was found
123+
- ``return 1``: lookup succeeded; item was found
124+
125+
Please start a public discussion if these guidelines won't work for your API.
126+
127+
.. note::
128+
129+
By *return value*, we mean the value returned by the *C return statement*.
109130

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

294315

316+
.. _limited-api-guidelines:
317+
295318
Guidelines for adding to the Limited API
296319
----------------------------------------
2973 54C3 20

298321
- Guidelines for the general :ref:`public-capi` apply.
322+
See :ref:`public-api-guidelines`.
299323

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

0 commit comments

Comments
 (0)
0