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.

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-leave@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/