Type Hinting

Advanced ~25 min read

Type hinting lets you add type annotations to your Python code, making it clearer what types of values functions expect and return. While Python remains dynamically typed at runtime, type hints improve code documentation, enable better IDE autocomplete and error detection, and can be checked statically with tools like mypy. Introduced in PEP 484 (Python 3.5) and enhanced in later versions!

Basic Type Annotations

You can add type hints to function parameters and return values using the syntax parameter: type and -> return_type. For simple types, use built-in types like int, str, list, dict.

# Basic Type Annotations

# Function type hints
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

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

def divide(a: float, b: float) -> float:
    """Divide two floats."""
    return a / b

# Using the functions
print("Type hints in action:")
result = add(5, 3)
print(f"add(5, 3) = {result}")

message = greet("Alice")
print(f"greet('Alice') = {message}")

quotient = divide(10.0, 2.0)
print(f"divide(10.0, 2.0) = {quotient}")

# Type hints don't enforce types at runtime
# This still works (Python is dynamically typed)
result = add("hello", "world")  # No error at runtime!
print(f"\nType hints are not enforced: {result}")

# Variable annotations
name: str = "Alice"
age: int = 30
height: float = 5.6

print("\nVariable annotations:")
print(f"name: {name} (type: {type(name).__name__})")
print(f"age: {age} (type: {type(age).__name__})")
print(f"height: {height} (type: {type(height).__name__})")

# Multiple return types (without Union - Python 3.10+)
def get_value(mode: str) -> int | str:
    """Return different types based on mode."""
    if mode == "number":
        return 42
    else:
        return "default"

print("\nUnion types (Python 3.10+ syntax):")
print(get_value("number"))  # int
print(get_value("text"))    # str

Output

Click Run to execute your code

Why Use Type Hints:
- Documentation: Makes code self-documenting about expected types
- IDE Support: Better autocomplete, refactoring, and error detection
- Type Checking: Tools like mypy can catch type errors before runtime
- Refactoring: Easier to safely modify code when types are known
Note: Type hints don't affect runtime behavior - Python remains dynamically typed!

The typing Module

For more complex types, use the typing module. It provides generic types like List, Dict, Optional, Union, and more. Python 3.9+ allows using built-in types like list and dict directly in type hints!

# The typing Module

from typing import List, Dict, Tuple, Optional, Union

# List type hints
def process_numbers(numbers: List[int]) -> List[int]:
    """Process a list of integers."""
    return [x * 2 for x in numbers]

# Dict type hints
def get_contact(name: str) -> Dict[str, str]:
    """Get contact information."""
    return {"name": name, "email": f"{name}@example.com"}

# Tuple type hints
def get_coordinates() -> Tuple[float, float]:
    """Get x, y coordinates."""
    return (10.5, 20.3)

print("Typing module examples:")
numbers = [1, 2, 3, 4, 5]
doubled = process_numbers(numbers)
print(f"Doubled: {doubled}")

contact = get_contact("Alice")
print(f"Contact: {contact}")

coords = get_coordinates()
print(f"Coordinates: {coords}")

# Python 3.9+ can use built-in types directly
def modern_process_numbers(numbers: list[int]) -> list[int]:
    """Modern syntax (Python 3.9+)."""
    return [x * 2 for x in numbers]

def modern_get_contact(name: str) -> dict[str, str]:
    """Modern syntax (Python 3.9+)."""
    return {"name": name, "email": f"{name}@example.com"}

# Complex types
def process_data(data: List[Dict[str, Union[int, str]]]) -> Dict[str, int]:
    """Process complex nested data structures."""
    result = {}
    for item in data:
        key = item.get("key", "")
        value = item.get("value", 0)
        if isinstance(value, int):
            result[key] = value
    return result

print("\nComplex types:")
data = [{"key": "a", "value": 1}, {"key": "b", "value": 2}]
processed = process_data(data)
print(f"Processed: {processed}")

# Function type hints
from typing import Callable

def apply_function(func: Callable[[int, int], int], a: int, b: int) -> int:
    """Apply a function to two integers."""
    return func(a, b)

print("\nFunction type hints:")
result = apply_function(lambda x, y: x + y, 5, 3)
print(f"apply_function(lambda x, y: x + y, 5, 3) = {result}")

Output

Click Run to execute your code

Pro Tip: In Python 3.9+, you can use built-in types like list[str] instead of List[str] from typing. Use from __future__ import annotations at the top of files for Python 3.7+ to enable this syntax!

Optional and Union Types

Use Optional[Type] for values that can be None (same as Union[Type, None]). Use Union[Type1, Type2] when a value can be one of multiple types. Python 3.10+ supports the cleaner Type1 | Type2 syntax!

# Optional and Union Types

from typing import Optional, Union, List, Dict

# Optional[Type] is the same as Union[Type, None]
def find_user(name: str) -> Optional[dict]:
    """Find user, return None if not found."""
    users = {"Alice": {"age": 30}, "Bob": {"age": 25}}
    return users.get(name)

def get_age(name: str) -> Union[int, None]:  # Same as Optional[int]
    """Get user age, return None if not found."""
    users = {"Alice": 30, "Bob": 25}
    return users.get(name)

print("Optional types:")
user = find_user("Alice")
if user:
    print(f"Found user: {user}")
else:
    print("User not found")

user = find_user("Charlie")
if user is None:
    print("User not found")

# Union for multiple types
def process_value(value: Union[int, str, float]) -> str:
    """Process value of different types."""
    return str(value)

print("\nUnion types:")
print(process_value(42))      # int
print(process_value("hello")) # str
print(process_value(3.14))    # float

# Python 3.10+ syntax: Type1 | Type2
def modern_find_user(name: str) -> dict | None:
    """Modern syntax (Python 3.10+)."""
    users = {"Alice": {"age": 30}, "Bob": {"age": 25}}
    return users.get(name)

def modern_process_value(value: int | str | float) -> str:
    """Modern syntax (Python 3.10+)."""
    return str(value)

# Optional with default None
def create_config(name: Optional[str] = None) -> dict:
    """Create config with optional name."""
    return {"name": name or "default"}

print("\nOptional with defaults:")
print(create_config("custom"))
print(create_config())  # None

# Complex optional types
def parse_data(data: Optional[List[Dict[str, Union[int, str]]]]) -> Optional[Dict[str, int]]:
    """Parse optional complex data."""
    if data is None:
        return None
    result = {}
    for item in data:
        key = item.get("key", "")
        value = item.get("value", 0)
        if isinstance(value, int):
            result[key] = value
    return result

print("\nComplex optional types:")
data = [{"key": "a", "value": 1}, {"key": "b", "value": 2}]
result = parse_data(data)
print(f"Parsed: {result}")

result = parse_data(None)
print(f"Parsed None: {result}")

Output

Click Run to execute your code

Variable Type Annotations

You can also annotate variables directly, not just function parameters. This is useful for class attributes, module-level variables, and complex types that might not be obvious.

# Variable Type Annotations

from typing import List, Dict, Optional

# Simple variable annotations
name: str = "Alice"
age: int = 30
is_active: bool = True

print("Simple variable annotations:")
print(f"name: {name}, type: {type(name).__name__}")
print(f"age: {age}, type: {type(age).__name__}")
print(f"is_active: {is_active}, type: {type(is_active).__name__}")

# Collection annotations
numbers: List[int] = [1, 2, 3, 4, 5]
contacts: Dict[str, str] = {"Alice": "alice@example.com", "Bob": "bob@example.com"}

print("\nCollection annotations:")
print(f"numbers: {numbers}")
print(f"contacts: {contacts}")

# Optional variables
maybe_name: Optional[str] = None
maybe_age: Optional[int] = 25

print("\nOptional variables:")
print(f"maybe_name: {maybe_name}")
print(f"maybe_age: {maybe_age}")

# Later assignment
maybe_name = "Bob"
print(f"maybe_name after assignment: {maybe_name}")

# Complex nested types
user_data: List[Dict[str, Union[int, str]]] = [
    {"name": "Alice", "age": 30},
    {"name": "Bob", "age": 25}
]

print("\nComplex nested types:")
for user in user_data:
    print(f"User: {user}")

# Class attribute annotations
class User:
    name: str
    age: int
    email: Optional[str] = None
    
    def __init__(self, name: str, age: int, email: Optional[str] = None):
        self.name = name
        self.age = age
        self.email = email

print("\nClass with type annotations:")
user = User("Alice", 30, "alice@example.com")
print(f"User: {user.name}, Age: {user.age}, Email: {user.email}")

# Module-level constants
MAX_USERS: int = 100
DEFAULT_TIMEOUT: float = 30.0
SUPPORTED_LANGUAGES: List[str] = ["Python", "Java", "Go"]

print("\nModule-level constants:")
print(f"MAX_USERS: {MAX_USERS}")
print(f"DEFAULT_TIMEOUT: {DEFAULT_TIMEOUT}")
print(f"SUPPORTED_LANGUAGES: {SUPPORTED_LANGUAGES}")

# Type hints without initial value (requires type checker)
# This is valid Python, but mypy will check the type
def process_user():
    user_id: int
    user_id = 123  # Must assign before use
    return user_id

print(f"\nVariable assigned later: {process_user()}")

Output

Click Run to execute your code

Important: Type hints are not enforced at runtime! Python will still allow you to pass any type. Type hints are primarily for documentation and static type checking. Use type checkers like mypy to catch type errors before runtime!

Common Mistakes

1. Thinking type hints enforce types at runtime

# Wrong - type hints don't prevent runtime errors
def add(a: int, b: int) -> int:
    return a + b

# This still works - Python doesn't check types at runtime!
result = add("hello", "world")  # No error, returns "helloworld"
result = add([1, 2], [3, 4])    # No error, returns [1, 2, 3, 4]

# Type hints are for documentation and static type checkers only
# Use mypy or other tools to catch these before runtime!

2. Using old typing.List syntax when not needed

# Old way (Python 3.8 and earlier)
from typing import List, Dict

def process(items: List[str]) -> Dict[str, int]:
    return {}

# Modern way (Python 3.9+)
def process(items: list[str]) -> dict[str, int]:
    return {}

# Or for Python 3.7+ with future import
from __future__ import annotations

def process(items: list[str]) -> dict[str, int]:
    return {}

3. Forgetting Optional for None-able values

# Wrong - suggests value can't be None
from typing import Optional

def find_user(name: str) -> dict:  # Type checker might complain
    if name not in database:
        return None  # Type error: returning None but hint says dict
    
    return {"name": name}

# Correct - use Optional
def find_user(name: str) -> Optional[dict]:
    if name not in database:
        return None  # OK - Optional allows None
    return {"name": name}

Exercise: Add Type Hints to a Function

Task: Write a function with comprehensive type hints that processes user data. The function should accept a list of user dictionaries and return statistics.

Requirements:

Create a function get_user_stats(users) that processes user data
Parameter: list of dictionaries, each with name (str) and age (int)
Return: dictionary with keys total (int), avg_age (float), and names (list of str)
Use type hints for all parameters and return value
Import necessary types from typing module
Handle empty list case

# Exercise: Add Type Hints to a Function
# Write a function with comprehensive type hints that processes user data.
# The function should accept a list of user dictionaries and return statistics.

from typing import List, Dict, Any

# TODO: Implement get_user_stats with proper type hints
def get_user_stats(users: List[Dict[str, Any]]) -> Dict[str, Any]:
    """
    Calculate statistics from a list of user dictionaries.
    
    Args:
        users: List of user dicts with 'name' (str) and 'age' (int)
    
    Returns:
        Dict with 'total' (int), 'avg_age' (float), 'names' (List[str])
    """
    # TODO: Handle empty list case
    # TODO: Calculate total number of users
    # TODO: Calculate average age
    # TODO: Extract all names
    # TODO: Return dictionary with statistics
    pass

# Test the function
users = [
    {"name": "Alice", "age": 25},
    {"name": "Bob", "age": 30},
    {"name": "Charlie", "age": 35}
]

stats = get_user_stats(users)
print(f"Total users: {stats['total']}")
print(f"Average age: {stats['avg_age']:.1f}")
print(f"Names: {', '.join(stats['names'])}")

Output

Click Run to execute your code

Show Solution

from typing import List, Dict, Any

def get_user_stats(users: List[Dict[str, Any]]) -> Dict[str, Any]:
    """
    Calculate statistics from a list of user dictionaries.
    
    Args:
        users: List of user dicts with 'name' (str) and 'age' (int)
    
    Returns:
        Dict with 'total' (int), 'avg_age' (float), 'names' (List[str])
    """
    if not users:
        return {"total": 0, "avg_age": 0.0, "names": []}
    
    total = len(users)
    ages = [user["age"] for user in users]
    avg_age = sum(ages) / len(ages)
    names = [user["name"] for user in users]
    
    return {
        "total": total,
        "avg_age": avg_age,
        "names": names
    }


# Test the function
users = [
    {"name": "Alice", "age": 25},
    {"name": "Bob", "age": 30},
    {"name": "Charlie", "age": 35}
]

stats = get_user_stats(users)
print(f"Total users: {stats['total']}")
print(f"Average age: {stats['avg_age']:.1f}")
print(f"Names: {', '.join(stats['names'])}")

Summary

Type Hints: Annotations that document expected types without affecting runtime behavior
Function Annotations: Use parameter: type and -> return_type syntax
Built-in Types: Use int, str, list, dict for simple types (Python 3.9+)
typing Module: Provides List, Dict, Optional, Union for complex types
Optional: Optional[Type] means Type | None, for values that can be None
Union: Union[Type1, Type2] or Type1 | Type2 (Python 3.10+) for multiple possible types
Variable Annotations: Can annotate variables directly: name: str = "value"
Static Checking: Use tools like mypy to validate type hints before runtime
Benefits: Better documentation, IDE support, easier refactoring, catch errors early

What's Next?

Type hinting helps make your code more maintainable and self-documenting! You've now completed all the Advanced Topics modules. Continue exploring Python by diving deeper into specific libraries, frameworks, or advanced patterns. Consider learning about virtual environments, package management, async programming, or contributing to open source projects to further your Python journey!

Previous Regular Expressions

Next Virtual Envs

Basic Type Annotations

The typing Module

Optional and Union Types

Variable Type Annotations

Common Mistakes

1. Thinking type hints enforce types at runtime

2. Using old typing.List syntax when not needed

3. Forgetting Optional for None-able values

Exercise: Add Type Hints to a Function

Summary

What's Next?

Enjoying these tutorials?