Document the preferred naming convention for new API
erlend-aasland opened this issue · comments
We need a naming convention for new versions of an existing API. Illustrated by an example:
PyFoo_Bar()
is a problematic API; it returns a borrowed reference, suppresses arbitrary exceptions, and requires callers to check PyErr_Occurred()
to find out if an exception was raised. A PR now exists to replace PyFoo_Bar()
with a new and non-problematic API, but unfortunately that PR cannot be merged, because unlike the implementation of the new API, there is no consensus on the naming of the new API; after all, PyFoo_Bar()
is the perfect name. How to proceed?
@vstinner has suggested to add a Ref suffix when fixing APIs that return borrowed references1.
I propose to follow the SQLite practise of adding a version specifier2 if an API is replaced.
Footnotes
In capi-workgroup/problems#52 (comment), @vstinner points out that there is already precedent for using the number suffix in the Python C API.
Closing as not planned. See also capi-workgroup/problems#52 (comment).