Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/source/literal_types.rst
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,24 @@ value whenever it's used before performing type checking. This is why the reveal
type of ``c`` is ``Literal[19]?``: the question mark at the end reflects this
context-sensitive nature.

A module-level ``Final`` remembers the value of its initializer even when an explicit
type is given, since it cannot be rebound and code in another module has no code flow
information to narrow it back to the assigned value otherwise:

.. code-block:: python

from typing import Final, Literal

def expects_literal(x: Literal[19]) -> None: pass

d: Final[int] = 19

reveal_type(d) # Revealed type is "Literal[19]?"
expects_literal(d) # ...and this type checks!

Class attributes, instance attributes and names local to a function keep the declared
type instead.

For example, mypy will type check the above program almost as if it were written like so:

.. code-block:: python
Expand Down
56 changes: 56 additions & 0 deletions mypy/checker.py
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,7 @@ def __init__(self) -> None:
from mypy.patterns import AsPattern, StarredPattern
from mypy.plugin import Plugin
from mypy.plugins import dataclasses as dataclasses_plugin
from mypy.reachability import ALWAYS_FALSE, ALWAYS_TRUE, infer_condition_value
from mypy.scope import Scope
from mypy.semanal import is_trivial_body, refers_to_fullname, set_callable_name
from mypy.semanal_enum import ENUM_BASES, ENUM_SPECIAL_PROPS
Expand Down Expand Up @@ -274,6 +275,7 @@ def __init__(self) -> None:
FunctionLike,
Instance,
LiteralType,
LiteralValue,
NoneType,
Overloaded,
PartialType,
Expand Down Expand Up @@ -3483,6 +3485,58 @@ def check_type_alias_rvalue(self, s: AssignmentStmt) -> None:
alias_type = self.expr_checker.accept(s.rvalue)
self.store_type(s.lvalues[-1], alias_type)

def expose_module_final_literal_type(
self, lvalue: Lvalue, rvalue: Expression, rvalue_type: Type
) -> None:
"""Remember the initializer value of a module-level Final in its type.

A module-level Final cannot be rebound, so the value of its initializer is the
value of every read of the variable. Code flow narrowing gives the same result
within the defining module, but a read from another module has no narrowing, so
a statically known value (for example a platform check stored in a Final[bool])
would otherwise be lost.
"""
if not isinstance(lvalue, NameExpr) or lvalue.kind != GDEF:
return
if self.scope.top_level_function() is not None:
return
if not isinstance(lvalue.node, Var):
return
var = lvalue.node
# A class body or instance Final can still be assigned in a constructor.
if not var.is_final or var.info:
return
declared = get_proper_type(var.type)
if not isinstance(declared, Instance) or declared.last_known_value is not None:
return
literal_value = self.module_final_initializer_literal_value(declared, rvalue, rvalue_type)
if literal_value is not None:
var.type = declared.copy_modified(
last_known_value=LiteralType(value=literal_value, fallback=declared)
)

def module_final_initializer_literal_value(
self, declared: Instance, rvalue: Expression, rvalue_type: Type
) -> LiteralValue | None:
proper_type = get_proper_type(rvalue_type)
if (
isinstance(proper_type, Instance)
and proper_type.last_known_value is not None
and proper_type.type is declared.type
):
return proper_type.last_known_value.value
if declared.type.fullname != "builtins.bool":
return None
# A platform or version check has an exact value for the current options, but
# only values that also hold at runtime qualify: "TYPE_CHECKING" and friends
# are true for mypy alone.
truth_value = infer_condition_value(rvalue, self.options)
if truth_value == ALWAYS_TRUE:
return True
if truth_value == ALWAYS_FALSE:
return False
return None

def check_assignment(
self, lvalue: Lvalue, rvalue: Expression, infer_lvalue_type: bool = True
) -> None:
Expand Down Expand Up @@ -3604,6 +3658,7 @@ def check_assignment(
# The above call may update inferred variable type. Prevent further
# inference.
inferred = None
self.expose_module_final_literal_type(lvalue, rvalue, rvalue_type)

# Special case: only non-abstract non-protocol classes can be assigned to
# variables with explicit type `Type[A]`, where A is protocol or abstract.
Expand Down Expand Up @@ -3662,6 +3717,7 @@ def check_assignment(
):
rvalue_type = remove_instance_last_known_values(rvalue_type)
self.infer_variable_type(inferred, lvalue, rvalue_type, rvalue)
self.expose_module_final_literal_type(lvalue, rvalue, rvalue_type)
self.check_assignment_to_slots(lvalue)
if (
isinstance(lvalue, RefExpr)
Expand Down
166 changes: 166 additions & 0 deletions test-data/unit/check-final.test
Original file line number Diff line number Diff line change
Expand Up @@ -1322,3 +1322,169 @@ class S9(S2, S4): # E: Class "S9" has incompatible disjoint bases
pass

[builtins fixtures/tuple.pyi]

[case testFinalModuleLevelAnnotatedLiteralInitializer]
from typing import Final, Literal

NUM: Final[int] = 1
NAME: Final[str] = "hi"
FLAG: Final[bool] = True
NOT_ANNOTATED: Final = 2

def expect_num(x: Literal[1]) -> None: ...
def expect_name(x: Literal["hi"]) -> None: ...
def expect_flag(x: Literal[True]) -> None: ...
def expect_two(x: Literal[2]) -> None: ...

reveal_type(NUM) # N: Revealed type is "Literal[1]?"
reveal_type(NAME) # N: Revealed type is "Literal['hi']?"
reveal_type(FLAG) # N: Revealed type is "Literal[True]?"
reveal_type(NOT_ANNOTATED) # N: Revealed type is "Literal[2]?"

expect_num(NUM)
expect_name(NAME)
expect_flag(FLAG)
expect_two(NOT_ANNOTATED)
[out]

[case testFinalModuleLevelAnnotatedLiteralInitializerReadFromOtherModule]
import flags
from flags import FLAG, NAME, NUM, NOT_ANNOTATED
from typing import Literal

def expect_num(x: Literal[1]) -> None: ...
def expect_name(x: Literal["hi"]) -> None: ...
def expect_flag(x: Literal[True]) -> None: ...
def expect_two(x: Literal[2]) -> None: ...

expect_num(NUM)
expect_name(NAME)
expect_flag(FLAG)
expect_two(NOT_ANNOTATED)
expect_num(flags.NUM)
expect_name(flags.NAME)
expect_flag(flags.FLAG)
expect_two(flags.NOT_ANNOTATED)

reveal_type(NUM) # N: Revealed type is "Literal[1]?"
reveal_type(flags.NUM) # N: Revealed type is "Literal[1]?"
reveal_type(flags.NAME) # N: Revealed type is "Literal['hi']?"
reveal_type(flags.FLAG) # N: Revealed type is "Literal[True]?"
reveal_type(flags.NOT_ANNOTATED) # N: Revealed type is "Literal[2]?"

[file flags.py]
from typing import Final

NUM: Final[int] = 1
NAME: Final[str] = "hi"
FLAG: Final[bool] = True
NOT_ANNOTATED: Final = 2
[out]

[case testFinalModuleLevelEnumLiteralInitializer]
from enum import Enum
from typing import Final, Literal

class Color(Enum):
RED = 1
GREEN = 2

COLOR: Final[Color] = Color.RED

def expect_red(x: Literal[Color.RED]) -> None: ...

reveal_type(COLOR) # N: Revealed type is "Literal[__main__.Color.RED]?"
expect_red(COLOR)
[builtins fixtures/enum.pyi]
[out]

[case testFinalModuleLevelEnumLiteralInitializerReadFromOtherModule]
import flags
from typing import Literal

def expect_red(x: Literal[flags.Color.RED]) -> None: ...

reveal_type(flags.COLOR) # N: Revealed type is "Literal[flags.Color.RED]?"
expect_red(flags.COLOR)

[file flags.py]
from enum import Enum
from typing import Final

class Color(Enum):
RED = 1
GREEN = 2

COLOR: Final[Color] = Color.RED
[builtins fixtures/enum.pyi]
[out]

[case testFinalModuleLevelStaticallyKnownBoolInitializer]
# flags: --platform linux --python-version 3.11
import sys
from typing import Final, Literal

IS_WIN: Final[bool] = sys.platform == "win32"
IS_WIN_INFERRED: Final = sys.platform == "win32"
IS_LINUX: Final[bool] = sys.platform.startswith("lin")
PY312: Final[bool] = sys.version_info >= (3, 12)
MAYBE_WIN: bool = sys.platform == "win32"

def expect_false(x: Literal[False]) -> None: ...
def expect_true(x: Literal[True]) -> None: ...

reveal_type(IS_WIN) # N: Revealed type is "Literal[False]?"
reveal_type(IS_WIN_INFERRED) # N: Revealed type is "Literal[False]?"
reveal_type(IS_LINUX) # N: Revealed type is "Literal[True]?"
reveal_type(PY312) # N: Revealed type is "Literal[False]?"

# A plain annotation can be assigned a different value later, so it keeps "bool".
reveal_type(MAYBE_WIN) # N: Revealed type is "builtins.bool"

expect_false(IS_WIN)
expect_false(IS_WIN_INFERRED)
expect_true(IS_LINUX)
expect_false(PY312)
[builtins fixtures/ops.pyi]
[out]

[case testFinalModuleLevelNonLiteralInitializer]
from typing import Final

class Base: ...
class Sentinel(Base): ...

NO_INFO: Final[Base] = Sentinel()
ITEMS: Final[list[int]] = []
DICT: Final[dict[str, int]] = {}
AS_OBJECT: Final[object] = 1
TUPLE: Final[tuple[int, ...]] = (1, 2)

reveal_type(NO_INFO) # N: Revealed type is "__main__.Base"
reveal_type(ITEMS) # N: Revealed type is "builtins.list[builtins.int]"
reveal_type(DICT) # N: Revealed type is "builtins.dict[builtins.str, builtins.int]"
reveal_type(AS_OBJECT) # N: Revealed type is "builtins.object"
reveal_type(TUPLE) # N: Revealed type is "builtins.tuple[builtins.int, ...]"
[builtins fixtures/dict.pyi]
[out]

[case testFinalLiteralInitializerNotExposedOutsideModuleScope]
from typing import Final, Literal

class C:
class_num: Final[int] = 1

def __init__(self) -> None:
self.inst_num: Final[int] = 1

def f() -> None:
local_num: Final[int] = 1

def expect_num(x: Literal[1]) -> None: ...
expect_num(local_num) # E: Argument 1 to "expect_num" has incompatible type "int"; expected "Literal[1]"
reveal_type(local_num) # N: Revealed type is "builtins.int"

reveal_type(C.class_num) # N: Revealed type is "builtins.int"
c: C
reveal_type(c.inst_num) # N: Revealed type is "builtins.int"
[out]
5 changes: 3 additions & 2 deletions test-data/unit/check-formatting.test
Original file line number Diff line number Diff line change
Expand Up @@ -516,11 +516,12 @@ from typing import Final

GOOD: Final = 'c'
BAD: Final = 'no'
OK: Final[str] = '...'
# The value of a module level Final is known, so the placeholder is checked as well.
NOT_CHAR: Final[str] = '...'

'{:c}'.format(GOOD)
'{:c}'.format(BAD) # E: ":c" requires int or char
'{:c}'.format(OK)
'{:c}'.format(NOT_CHAR) # E: ":c" requires int or char
[builtins fixtures/primitives.pyi]

[case testFormatCallForcedConversions]
Expand Down
17 changes: 3 additions & 14 deletions test-data/unit/check-literal.test
Original file line number Diff line number Diff line change
Expand Up @@ -2110,13 +2110,11 @@ force4(reveal_type(f.instancevar4)) # N: Revealed type is "None"
[builtins fixtures/primitives.pyi]
[out]

[case testLiteralFinalDirectInstanceTypesSupersedeInferredLiteral]
[case testLiteralFinalClassAndInstanceVarDirectInstanceTypesSupersedeInferredLiteral]
from typing import Final, Literal

var1: Final[int] = 1
var2: Final[str] = "foo"
var3: Final[bool] = True
var4: Final[None] = None
# A module level Final is not covered here: code in another module cannot narrow it,
# so the literal value of its initializer is exposed. See check-final.test instead.

class Foo:
classvar1: Final[int] = 1
Expand All @@ -2135,15 +2133,6 @@ def force2(x: Literal["foo"]) -> None: pass
def force3(x: Literal[True]) -> None: pass
def force4(x: Literal[None]) -> None: pass

reveal_type(var1) # N: Revealed type is "builtins.int"
reveal_type(var2) # N: Revealed type is "builtins.str"
reveal_type(var3) # N: Revealed type is "builtins.bool"
reveal_type(var4) # N: Revealed type is "None"
force1(var1) # E: Argument 1 to "force1" has incompatible type "int"; expected "Literal[1]"
force2(var2) # E: Argument 1 to "force2" has incompatible type "str"; expected "Literal['foo']"
force3(var3) # E: Argument 1 to "force3" has incompatible type "bool"; expected "Literal[True]"
force4(var4)

reveal_type(Foo.classvar1) # N: Revealed type is "builtins.int"
reveal_type(Foo.classvar2) # N: Revealed type is "builtins.str"
reveal_type(Foo.classvar3) # N: Revealed type is "builtins.bool"
Expand Down
3 changes: 1 addition & 2 deletions test-data/unit/diff.test
Original file line number Diff line number Diff line change
Expand Up @@ -1036,11 +1036,10 @@ __main__.C.y
__main__.C.yi
__main__.C.z
__main__.C.zi
__main__.same2
__main__.v
__main__.w
__main__.x
__main__.y
__main__.z

[case testFinalFlagsTriggerMethod]
from typing import final
Expand Down
2 changes: 1 addition & 1 deletion test-data/unit/fine-grained.test
Original file line number Diff line number Diff line change
Expand Up @@ -8906,7 +8906,7 @@ qux: Final[int] = 4
==
main:4: error: Argument 1 to "expect_3" has incompatible type "Literal[4]"; expected "Literal[3]"
==
main:4: error: Argument 1 to "expect_3" has incompatible type "int"; expected "Literal[3]"
main:4: error: Argument 1 to "expect_3" has incompatible type "Literal[4]"; expected "Literal[3]"

[case testLiteralFineGrainedStringConversionPython3]
from mod1 import foo
Expand Down
Loading