[Python-Dev] Support for marking limited API elements in C API docs (original) (raw)

Eric V. Smith eric at trueblade.com
Sat Oct 12 22:09:24 CEST 2013

On 10/12/2013 4:04 PM, Georg Brandl wrote:

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 PyTupleResize(PyObject **p, Pyssizet 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.

I'm not sure I understand what's being labeled "notlimited". But it seems to be a tautology that the stable API/ABI is not changing. So I think it makes more sense to label those as "stableabi" and be finished with this task, rather than trying to remember to add some markup every time we add a new function.

-- Eric.

More information about the Python-Dev mailing list