Skip to content

Docs: fill in descriptor C API docs#146644

Open
Boyeep wants to merge 3 commits intopython:mainfrom
Boyeep:descriptor-c-api-docs
Open

Docs: fill in descriptor C API docs#146644
Boyeep wants to merge 3 commits intopython:mainfrom
Boyeep:descriptor-c-api-docs

Conversation

@Boyeep
Copy link
Copy Markdown

@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
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
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
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

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

@ZeroIntensity ZeroIntensity Awaiting requested review from ZeroIntensity ZeroIntensity is a code owner

Assignees

No one assigned

Labels

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

Projects

Docs PRs
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Boyeep @ZeroIntensity