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/5d23e282af69d404a3430bb95aefe371112... 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