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 <encukou@gmail.com>

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:: int PyDictViewSet_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 <zintensitydev@gmail.com> Co-authored-by: Petr Viktorin <encukou@gmail.com>

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 <zintensitydev@gmail.com> Co-authored-by: Petr Viktorin <encukou@gmail.com>

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 <zintensitydev@gmail.com> Co-authored-by: Petr Viktorin <encukou@gmail.com>

…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 <zintensitydev@gmail.com> Co-authored-by: Petr Viktorin <encukou@gmail.com>

* 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) ...

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

81bcdec

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

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

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

bedevere-app bot 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 resolved Hide resolved

Update Doc/c-api/dict.rst

de6b12f

Co-authored-by: Petr Viktorin <encukou@gmail.com>

ZeroIntensity commented Nov 5, 2025

View reviewed changes

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

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

Doc/c-api/dict.rst Outdated Show resolved Hide 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-app bot 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:main Nov 13, 2025
28 checks passed

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

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

bedevere-app bot removed the awaiting merge label Nov 13, 2025

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

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


		.. c:function:: int PyDictViewSet_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!

picnixz Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

picnixz Nov 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!

ZeroIntensity Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

picnixz Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Nov 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-app bot commented Nov 13, 2025

Uh oh!

bedevere-app bot commented Nov 13, 2025

Uh oh!

bedevere-app bot commented Nov 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ZeroIntensity commented Nov 4, 2025 •

edited

Loading

picnixz Nov 12, 2025 •

edited

Loading

encukou left a comment •

edited

Loading