From 91c2a05189a017c4d5a6ea7b44c04568a932b20b Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 23 Jun 2023 13:43:53 +0200 Subject: [PATCH 1/4] Add guidelines for C API return values --- developer-workflow/c-api.rst | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index d9078d24f..571337601 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -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 @@ -106,6 +109,20 @@ 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 that return a ``PyObject *`` pointer 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. C API Tests ----------- @@ -292,10 +309,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. From e4959a346142674e666faf37b6988b328a5bdd0b Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 23 Jun 2023 13:50:06 +0200 Subject: [PATCH 2/4] Be explicit about what a return value is --- developer-workflow/c-api.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index 571337601..424fa3d7a 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -124,6 +124,10 @@ Guidelines for expanding/changing the public API Please start a public discussion if these guidelines won't work for your API. +.. note:: + + With *return value*, we mean the value returned by the *C return statement*. + C API Tests ----------- From 1baa415d6a75dc5262c0856ea4355f05607b4f4d Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 23 Jun 2023 13:55:18 +0200 Subject: [PATCH 3/4] Wording --- developer-workflow/c-api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index 424fa3d7a..b268930fb 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -109,8 +109,8 @@ 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 that return a ``PyObject *`` pointer must return a valid pointer - on success and ``NULL`` with an exception raised on error. +- 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. From 8458b6fabc9706fdc4bc3a950ce50271369151cb Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 24 Jun 2023 00:45:05 +0200 Subject: [PATCH 4/4] Apply suggestions from CAM's review Co-authored-by: C.A.M. Gerlach --- developer-workflow/c-api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index b268930fb..103abe7b0 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -109,7 +109,7 @@ 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 +- 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. @@ -126,7 +126,7 @@ Please start a public discussion if these guidelines won't work for your API. .. note:: - With *return value*, we mean the value returned by the *C return statement*. + By *return value*, we mean the value returned by the *C return statement*. C API Tests -----------