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 — Docs: Add classes to C API return value annotations by hugovk · Pull Request #117926 · python/cpython

Conversation

@hugovk

@hugovk hugovk commented Apr 16, 2024 •
edited
Loading

Uh oh!

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

Copy link
Copy Markdown
Member

Currently light green is used for all return types

  • "Return value: Always NULL."
  • "Return value: New reference."
  • "Return value: Borrowed reference."

For example: https://docs.python.org/3/c-api/exceptions.html

Screenshots

image

image

image

A borrowed reference is not necessarily a "bad" thing, but we may want to use something other than green that indicates it's "good", to indicate they should be treated with care.

One option is yellow.

  1. These annotations are added in Doc/tools/extensions/c_annotations.py. The first step is to add CSS classes in this file.

  2. The light green colour is defined in https://github.com/python/python-docs-theme. The second step is to adjust the colours in the theme.

This PR also includes some light cleanup whilst we're touching this file, see commits.

📚 Documentation preview 📚: https://cpython-previews--117926.org.readthedocs.build/

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
erlend-aasland reacted with rocket emoji
All reactions
  • 🚀 1 reaction
hugovk added 4 commits April 16, 2024 12:33
@hugovk
Add classes to C API return value annotations
111795c
@hugovk
Cleanup: remove duplicate key and sort; remove unused variable; white…
48884bb 
…space
@hugovk
Cleanup: remove redundant encoding and default open mode
1aa606c
@hugovk
Use f-string
7d0ac69
@bedevere-app bedevere-app Bot added the awaiting core review label Apr 16, 2024
@hugovk hugovk added skip issue skip news docs Documentation in the Doc dir labels Apr 16, 2024
sobolevn
sobolevn reviewed Apr 16, 2024
View reviewed changes

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

👍

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/tools/extensions/c_annotations.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/tools/extensions/c_annotations.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
erlend-aasland
erlend-aasland approved these changes Apr 16, 2024
View reviewed changes

@erlend-aasland erlend-aasland 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.

Looks good

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting core review labels Apr 16, 2024
@hugovk hugovk added the needs backport to 3.12 only security fixes label Apr 16, 2024
@hugovk @sobolevn
Explicitly specify encoding='utf8'
f923cc3 
Co-authored-by: Nikita Sobolev <[email protected]>
sobolevn
sobolevn approved these changes Apr 16, 2024
View reviewed changes
@hugovk
hugovk enabled auto-merge (squash) April 16, 2024 15:44
@hugovk
hugovk merged commit 3284b84 into python:main Apr 16, 2024
@hugovk
hugovk deleted the docs-c-api-return-value-classes branch April 16, 2024 15:56
@miss-islington-app

miss-islington-app Bot commented Apr 16, 2024

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the awaiting merge label Apr 16, 2024
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Apr 16, 2024
@hugovk @sobolevn @miss-islington
Docs: Add classes to C API return value annotations (pythonGH-117926)
eac8b7d 
(cherry picked from commit 3284b84)

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Nikita Sobolev <[email protected]>
@bedevere-app

bedevere-app Bot commented Apr 16, 2024

Copy link
Copy Markdown

GH-117937 is a backport of this pull request to the 3.12 branch.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.12 only security fixes label Apr 16, 2024
hugovk added a commit that referenced this pull request Apr 16, 2024
@miss-islington @hugovk @sobolevn
[3.12] Docs: Add classes to C API return value annotations (GH-117926) (
67dc681 
#117937)

Docs: Add classes to C API return value annotations (GH-117926)
(cherry picked from commit 3284b84)

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Nikita Sobolev <[email protected]>
diegorusso pushed a commit to diegorusso/cpython that referenced this pull request Apr 17, 2024
@hugovk @sobolevn @diegorusso
Docs: Add classes to C API return value annotations (python#117926)
501600a 
Co-authored-by: Nikita Sobolev <[email protected]>
@hugovk hugovk mentioned this pull request Apr 17, 2024
Use different colour for 'Return value: Borrowed reference' python/python-docs-theme#188
Merged
@hugovk

hugovk commented Apr 17, 2024

Copy link
Copy Markdown
Member Author

Step two: python/python-docs-theme#188
erlend-aasland reacted with rocket emoji
All reactions
  • 🚀 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sobolevn sobolevn sobolevn approved these changes
@erlend-aasland erlend-aasland erlend-aasland 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 issue 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.

3 participants

@hugovk @sobolevn @erlend-aasland
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.