From ba7ce7b6c09690696df3d4df596fca86f52a75e6 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 26 Jun 2023 20:58:43 +0200 Subject: [PATCH 1/6] Improve C API guidelines for return values Clarify that returning an error indicator should be done iff an exception is raised. For functions returning an int, a _negative value_ should be returned. Suggest -1 unless there is a need to distinguish between error types. --- developer-workflow/c-api.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index 103abe7b0a..cbecf8b085 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -110,9 +110,11 @@ Guidelines for expanding/changing the public API 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. + and ``NULL`` if and only if an exception is raised. + Most other API must return ``0`` on success, + and a negative value if and only if an exception is raised. + Unless there is need to distinguish between error types, + ``-1`` should be used as the error value. - APIs with lesser and greater results must return ``0`` for the lesser result, and ``1`` for the greater result. From d45cfd15d7638b276e5e6a792313ed3b1c5a991f Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 26 Jun 2023 21:11:15 +0200 Subject: [PATCH 2/6] Commas --- 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 cbecf8b085..8689f867c5 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -110,9 +110,9 @@ Guidelines for expanding/changing the public API fields, arguments and return values are well defined. - Functions returning ``PyObject *`` must return a valid pointer on success, - and ``NULL`` if and only if an exception is raised. + and ``NULL`` if, and only if, an exception is raised. Most other API must return ``0`` on success, - and a negative value if and only if an exception is raised. + and a negative value if, and only if, an exception is raised. Unless there is need to distinguish between error types, ``-1`` should be used as the error value. From 01335f54efcffcb3a93a05bc64c57e238e5c14f1 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 28 Aug 2023 08:44:11 +0200 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- 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 8689f867c5..cbecf8b085 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -110,9 +110,9 @@ Guidelines for expanding/changing the public API fields, arguments and return values are well defined. - Functions returning ``PyObject *`` must return a valid pointer on success, - and ``NULL`` if, and only if, an exception is raised. + and ``NULL`` if and only if an exception is raised. Most other API must return ``0`` on success, - and a negative value if, and only if, an exception is raised. + and a negative value if and only if an exception is raised. Unless there is need to distinguish between error types, ``-1`` should be used as the error value. From b045b03732d4a7624bea213a1a1ee1cfc835d402 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 31 Aug 2023 22:35:48 +0200 Subject: [PATCH 4/6] Update developer-workflow/c-api.rst Co-authored-by: Petr Viktorin --- developer-workflow/c-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index cbecf8b085..6230b86adf 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -111,7 +111,7 @@ Guidelines for expanding/changing the public API - Functions returning ``PyObject *`` must return a valid pointer on success, and ``NULL`` if and only if an exception is raised. - Most other API must return ``0`` on success, + Other API must return ``0`` on success, and a negative value if and only if an exception is raised. Unless there is need to distinguish between error types, ``-1`` should be used as the error value. From 95b59518f8eb8945c824e30e8e5e1a211f48bbd5 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 6 Sep 2023 23:12:18 +0200 Subject: [PATCH 5/6] Update developer-workflow/c-api.rst --- 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 6230b86adf..c97ef97695 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -113,8 +113,8 @@ Guidelines for expanding/changing the public API and ``NULL`` if and only if an exception is raised. Other API must return ``0`` on success, and a negative value if and only if an exception is raised. - Unless there is need to distinguish between error types, - ``-1`` should be used as the error value. + ``-1`` should be used as the error value; + the caller should use the C idiom ``if (func() < 0)`` to check for errors. - APIs with lesser and greater results must return ``0`` for the lesser result, and ``1`` for the greater result. From 8049811636f303820607f1a0ef1969e830fd6390 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 13 Sep 2023 10:37:29 +0200 Subject: [PATCH 6/6] Update developer-workflow/c-api.rst Co-authored-by: Victor Stinner --- developer-workflow/c-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index c97ef97695..7b727a7352 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -111,7 +111,7 @@ Guidelines for expanding/changing the public API - Functions returning ``PyObject *`` must return a valid pointer on success, and ``NULL`` if and only if an exception is raised. - Other API must return ``0`` on success, + Other API must return an ``int``: return ``0`` on success, and a negative value if and only if an exception is raised. ``-1`` should be used as the error value; the caller should use the C idiom ``if (func() < 0)`` to check for errors.