gh-141004: Document C APIs for dictionary keys, values, and items#141009

ZeroIntensity · 2025-11-04T17:07:21Z

Issue: Document the entire C API #141004

📚 Documentation preview 📚: https://cpython-previews--141009.org.readthedocs.build/en/141009/c-api/dict.html#dictionary-objects

Doc/c-api/dict.rst

Co-authored-by: Petr Viktorin <[email protected]>

Doc/c-api/dict.rst

ZeroIntensity · 2025-11-12T23:06:32Z

@encukou, this PR is blocking #141136. Are you happy with this?

picnixz · 2025-11-12T23:22:56Z

Doc/c-api/dict.rst

+
+.. c:function::intPyDictViewSet_Check(PyObject *o)
+
+ Return true if *o* is a view of a set inside a dictionary. This is currently


Can we use "op" for the argument as we use it everywhere else for "object pointer"?

TIL that's what it stood for, I thought it was "operand". I'll update it.

FTR there are other occurrences below

Ah, right. Fixed those too.

picnixz · 2025-11-12T23:45:33Z

Doc/c-api/dict.rst

+.. c:var:: PyTypeObject PyDictItems_Type
+
+ Type object for a view of dictionary items. In Python, this is the type of
+ the object returned by :meth:`dict.items`.


Don't we have collections.abc.DictViewSomething? or types.*?

We do, but I'm not sure it's worth pointing to it here, because there's no actual correlation between the two types at runtime.

encukou

Please consider:

a table to avoid repetitive prose
a single “Dict view objects” section with all these and PyDictViewSet_Check

But, the PR is an improvement as is.

ZeroIntensity · 2025-11-13T14:57:20Z

a single “Dict view objects” section with all these and PyDictViewSet_Check

I like that idea, I went with that. I'm not too sure how I would format this under a table.

miss-islington-app · 2025-11-13T15:02:25Z

Thanks @ZeroIntensity for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

…ms (pythonGH-141009) (cherry picked from commit f72768f) Co-authored-by: Peter Bierma <[email protected]> Co-authored-by: Petr Viktorin <[email protected]>

bedevere-app · 2025-11-13T15:02:34Z

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

…ms (pythonGH-141009) (cherry picked from commit f72768f) Co-authored-by: Peter Bierma <[email protected]> Co-authored-by: Petr Viktorin <[email protected]>

bedevere-app · 2025-11-13T15:02:39Z

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

…ems (GH-141009) (GH-141512) gh-141004: Document C APIs for dictionary keys, values, and items (GH-141009) (cherry picked from commit f72768f) Co-authored-by: Peter Bierma <[email protected]> Co-authored-by: Petr Viktorin <[email protected]>

…ems (GH-141009) (GH-141513) gh-141004: Document C APIs for dictionary keys, values, and items (GH-141009) (cherry picked from commit f72768f) Co-authored-by: Peter Bierma <[email protected]> Co-authored-by: Petr Viktorin <[email protected]>

* main: (463 commits) pythongh-140601: Add ResourceWarning to iterparse when not closed (pythonGH-140603) pythongh-137969: Fix double evaluation of `ForwardRef`s which rely on globals (python#140974) pythongh-139109: A new tracing JIT compiler frontend for CPython (pythonGH-140310) pythongh-141004: Document `PyErr_RangedSyntaxLocationObject` (python#141521) pythongh-140873: Add support of non-descriptor callables in functools.singledispatchmethod() (pythonGH-140884) pythongh-139653: Add PyUnstable_ThreadState_SetStackProtection() (python#139668) pythongh-141004: Document `PyCode_Optimize` (pythonGH-141378) pythongh-141004: Document C APIs for dictionary keys, values, and items (pythonGH-141009) pythongh-137959: Fix `TIER1_TO_TIER2` macro name in JIT InternalDocs (pythonGH-141496) pythongh-139871: Add `bytearray.take_bytes([n])` to efficiently extract `bytes` (pythonGH-140128) pythongh-140601: Refactor ElementTree.iterparse() tests (pythonGH-141499) pythongh-135801: Add the module parameter to compile() etc (pythonGH-139652) pythongh-140260: fix data race in `_struct` module initialization with subinterpreters (python#140909) pythongh-137109: refactor warning about threads when forking (python#141438) pythongh-141004: Document `PyRun_InteractiveOneObject` (pythonGH-141405) pythongh-124111: Fix TCL 9 thread detection (pythonGH-128103) pythongh-141442: Add escaping to iOS testbed arguments (python#141443) pythongh-140936: Fix JIT assertion crash at finalization if some generator is alive (pythonGH-140969) Add details about JIT build infrastructure and updating dependencies to `Tools/jit` (python#141167) pythongh-141412: Use reliable target URL for urllib example (pythonGH-141428) ...

* 'main' of github.com:python/cpython: (464 commits) pythongh-140601: Add ResourceWarning to iterparse when not closed (pythonGH-140603) pythongh-137969: Fix double evaluation of `ForwardRef`s which rely on globals (python#140974) pythongh-139109: A new tracing JIT compiler frontend for CPython (pythonGH-140310) pythongh-141004: Document `PyErr_RangedSyntaxLocationObject` (python#141521) pythongh-140873: Add support of non-descriptor callables in functools.singledispatchmethod() (pythonGH-140884) pythongh-139653: Add PyUnstable_ThreadState_SetStackProtection() (python#139668) pythongh-141004: Document `PyCode_Optimize` (pythonGH-141378) pythongh-141004: Document C APIs for dictionary keys, values, and items (pythonGH-141009) pythongh-137959: Fix `TIER1_TO_TIER2` macro name in JIT InternalDocs (pythonGH-141496) pythongh-139871: Add `bytearray.take_bytes([n])` to efficiently extract `bytes` (pythonGH-140128) pythongh-140601: Refactor ElementTree.iterparse() tests (pythonGH-141499) pythongh-135801: Add the module parameter to compile() etc (pythonGH-139652) pythongh-140260: fix data race in `_struct` module initialization with subinterpreters (python#140909) pythongh-137109: refactor warning about threads when forking (python#141438) pythongh-141004: Document `PyRun_InteractiveOneObject` (pythonGH-141405) pythongh-124111: Fix TCL 9 thread detection (pythonGH-128103) pythongh-141442: Add escaping to iOS testbed arguments (python#141443) pythongh-140936: Fix JIT assertion crash at finalization if some generator is alive (pythonGH-140969) Add details about JIT build infrastructure and updating dependencies to `Tools/jit` (python#141167) pythongh-141412: Use reliable target URL for urllib example (pythonGH-141428) ...

…ms (pythonGH-141009) Co-authored-by: Petr Viktorin <[email protected]>

Document C APIs for dictionary keys, values, and items.
81bcdec

bedevere-appbot added awaiting core review docs Documentation in the Doc dir skip news labels Nov 4, 2025

github-project-automationbot added this to Docs PRs Nov 4, 2025

github-project-automationbot moved this to Todo in Docs PRs Nov 4, 2025

bedevere-appbot mentioned this pull request Nov 4, 2025
Document the entire C API #141004
Open

ZeroIntensity added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Nov 4, 2025

encukou reviewed Nov 4, 2025
View reviewed changes

Doc/c-api/dict.rst Outdated Show resolvedHide resolved

Update Doc/c-api/dict.rst
de6b12f
Co-authored-by: Petr Viktorin <[email protected]>

ZeroIntensity commented Nov 5, 2025
View reviewed changes

Doc/c-api/dict.rst Outdated Show resolvedHide resolved
Doc/c-api/dict.rst Outdated Show resolvedHide resolved
Doc/c-api/dict.rst Outdated Show resolvedHide resolved

ZeroIntensity added 2 commits November 5, 2025 09:27

Remove iterator types
fcee529

Merge branch 'main' into document-missing-dict
823ace9

ZeroIntensity mentioned this pull request Nov 12, 2025
gh-141004: Document PyODict* APIs #141136
Merged

picnixz reviewed Nov 12, 2025
View reviewed changes

Use "op" instead of "o".
2cd976b

picnixz reviewed Nov 12, 2025
View reviewed changes

"o" -> "op" (for real this time)
66f3faa

encukou approved these changes Nov 13, 2025
View reviewed changes

bedevere-appbot added awaiting merge and removed awaiting core review labels Nov 13, 2025

Add all under one section
a394837

ZeroIntensity enabled auto-merge (squash) November 13, 2025 14:57

ZeroIntensity merged commit f72768f into python:mainNov 13, 2025
28 checks passed

ZeroIntensity deleted the document-missing-dict branch November 13, 2025 15:02

github-project-automationbot moved this from Todo to Done in Docs PRs Nov 13, 2025

bedevere-appbot removed the awaiting merge label Nov 13, 2025

bedevere-appbot removed the needs backport to 3.14 bugs and security fixes label Nov 13, 2025

bedevere-appbot removed the needs backport to 3.13 bugs and security fixes label Nov 13, 2025

StanFromIreland pushed a commit to StanFromIreland/cpython that referenced this pull request Dec 6, 2025
pythongh-141004: Document C APIs for dictionary keys, values, and ite…
9ddca3e
…ms (pythonGH-141009) Co-authored-by: Petr Viktorin <[email protected]>


		.. c:function::intPyDictViewSet_Check(PyObject *o)

		Return true if o is a view of a set inside a dictionary. This is currently

Uh oh!

gh-141004: Document C APIs for dictionary keys, values, and items#141009

gh-141004: Document C APIs for dictionary keys, values, and items #141009

Uh oh!

Conversation

ZeroIntensity commented Nov 4, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ZeroIntensity commented Nov 12, 2025

Uh oh!

picnixzNov 12, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensityNov 12, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensityNov 12, 2025

Choose a reason for hiding this comment

Uh oh!

picnixzNov 12, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensityNov 13, 2025

Choose a reason for hiding this comment

Uh oh!

picnixzNov 12, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensityNov 13, 2025

Choose a reason for hiding this comment

Uh oh!

encukou left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity commented Nov 13, 2025

Uh oh!

Uh oh!

miss-islington-appbot commented Nov 13, 2025

Uh oh!

bedevere-appbot commented Nov 13, 2025

Uh oh!

bedevere-appbot commented Nov 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ZeroIntensity commented Nov 4, 2025•
edited
Loading

picnixzNov 12, 2025•
edited
Loading

encukou left a comment •
edited
Loading