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.

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

Add guidelines for C API with output parameters #1128

Closed
Changes from all commits
Commits
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: 26 additions & 0 deletions developer-workflow/c-api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,32 @@ Guidelines for expanding/changing the public API
- ``return 0``: lookup succeeded; no item was found
- ``return 1``: lookup succeeded; item was found

- APIs with output parameters should ensure that each output parameter is
initialized for all code paths.
Example:

.. code-block:: c

int
PyFoo_Bar(PyObject **out)
{
PyObject *value;
int rc = foo_bar(&value);
Copy link
Member

@vstinner vstinner Jun 26, 2023

Choose a reason for hiding this comment

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

Maybe you could mimic a legacy API call which returns NULL if not found and on error, and call PyErr_Occurred(). So the difference with the two APIs is even more obvious?

// Error case
if (rc < 0) {
erlend-aasland marked this conversation as resolved.
Show resolved Hide resolved
*out = NULL;
return -1;
}
// Not found (lesser result)
if (rc == 0) {
*out = NULL;
return 0;
}
// Found (greater result)
*out = Py_NewRef(value);
return 1;
}

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

.. note::
Expand Down