Type hinting and Annotations

---

Type hinting in Python

Type hinting is a formal solution to a problem developers faced for years in Python: ambiguity.

In standard Python (which is dynamically typed), you don't declare what type a variable is. You just assign it. While flexible, this can lead to "runtime errors" where you accidentally try to divide a string or access a property of None.

Type hinting allows you to explicitly state what datatype a variable, argument, or return value should be.

What is Type Hinting?

Introduced in Python 3.5 (via PEP 484), type hints are syntax that lets you annotate your code with type information.

Without Type Hints:

def calculate_price(item, quantity):
    return item.price * quantity

Is item a dictionary? A class instance? Is quantity an integer or a float? You have to read the entire function (or guess) to know.

With Type Hints:

def calculate_price(item: Product, quantity: int) -> float:
    return item.price * quantity

Now we know exactly what inputs are expected and what output is returned.

The Purpose: Why use them?

Type hints serve three main purposes, none of which actually change how your code runs.

• Static Analysis (Bug Catching): This is the biggest benefit. Tools like mypy or pyright can scan your code before you run it. If you try to pass a string into a function that expects an integer, the tool will yell at you, preventing a bug from hitting production.

• IDE Support & Autocomplete: When an IDE (like VS Code or PyCharm) knows that item is an instance of Product, it can give you a dropdown menu of all the attributes available on Product (like .price, .name, etc.).

• Documentation: Type hints act as live documentation. You don't need to write docstrings saying "x is an int"; the code speaks for itself.

Syntax Examples

Here is how the syntax has evolved. Note that in modern Python (3.9+), you can use standard collection types (like list) directly.

A. Basic Variables

name: str = "Alice"
age: int = 30
is_active: bool = True

B. Functions

You define the types of arguments inside the parentheses and the return type after the ->.

def greet(name: str) -> str:
    return f"Hello, {name}"

C. Collections (Lists and Dictionaries)

You can specify what goes inside the data structure.

# Python 3.9+ syntax
scores: list[int] = [10, 20, 30]
user_map: dict[str, int] = {"Alice": 1, "Bob": 2}

# Older syntax (requires 'from typing import List, Dict')
scores: List[int] = [10, 20, 30]

D. Unions and Optionals

Sometimes a variable can be more than one thing.

from typing import Union, Optional

# Takes an int OR a float
def double(number: Union[int, float]) -> float:
    return number * 2

# Modern Python 3.10+ syntax for Union is simply '|'
def double(number: int | float) -> float:
    return number * 2

# Optional means "Type X or None"
def find_user(user_id: int) -> Optional[str]:
    # Returns a string name OR None if not found
    return database.get(user_id)

---

Important Limitations

It is critical to understand what type hints are not.

• They are NOT enforced at runtime: Python is still a dynamic language. If you write x: int = "hello", Python will execute that code happily without crashing. The hints are ignored by the Python interpreter; they are purely for external tools (IDEs and linters) and developers.

• Maintenance Overhead: If you change your code logic, you must update your type hints. Incorrect type hints are often worse than no type hints because they lie to the developer.

• Verbosity: Heavily typed Python can start to look like Java or C++. It adds visual noise, which some Python purists dislike.

Feature	Dynamic Python	Typed Python
Runtime Speed	Identical	Identical (Hints are ignored)
Development Speed	Faster initially	Slower initially, faster debugging later
Tooling	Standard	Enables mypy, Pydantic, better Autocomplete
Safety	Relies on unit tests	Relies on Static Analysis + tests

This is a great direction. You are moving from "basic syntax" into structural typing (TypedDict) and metadata (Annotated). These are essential when working with APIs, JSON data, or libraries like FastAPI.

Here is the breakdown of TypedDict and the concept of Annotations.

---

TypedDict: Structuring Dictionaries

In standard Python, dictionaries are free-for-all containers. You might type hint a dictionary as dict[str, Any], but that tells you nothing about which keys exist.

TypedDict (introduced in Python 3.8) allows you to define a dictionary with a fixed schema. It tells the type checker: "This dictionary must have exactly these keys, and they must have these specific value types."

A. Basic Syntax

You typically define a TypedDict as a class that inherits from it.

from typing import TypedDict

# Define the schema
class UserProfile(TypedDict):
    id: int
    username: str
    email: str

# Usage
# Valid ✅
user: UserProfile = {"id": 1, "username": "dave", "email": "[e-mail]"}

# Invalid ❌ (Type checker will flag missing 'email' or wrong types)
invalid_user: UserProfile = {"id": "one", "username": "dave"}

B. Handling Optional Keys

By default, all keys defined in a TypedDict are required. If you want some keys to be optional, you have two approaches depending on your Python version.

The Modern Way (Python 3.11+): NotRequired

This is the preferred, cleanest syntax.

from typing import TypedDict, NotRequired

class Movie(TypedDict):
    title: str
    year: int
    rating: NotRequired[float]  # This key can be missing

data: Movie = {"title": "Inception", "year": 2010} # Valid ✅

The Older Way: total=False

If you are on older Python versions, you have to use inheritance tricks. You define a base class for required keys and inherit for optional ones, or set total=False (which makes all keys optional).

# All keys in this dict are optional
class SearchParams(TypedDict, total=False):
    query: str
    page: int

Key Takeaway: TypedDict does not create a new "class" instance at runtime. The object user above is still just a plain Python dict. The class definition is purely for the type checker.

---

Annotations: The Concept & The Type

"Annotations" in Python can refer to two distinct things. It is important to distinguish between the mechanism and the specific type.

A. The Mechanism (__annotations__)

When you write x: int = 5, Python stores that type hint in a special dictionary called __annotations__.

This is important because Python doesn't use the types, but it exposes them so other libraries can use them.

def multiply(a: int, b: int) -> int:
    return a * b

# You can access these hints at runtime!
print(multiply.__annotations__)
# Output: {'a': <class 'int'>, 'b': <class 'int'>, 'return': <class 'int'>}

Libraries like Pydantic, FastAPI, and Typer read this dictionary at runtime to validate your data automatically.

B. The Annotated Type

There is a specific tool in the typing module called Annotated (introduced in Python 3.9). It allows you to attach extra metadata to a type hint.

The type checker only cares about the first argument (the actual type). It ignores the rest. However, third-party libraries use those extra arguments to do powerful things.

Syntax: Annotated[Type, Metadata, Metadata...]

Example 1: Documentation (Passive)

from typing import Annotated

# To a type checker, this is just a 'str'
# To a human reading the code, we know strictly what kind of string
UserId = Annotated[str, "Must be a 32-char UUID"]

Example 2: Validation (Active - e.g., using Pydantic)

This is where Annotated shines. You can combine the type with validation rules.

from typing import Annotated
from pydantic import Field

# We define a type that is an Int, AND must be positive
PositiveInt = Annotated[int, Field(gt=0)] 

def create_item(item_id: PositiveInt):
    pass

Putting it together

Here is a realistic snippet you might see in a modern API backend:

from typing import TypedDict, Annotated
from typing import NotRequired

# 1. Using Annotated to define a constrained type
# "An integer that represents a database ID"
DbId = Annotated[int, "The primary key from the Users table"]

# 2. Using TypedDict to define the shape of the data
class UserPayload(TypedDict):
    id: DbId
    username: str
    # 3. An optional email field
    email: NotRequired[str] 

def process_user(data: UserPayload):
    # The IDE knows 'data' has an 'id' and 'username'
    # The developer knows 'id' implies a database key
    print(data['username'])

Type hinting a decorator

---

---