FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

bpo-43795: PEP 652 user documentation by encukou · Pull Request #25668 · python/cpython · GitHub

  1. python
  2. cpython

Repository navigation

bpo-43795: PEP 652 user documentation - #25668

Merged
miss-islington merged 14 commits into
python:mainfrom
encukou:pep652-document
May 11, 2021
ConversationCommits (14)ChecksFiles changed
Merged

bpo-43795: PEP 652 user documentation#25668
miss-islington merged 14 commits into
python:mainfrom
encukou:pep652-document

Conversation

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

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

encukou added 2 commits April 27, 2021 21:16
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.
Add Stable ABI (PEP 652) documentation
61cf858
encukou added docs Documentation in the Doc dir skip news DO-NOT-MERGE labels Apr 27, 2021
encukou mentioned this pull request Apr 29, 2021
Merged
encukou and others added 5 commits April 29, 2021 17:06
Mark up Py_LIMITED_API as a macro
b9dc6d2
Replace Include/README.rst with a link to the devguide
15cc273 
Devguide PR: python/devguide#682
Merge in the main branch
f37ec96
Add a list of the stable ABI to the docs
d3c3107
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 <william.ayd@icloud.com>

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:

encukou marked this pull request as ready for review April 29, 2021 16:03
encukou mentioned this pull request Apr 29, 2021
Closed

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:

orsenthil reviewed May 7, 2021
View reviewed changes

orsenthil left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

Comment thread Doc/c-api/apiabiversion.rst
Comment thread Doc/c-api/apiabiversion.rst Outdated
willingc approved these changes May 7, 2021
View reviewed changes

willingc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

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 May 7, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

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 May 7, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Nice table as an example 😄

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 May 7, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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.

encukou May 7, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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.

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 May 7, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Good example.

encukou commented May 7, 2021

Copy link
Copy Markdown
Member Author

Thank you for the thoughtful comments!

miss-islington merged commit b05955d into python:main May 11, 2021

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

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.
🐍🍒⛏🤖

bedevere-bot commented May 11, 2021

Copy link
Copy Markdown

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

encukou deleted the pep652-document branch May 11, 2021 14:04

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 :)

willingc pushed a commit that referenced this pull request May 14, 2021
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 <encukou@gmail.com>

Co-authored-by: Petr Viktorin <encukou@gmail.com>
pablogsal mentioned this pull request Jul 18, 2021
Closed
encukou mentioned this pull request Jun 7, 2022
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

orsenthil orsenthil left review comments
willingc willingc approved these changes

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.

6 participants

Back | FazBrowse Home | New Git URL