[Python-Dev] Expected stability of PyCode_New() and types.CodeType() signatures

[Petr Viktorin]

Hello,
PEP 570 (Positional-Only Parameters) changed the signatures of 
PyCode_New() and types.CodeType(), adding a new argument for "posargcount".
Our policy for such changes seems to be fragmented tribal knowledge. I'm 
writing to check if my understanding is reasonable, so I can apply it 
and document it explicitly.

There is a surprisingly large ecosystem of tools that create code objects.
The expectation seems to be that these tools will need to be adapted for 
each minor version of Python.

But that's not the same as saying that if you use types.CodeType(), 
you're on your own. To me [PR 13271], seems to go too far when it adds:
 > These types are not supposed to be instantiated outside of
 > CPython internals and constructor signatures will vary
 > between Python versions.

This kind of "washing our hands" doesn't do justice to tools like 
Cython, whose use of PyCode_New is (IMO) perfectly justified. As is 
adapting to Python minor versions.

So, we should document the changes as any backwards-incompatible change.
Specifically, changes should be (or should have been, in hindsight) 
mentioned in:
* The "API changes" and/or "Porting" sections of the What's New document
* Version history of the documentation (e.g. versionchanged blocks)
* Any relevant PEPs

Also, the expected level of API stability should be documented in the docs.

Does that sound right?


PEP 570: https://www.python.org/dev/peps/pep-0570/
PyCode_New: https://docs.python.org/3.8/c-api/code.html#c.PyCode_New
[PR 13271]: https://github.com/python/cpython/pull/13271/files