Docs: TypedDict is now of type function instead of class

[gaborbernat]

BPO	41973
Nosy	@gvanrossum, @ssbarnea, @serhiy-storchaka, @asottile, @gaborbernat, @Fidget-Spinner, @akulakov

^{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 2020-10-08.06:26:46.964>
labels = ['3.11', '3.9', '3.10', 'docs']
title = 'Docs: TypedDict is now of type function instead of class'
updated_at = <Date 2021-08-01.18:01:50.338>
user = 'https://github.com/gaborbernat'

bugs.python.org fields:

activity = <Date 2021-08-01.18:01:50.338>
actor = 'serhiy.storchaka'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-10-08.06:26:46.964>
creator = 'gaborjbernat'
dependencies = []
files = []
hgrepos = []
issue_num = 41973
keywords = []
message_count = 7.0
messages = ['378212', '378213', '378216', '378217', '398707', '398717', '398718']
nosy_count = 8.0
nosy_names = ['gvanrossum', 'ssbarnea', 'docs@python', 'serhiy.storchaka', 'Anthony Sottile', 'gaborjbernat', 'kj', 'andrei.avk']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue41973'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• gh-86139: Correct NamedTuple and TypedDict's type in typing.rst #143692
• [3.14] gh-86139: Correct NamedTuple and TypedDict's type in typing.rst (GH-143692) #143696
• [3.13] gh-86139: Correct NamedTuple and TypedDict's type in typing.rst (GH-143692) #143697
• gh-143728: Keep TypedDict and NamedTuple in class role in docs #143702

[gaborbernat]

❯ py -3.8 -c 'from typing import TypedDict; print(type(TypedDict))'
<class 'typing._TypedDictMeta'>

❯ py -3.9 -c 'from typing import TypedDict; print(type(TypedDict))'
<class 'function'>

Python 3.9 changed the type of the TypedDict but the documentation still says it's a class - see https://docs.python.org/3.9/library/typing.html#typing.TypedDict. I must also say I'm suprised you can inherit from a function, but we should update the documentation to reflect that the type of the element in question is no longer class.

[asottile]

Seems to be due to https://bugs.python.org/issue40187

[gaborbernat]

Static checkers/linters (see e.g. pylint-dev/pylint#3884) are caught of guard by being able to inherit from functions. They'll need to adapt, but let's update the documentation to reflect this.

[gaborbernat]

This seem to apply to typing.NamedTuple too.

[akulakov]

I haven't looked too much into typing module, so take this with a grain of salt, but my understanding is that TypedDict is a special construct (as the first sentence in the docs defines it), which can be used as a base. I think most users would consider something a kind of a class if it can be inherited from by a user-defined class, so this classification in the docs is useful.

Normally functions can't be used as a base of course. There's no "inheritable from" abc or anything like that and functions are not inherited from "function type". You generally don't care if something is a function, you care if it's a callable and test for that with callable().

So in a sense a function is the most inherently duck typed object in Python.

The only way for a specific check of a function type is AFAIK type(known_function) == type(myobj), but this type of checking is discouraged.

So static checkers that run into a problem with this are probably assuming too much about what a function is or should be in Python.

To sum up, TypedDict is a kind of a construct between a class and a function that's more usefully documented as, and used as, a class. The docs make it very clear that it's not your usual, run of the mill class.

[serhiy-storchaka]

TypeDict is a callable, it can be used as

    Point2D = TypedDict('Point2D', x=int, y=int, label=str)

It can also be used as a base in class definition, but is is not a class itself. It does not occur in __bases__ of the created class, and it cannot be used in isinstance() and issubclass() checks. It is just yet one weird way to customize class creation.

I agree that documenting it as class is not correct. Perhaps it should be declared as a function (with specifying its signature when used as a function) and referred with the :data: role.

[serhiy-storchaka]

Actually most names defined in typing are no longer classes.