Add guidelines for C API with output parameters

[erlend-aasland]

---

📚 Documentation preview 📚: https://cpython-devguide--1128.org.readthedocs.build/

[vstinner]

LGTM, I just left some comments

[vstinner]

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?

[vstinner]

LGTM.

[erlend-aasland]

See also python/cpython#108797.

[vstinner]

Do you need a different review? Or are you waiting for something?

[erlend-aasland]

Do you need a different review? Or are you waiting for something?

I think @encukou wants to wait until the sprint before any C API guidelines are updated in any kind of way. Correct me if I'm wrong, Petr.

[vstinner]

I think @encukou wants to wait until the sprint before any C API guidelines are updated in any kind of way. Correct me if I'm wrong, Petr.

Oh, I wasn't aware of that.

[serhiy-storchaka]

Some converters, like _PyEval_SliceIndex(), are designed so that they do not set the output parameter if the argument is None. It allows to set the default value to what you want: 0, -1, PY_SSIZE_T_MAX or Py_SIZE(self). It is the only way, because the signature of such converters is fixed, and they cannot take other arguments.

[erlend-aasland]

Some converters, like _PyEval_SliceIndex(), are designed so that they do not set the output parameter if the argument is None. It allows to set the default value to what you want: 0, -1, PY_SSIZE_T_MAX or Py_SIZE(self). It is the only way, because the signature of such converters is fixed, and they cannot take other arguments.

As I commented on python/cpython#108797, I think the guideline should care only about the general case, not the special case. There will be deviant APIs once in a while; that's ok.

BTW, _PyEval_SliceIndex is exposed through Python.h, but I guess it is considered an internal and/or private API since it is not documented and it is prefixed with an underscore. The guidelines are for public API.

[vstinner]

I think the guideline should care only about the general case, not the special case.

I concur with @erlend-aasland on that.

[vstinner]

FYI there is one public converter :-) PyUnicode_FSConverter().

I tried to move other private ones to the internal C API, but it's quite complicated: python/cpython#106320 (comment) I decided to give up in Python 3.13. I prefer to wait to see what's going on with the limited C API.

[erlend-aasland]

I'll leave this to the C API workgroup.