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

Georg Brandl g.brandl at gmx.net
Sat Oct 12 22:25:36 CEST 2013

Am 12.10.2013 22:16, schrieb Antoine Pitrou:

>> 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. Well, tagging things which are "not something" feels weird IMHO.

Sorry, that seems like arbitrary bike-shedding. It's like saying you don't want to document that pickle, shelve and marshal are not safe against untrusted data, but rather document that all other modules are.

> ("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. I still don't like that name, because it doesn't convey any interesting information. "Stable ABI" is immediately informative.

It can be changed, but we document the C API, not an ABI.

cheers, Georg

More information about the Python-Dev mailing list