python / python/mypy

TypedDict -> dict compatibility

Open
#13,122 6 comments 10 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

feature topic-typed-dict
Dominant language
Python
Stars
20.6k
Forks
3.3k
PR merge metrics
PR metrics pending

Description

Feature

Allow for TypedDicts (or a new type specialized for this purpose) to be compatible with dict when the receiver declares it is not going to mutate the dict.

Pitch

When using a TypedDict, it is common to eventually pass it to a function that takes an arbitrary dict or return it to the caller expecting the same. Currently this is rejected, and the reason makes sense. For example, this is correctly rejected:

class DefinitelyContainsStatus(TypedDict):
    status: str

def delete_status(d: dict):
    del d['status']

d: DefinitelyContainsStatus = {'status': 'ok'}
delete_status(d)
assert d['status'] == 'ok'

If it were permitted, a type checker wouldn't be able to know how the dict is going to be mutated, and then any other references that may exist would still expect it to conform to the TypedDict.

However, this presumably valid case is also rejected:

def foo() -> DefinitelyContainsStatus:
    return {'status': 'ok'}

f: dict[str, str] = foo()

# error: Incompatible types in assignment (expression has type "DefinitelyContainsStatus", variable has type "Dict[str, str]")  [assignment]

Here's a real-world example that has lead to the creation of this feature request. In Flask it is allowed to return a dict from a view function, which it then converts to JSON. This is particularly convenient in order to apply type checking to a JSON-based HTTP API. However, when the return type is declared to be some TypedDict, this is rejected:

class Example(TypedDict):
    status: str

@blueprint.route("/example")
def example() -> Example:
    return {"status": "ok"}

# error: Value of type variable "ft.RouteDecorator" of function cannot be "Callable[[str], Example]"  [type-var]

On the Flask side of things, they specifically require a real dict, so they cannot change the type to accept Mapping. It would be quite useful to be able to allow returning TypedDict from a function to a caller that accepts dict.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No files, tests, or entry points are named. Start by examining the TypedDict and dict compatibility examples in the issue, then trace the type-checker's existing assignment and callable compatibility rules. Done means safe non-mutating uses are accepted while the deletion example remains rejected.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
devtools
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.