diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index 103abe7b0..d2816378b 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -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); + // Error case + if (rc < 0) { + *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::