[Python-Dev] Expected stability of PyCode_New() and types.CodeType() signatures
encukou at gmail.com
Fri May 31 04:46:58 EDT 2019
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)
* 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/
[PR 13271]: https://github.com/python/cpython/pull/13271/files
More information about the Python-Dev