classification
Title: clarify in types.rst that FunctionTypes & co constructors don't have stable signature
Type: Stage: patch review
Components: Documentation Versions: Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, mbussonn, pablogsal, petr.viktorin, terry.reedy, vstinner
Priority: normal Keywords: patch

Created on 2019-05-12 22:03 by mbussonn, last changed 2019-06-11 21:52 by vstinner.

Pull Requests
URL Status Linked Edit
PR 13271 merged mbussonn, 2019-05-13 00:28
Messages (10)
msg342271 - (view) Author: Matthias Bussonnier (mbussonn) * Date: 2019-05-12 22:03
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.
msg344084 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-05-31 16:16
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.
msg344096 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2019-05-31 17:43
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.
msg344099 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2019-05-31 18:12
Being said that, I am very happy with the current changes on the PR :)

 Thank you @Terry and @Petr for helping with this!
msg344104 - (view) Author: Matthias Bussonnier (mbussonn) * Date: 2019-05-31 18:45
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...
msg344112 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-05-31 19:47
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.
msg344114 - (view) Author: Matthias Bussonnier (mbussonn) * Date: 2019-05-31 20:02
>  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.
msg344135 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-05-31 22:16
Yes, I think " Not for the faint of heart." could be replaced or augmented by 'api may change'
msg344347 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2019-06-03 00:43
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/13136e83a637a9f1cfbada7e93097005296659b4
msg345274 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-06-11 21:52
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)
History
Date User Action Args
2019-06-11 21:52:41vstinnersetnosy: + vstinner
messages: + msg345274
2019-06-03 00:43:24petr.viktorinsetmessages: + msg344347
2019-05-31 22:16:38terry.reedysetmessages: + msg344135
2019-05-31 20:02:15mbussonnsetmessages: + msg344114
2019-05-31 19:47:05terry.reedysetmessages: + msg344112
2019-05-31 18:45:59mbussonnsetmessages: + msg344104
2019-05-31 18:12:06pablogsalsetmessages: + msg344099
2019-05-31 17:43:40pablogsalsetnosy: + pablogsal
messages: + msg344096
2019-05-31 16:16:39terry.reedysetnosy: + petr.viktorin, terry.reedy
messages: + msg344084
2019-05-13 00:28:11mbussonnsetkeywords: + patch
stage: patch review
pull_requests: + pull_request13177
2019-05-12 22:03:30mbussonncreate