search

python / cpython

The Python programming language
https://www.python.org/
Other
61.35k stars 29.55k forks source link

C API dictionary views type checkers are not documented #80008

Open a194bc7e-5121-41ab-8683-1b0c8e41be0b opened 5 years ago

a194bc7e-5121-41ab-8683-1b0c8e41be0b commented 5 years ago
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: ```python assignee = None closed_at = None created_at = 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 = user = 'https://github.com/salty-horse' ``` bugs.python.org fields: ```python activity = actor = 'serhiy.storchaka' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation', 'C API'] creation = 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'] ```

a194bc7e-5121-41ab-8683-1b0c8e41be0b commented 5 years ago

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 commented 4 years ago

They were added in a22e8bdfd92cd4f1bc3d60e91df6410c4efde6a0. 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 commented 1 year ago

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 commented 1 year ago

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.