gh-133678: Add a banner to C API doc to recommend 3rd party tools

[vstinner]

• Issue: [C API] Add a banner to the C API documentation to recommend tools #133678

---

📚 Documentation preview 📚:

👎 1 encukou reacted with thumbs down emoji

[vstinner]

Banner added to all pages (the gray note):

---

Link to this new section:

[zooba]

I think we'll need a bit more nuance in here, explaining why we still have a C API at all if we're telling people not to use it (obvious to us, not obvious to someone who happens to be reading these docs for the first time).

[efimov-mikhail]

I think we'll need a bit more nuance in here, explaining why we still have a C API at all if we're telling people not to use it (obvious to us, not obvious to someone who happens to be reading these docs for the first time).

Totally agree. For example, I've personally taken a lot of information from the last discuss thread. It seems to be very useful to document these nuances in concise manner.

[zooba]

I also think we need to be careful to indicate that these are not supported by the same people who maintain Python, and issues need to be raised with the projects directly.

[philthompson10]

...and, by implication, other abstractions are not recommended?

[vstinner]

@zooba: I elaborated the rationale a little bit in the "Recommended third party tools" section. Feel free to propose better wording, I'm not good to write documentation :-)

Copy link

Member Author

vstinner commented May 8, 2025

...and, by implication, other abstractions are not recommended? It's not the case. Did I miss some major abstractions in my list?

Copy link

philthompson10 commented May 8, 2025

The list is at least inconsistent with https://docs.python.org/dev/faq/extending.html#writing-c-is-hard-are-there-any-alternatives However my problem is with the word recommended which implies some sort of official blessing which would put new (possibly better) abstractions at a disadvantage and implies some quality control process. I'd prefer something like established or commonly used.

Copy link

Contributor

efimov-mikhail commented May 8, 2025

However my problem is with the word recommended which implies some sort of official blessing which would put new (possibly better) abstractions at a disadvantage and implies some quality control process. IMO, this is actually a recommended API for the most of the projects. There is no direct implication that other abstraction could not be better in future. In fact, it's not a problem to add a new entry to this list, if some project had proven as a well-established alternative. But at the moment a maintainer of some project can use C API directly or through some binding. And CPython developers encourage that maintainer to use the latter.

zooba reviewed May 8, 2025

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

zooba reviewed May 8, 2025

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

terryjreedy reviewed May 8, 2025

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

vstinner and others added 3 commits May 9, 2025 07:44

Update Doc/c-api/intro.rst …

0970a14

Co-authored-by: Steve Dower <steve.dower@microsoft.com>

Update Doc/c-api/intro.rst …

d19037e

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>

Update

abfa188

vstinner marked this pull request as ready for review May 9, 2025 05:55

vstinner requested review from kumaraditya303, encukou, pganssle, abalkin, ericsnowcurrently, brettcannon, ncoghlan, warsaw and FFY00 as code owners May 9, 2025 05:55

vstinner requested review from AA-Turner, hugovk and 1st1 as code owners May 9, 2025 05:55

bedevere-app bot added the awaiting core review label May 9, 2025

vstinner changed the title gh-133678: Add a banner to C API doc to recommend tools gh-133678: Add a banner to C API doc to recommend 3rd party tools May 9, 2025

efimov-mikhail approved these changes May 9, 2025

View reviewed changes

ZeroIntensity added docs Documentation in the Doc dir topic-C-API labels May 9, 2025

github-project-automation bot added this to Docs PRs May 9, 2025

github-project-automation bot moved this to Todo in Docs PRs May 9, 2025

ncoghlan reviewed May 10, 2025

View reviewed changes

Doc/tools/extensions/c_annotations.py Outdated Show resolved Hide resolved

ncoghlan reviewed May 10, 2025

View reviewed changes

Copy link

Contributor

ncoghlan left a comment

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 Hide comment

Suggested an adjustment to the banner wording. The intro to https://docs.python.org/3/extending/index.html should also be updated (potentially replacing the existing 3rd party tool list there and cross-referencing it from the C API intro rather than making a new separate list in the C API docs intro)

AA-Turner reviewed May 10, 2025

View reviewed changes

Doc/tools/extensions/c_annotations.py

Comment on lines +268 to +269

		class CAPIToolsBanner(SphinxDirective):
		"""CAPI Tools banner."""

Copy link

Member

AA-Turner May 10, 2025

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 Hide comment

From an implementation perspective, it would be better to use an .. include:: directive rather than adding custom code here.

I don't have a strong opinion on the banner in general, but I wonder if adding it to every page is a bit much? I defer to the C API group for deliberations here, though.

A

Copy link

Contributor

ncoghlan May 10, 2025

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 Hide comment

We've had the existing note in the extending/embedding intro for a long time, but it doesn't really work for anyone coming in from a deep link (including search results). A banner seems like a plausible improvement.

Given the possibility of anchor targets dropping people in well down the pages, though, I do wonder if a hovering banner like the ones added to finalised PEPs might be a better technical approach.

Update Doc/tools/extensions/c_annotations.py …

be3fdb5

Co-authored-by: Alyssa Coghlan <ncoghlan@gmail.com>

brettcannon removed their request for review May 12, 2025 19:50

kumaraditya303 removed their request for review May 21, 2025 09:39

Copy link

Member Author

vstinner commented May 22, 2025

#134526.

❤️ 1 encukou reacted with heart emoji

vstinner closed this May 22, 2025

vstinner deleted the c_api_banner branch May 22, 2025 16:45

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

ncoghlan ncoghlan left review comments

zooba zooba left review comments

AA-Turner AA-Turner left review comments

terryjreedy terryjreedy left review comments

efimov-mikhail efimov-mikhail approved these changes

encukou Awaiting requested review from encukou encukou is a code owner

pganssle Awaiting requested review from pganssle pganssle is a code owner

abalkin Awaiting requested review from abalkin abalkin is a code owner

ericsnowcurrently Awaiting requested review from ericsnowcurrently ericsnowcurrently is a code owner

warsaw Awaiting requested review from warsaw warsaw is a code owner

FFY00 Awaiting requested review from FFY00 FFY00 is a code owner

hugovk Awaiting requested review from hugovk hugovk is a code owner

1st1 Awaiting requested review from 1st1 1st1 is a code owner

Assignees

No one assigned

Labels

awaiting core review docs Documentation in the Doc dir skip news topic-C-API

Projects

Docs PRs

Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

None yet

Follow Lee on X/Twitter - Father, Husband, Serial builder creating AI, crypto, games & web tools. We are friends :) AI Will Come To Life!

Check out: eBank.nz (Art Generator) | Netwrck.com (AI Tools) | Text-Generator.io (AI API) | BitBank.nz (Crypto AI) | ReadingTime (Kids Reading) | RewordGame | BigMultiplayerChess | WebFiddle | How.nz | Helix AI Assistant

8 participants

Footer

© 2025 GitHub, Inc.

Footer navigation

• Terms
• Privacy
• Security
• Status
• Docs
• Contact
• Manage cookies
• Do not share my personal information

Follow Lee on X/Twitter - Father, Husband, Serial builder creating AI, crypto, games & web tools. We are friends :) AI Will Come To Life!

Check out: eBank.nz (Art Generator) | Netwrck.com (AI Tools) | Text-Generator.io (AI API) | BitBank.nz (Crypto AI) | ReadingTime (Kids Reading) | RewordGame | BigMultiplayerChess | WebFiddle | How.nz | Helix AI Assistant

[vstinner]

...and, by implication, other abstractions are not recommended?

It's not the case. Did I miss some major abstractions in my list?

[philthompson10]

The list is at least inconsistent with https://docs.python.org/dev/faq/extending.html#writing-c-is-hard-are-there-any-alternatives

However my problem is with the word recommended which implies some sort of official blessing which would put new (possibly better) abstractions at a disadvantage and implies some quality control process. I'd prefer something like established or commonly used.

[efimov-mikhail]

However my problem is with the word recommended which implies some sort of official blessing which would put new (possibly better) abstractions at a disadvantage and implies some quality control process.

IMO, this is actually a recommended API for the most of the projects. There is no direct implication that other abstraction could not be better in future. In fact, it's not a problem to add a new entry to this list, if some project had proven as a well-established alternative.

But at the moment a maintainer of some project can use C API directly or through some binding. And CPython developers encourage that maintainer to use the latter.

[ncoghlan]

Suggested an adjustment to the banner wording. The intro to https://docs.python.org/3/extending/index.html should also be updated (potentially replacing the existing 3rd party tool list there and cross-referencing it from the C API intro rather than making a new separate list in the C API docs intro)

[AA-Turner]

From an implementation perspective, it would be better to use an .. include:: directive rather than adding custom code here.

I don't have a strong opinion on the banner in general, but I wonder if adding it to every page is a bit much? I defer to the C API group for deliberations here, though.

A

[ncoghlan]

We've had the existing note in the extending/embedding intro for a long time, but it doesn't really work for anyone coming in from a deep link (including search results). A banner seems like a plausible improvement.

Given the possibility of anchor targets dropping people in well down the pages, though, I do wonder if a hovering banner like the ones added to finalised PEPs might be a better technical approach.

[vstinner]

#134526.