Skip to content

Docs: fill in descriptor C API docs#146644

Merged
ZeroIntensity merged 3 commits intopython:mainfrom
Boyeep:descriptor-c-api-docs
Mar 31, 2026
Merged

Docs: fill in descriptor C API docs#146644
ZeroIntensity merged 3 commits intopython:mainfrom
Boyeep:descriptor-c-api-docs

Conversation

@Boyeep
Copy link
Copy Markdown
Contributor

@Boyeep Boyeep commented Mar 30, 2026 •
edited by github-actions bot
Loading

This documents several missing entries in Doc/c-api/descriptor.rst.

Changes in this PR:

  • document PyDescr_NewGetSet
  • document PyDescr_NewMember
  • document PyDescr_NewMethod
  • document PyDescr_NewWrapper
  • document PyDescr_NewClassMethod
  • document PyWrapper_New
  • fix nearby Python type references for descriptor objects so they match the actual types module names

This is a docs-only change.

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

@Boyeep Boyeep requested a review from ZeroIntensity as a code owner March 30, 2026 20:38
@python-cla-bot
Copy link
Copy Markdown

python-cla-bot bot commented Mar 30, 2026 •
edited
Loading

All commit authors signed the Contributor License Agreement.

CLA signed

@bedevere-app bedevere-app bot added docs Documentation in the Doc dir skip news awaiting review labels Mar 30, 2026
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Mar 30, 2026
ZeroIntensity
ZeroIntensity reviewed Mar 31, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@ZeroIntensity ZeroIntensity left a comment

Choose a reason for hiding this comment

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

Thanks for tackling these.

Doc/c-api/descriptor.rst


.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped)
Copy link
Copy Markdown
Member

@ZeroIntensity ZeroIntensity Mar 31, 2026

Choose a reason for hiding this comment

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

wrapperbase is undocumented as well -- can we fix that in this PR?

Copy link
Copy Markdown
Contributor Author

@Boyeep Boyeep Mar 31, 2026

Choose a reason for hiding this comment

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

Sure, I'll be working on it

Doc/c-api/descriptor.rst
Comment on lines +13 to +14
Create a new get-set descriptor for extension type *type* from the
:c:type:`PyGetSetDef` structure *getset*.
Copy link
Copy Markdown
Member

@ZeroIntensity ZeroIntensity Mar 31, 2026

Choose a reason for hiding this comment

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

Let's elaborate a little more (the same goes for the ones below):

  1. What is a get-set descriptor, exactly?
  2. Why do users care? (Or, what might they use this for?)
  3. What does this correspond to in Python?

@Boyeep
Copy link
Copy Markdown
Contributor Author

Boyeep commented Mar 31, 2026

Implemented, thanks! I expanded the new descriptor docs to explain:

  1. what each descriptor is
  2. where extension authors encounter it (tp_getset, tp_members, tp_methods, and slot-based special methods)
  3. why it is useful
  4. and what it corresponds to in Python.

I also documented wrapperbase, which fixes the docs warning for that identifier.

@Boyeep Boyeep requested review from AA-Turner and hugovk as code owners March 31, 2026 03:43
@Boyeep
Copy link
Copy Markdown
Contributor Author

Boyeep commented Mar 31, 2026

Added a follow-up to remove Doc/c-api/descriptor.rst from Doc/tools/.nitignore now that the new references are resolved and the page builds cleanly in nitpicky mode. That should address the Docs / Docs CI failure from the previous push.

@hugovk hugovk removed their request for review March 31, 2026 12:49
@Boyeep Boyeep requested a review from ZeroIntensity March 31, 2026 16:22
ZeroIntensity
ZeroIntensity approved these changes Mar 31, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@ZeroIntensity ZeroIntensity left a comment

Choose a reason for hiding this comment

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

Thanks!

@ZeroIntensity ZeroIntensity added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Mar 31, 2026
@ZeroIntensity ZeroIntensity merged commit 9e1f164 into python:main Mar 31, 2026
37 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Mar 31, 2026
@miss-islington-app
Copy link
Copy Markdown

miss-islington-app bot commented Mar 31, 2026

Thanks @Boyeep for the PR, and @ZeroIntensity for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

@miss-islington-app
Copy link
Copy Markdown

miss-islington-app bot commented Mar 31, 2026

Sorry, @Boyeep and @ZeroIntensity, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 9e1f1644cd7b7661f0748bb37351836e8d6f37e2 3.14

@miss-islington-app
Copy link
Copy Markdown

miss-islington-app bot commented Mar 31, 2026

Sorry, @Boyeep and @ZeroIntensity, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 9e1f1644cd7b7661f0748bb37351836e8d6f37e2 3.13

@ZeroIntensity
Copy link
Copy Markdown
Member

ZeroIntensity commented Mar 31, 2026

@Boyeep Would you like to try the backport?

@Boyeep
Copy link
Copy Markdown
Contributor Author

Boyeep commented Mar 31, 2026

I checked the conflicts for both 3.14 and 3.13. They’re in Doc/c-api/descriptor.rst and Doc/tools/.nitignore, and they look like straightforward docs drift from the maintenance branches.

descriptor.rst still has the older placeholder section there, and .nitignore still lists Doc/c-api/descriptor.rst, so the resolution is to keep the new descriptor docs, keep the maintenance-branch PyProperty_Type docs, and remove Doc/c-api/descriptor.rst from .nitignore.

@Boyeep Would you like to try the backport?

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

Reviewers

@ZeroIntensity ZeroIntensity ZeroIntensity approved these changes

@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner

Assignees

@ZeroIntensity ZeroIntensity

Labels

docs Documentation in the Doc dir needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes skip issue skip news topic-C-API

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Boyeep @ZeroIntensity