Don't parameterise typing.Final

2026-02-10T00:00:00+00:00

Python has a typing.Final annotation that can be used to mark that a name cannot be reassigned. Type-checkers will complain if a final name is reassigned.

from typing import Final

CONST: Final = "This cannot be reassigned."
CONST = "This is a type error."  # Error: cannot assign to final name.

Like other type annotations in Python, typing.Final can be parameterised to annotate the underlying type as well.

from typing import Final

PORT: Final[int] = 8080  # int (mypy 1.19)

However, this isn’t necessary. The type-checker will infer the type of the name absent the parametrisation. Moreover, the type inferred by the type checker will likely be the most precise valid type for its context.

from typing import Final

PORT: Final = 8080  # Literal[8080] (mypy 1.19)

This differs from other type annotations users might be familiar with, which are less precise when unparameterised (such as bare generics).

It’s only worth parameterising typing.Final if the type that would be inferred by the type-checker in its absence is incorrect or otherwise undesirable.

from typing import Final

lst: Final = [1, 2, 3]

def fn(o: list[int | None]) -> None: ...

fn(lst)  # Got list[int], expected list[int | None] (mypy 1.19)

One solution to the problem above would be to use collections.abc.Sequence in the function signature instead which, unlike list, is covariant. However, if we did not want to do that, another solution would be to annotate lst as typing.Final[list[int | None]] to prevent the type-checker from inferring the more precise (yet undesired) type of list[int]. The type of lst would then satisfy the type required by the function signature.

By leaving typing.Final unparameterised, we avoid an extra burden and let the type-checker infer the best type.

Additional note

Indicating that a name is final means it should not be reassigned. It can, however, be mutated. Using immutable types (such as tuples) can thus alter the resulting type.

from typing import Final

lst: Final = [1, 2, 3]  # list[int]
tup: Final = (1, 2, 3)  # tuple[Literal[1], Literal[2], Literal[3]]

Sentinel values in Python

2025-10-29T00:00:00+00:00

In Python, we sometimes want to create sentinel values (for example, to act as a placeholder default value distinct from None). The simplest way to do this is to create a new object and perform an identity check.

Unset = object()

Let’s say that a can be an int or None or this Unset sentinel value; how would we type a? Using int | None | object would accept all values due to the union with object, which we don’t want.

We could try creating a new class just for this sentinel.

class UnsetT:
    pass

Unset = UnsetT()

However, int | None | Unset wouldn’t narrow to int | None if we performed an a is not Unset check. Just because a value is not a specific instance of a type doesn’t mean it cannot be some other instance of that type. We’d have to perform an isinstance check, which is more expensive and not nice to read.

For a type-correct sentinel value, we can use an enum.Enum value (which is special-cased by type-checkers). By doing this, type-checkers can rule out the enumeration type by checking against its one and only member. Using the new type keyword, we can avoid exposing this implementation detail (though we unfortunately need separate names for the sentinel instance and its type).

import enum

class _UnsetT(enum.Enum):
    UNSET = enum.auto()

Unset = _UnsetT.UNSET
type UnsetT = _UnsetT

def test(a: int | None | UnsetT = Unset) -> None:
    if a is Unset:
        return
    reveal_type(a)  # Revealed type is "builtins.int | None"

Until PEP 661 is accepted, this might be the best we can do!

Notes

Don't parameterise typing.Final

Additional note

Sentinel values in Python