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

[STINNER Victor]

STINNER Victor  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Petr Viktorin]

Petr Viktorin  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/13136e83a637a9f1cfbada7e93097005296659b4


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Matthias Bussonnier]

Matthias Bussonnier  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Matthias Bussonnier]

Matthias Bussonnier  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Pablo Galindo Salgado]

Pablo Galindo Salgado  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Pablo Galindo Salgado]

Pablo Galindo Salgado  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Matthias Bussonnier]

Change by Matthias Bussonnier :


--
keywords: +patch
pull_requests: +13177
stage:  -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Matthias Bussonnier]

New submission from Matthias Bussonnier :

>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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com