clarify in types.rst that FunctionTypes & co constructors don't have stable signature

[Carreau]

BPO	36896
Nosy	@terryjreedy, @vstinner, @encukou, @Carreau, @pablogsal
PRs	bpo-36896: Clarify that some types constructors are unstable #13271

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-05-12.22:03:30.156>
labels = ['3.8', 'docs']
title = "clarify in types.rst that FunctionTypes & co  constructors don't have stable signature"
updated_at = <Date 2019-06-11.21:52:41.080>
user = 'https://github.com/Carreau'

bugs.python.org fields:

activity = <Date 2019-06-11.21:52:41.080>
actor = 'vstinner'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-05-12.22:03:30.156>
creator = 'mbussonn'
dependencies = []
files = []
hgrepos = []
issue_num = 36896
keywords = ['patch']
message_count = 10.0
messages = ['342271', '344084', '344096', '344099', '344104', '344112', '344114', '344135', '344347', '345274']
nosy_count = 6.0
nosy_names = ['terry.reedy', 'vstinner', 'petr.viktorin', 'docs@python', 'mbussonn', 'pablogsal']
pr_nums = ['13271']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue36896'
versions = ['Python 3.8']

[Carreau]

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.

[terryjreedy]

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.

[pablogsal]

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.

[pablogsal]

Being said that, I am very happy with the current changes on the PR :)

Thank you @terry and @petr for helping with this!

[Carreau]

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...

[terryjreedy]

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.

[Carreau]

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.

[terryjreedy]

Yes, I think " Not for the faint of heart." could be replaced or augmented by 'api may change'

[encukou]

New changeset 13136e8 by Petr Viktorin (Matthias Bussonnier) in branch 'master':
bpo-36896: Clarify that some types constructors are unstable (GH-13271)
13136e8

[vstinner]

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)

[iritkatriel]

CodeType.replace() was documented in https://bugs.python.org/issue37032.

[vstinner]

Somehow related: @encukou wrote PEP 689 "Unstable C API tier": https://peps.python.org/pep-0689/