python / python/mypy

Error message for `TypeForm` arguments with a single unresolvable forward reference is misleading

Open
#21,695 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug topic-type-form
Dominant language
Python
Stars
20.6k
Forks
3.3k
PR merge metrics
PR metrics pending

Description

Bug Report

When passing a single strategized type expression to a function accepting a TypeForm argument, which cannot be fully resolved, due to e.g. a missing import, we get an arg-type error of the form:

Instead of an error, telling us why the type expression is invalid.

To Reproduce
https://mypy-play.net/?mypy=master&python=3.14&gist=891447236311046360886ba63c1fac83

from typing_extensions import TypeForm

def foo[T](x: TypeForm[T]) -> None:
    pass

foo("Unresolvable")

Expected Behavior

mypy should emit a name-error for Unresolvable, since it was never defined. The given example is probably the most controversial case though, since someone may actually accidentally be passing an invalid string literal, but the same thing happens for less controversial cases like "list[Unresolvable]". But I think either way it makes more sense to treat the given string literal as a type expression and emit the same errors you would emit if you saw the same string literal in an annotation.

Actual Behavior

error: Argument 1 to "foo" has incompatible type "str"; expected "TypeForm[Never]"  [arg-type]

This error does not help us solve the problem in our code at all.

Your Environment

  • Mypy version used: 2.2
  • Python version used: 3.14

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

Start by running the supplied mypy-play reproduction with mypy 2.2 and Python 3.14, then trace the TypeForm argument-checking path for a single unresolved string expression. Done means the example reports a name-error for Unresolvable, rather than only the misleading arg-type error.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
compilers
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.