[issue36896] clarify in types.rst that FunctionTypes & co constructors don't have stable signature
New submission from Matthias Bussonnier <bussonniermatthias@gmail.com>:
From bpo-36886,
IT is unclear the FunctionTypes, CodeTypes ... etc are not stable between python versions, and the recent addition of `:=` change some of the signatures. This suggest 2 things: - A CYA sentence in types.rst "These types are not supposed to be instantiated outside of CPython internals and constructor signatures will vary between python versions." or alike - As many people don't read online documentation but on the docstring via calling `help()`, to add something similar to all the docstrings of said-objects constructors. ---------- assignee: docs@python components: Documentation messages: 342271 nosy: docs@python, mbussonn priority: normal severity: normal status: open title: clarify in types.rst that FunctionTypes & co constructors don't have stable signature versions: Python 3.8 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
Change by Matthias Bussonnier <bussonniermatthias@gmail.com>: ---------- keywords: +patch pull_requests: +13177 stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: In msg342227 Pablo Galindo Salgado said "I am +1 to such a sentence, but I think this is a decision that more core devs should agree on."
"These types are not supposed to be instantiated outside of CPython internals"
At least Petr Vidtorin and I disagree with this part. As Petr wrote on pydev thread "Expected stability of PyCode_New() and types.CodeType() signatures", there are multiple tools that instantiate code objects, in particular Cython, which is far from being a rogue project. Python is a 'consenting adults' languages, and we generally do not officially tell people what they are 'supposed' to do or not do. ---------- nosy: +petr.viktorin, terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
Pablo Galindo Salgado <pablogsal@gmail.com> added the comment: Although I completely agree with the decision of figuring out an explicit consensus regarding these APIs, I will explain a bit my +1: My +1 is not about the usage of PyCode_New, is about the usage of `types.CodeType`. The constructor for the later has never been documented on the Python side, so one could argue that is not a supported feature to manually construct code objects. The more we expose and call "stable" regarding internals, the less freedom we will have to apply optimizations and add additional data members to internal structures. With this, I am not saying that we should say that whoever uses this is a "roge" project but marking these APIs as stable will greatly restrict future changes. ---------- nosy: +pablogsal _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
Pablo Galindo Salgado <pablogsal@gmail.com> added the comment: Being said that, I am very happy with the current changes on the PR :) Thank you @Terry and @Petr for helping with this! ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
Matthias Bussonnier <bussonniermatthias@gmail.com> added the comment: Victor recently implemented CodeType.replace(); which I believe will cover many of the usecase. Should I also send a PR that update the DocStrings of (some of) ? these objects? many people don't go and read the html docs... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: Pablo, I am all for respectfully preserving implementation freedom where we can. From idlelib.__init__: [idlelib files other than idle*.*] "are private implementations. Their details are subject to change. See PEP 434 for more. Import them at your own risk." Matthias: I don't believe we put version changed notes in docstrings, as they are for the current code. But if a docstring covers arguments, as usual, then the new one should be added. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
Matthias Bussonnier <bussonniermatthias@gmail.com> added the comment:
I don't believe we put version changed notes in docstrings,
Oh no I was thinking a note in the docstring "constructor signature may change between Python versions". Whether to put changed/addition info in docstrings is another subject and a thing I would be in favor of; but let's not digress and the current issue which is to convey to users the non-stability of interface. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: Yes, I think " Not for the faint of heart." could be replaced or augmented by 'api may change' ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
Petr Viktorin <encukou@gmail.com> added the comment: New changeset 13136e83a637a9f1cfbada7e93097005296659b4 by Petr Viktorin (Matthias Bussonnier) in branch 'master': bpo-36896: Clarify that some types constructors are unstable (GH-13271) https://github.com/python/cpython/commit/13136e83a637a9f1cfbada7e93097005296... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
STINNER Victor <vstinner@redhat.com> added the comment: Would it be the right place to document the new CodeType.replace() method which is designed to help to write "future-proof" code? (not rely on the exact constructor API) ---------- nosy: +vstinner _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36896> _______________________________________
participants (5)
-
Matthias Bussonnier -
Pablo Galindo Salgado
-
Petr Viktorin
-
STINNER Victor
-
Terry J. Reedy