[Python-Dev] Support for marking limited API elements in C API docs
Georg Brandl
g.brandl at gmx.net
Sat Oct 12 22:04:57 CEST 2013
Am 12.10.2013 21:56, schrieb Antoine Pitrou:
> On Sat, 12 Oct 2013 21:19:16 +0200
> Georg Brandl <g.brandl at gmx.net> wrote:
>> Am 12.10.2013 20:20, schrieb Serhiy Storchaka:
>> > 12.10.13 21:04, Georg Brandl написав(ла):
>> >> in light of the recent thread about PEPs not forming part of the docs,
>> >> I've just pushed a change that allows to document C API elements
>> >> not part of the limited API as such. It is done like this:
>> >>
>> >> ... c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
>> >> :notlimited:
>> >>
>> >> I have not yet begun adding these to the documents; if someone wants to
>> >> help with this I am glad for volunteers.
>> >
>> > Why this is needed? The limited API is unstable and only developers of
>> > CPython can use it (but they can look in headers).
>>
>> Well, I may be reading PEP 384 wrongly, but the point is exactly to have a
>> *stable* API for *non-core* developers to rely upon, so that they can build
>> extensions that don't need to be recompiled for every version of Python.
>
> This is true.
>
> However, I find the proposed markup not very enlightening :-)
> I would prefer if "limited" APIs where marked with a :stableabi: tag.
The way I did it was based on the expected number of changes, which would
be lower with the "not-limited" elements being labeled. But changing it
around is trivial.
> ("limited API" is really a bad synonym for "stable ABI" IMO)
It's not a synonym: to get a stable ABI, you use the limited API. Of course
Martin should confirm that this terminology matches his intentions.
cheers,
Georg
More information about the Python-Dev
mailing list