GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — bpo-43795: PEP 652 user documentation by encukou · Pull Request #25668 · python/cpython

Conversation

@encukou

@encukou encukou commented Apr 27, 2021 •
edited by miss-islington
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member
  • Reformat the C API and ABI Versioning page (and extend/clarify a bit)
  • Rewrite the stable ABI docs into a general text on C API Compatibility
  • Add a list of Limited API contents, and notes for the individual items.
  • Replace Include/README.rst with a link to a devguide page with the same info

https://bugs.python.org/issue43795

Automerge-Triggered-By: GH:encukou

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
encukou added 2 commits April 27, 2021 21:16
@encukou
Doc: Reformat the C API and ABI Versioning page
28e34ab 
Mark up all the version macros, adding them to the index and allowing
links to them.

Clarify that these are resolved at build time.

Add an example for Python 3.10. Some people might assume this is 0x10,
not 0xA, based on how well PY_VERSION_HEX "reads" in hex.

Link to the (upcoming) page on API and ABI stability.
@encukou
Add Stable ABI (PEP 652) documentation
61cf858
@encukou encukou added docs Documentation in the Doc dir skip news DO-NOT-MERGE labels Apr 27, 2021
@the-knights-who-say-ni the-knights-who-say-ni added the CLA signed label Apr 27, 2021
@bedevere-bot bedevere-bot added the awaiting core review label Apr 27, 2021
@encukou encukou mentioned this pull request Apr 29, 2021
Add a page on changing the C API (PEP-652) python/devguide#682
Merged
encukou and others added 5 commits April 29, 2021 17:06
@encukou
Mark up Py_LIMITED_API as a macro
b9dc6d2
@encukou
Replace Include/README.rst with a link to the devguide
15cc273 
Devguide PR: python/devguide#682
@encukou
Merge in the main branch
f37ec96
@encukou
Add a list of the stable ABI to the docs
d3c3107
@encukou @WillAyd
Add "Part of the Stable ABI" annotations to the documentation
179c132 
This replaces the existing :stableabi:, which wasn't really used.

Doc/data/stable_abi.dat is expanded to include all relevant
info (kind of the symbol and version it was added in), and the
c_annotations Sphinx extension reads this file and adds
notes similar to ones added by :stableabi: (which wasn't really
used).

Relevant prior work: python#23185
Co-authored-by: Will Ayd <[email protected]>
@encukou

encukou commented Apr 29, 2021

Copy link
Copy Markdown
Member Author

As per the PEP, I added a list of everything in the limited API, as well as notes in individual doc entries. A screenshot of the notes:

image
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@encukou
encukou marked this pull request as ready for review April 29, 2021 16:03
@encukou encukou added DO-NOT-MERGE and removed DO-NOT-MERGE labels Apr 29, 2021
@encukou encukou mentioned this pull request Apr 29, 2021
bpo-29086: Add stableabi option to Documentation #23185
Closed
@encukou encukou removed the DO-NOT-MERGE label May 4, 2021
encukou added 4 commits May 5, 2021 19:36
@encukou
Merge in the main branch
377dd60
@encukou
Regenerate generated files
920965d
@encukou
Document platform-specific Limited API
6b4c8db
@encukou
Generate the stable ABI list from stable_abi.dat
e958d56
@encukou

encukou commented May 6, 2021

Copy link
Copy Markdown
Member Author

The docs notes will now show platform restrictions, based on #ifdef, like the “on Windows" here:

image
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
orsenthil
orsenthil reviewed May 7, 2021
View reviewed changes

@orsenthil orsenthil left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good to me. I had few nits to clarify.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/apiabiversion.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/c-api/apiabiversion.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
willingc
willingc approved these changes May 7, 2021
View reviewed changes

@willingc willingc left a comment

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @encukou. Nice work improving clarity here. I've made a few suggestions for consideration. Thanks again ☀️

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
minrk reacted with heart emoji
All reactions
  • ❤️ 1 reaction
Comment thread Doc/c-api/apiabiversion.rst Outdated

Thus ``3.4.1a2`` is hexversion ``0x030401a2``.
CPython exposes its version number in the following macros.
Note that these correspond to the version code is built with,

@willingc willingc May 7, 2021

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps bold part of this sentence re: build version vs run-time version.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
encukou reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Comment thread Doc/c-api/apiabiversion.rst Outdated
version information can be found by treating it as a 32 bit number in
the following manner:

+-------+-------------------------+-------------------------+

@willingc willingc May 7, 2021

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice table as an example 😄

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/stable.rst Outdated
(x>=2) on the particular :ref:`platform <stable-abi-platform>`.

Defining ``Py_LIMITED_API`` to a value of :c:data:`PY_VERSION_HEX` will
do the same, but allow additional API added up to specified version,

@willingc willingc May 7, 2021

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great improvements to this section. The wording in this item is slightly confusing. Does this mean: It will use the Limited API for this version and later versions. Earlier versions lose compatibility since additional API may exist prior to this version.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
encukou reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

@encukou encukou May 7, 2021

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the note! It really helps to have a second set of eyes here.
I've shuffled the paragraph around; hopefully things are clearer with this order.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/stable.rst

For example, while :c:func:`PyList_GetItem` is available, its “unsafe” macro
variant :c:func:`PyList_GET_ITEM` is not.
The macro can be faster because it can rely on version-specific implementation

@willingc willingc May 7, 2021

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good example.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@bedevere-bot bedevere-bot added awaiting merge and removed awaiting core review labels May 7, 2021
encukou added 2 commits May 7, 2021 16:33
@encukou
apiabiversion: Bold "build" & "run"
d0792e5
@encukou
PY_VERSION_HEX: Add examples to the table
3fbc13a
@encukou
Reword paragraph on specific value for Py_LIMITED_API
5637b1f
@encukou

encukou commented May 7, 2021

Copy link
Copy Markdown
Member Author

Thank you for the thoughtful comments!
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@encukou encukou added 🤖 automerge labels May 11, 2021
@miss-islington
miss-islington merged commit b05955d into python:main May 11, 2021
@miss-islington

miss-islington commented May 11, 2021

Copy link
Copy Markdown
Contributor

Sorry, I can't merge this PR. Reason: Base branch was modified. Review and try the merge again..
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington

miss-islington commented May 11, 2021

Copy link
Copy Markdown
Contributor

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10.
🐍🍒⛏🤖
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-bot bedevere-bot removed awaiting merge needs backport to 3.10 labels May 11, 2021
@bedevere-bot

bedevere-bot commented May 11, 2021

Copy link
Copy Markdown

GH-26034 is a backport of this pull request to the 3.10 branch.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@encukou
encukou deleted the pep652-document branch May 11, 2021 14:04
@encukou

encukou commented May 11, 2021

Copy link
Copy Markdown
Member Author

This can be confusing; more and more often and I need a page to link to. So I merged this.
However, I'd be happy for more suggestions/improvements :)
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
willingc pushed a commit that referenced this pull request May 14, 2021
@miss-islington @encukou
bpo-43795: PEP 652 user documentation (GH-25668) (GH-26034)
3739371 
- Reformat the C API and ABI Versioning page (and extend/clarify a bit)
- Rewrite the stable ABI docs into a general text on C API Compatibility
- Add a list of Limited API contents, and notes for the individual items.
- Replace `Include/README.rst` with a link to a devguide page with the same info
(cherry picked from commit b05955d)

Co-authored-by: Petr Viktorin <[email protected]>

Co-authored-by: Petr Viktorin <[email protected]>
@pablogsal pablogsal mentioned this pull request Jul 18, 2021
[3.10] Correct the order of regen-abidump #27228
Closed
@encukou encukou mentioned this pull request Jun 7, 2022
Implement PEP 652 -- Maintaining the Stable ABI #87961
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@orsenthil orsenthil orsenthil left review comments
@willingc willingc willingc approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

6 participants

@encukou @miss-islington @bedevere-bot @orsenthil @willingc @the-knights-who-say-ni
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.