from __future__ import annotations unexpectedly adds Module(".xxx") to the type?

[Andrej730]

Met this one, yet couldn't find any related issues. Why this occurs and is there a workaround that would keep it just bar and let me still use from __future__ import annotations?

[erictraut]

This is behavior is intended, but the reason is somewhat subtle. I'll try to explain.

This is an __index__.py file, so the statement from .bar import bar assigns two values to the local symbol bar. The module loader first writes a value to bar that is a reference to the submodule. This value is then overwritten with the value imported from that submodule (a reference to a class). Pyright statically models both of these assignments. When multiple values are assigned to the same symbol, that symbol has no type declaration, and it is accessed from an inner scope, its type is inferred based on all values assigned to it in the outer scope. Here's a simplified example that demonstrates this.

x = 1
x = ""

def func():
    reveal_type(x)  # int | str

Something similar is happening here with bar in your code sample. There are two values written to bar (a Module and a class), so its inferred type, from the perspective of an inner scope, is the union of the two types.

Contrast that with the case where the symbol is accessed within the same execution scope. Here, a static type checker can use code flow analysis to determine the exact narrowed type of the symbol at the point where its type is requested.

x = 1
x = ""

reveal_type(x)  # Literal['']

When you use from __future__ import annotations, you're effectively wrapping all of your type annotations in an inner scope — a lambda that allows for deferred evaluation of the annotation expression. In this case, pyright cannot use code flow analysis to determine the type of the symbol because the symbol may not be declared at that point in the program. It could be a forward reference. Instead, it uses the inferred type from the outer scope.

The way that most package authors work around this issue is to use an aliased import statement.

from __future__ import annotations

from .bar import bar as _bar

def foo() -> _bar: ...

Or

from __future__ import annotations

from . import bar as _bar

def foo() -> _bar.bar: ...

[Andrej730]

Interesting! Unfortunately renaming wouldn't work for me since I also export this class - test_package has py.typed and __all__ = ["bar"]. Though there is some alternative:

# `_bar` will be used for typing and `bar` for export.
from .bar import bar as _bar 
from .bar import bar 

This is an __index__.py file, so the statement from .bar import bar assigns two values to the local symbol bar. The module loader first writes a value to bar that is a reference to the submodule. This value is then overwritten with the value imported from that submodule (a reference to a class). Pyright statically models both of these assignments.

Are there any cases when this would be important? It seems from xxx import yyy will never produce yyy that would be referring to xxx module instead of xxx.yyy symbol and intermediate assignment of reference to the submodule to xxx seems more of an implementation detail.

[Andrej730]

Coming back to this, using from .bar import bar as _bar is making test_package.bar a module, so we have to make bar a class again:

1. bar = _bar - seems to work, but go to definition of test_package.bar now annoyingly leads to the bar = assignment.
2. from .bar import bar as _bar + from .bar import bar - seems to be the best option indeed.