Python Type-Annotated Variable

A type-annotated variable in Python is a variable explicitly bound to a type hint using a colon (:) syntax, as defined in PEP 526. These annotations specify the expected data type of the variable for static type checkers, IDEs, and linters, without altering Python’s inherent dynamic runtime typing behavior.

Syntax

The syntax consists of the variable identifier, a colon, the type expression, and an optional assignment. Initialized Variable:

variable_name: expected_type = initial_value

Uninitialized Variable: Variables can be annotated without immediate assignment. This declares the type for static analysis but does not bind the variable to a value in the local namespace.

variable_name: expected_type

Runtime Mechanics

Python does not enforce type annotations at runtime. The interpreter evaluates the type expression but does not prevent type-mismatched assignments.

# Static checkers flag this, but Python executes it without raising an error.
count: int = "five" 

The __annotations__ Dictionary: When variables are annotated at the module level or class level, Python evaluates the type expression at runtime and stores the mapping in the __annotations__ dunder attribute.

class ServerConfig:
    host: str = "127.0.0.1"
    port: int

print(ServerConfig.__annotations__)

# Output: {'host': <class 'str'>, 'port': <class 'int'>}

Note: To optimize memory and performance, Python does not store annotations for local variables defined inside functions or methods. They are strictly consumed by static analysis tools.

Type Expressions

Type annotations can range from built-in primitives to complex generic types. Primitives:

is_active: bool = True
threshold: float = 3.14

Standard Collections (PEP 585): Modern Python allows standard collections to be parameterized directly using square brackets.

user_ids: list[int] = [1, 2, 3]
environment_vars: dict[str, str] = {"ENV": "production"}
coordinates: tuple[float, float] = (45.0, -90.0)

Union Types (PEP 604): The bitwise OR operator (|) is used to indicate that a variable can accept one of multiple types.

# Can be an integer or a string
identifier: int | str = "ID-492"


# Equivalent to typing.Optional[int]
timeout: int | None = None 

Advanced Typing Constructs: For more complex structural typing, the typing module provides specialized constructs.

from typing import Any, Callable, Literal

# Accepts absolutely any type (disables strict type checking for this variable)
payload: Any = {"data": 123}

# A variable holding a function that takes an int and returns a str
formatter: Callable[[int], str] = lambda x: f"Value: {x}"

# Restricts the variable to specific literal values
status: Literal["pending", "running", "failed"] = "running"

Type Aliases (PEP 613 / PEP 695)

Type expressions can be assigned to variables to create reusable type aliases. In Python 3.12+, the type keyword is used to explicitly declare an alias. For Python 3.10 and 3.11, typing.TypeAlias is used to explicitly distinguish aliases from standard variable assignments.

# Python 3.12+ syntax
type Vector = list[float]
velocity: Vector = [9.8, 0.0, -1.2]


# Legacy syntax (Python 3.10+)
from typing import TypeAlias
Matrix: TypeAlias = list[list[int]]
grid: Matrix = [[1, 0], [0, 1]]