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

Terry Reedy tjreedy at udel.edu
Fri May 31 12:37:01 EDT 2019


On 5/31/2019 4:46 AM, Petr Viktorin wrote:
> 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.

I summarized the above on the issue
https://bugs.python.org/issue36896
and suggested specific revisions on the PR.
https://github.com/python/cpython/pull/13271

> 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

The second PR for Document changes ... added something to What's New.
https://bugs.python.org/issue36886
https://github.com/python/cpython/commit/5d23e282af69d404a3430bb95aefe371112817b3

If you think something more is needed, say so on the issue.

> * Version history of the documentation (e.g. versionchanged blocks)

We put version history of the code (but not of the docs) in the docs.
https://docs.python.org/3/reference/compound_stmts.html#function-definitions
should have a version-changed note for the added '/' syntax.

> * Any relevant PEPs

If you mean PEPs other than 570, we don't do that.

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

Yes.  I think that part of PR 13271, rewritten, is good.

> 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


-- 
Terry Jan Reedy



More information about the Python-Dev mailing list