On Thu, Mar 25, 2021 at 11:58 AM Mark Shannon <m...@hotpy.org> wrote:
> Hi Victor, > > I'm with you 100% on not returning borrowed references, doing so is just > plain dangerous. > > However, is a blanket ban on stealing references the right thing? > > Maybe the problem is the term "stealing". > The caller is transferring the reference to the callee. > In some circumstances it can make a lot of sense to do so, since the > caller has probably finished with the reference and the callee needs a > new one. > > Cheers, > Mark. > When was the last time a non-internal API that transferred references added? I suggest keeping the restriction on new APIs in place until we actually find a situation where we think we "need" one outside of Include/internal/ to help force the discussion as to why that needs to be public. -gps On 25/03/2021 4:27 pm, Victor Stinner wrote: > > Hi, > > > > A new Include/README.rst file was just added to document the 3 C API > > provided by CPython: > > > > * Include/: Limited C API > > * Include/cpython/: CPython implementation details > > * Include/internal/: The internal API > > > > I would like to note that *new* public C API functions must no longer > > steal references or return borrowed references. > > > > Don't worry, there is no plan to deprecate or remove existing > > functions which do that, like PyModule_AddObject() (streal a > > reference) or PyDict_GetItem() (return a borrowed reference). The > > policy is only to *add* new functions. > > > > IMO for the *internal* C API, it's fine to continue doing that for > > best performances. > > > > Moreover, the limited C API must not expose "implementation details". > > For example, structure members must not be accessed directly, because > > most structures are excluded from the limited C API. A function call > > hiding implementation details is usually better. > > > > Here is a copy of the current Include/README.rst file: > > > > The Python C API > > ================ > > > > The C API is divided into three sections: > > > > 1. ``Include/`` > > 2. ``Include/cpython/`` > > 3. ``Include/internal/`` > > > > > > Include: Limited API > > ==================== > > > > ``Include/``, excluding the ``cpython`` and ``internal`` subdirectories, > > contains the public Limited API (Application Programming Interface). > > The Limited API is a subset of the C API, designed to guarantee ABI > > stability across Python 3 versions, and is defined in :pep:`384`. > > > > Guidelines for expanding the Limited API: > > > > - Functions *must not* steal references > > - Functions *must not* return borrowed references > > - Functions returning references *must* return a strong reference > > - Macros should not expose implementation details > > - Please start a public discussion before expanding the API > > - Functions or macros with a ``_Py`` prefix do not belong in > ``Include/``. > > > > It is possible to add a function or macro to the Limited API from a > > given Python version. For example, to add a function to the Limited API > > from Python 3.10 and onwards, wrap it with > > ``#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000``. > > > > > > Include/cpython: CPython implementation details > > =============================================== > > > > ``Include/cpython/`` contains the public API that is excluded from the > > Limited API and the Stable ABI. > > > > Guidelines for expanding the public API: > > > > - Functions *must not* steal references > > - Functions *must not* return borrowed references > > - Functions returning references *must* return a strong reference > > > > > > Include/internal: The internal API > > ================================== > > > > > > With PyAPI_FUNC or PyAPI_DATA > > ----------------------------- > > > > Functions or structures in ``Include/internal/`` defined with > > ``PyAPI_FUNC`` or ``PyAPI_DATA`` are internal functions which are > > exposed only for specific use cases like debuggers and profilers. > > > > > > With the extern keyword > > ----------------------- > > > > Functions in ``Include/internal/`` defined with the ``extern`` keyword > > *must not and can not* be used outside the CPython code base. Only > > built-in stdlib extensions (built with the ``Py_BUILD_CORE_BUILTIN`` > > macro defined) can use such functions. > > > > When in doubt, new internal C functions should be defined in > > ``Include/internal`` using the ``extern`` keyword. > > > > Victor > > > _______________________________________________ > Python-Dev mailing list -- python-dev@python.org > To unsubscribe send an email to python-dev-le...@python.org > https://mail.python.org/mailman3/lists/python-dev.python.org/ > Message archived at > https://mail.python.org/archives/list/python-dev@python.org/message/5UURMDSQUGSNZEUDUSQNHWRZIUKDIZJH/ > Code of Conduct: http://python.org/psf/codeofconduct/ >
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/XJK6K7LEWL7ZKHS3YG7V4SCX7XLXEBL2/ Code of Conduct: http://python.org/psf/codeofconduct/
