PEP 689: Semi-stable C API tier #2559

encukou · 2022-04-26T12:21:35Z

AA-Turner

More comments than I intended, sorry! Some are very trivial, some are larger points (although I'm not an expert in the C-API, so please ignore things that I've gotten wrong).

A

pep-0689.rst

AA-Turner · 2022-04-26T15:59:39Z

pep-0689.rst

+We need a tier between Public and Private to accomodate tools like
+advanced debuggers and JIT compilers, which need access to CPython
+internals but assume the C-API they use does not change in patch releases.


Style / semantics -- I would phrase this the other way around, introducing the requirement first rather than "We need". Something like:

Suggested change

We need a tier between Public and Private to accomodate tools like

advanced debuggers and JIT compilers, which need access to CPython

internals but assume the C-API they use does not change in patch releases.

Tools requring access to CPython internals (e.g. advanced

debuggers and JIT compilers) are often built for minor series releases

of CPython, and assume that the C-API interals used do not change

in patch releases. To support these tools, we need a tier between the

Public and Private C-API, with guarantees on stability throughout

the minor-series release.

Caveat: this is a stab at language, my terminology might be far off the mark, and it may be entirely out of line with what you intend to express.

That is what I wanted to say, but it uses twice as much text to say it.
Why is it better? (That's a genuine question.)

The current wording is in the rationale section, which is setting out the justification for the proposal. To me, it seems odd to phrase it "We need <feature> because <thing> requires <requirement>, but we don't guarantee requirement.

My suggested rephrasing more explicity spells out that we want to support <thing> properly, there is a reason the current state doesn't work (no guarantees at an API level of stability), and hence <feature> is needed that provides those guarantees.

So this was more a "readability" suggestion, though as author you very much have the right to reject it!

A

pep-0689.rst

AA-Turner · 2022-04-26T16:06:58Z

pep-0689.rst

+Open Issues
+===========
+
+- “Semi-stable” is not a perfect name.


Sphinx will auto-convert the quotes.

Suggested change

- “Semi-stable” is not a perfect name.

- "Semi-stable" is not a perfect name.

But it accepts proper quotes as well, as far as I know.

AA-Turner · 2022-04-26T16:07:44Z

pep-0689.rst

+Specification
+=============
+
+Several functions and types (“APIs”) will be moved to a new *semi-stable* tier.


Suggested change

Several functions and types (“APIs”) will be moved to a new *semi-stable* tier.

Several functions and types ("APIs") will be moved to a new *semi-stable* tier.

AA-Turner · 2022-04-26T16:07:50Z

pep-0689.rst

+stability.
+
+However, leading underscores usually mark *fully private* API.
+CPython developers familiar with the “underscore means internal”


Suggested change

CPython developers familiar with the “underscore means internal”

CPython developers familiar with the "underscore means internal"

pep-0689.rst

JelleZijlstra · 2022-04-26T16:17:13Z

pep-0689.rst

+Rejected Ideas
+==============
+
+It might be good to add a similar tier in the Python (not C) API,


I feel like in practice this is already true for e.g. the ast module; I think Guido brought that up in the past too.

But like with CodeType, there's no warning outside the documentation. It's easy to miss this in a review.

JelleZijlstra · 2022-04-26T16:17:47Z

pep-0689.rst

+Open Issues
+===========
+
+- “Semi-stable” is not a perfect name.


I don't really like the name either, but haven't been able to think of anything better.

pep-0689.rst

encukou · 2022-04-27T10:05:29Z

pep-0689.rst

+We need a tier between Public and Private to accomodate tools like
+advanced debuggers and JIT compilers, which need access to CPython
+internals but assume the C-API they use does not change in patch releases.


That is what I wanted to say, but it uses twice as much text to say it.
Why is it better? (That's a genuine question.)

encukou · 2022-04-27T12:58:36Z

pep-0689.rst

+Rejected Ideas
+==============
+
+It might be good to add a similar tier in the Python (not C) API,


But like with CodeType, there's no warning outside the documentation. It's easy to miss this in a review.

Co-authored-by: Adam Turner <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>

encukou · 2022-04-27T13:12:53Z

Thank you for the editing!
I'll merge so the PEP can be reviewed on python-dev; I don't mean to ignore the unresolved conversations.

> The current wording is in the rationale section, which is > setting out the justification for the proposal. To me, it > seems odd to phrase it "We need <feature> because <thing> > requires <requirement>, but we don't guarantee requirement. > > My suggested rephrasing more explicity spells out that we > want to support <thing> properly, there is a reason the > current state doesn't work (no guarantees at an API level > of stability), and hence <feature> is needed that provides > those guarantees. - python#2559 (comment)

PEP 689 -- Semi-stable C API tier

9eeb8ad

encukou requested a review from a team as a code owner April 26, 2022 12:21

AA-Turner reviewed Apr 26, 2022

View reviewed changes

JelleZijlstra reviewed Apr 26, 2022

View reviewed changes

encukou commented Apr 27, 2022

View reviewed changes

Apply suggestions from code review

f8fbe52

Co-authored-by: Adam Turner <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>

encukou merged commit 7f53796 into python:main Apr 27, 2022

encukou deleted the pep-semistable branch April 27, 2022 13:13

CAM-Gerlach added the new-pep A new draft PEP submitted for initial review label May 3, 2022

encukou mentioned this pull request May 3, 2022

PEP 689: Rename to "Unstable C API tier" #2576

Merged

erlend-aasland mentioned this pull request May 13, 2022

pep8/greppable exception messages erlend-aasland/peps#1

Closed

erlend-aasland mentioned this pull request Jun 27, 2022

pep 687/mark as accepted erlend-aasland/peps#2

Closed

-We need a tier between Public and Private to accomodate tools like
-advanced debuggers and JIT compilers, which need access to CPython
-internals but assume the C-API they use does not change in patch releases.
+Tools requring access to CPython internals (e.g. advanced
+debuggers and JIT compilers) are often built for minor series releases
+of CPython, and assume that the C-API interals used do not change
+in patch releases. To support these tools, we need a tier between the
+Public and Private C-API, with guarantees on stability throughout
+the minor-series release.

	- “Semi-stable” is not a perfect name.
	- "Semi-stable" is not a perfect name.

	Several functions and types (“APIs”) will be moved to a new semi-stable tier.
	Several functions and types ("APIs") will be moved to a new semi-stable tier.

	CPython developers familiar with the “underscore means internal”
	CPython developers familiar with the "underscore means internal"

Uh oh!

PEP 689: Semi-stable C API tier #2559

PEP 689: Semi-stable C API tier #2559

Uh oh!

Conversation

encukou commented Apr 26, 2022

Uh oh!

AA-Turner left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AA-Turner Apr 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AA-Turner Apr 27, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

encukou commented Apr 27, 2022

Uh oh!

Uh oh!

AA-Turner left a comment •

edited

Loading

AA-Turner Apr 26, 2022 •

edited

Loading

AA-Turner Apr 27, 2022 •

edited

Loading