C API dictionary views type checkers are not documented

[salty-horse]

BPO	35827
Nosy	@salty-horse, @tiran, @serhiy-storchaka

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-01-25.12:05:04.644>
labels = ['3.7', '3.8', '3.9', 'expert-C-API', 'type-feature', 'docs']
title = 'C API dictionary views type checkers are not documented'
updated_at = <Date 2019-12-10.11:21:51.844>
user = 'https://github.com/salty-horse'

bugs.python.org fields:

activity = <Date 2019-12-10.11:21:51.844>
actor = 'serhiy.storchaka'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'C API']
creation = <Date 2019-01-25.12:05:04.644>
creator = 'salty-horse'
dependencies = []
files = []
hgrepos = []
issue_num = 35827
keywords = []
message_count = 2.0
messages = ['334355', '358182']
nosy_count = 4.0
nosy_names = ['salty-horse', 'christian.heimes', 'docs@python', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue35827'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

[salty-horse]

dictobject.h defines several helpers to ease checking of dictionary view types. If they are meant to be part of the API, they should be documented.

PyDictKeys_Check
PyDictItems_Check
PyDictValues_Check
PyDictViewSet_Check

Should they be added to dict.rst, or a separate file?

[serhiy-storchaka]

They were added in a22e8bd. Additional types like PyDictRevIterKey_Type were added later. I am not sure that all these types should be exposed in the public C API.

[iritkatriel]

They seem to be misnamed too. With these checks they should probably have been named *_CheckExact:

#define PyDictKeys_Check(op) (Py_Type(op) == &PyDictKeys_Type)
#define PyDictItems_Check(op) (Py_Type(op) == &PyDictItems_Type)
#define PyDictValues_Check(op) (Py_Type(op) == &PyDictValues_Type)

[encukou]

They can't be subclassed (they don't have Py_TPFLAGS_BASETYPE), so the C equality is good for both _Check and _CheckExact.

They are in a public header, so removing them would need a deprecation cycle. Better to document them, IMO. (PRs welcome.)

If we deprecate them: you can use PyType_IsSubtype for any type that doesn't have a _Check convenience macro.