gh-89554: Document standard type objects in types as classes by gaborbernat · Pull Request #150676 · python/cpython · GitHub

The types module exposes built-in type objects (FunctionType, LambdaType, MethodType, the descriptor type family, FrameType, CoroutineType, AsyncGeneratorType, and the newer FrameLocalsProxyType / LazyImportType). These are classes, but the documentation marks them with the .. data:: directive, so existing :class: cross-references to them resolve against a missing py:class target and fail. Affected references appear in Doc/c-api/descriptor.rst, Doc/c-api/frame.rst, Doc/c-api/gen.rst, Doc/c-api/structures.rst, Doc/library/inspect.rst, and several Doc/whatsnew/ pages.

This switches those entries to .. class::, matching how UnionType, CapsuleType, CodeType, and ModuleType are already documented in the same file, and updates the few :data: references to :class: so nothing breaks in the other direction.

The singleton-value types NoneType, NotImplementedType, and EllipsisType are handled in a separate PR.

Refs: gh-89554 (reported in 2021; UnionType was fixed then in GH-28757, the remainder left open). Documentation-only change, so no Misc/NEWS entry (skip news).

cc @AA-Turner as the Lib/types.py maintainer.

The type objects exposed by the types module (FunctionType, MethodType, the descriptor type family, FrameType and others) are classes, but were documented with the ".. data::" directive. As a result existing ":class:`types.X`" cross-references, such as those in the C API docs for descriptors, frames, generators and structures, and in inspect and the What's New pages, fail to resolve against a py:class target. Switch these entries to ".. class::", matching the existing treatment of UnionType, CapsuleType, CodeType and ModuleType in the same file, and update the handful of ":data:" references accordingly so nothing breaks in the other direction. The singleton-value types NoneType, NotImplementedType and EllipsisType are left as ".. data::" for now, since they are referenced as the type of a singleton value (:data:) and warrant a separate discussion.

Documentation build overview

📚 cpython-previews | 🛠️ Build #32924395 | 📁 Comparing 3df4894 against main (2f8f569)

🔍 Preview build

4 files changed
± howto/a-conceptual-overview-of-asyncio.html
± library/types.html
± whatsnew/3.10.html
± whatsnew/3.15.html

Those are actually real data, not classes. The objects are not defined in those modules, but in C and therefore there is a distinction between them.

Backward-compatibility check.

Across these symbols, downstream nitpick_ignore lists reference them as py:class 8–150× more than py:data (FunctionType 330:39, FrameType 251:8, MethodType 180:17, GeneratorType 152:1), and Sphinx autodoc already emits :py:class: for them via _INVALID_BUILTIN_CLASSES.
The only verified independent hand-written :data: reference that would break is SimPy (a :data: reference to types.MethodType in docs/about/defense_of_design.rst).
:obj: and autodoc references are unaffected; existing :class: references (for example throughout Doc/c-api/) get fixed.

This resolves more references than it breaks.

That distinction is real at the implementation level: types re-exports type objects defined in C rather than defining them itself.

The difficulty is that the same file already documents C-defined type objects with .. class::: CodeType, ModuleType, TracebackType, MappingProxyType, GenericAlias, UnionType, and CapsuleType. None of those are defined in types.py either; they are C type objects exposed as names, the same as FunctionType or FrameType. So "defined in C" does not separate the current .. data:: entries from the .. class:: ones. The split that does hold is whether a constructor signature is shown, and UnionType / CapsuleType are .. class:: without one.

The directive also drives cross-referencing rather than provenance. inspect.isclass() is true for all of these, and CPython's own C-API docs already reference them with :class: — for example Doc/c-api/descriptor.rst (GetSetDescriptorType, MemberDescriptorType, MethodDescriptorType, WrapperDescriptorType), Doc/c-api/frame.rst (FrameType), and Doc/c-api/gen.rst (AsyncGeneratorType) — which is why those links do not resolve today. Downstream, Sphinx itself maps these to their types.* name and renders them as classes in _INVALID_BUILTIN_CLASSES, so autodoc emits class references to them regardless of the directive used here. Other projects keep their own copy of that table, for example npdoc2md and quicktile.

What criterion would you want applied? If "type objects re-exported from C should be .. data::", then CodeType / ModuleType / TracebackType / UnionType / CapsuleType fall under it too and should move back for consistency. If "documented as a class when it is a class", the remaining .. data:: entries are the ones out of step. Either way works for me; I would just like the file to end up internally consistent.

Urgh ok, let'd use class everywhere. It will solve future issues. It may also solve issues with autodoc in general.

LGTM. 👍

Thanks @gaborbernat for the PR, and @serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

Sorry, @gaborbernat and @serhiy-storchaka, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker bc055444e4ade9e210139d07200f602a4a9feb67 3.14

GH-150761 is a backport of this pull request to the 3.15 branch.

Sorry, @gaborbernat and @serhiy-storchaka, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker bc055444e4ade9e210139d07200f602a4a9feb67 3.13

…H-150676) (GH-150761) Use the directive and the role "class" instead of "data" for classes exposed in the types module. (cherry picked from commit bc05544) Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>

Please don't forget about backports.

GH-153757 is a backport of this pull request to the 3.14 branch.

GH-153758 is a backport of this pull request to the 3.13 branch.

…H-150676) (GH-153758) Use the directive and the role "class" instead of "data" for classes exposed in the types module. (cherry picked from commit bc05544) Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>

…H-150676) (GH-153757) Use the directive and the role "class" instead of "data" for classes exposed in the types module. (cherry picked from commit bc05544) Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>

gaborbernat requested a review from AA-Turner as a code owner May 31, 2026 17:04

bedevere-app Bot added docs Documentation in the Doc dir skip news labels May 31, 2026

bedevere-app Bot mentioned this pull request May 31, 2026

Intersphinx inventory classifies some type-like objects as data #89554

Open

bedevere-app Bot added the awaiting review label May 31, 2026

github-project-automation Bot added this to Docs PRs May 31, 2026

github-project-automation Bot moved this to Todo in Docs PRs May 31, 2026

gaborbernat mentioned this pull request May 31, 2026

gh-89554: Document NoneType, NotImplementedType and EllipsisType as classes #150682

Merged

serhiy-storchaka approved these changes Jun 2, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting review labels Jun 2, 2026

serhiy-storchaka added needs backport to 3.13 only security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 bugs and security fixes labels Jun 2, 2026

serhiy-storchaka merged commit bc05544 into python:main Jun 2, 2026
46 checks passed

github-project-automation Bot moved this from Todo to Done in Docs PRs Jun 2, 2026

bedevere-app Bot removed the awaiting merge label Jun 2, 2026

miss-islington-app Bot assigned serhiy-storchaka Jun 2, 2026

bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Jun 2, 2026

serhiy-storchaka removed their assignment Jul 15, 2026

serhiy-storchaka mentioned this pull request Jul 15, 2026

[3.14] gh-89554: Document standard type objects in types as classes (GH-150676) #153757

Merged

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Jul 15, 2026

serhiy-storchaka mentioned this pull request Jul 15, 2026

[3.13] gh-89554: Document standard type objects in types as classes (GH-150676) #153758

Merged

bedevere-app Bot removed the needs backport to 3.13 only security fixes label Jul 15, 2026

gaborbernat deleted the gh-89554-types-class-roles branch October 3, 2026 15:12

gh-89554: Document standard type objects in types as classes by gaborbernat · Pull Request #150676 · python/cpython · GitHub

Repository navigation

gh-89554: Document standard type objects in types as classes - #150676

gh-89554: Document standard type objects in types as classes#150676serhiy-storchaka merged 1 commit intopython:mainpython/cpython:mainfrom gaborbernat:gh-89554-types-class-rolesgaborbernat/cpython:gh-89554-types-class-rolesCopy head branch name to clipboard

Conversation

gaborbernat commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented May 31, 2026

Documentation build overview

Uh oh!

picnixz commented May 31, 2026

Uh oh!

gaborbernat commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gaborbernat commented Jun 1, 2026

Uh oh!

picnixz commented Jun 1, 2026

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app Bot commented Jun 2, 2026

Uh oh!

miss-islington-app Bot commented Jun 2, 2026

Uh oh!

bedevere-app Bot commented Jun 2, 2026

Uh oh!

miss-islington-app Bot commented Jun 2, 2026

Uh oh!

serhiy-storchaka commented Jul 15, 2026

Uh oh!

bedevere-app Bot commented Jul 15, 2026

Uh oh!

bedevere-app Bot commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gh-89554: Document standard type objects in types as classes#150676
serhiy-storchaka merged 1 commit into
python:mainfrom
gaborbernat:gh-89554-types-class-roles

gaborbernat commented May 31, 2026 •
edited
Loading

gaborbernat commented Jun 1, 2026 •
edited
Loading