Type Hints

🏷️ Python Type Hints: Teaching Your Code to Speak Clearly

The Story of the Confused Mailroom

Imagine you work in a giant mailroom. Every day, packages arrive with no labels. You don’t know if a box contains books, fragile glass, or heavy machinery. You handle everything the same way—and sometimes things break! 💔

Now imagine every package has a clear label: “Books - Handle Normally” or “Glass - Fragile!” Suddenly, your job becomes easier. You know exactly what’s inside before you open anything.

Type Hints in Python work exactly like these labels. They tell everyone (including you!) what kind of data goes into your functions and what comes out.

🎯 What Are Type Hints?

Type hints are labels for your code. They don’t change how Python runs—Python still works the same. But they help:

• You remember what your function expects
• Your teammates understand your code faster
• Your code editor catch mistakes before you run the program

Think of it like this:

Without labels: “Hey, give me… something.” With labels: “Hey, give me a number, and I’ll give you back a word.”

📦 Basic Type Annotations

This is where we add our first labels!

The Simple Recipe

def greet(name: str) -> str:
    return "Hello, " + name

Let’s break this down:

• name: str → The package coming IN is a string (text)
• -> str → The package going OUT is also a string

More Examples

# A function that adds two numbers
def add(a: int, b: int) -> int:
    return a + b

# A function that checks if someone is adult
def is_adult(age: int) -> bool:
    return age >= 18

# A function that calculates price
def get_price(item: str) -> float:
    prices = {"apple": 1.50, "banana": 0.75}
    return prices.get(item, 0.0)

Variables Can Have Labels Too!

# Labeling variables directly
player_name: str = "Alex"
player_score: int = 100
is_winner: bool = True
temperature: float = 98.6

graph TD
    A["Your Function"] --> B["Input Label: str"]
    A --> C["Input Label: int"]
    A --> D["Output Label: bool"]
    style A fill:#4ECDC4,color:#fff
    style B fill:#FF6B6B,color:#fff
    style C fill:#FF6B6B,color:#fff
    style D fill:#95E1D3,color:#333

🧰 Common Type Hints

Here are the labels you’ll use most often. Think of these as your starter pack!

Basic Types (The Everyday Labels)

Container Types (Boxes of Things)

When you have a box full of items, you label both the box AND what’s inside!

# A list of names (box of strings)
names: list[str] = ["Alice", "Bob", "Charlie"]

# A dictionary (labeled drawers)
ages: dict[str, int] = {"Alice": 25, "Bob": 30}

# A tuple (sealed package - can't change)
point: tuple[int, int] = (10, 20)

# A set (bag of unique items)
unique_ids: set[int] = {1, 2, 3, 4, 5}

Visual Guide

graph TD
    subgraph Containers
        L["list[str]<br/>📦 Box of words"]
        D["dict[str, int]<br/>🗄️ Labeled drawers"]
        T["tuple[int, int]<br/>📮 Sealed pair"]
        S["set[int]<br/>🎒 Unique items"]
    end

📚 The typing Module

Sometimes basic labels aren’t enough. The typing module gives you superpowers!

Optional: “Maybe There, Maybe Not”

from typing import Optional

def find_user(user_id: int) -> Optional[str]:
    users = {1: "Alice", 2: "Bob"}
    return users.get(user_id)
    # Returns a string OR None

Real-life analogy: You check your mailbox. Sometimes there’s a letter, sometimes it’s empty. Optional[str] means “maybe a string, maybe nothing.”

Union: “This OR That”

from typing import Union

def double(value: Union[int, float]) -> Union[int, float]:
    return value * 2
    # Works with whole numbers AND decimals!

Python 3.10+ shortcut:

def double(value: int | float) -> int | float:
    return value * 2

Callable: “A Function That Takes a Function”

from typing import Callable

def apply_twice(
    func: Callable[[int], int],
    value: int
) -> int:
    return func(func(value))

# Usage
def add_one(x: int) -> int:
    return x + 1

result = apply_twice(add_one, 5)  # Returns 7

Analogy: You give someone a recipe (the function) and an ingredient (the value). They use the recipe twice!

Any: “I Accept Everything”

from typing import Any

def print_anything(item: Any) -> None:
    print(item)

Use Any sparingly—it’s like a label that says “???”

🏷️ Type Aliases

When your labels get long and complicated, give them a nickname!

The Problem

# This is hard to read!
def process(
    data: dict[str, list[tuple[int, str]]]
) -> dict[str, list[tuple[int, str]]]:
    return data

The Solution: Give It a Name!

# Create a nickname (alias)
StudentRecord = dict[str, list[tuple[int, str]]]

# Now use the simple name
def process(data: StudentRecord) -> StudentRecord:
    return data

More Alias Examples

# Simple aliases
UserID = int
Username = str
Email = str

# Complex aliases made simple
Coordinates = tuple[float, float]
UserInfo = dict[str, str | int]
Matrix = list[list[int]]

# Using them
def get_location(user: UserID) -> Coordinates:
    return (40.7128, -74.0060)

def create_grid(rows: int, cols: int) -> Matrix:
    return [[0] * cols for _ in range(rows)]

graph TD
    A["Long Type:<br/>dict[str, list[int]]"]
    -->|"Give nickname"| B["Alias:<br/>GradeBook"]
    B -->|"Use everywhere"| C["Clean Code! ✨"]
    style B fill:#4ECDC4,color:#fff
    style C fill:#95E1D3,color:#333

🧬 Generic Types

Generics are like mad libs for types. You create a template and fill in the blanks later!

The Concept

Imagine a box that can hold anything. Instead of saying “box of strings” or “box of numbers,” you say “box of ___” and fill it in when you use it.

from typing import TypeVar, Generic

# Create a blank to fill in later
T = TypeVar('T')

# A box that can hold anything
class Box(Generic[T]):
    def __init__(self, item: T):
        self.item = item

    def get(self) -> T:
        return self.item

Using Generic Classes

# Fill in the blank with 'str'
string_box: Box[str] = Box("Hello!")
word = string_box.get()  # word is a str

# Fill in the blank with 'int'
number_box: Box[int] = Box(42)
num = number_box.get()  # num is an int

Generic Functions

from typing import TypeVar

T = TypeVar('T')

def first_item(items: list[T]) -> T:
    return items[0]

# Works with any list!
name = first_item(["a", "b", "c"])  # str
number = first_item([1, 2, 3])      # int

Multiple Type Variables

from typing import TypeVar

K = TypeVar('K')  # Key type
V = TypeVar('V')  # Value type

def swap(a: K, b: V) -> tuple[V, K]:
    return (b, a)

# K=str, V=int
result = swap("hello", 42)  # (42, "hello")

graph TD
    subgraph "Generic[T]"
        A["Box[___]<br/>Template"]
        -->|"T = str"| B["Box[str]<br/>Words"]
        A -->|"T = int"| C["Box[int]<br/>Numbers"]
        A -->|"T = bool"| D["Box[bool]<br/>Yes/No"]
    end
    style A fill:#667eea,color:#fff

🎁 Putting It All Together

Let’s see everything working in harmony!

from typing import TypeVar, Optional, Callable

# Type alias for clarity
UserID = int
Username = str

# Generic type variable
T = TypeVar('T')

# A real-world function
def find_or_default(
    items: list[T],
    condition: Callable[[T], bool],
    default: T
) -> T:
    for item in items:
        if condition(item):
            return item
    return default

# Using it
numbers = [1, 2, 3, 4, 5]
first_even = find_or_default(
    numbers,
    lambda x: x % 2 == 0,
    0
)  # Returns 2

🌟 Why Type Hints Make You a Better Coder

1. Catch bugs early → Your editor warns you before you run
2. Read code faster → Labels tell the story
3. Refactor safely → Change code with confidence
4. Document automatically → No extra comments needed

🚀 Your Type Hints Journey

graph TD
    A["Start Here:<br/>Basic Types"]
    --> B["Level Up:<br/>Common Hints"]
    B --> C["Power User:<br/>typing Module"]
    C --> D["Pro Move:<br/>Type Aliases"]
    D --> E["Master Level:<br/>Generics"]
    style A fill:#FF6B6B,color:#fff
    style E fill:#4ECDC4,color:#fff

Remember: Type hints are your friends, not your bosses. Python won’t stop you if you ignore them—but your future self will thank you for using them! 🙌

You’ve got this! Start with basic annotations, and soon you’ll be writing type hints like a pro. Each label you add makes your code clearer and your life easier. Happy coding! 💻✨