classification
Title: Document the ABCs for instance/subclass checks of dict view types
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ebarry, story645, terry.reedy
Priority: normal Keywords: patch

Created on 2016-07-18 01:25 by story645, last changed 2016-07-22 20:28 by terry.reedy.

Files
File name Uploaded Description Edit
dict_view_doc_1.patch ebarry, 2016-07-18 01:41 review
Messages (3)
msg270672 - (view) Author: hannah (story645) Date: 2016-07-18 01:25
While there is documentation that dict.keys(), dict.values(), and dict.items() are now view objects(https://docs.python.org/3/library/stdtypes.html#dict-views), there's no mention dictviews, dict_keys, dict_values, and dict_items not being built-ins. This is confusing because type(dict.keys()) returns dict_keys, type(dict.values()) returns dict_values, etc., and the documentation uses `dictview` as the object signature, and so it's unclear how to do object introspection on dictview objects. 

The #python-dev channel suggested that the canonical way to do the object introspection is to use the collections.abc.mapview types; the documentation for dicts should reflect this (and that dictview and the rest are not __builtin__ types/in the python namspace).
msg270674 - (view) Author: Emanuel Barry (ebarry) * Date: 2016-07-18 01:41
"The #python-dev channel" being me in this context ;) Patch attached.
msg271029 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-07-22 20:28
The view objects *are* built-ins, but are not exposed in the __builtins__ module.  This is true of many internal types, perhaps even a majority. The function and list_iterator classes are other examples.

>>> type(lambda: 0)
<class 'function' at 0x0000000054B038B0>
>>> type(iter([]))
<class 'list_iterator' at 0x0000000054B05A60>

A few such 'hidden' classes are exposed in the types module.

"This module provides names for many of the types that are required to implement a Python interpreter. It deliberately avoids including some of the types that arise only incidentally during processing such as the listiterator type.

Typical use of these names is for isinstance() or issubclass() checks."

The function class is.

"types.FunctionType
types.LambdaType

    The type of user-defined functions and functions created by lambda expressions."
  
The list_iterator class is not. Perhaps the rationale is that there is no reason to know whether an iterator is iterating over a list, tuple, range, set, frozenset, dict, or anything else.  They are all used the same.  On the other hand, Different view types are used a bit differently.

Types includes a generic MappingProxyType.  Perhaps you should propose adding the specific dict view types.  Or you can create them yourself.
  KeysViewType = type({}.keys())
  ValuesViewType = type({}.values())
  ItemsViewType = type({}.items())
This is the code that would be used in the module if they were added there.
History
Date User Action Args
2016-07-22 20:28:14terry.reedysetnosy: + terry.reedy

messages: + msg271029
versions: - Python 3.2, Python 3.3, Python 3.4
2016-07-18 01:43:08ebarrysettitle: documentiona of dict view types -> Document the ABCs for instance/subclass checks of dict view types
2016-07-18 01:41:17ebarrysetfiles: + dict_view_doc_1.patch

nosy: + ebarry
messages: + msg270674

keywords: + patch
stage: patch review
2016-07-18 01:26:43story645settitle: Document checking dict types -> documentiona of dict view types
2016-07-18 01:25:16story645create