Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

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]]
Master Python with Deep Grasping Methodology!Learn More