Should a method name shadow outer names when quoted or with PEP563?

[sterliakov]

Bug Report

If a class defines a method with a name shadowing outer name, mypy always rejects it in annotations.

To Reproduce

Consider the following snippet (playground):

#from __future__ import annotations

from typing import get_type_hints, get_origin

class Foo:
    def list(self) -> None: ...
    
    def method(self) -> list[str]:  # E: Function "__main__.Foo.list" is not valid as a type  [valid-type]
        return [""]

Foo().method().append("")  # E: "list?[builtins.str]" has no attribute "append"  [attr-defined]

if get_origin(get_type_hints(Foo.method)['return']) is list:
    print("Resolved to builtins.list")
else:
    print("Resolved as something else")

When run against it, mypy is producing a correct valid-type error, matching runtime behaviour.

$ mypy a.py
a.py:8: error: Function "a.Foo.list" is not valid as a type  [valid-type]
a.py:8: note: Perhaps you need "Callable[...]" or a callback protocol?
a.py:11: error: "list?[builtins.str]" has no attribute "append"  [attr-defined]
Found 2 errors in 1 file (checked 1 source file)

$ pyright a.py
/tmp/tmp.StzhaQlnmA/a.py
  /tmp/tmp.StzhaQlnmA/a.py:8:25 - error: Expected class but received "(self: Self@Foo) -> None" (reportGeneralTypeIssues)
1 error, 0 warnings, 0 informations 

$ python a.py
Traceback (most recent call last):
  File "/tmp/tmp.StzhaQlnmA/a.py", line 5, in <module>
    class Foo:
    ...<3 lines>...
            return [""]
  File "/tmp/tmp.StzhaQlnmA/a.py", line 8, in Foo
    def method(self) -> list[str]:  # E: Function "__main__.Foo.list" is not valid as a type  [valid-type]
                        ~~~~^^^^^
TypeError: 'function' object is not subscriptable

Now let's uncomment the future import or quote list[int] (both behave equivalently).

from __future__ import annotations

from typing import get_type_hints, get_origin

class Foo:
    def list(self) -> None: ...
    
    def method(self) -> list[str]:  # E: Function "__main__.Foo.list" is not valid as a type  [valid-type]
        return [""]

Foo().method().append("")  # E: "list?[builtins.str]" has no attribute "append"  [attr-defined]

if get_origin(get_type_hints(Foo.method)['return']) is list:
    print("Resolved to builtins.list")
else:
    print("Resolved as something else")

$ mypy a.py
a.py:8: error: Function "a.Foo.list" is not valid as a type  [valid-type]
a.py:8: note: Perhaps you need "Callable[...]" or a callback protocol?
a.py:11: error: "list?[builtins.str]" has no attribute "append"  [attr-defined]
Found 2 errors in 1 file (checked 1 source file)

$ pyright a.py
0 errors, 0 warnings, 0 informations 

$ python a.py
Resolved to builtins.list

Runtime resolution also (unsurprisingly, probably) works as intended, so mypy does not model runtime semantics correctly?

Expected Behavior

Snippet with PEP563 enabled should pass mypy check

Actual Behavior

a.py:8: error: Function "a.Foo.list" is not valid as a type  [valid-type]
a.py:8: note: Perhaps you need "Callable[...]" or a callback protocol?
a.py:11: error: "list?[builtins.str]" has no attribute "append"  [attr-defined]
Found 2 errors in 1 file (checked 1 source file)

Your Environment

• Mypy version used: 1.14.1 and latest master
• Mypy command-line flags: N/A
• Mypy configuration options from mypy.ini (and other config files): N/A
• Python version used: 3.13

[sterliakov]

Ough, and it's actually worse and can also cause false negatives:

from __future__ import annotations

from typing import TypeAlias, TypeVar, get_type_hints, get_origin

U = TypeVar('U')

class B:
    list: TypeAlias = set[U]

    def fn(self) -> list[int]:
        return {0}

if get_origin(get_type_hints(B.fn)['return']) is list:
    print("Still a list...")
else:
    print("Not a list?")

mypy happily accepts this snippet, pyright rejects the return value (Type "set[int]" is not assignable to return type "list[int]"), and runtime typehint still evaluates to list.

If I use a non-shadowing alias instead (X: TypeAlias = set[U]), runtime evaluation fails with a NameError, while both mypy and pyright accept the whole snippet.

[erictraut]

Yes, when using deferred evaluation of annotations, the name resolution rules change. It took quite a bit of work in pyright to match the runtime behaviors in all cases. With deferred evaluation becoming the default in Python 3.14 (PEP 749), users will hit these edge cases more often.

[TeamSpen210]

In these situations, I usually just import builtins, then reference them from there. It's probably better for clarity anyway.

[sterliakov]

Yes, there are workarounds, of course: import builtins, typing.List, just declaring a top-level alias, etc. But the question is about correct/incorrect treatment of some valid/invalid code.