Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Closed
Carreau mannequin opened this issue May 12, 2019 · 12 comments
Closed

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

Carreau mannequin opened this issue May 12, 2019 · 12 comments
Labels
3.8 only security fixes docs Documentation in the Doc dir

Comments

@Carreau
Copy link
Mannequin

Carreau mannequin commented May 12, 2019

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
    Copy link
    Mannequin Author

    Carreau mannequin commented May 12, 2019

    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.

    @Carreau Carreau mannequin added the 3.8 only security fixes label May 12, 2019
    @Carreau Carreau mannequin assigned docspython May 12, 2019
    @Carreau Carreau mannequin added the docs Documentation in the Doc dir label May 12, 2019
    @terryjreedy
    Copy link
    Member

    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
    Copy link
    Member

    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
    Copy link
    Member

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

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

    @Carreau
    Copy link
    Mannequin Author

    Carreau mannequin commented May 31, 2019

    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
    Copy link
    Member

    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
    Copy link
    Mannequin Author

    Carreau mannequin commented May 31, 2019

    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
    Copy link
    Member

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

    @encukou
    Copy link
    Member

    encukou commented Jun 3, 2019

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

    @vstinner
    Copy link
    Member

    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)

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @iritkatriel
    Copy link
    Member

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

    @iritkatriel iritkatriel closed this as not planned Won't fix, can't repro, duplicate, stale Jul 3, 2022
    @vstinner
    Copy link
    Member

    vstinner commented Jul 4, 2022

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

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.8 only security fixes docs Documentation in the Doc dir
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    5 participants
    @vstinner @encukou @iritkatriel @pablogsal @terryjreedy