From 81bcdec4216c85222ec2b3fd3a19e37510b2cd7a Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 4 Nov 2025 12:06:32 -0500 Subject: [PATCH 1/6] Document C APIs for dictionary keys, values, and items. --- Doc/c-api/dict.rst | 82 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 0abbd662dad394..947884806d25f9 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -426,3 +426,85 @@ Dictionary Objects it before returning. .. versionadded:: 3.12 + + +.. c:function:: int PyDictViewSet_Check(PyObject *o) + + Return true if *o* is a view of a set inside a dictionary. This is + equivalent to :c:expr:`PyDictKeys_Check(o) || PyDictItems_Check(o)`. This + function always succeeds. + + +Dictionary Keys Objects +^^^^^^^^^^^^^^^^^^^^^^^ + +.. c:var:: PyTypeObject PyDictKeys_Type + + Type object for a view of dictionary keys. In Python, this is the type of + the object returned by :meth:`dict.keys`. + + +.. c:function:: int PyDictKeys_Check(PyObject *o) + + Return true if *o* is an instance of a dictionary keys view. This function + always succeeds. + + +.. c:var:: PyTypeObject PyDictIterKey_Type + + Iterator over the keys of a dictionary. + + +.. c:var:: PyTypeObject PyDictRevIterKey_Type + + Reversed iterator over the keys of a dictionary. + + +Dictionary Values Objects +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. c:var:: PyTypeObject PyDictValues_Type + + Type object for a view of dictionary values. In Python, this is the type of + the object returned by :meth:`dict.values`. + + +.. c:function:: int PyDictValues_Check(PyObject *o) + + Return true if *o* is an instance of a dictionary values view. This function + always succeeds. + + +.. c:var:: PyTypeObject PyDictIterValue_Type + + Iterator over the values of a dictionary. + + +.. c:var:: PyTypeObject PyDictRevIterValue_Type + + Reversed iterator over the values of a dictionary. + + +Dictionary Items Objects +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. 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`. + + +.. c:function:: int PyDictItems_Check(PyObject *o) + + Return true if *o* is an instance of a dictionary items view. This function + always succeeds. + + +.. c:var:: PyTypeObject PyDictIterItem_Type + + Iterator over the items of a dictionary. + + +.. c:var:: PyTypeObject PyDictRevIterItem_Type + + Reversed iterator over the items of a dictionary. From de6b12fd69278a224cb8d2c03dda73ecfae7bae9 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 4 Nov 2025 17:14:58 -0500 Subject: [PATCH 2/6] Update Doc/c-api/dict.rst Co-authored-by: Petr Viktorin --- Doc/c-api/dict.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 947884806d25f9..5efaced278fa20 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -430,7 +430,7 @@ Dictionary Objects .. c:function:: int PyDictViewSet_Check(PyObject *o) - Return true if *o* is a view of a set inside a dictionary. This is + Return true if *o* is a view of a set inside a dictionary. This is currently equivalent to :c:expr:`PyDictKeys_Check(o) || PyDictItems_Check(o)`. This function always succeeds. From fcee52955c1ea79e41e7af5a79d8b84b66f6e598 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 5 Nov 2025 09:27:16 -0500 Subject: [PATCH 3/6] Remove iterator types --- Doc/c-api/dict.rst | 30 ------------------------------ 1 file changed, 30 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 5efaced278fa20..8a10ce0d87d0e0 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -450,16 +450,6 @@ Dictionary Keys Objects always succeeds. -.. c:var:: PyTypeObject PyDictIterKey_Type - - Iterator over the keys of a dictionary. - - -.. c:var:: PyTypeObject PyDictRevIterKey_Type - - Reversed iterator over the keys of a dictionary. - - Dictionary Values Objects ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -475,16 +465,6 @@ Dictionary Values Objects always succeeds. -.. c:var:: PyTypeObject PyDictIterValue_Type - - Iterator over the values of a dictionary. - - -.. c:var:: PyTypeObject PyDictRevIterValue_Type - - Reversed iterator over the values of a dictionary. - - Dictionary Items Objects ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -498,13 +478,3 @@ Dictionary Items Objects Return true if *o* is an instance of a dictionary items view. This function always succeeds. - - -.. c:var:: PyTypeObject PyDictIterItem_Type - - Iterator over the items of a dictionary. - - -.. c:var:: PyTypeObject PyDictRevIterItem_Type - - Reversed iterator over the items of a dictionary. From 2cd976bcc13a14a6506a4020c8df7b411e32e5b8 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 12 Nov 2025 18:41:39 -0500 Subject: [PATCH 4/6] Use "op" instead of "o". --- Doc/c-api/dict.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 8a10ce0d87d0e0..b4457accc1bd0f 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -428,10 +428,10 @@ Dictionary Objects .. versionadded:: 3.12 -.. c:function:: int PyDictViewSet_Check(PyObject *o) +.. c:function:: int PyDictViewSet_Check(PyObject *op) - Return true if *o* is a view of a set inside a dictionary. This is currently - equivalent to :c:expr:`PyDictKeys_Check(o) || PyDictItems_Check(o)`. This + Return true if *op* is a view of a set inside a dictionary. This is currently + equivalent to :c:expr:`PyDictKeys_Check(op) || PyDictItems_Check(op)`. This function always succeeds. From 66f3faa0588e69220f15098cb9bd1509c3d9e8e3 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 12 Nov 2025 19:59:16 -0500 Subject: [PATCH 5/6] "o" -> "op" (for real this time) --- Doc/c-api/dict.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index b4457accc1bd0f..148664123f661b 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -444,9 +444,9 @@ Dictionary Keys Objects the object returned by :meth:`dict.keys`. -.. c:function:: int PyDictKeys_Check(PyObject *o) +.. c:function:: int PyDictKeys_Check(PyObject *op) - Return true if *o* is an instance of a dictionary keys view. This function + Return true if *op* is an instance of a dictionary keys view. This function always succeeds. @@ -459,9 +459,9 @@ Dictionary Values Objects the object returned by :meth:`dict.values`. -.. c:function:: int PyDictValues_Check(PyObject *o) +.. c:function:: int PyDictValues_Check(PyObject *op) - Return true if *o* is an instance of a dictionary values view. This function + Return true if *op* is an instance of a dictionary values view. This function always succeeds. @@ -474,7 +474,7 @@ Dictionary Items Objects the object returned by :meth:`dict.items`. -.. c:function:: int PyDictItems_Check(PyObject *o) +.. c:function:: int PyDictItems_Check(PyObject *op) - Return true if *o* is an instance of a dictionary items view. This function + Return true if *op* is an instance of a dictionary items view. This function always succeeds. From a39483703a173b47d7aa473f50a8b9fb4925194f Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 13 Nov 2025 09:56:32 -0500 Subject: [PATCH 6/6] Add all under one section --- Doc/c-api/dict.rst | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 148664123f661b..1b3380fb25d300 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -428,6 +428,9 @@ Dictionary Objects .. versionadded:: 3.12 +Dictionary View Objects +^^^^^^^^^^^^^^^^^^^^^^^ + .. c:function:: int PyDictViewSet_Check(PyObject *op) Return true if *op* is a view of a set inside a dictionary. This is currently @@ -435,9 +438,6 @@ Dictionary Objects function always succeeds. -Dictionary Keys Objects -^^^^^^^^^^^^^^^^^^^^^^^ - .. c:var:: PyTypeObject PyDictKeys_Type Type object for a view of dictionary keys. In Python, this is the type of @@ -450,9 +450,6 @@ Dictionary Keys Objects always succeeds. -Dictionary Values Objects -^^^^^^^^^^^^^^^^^^^^^^^^^ - .. c:var:: PyTypeObject PyDictValues_Type Type object for a view of dictionary values. In Python, this is the type of @@ -465,9 +462,6 @@ Dictionary Values Objects always succeeds. -Dictionary Items Objects -^^^^^^^^^^^^^^^^^^^^^^^^ - .. c:var:: PyTypeObject PyDictItems_Type Type object for a view of dictionary items. In Python, this is the type of