📘 TypedDict: Dictionary Schemas

🎯 Introduction

Welcome to this exciting tutorial on TypedDict! 🎉 In this guide, we’ll explore how to bring type safety to Python dictionaries, making your code more robust and maintainable.

You’ll discover how TypedDict can transform your Python development experience. Whether you’re building web applications 🌐, APIs 🖥️, or data processing pipelines 📊, understanding TypedDict is essential for writing type-safe, self-documenting code.

By the end of this tutorial, you’ll feel confident using TypedDict in your own projects! Let’s dive in! 🏊‍♂️

📚 Understanding TypedDict

🤔 What is TypedDict?

TypedDict is like a blueprint for dictionaries 🏗️. Think of it as a contract that specifies exactly what keys a dictionary should have and what types their values should be - like a form that tells you which fields to fill out and what kind of information goes in each field!

In Python terms, TypedDict provides static type hints for dictionaries with a fixed schema. This means you can:

✨ Define the exact structure of your dictionaries
🚀 Get IDE autocomplete and type checking
🛡️ Catch type errors before runtime

💡 Why Use TypedDict?

Here’s why developers love TypedDict:

Type Safety 🔒: Catch errors before they happen
Better IDE Support 💻: Autocomplete dictionary keys
Code Documentation 📖: Types serve as inline docs
Refactoring Confidence 🔧: Change code without fear

Real-world example: Imagine building a user management system 👥. With TypedDict, you can ensure every user dictionary has the required fields with correct types!

🔧 Basic Syntax and Usage

📝 Simple Example

Let’s start with a friendly example:

# 👋 Hello, TypedDict!
from typing import TypedDict

# 🎨 Creating a simple TypedDict
class Person(TypedDict):
    name: str        # 👤 Person's name
    age: int         # 🎂 Person's age
    email: str       # 📧 Email address

# 🏗️ Using our TypedDict
developer: Person = {
    "name": "Sarah",
    "age": 28,
    "email": "[email protected]"
}

# ✨ IDE now knows the structure!
print(f"Hello {developer['name']}! 👋")

💡 Explanation: TypedDict creates a type annotation for dictionaries. The IDE now knows exactly what keys are available!

🎯 Common Patterns

Here are patterns you’ll use daily:

from typing import TypedDict, Optional, List

# 🏗️ Pattern 1: Optional fields
class User(TypedDict, total=False):
    id: str
    name: str
    bio: Optional[str]      # 🎯 Optional field
    hobbies: List[str]      # 📚 List of hobbies

# 🎨 Pattern 2: Required and optional mix
class Product(TypedDict):
    id: str                 # Required
    name: str               # Required
    price: float            # Required
    
class ProductOptional(TypedDict, total=False):
    description: str        # Optional
    discount: float         # Optional

# 🔄 Pattern 3: Combining TypedDicts
class FullProduct(Product, ProductOptional):
    pass  # Has both required and optional fields!

💡 Practical Examples

🛒 Example 1: E-commerce Order System

Let’s build something real:

# 🛍️ E-commerce order system
from typing import TypedDict, List, Literal
from datetime import datetime

class Address(TypedDict):
    street: str
    city: str
    zip_code: str
    country: str

class OrderItem(TypedDict):
    product_id: str
    name: str
    quantity: int
    price: float
    emoji: str  # Every product needs an emoji! 🎨

class Order(TypedDict):
    order_id: str
    customer_name: str
    items: List[OrderItem]
    shipping_address: Address
    status: Literal["pending", "shipped", "delivered"]
    total: float

# 🛒 Order processing class
class OrderProcessor:
    def __init__(self):
        self.orders: List[Order] = []
    
    # ➕ Create new order
    def create_order(self, customer: str, address: Address) -> Order:
        order: Order = {
            "order_id": f"ORD-{len(self.orders) + 1:04d}",
            "customer_name": customer,
            "items": [],
            "shipping_address": address,
            "status": "pending",
            "total": 0.0
        }
        self.orders.append(order)
        print(f"📦 Created order for {customer}!")
        return order
    
    # 🛍️ Add item to order
    def add_item(self, order: Order, item: OrderItem) -> None:
        order["items"].append(item)
        order["total"] += item["price"] * item["quantity"]
        print(f"Added {item['emoji']} {item['name']} x{item['quantity']} to order!")
    
    # 📋 Display order summary
    def display_order(self, order: Order) -> None:
        print(f"\n🛒 Order {order['order_id']} Summary:")
        print(f"👤 Customer: {order['customer_name']}")
        print(f"📍 Ship to: {order['shipping_address']['city']}")
        print("📦 Items:")
        for item in order["items"]:
            subtotal = item["price"] * item["quantity"]
            print(f"  {item['emoji']} {item['name']} x{item['quantity']} = ${subtotal:.2f}")
        print(f"💰 Total: ${order['total']:.2f}")
        print(f"📊 Status: {order['status']}")

# 🎮 Let's use it!
processor = OrderProcessor()

# Create shipping address
address: Address = {
    "street": "123 Python Lane",
    "city": "Codeville",
    "zip_code": "12345",
    "country": "Pythonia"
}

# Create order
order = processor.create_order("Alice Developer", address)

# Add items
processor.add_item(order, {
    "product_id": "BOOK-001",
    "name": "Python Mastery",
    "quantity": 1,
    "price": 29.99,
    "emoji": "📘"
})

processor.add_item(order, {
    "product_id": "MUG-001",
    "name": "Code & Coffee Mug",
    "quantity": 2,
    "price": 12.99,
    "emoji": "☕"
})

processor.display_order(order)

🎯 Try it yourself: Add a method to update order status and calculate shipping costs!

🎮 Example 2: Game Character System

Let’s make it fun:

# 🏆 RPG character system
from typing import TypedDict, List, Dict, Optional

class Stats(TypedDict):
    health: int
    mana: int
    strength: int
    defense: int
    speed: int

class Skill(TypedDict):
    name: str
    damage: int
    mana_cost: int
    emoji: str
    description: str

class Equipment(TypedDict):
    name: str
    slot: Literal["weapon", "armor", "accessory"]
    bonus_stats: Dict[str, int]
    emoji: str

class Character(TypedDict):
    name: str
    class_type: Literal["warrior", "mage", "rogue"]
    level: int
    stats: Stats
    skills: List[Skill]
    equipment: Dict[str, Optional[Equipment]]
    experience: int

class GameEngine:
    def __init__(self):
        self.characters: Dict[str, Character] = {}
    
    # 🎮 Create new character
    def create_character(self, name: str, class_type: Literal["warrior", "mage", "rogue"]) -> Character:
        base_stats = {
            "warrior": Stats(health=100, mana=20, strength=15, defense=12, speed=8),
            "mage": Stats(health=60, mana=100, strength=5, defense=8, speed=10),
            "rogue": Stats(health=75, mana=50, strength=10, defense=9, speed=15)
        }
        
        starter_skills = {
            "warrior": [
                Skill(name="Sword Slash", damage=20, mana_cost=5, 
                     emoji="⚔️", description="A powerful sword attack"),
            ],
            "mage": [
                Skill(name="Fireball", damage=30, mana_cost=15,
                     emoji="🔥", description="Launches a blazing fireball"),
            ],
            "rogue": [
                Skill(name="Sneak Attack", damage=25, mana_cost=10,
                     emoji="🗡️", description="Strike from the shadows"),
            ]
        }
        
        character: Character = {
            "name": name,
            "class_type": class_type,
            "level": 1,
            "stats": base_stats[class_type],
            "skills": starter_skills[class_type],
            "equipment": {
                "weapon": None,
                "armor": None,
                "accessory": None
            },
            "experience": 0
        }
        
        self.characters[name] = character
        print(f"🎊 Created {class_type} named {name}!")
        return character
    
    # 🛡️ Equip item
    def equip_item(self, character: Character, item: Equipment) -> None:
        slot = item["slot"]
        old_item = character["equipment"][slot]
        
        if old_item:
            print(f"🔄 Replacing {old_item['emoji']} {old_item['name']}")
        
        character["equipment"][slot] = item
        
        # Apply stat bonuses
        for stat, bonus in item["bonus_stats"].items():
            if stat in character["stats"]:
                character["stats"][stat] += bonus
        
        print(f"✨ Equipped {item['emoji']} {item['name']}!")
    
    # 📊 Display character
    def display_character(self, character: Character) -> None:
        print(f"\n🎮 Character: {character['name']}")
        print(f"⚔️ Class: {character['class_type']} | Level: {character['level']}")
        print("📊 Stats:")
        for stat, value in character["stats"].items():
            print(f"  {stat.capitalize()}: {value}")
        print("🎯 Skills:")
        for skill in character["skills"]:
            print(f"  {skill['emoji']} {skill['name']} - {skill['damage']} damage")

# 🎮 Test the game!
game = GameEngine()
hero = game.create_character("Pythonista", "mage")

# Equip some items
magic_staff: Equipment = {
    "name": "Staff of Wisdom",
    "slot": "weapon",
    "bonus_stats": {"mana": 20, "strength": 5},
    "emoji": "🔮"
}

game.equip_item(hero, magic_staff)
game.display_character(hero)

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Inheritance and Composition

When you’re ready to level up, try this advanced pattern:

# 🎯 Advanced TypedDict patterns
from typing import TypedDict, Union, Literal

# Base types
class BaseEntity(TypedDict):
    id: str
    created_at: str
    updated_at: str

class Timestamps(TypedDict):
    created_at: str
    updated_at: str

# Composition approach
class UserBase(TypedDict):
    name: str
    email: str

class AdminUser(UserBase, Timestamps):
    role: Literal["admin"]
    permissions: List[str]

class RegularUser(UserBase, Timestamps):
    role: Literal["user"]
    subscription: Literal["free", "premium"]

# Union type for all users
User = Union[AdminUser, RegularUser]

# 🪄 Type narrowing function
def process_user(user: User) -> None:
    print(f"Processing {user['name']} ({user['role']})")
    
    if user["role"] == "admin":
        # TypeScript knows this is AdminUser now!
        print(f"  🛡️ Permissions: {', '.join(user['permissions'])}")
    else:
        # And this is RegularUser!
        print(f"  💎 Subscription: {user['subscription']}")

🏗️ Advanced Topic 2: Runtime Validation

For the brave developers:

# 🚀 Runtime validation with TypedDict
from typing import TypedDict, get_type_hints, get_origin, get_args
import json

class Config(TypedDict):
    debug: bool
    port: int
    host: str
    features: List[str]

def validate_typed_dict(data: dict, typed_dict_class: type) -> bool:
    """Validate dictionary against TypedDict schema"""
    hints = get_type_hints(typed_dict_class)
    
    for field, expected_type in hints.items():
        if field not in data:
            print(f"❌ Missing required field: {field}")
            return False
        
        value = data[field]
        
        # Simple type checking (can be extended)
        if expected_type == str and not isinstance(value, str):
            print(f"❌ Field '{field}' should be string, got {type(value).__name__}")
            return False
        elif expected_type == int and not isinstance(value, int):
            print(f"❌ Field '{field}' should be int, got {type(value).__name__}")
            return False
        elif expected_type == bool and not isinstance(value, bool):
            print(f"❌ Field '{field}' should be bool, got {type(value).__name__}")
            return False
    
    print("✅ Validation passed!")
    return True

# Test validation
config_data = {
    "debug": True,
    "port": 8000,
    "host": "localhost",
    "features": ["api", "websocket"]
}

validate_typed_dict(config_data, Config)

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Mutability Confusion

# ❌ Wrong way - modifying TypedDict class attributes!
class Settings(TypedDict):
    theme: str

Settings.theme = "dark"  # 💥 This doesn't do what you think!

# ✅ Correct way - create instances!
settings: Settings = {
    "theme": "dark"
}

🤯 Pitfall 2: Total vs Partial

# ❌ Dangerous - all fields required by default!
class UserProfile(TypedDict):
    name: str
    bio: str      # What if user hasn't written bio yet?
    avatar: str   # What if no avatar uploaded?

# ✅ Safe - use total=False for optional fields!
class UserProfile(TypedDict):
    name: str  # Always required

class UserProfileOptional(TypedDict, total=False):
    bio: str      # Optional
    avatar: str   # Optional

class FullUserProfile(UserProfile, UserProfileOptional):
    pass  # Name is required, bio and avatar are optional!

🤔 Pitfall 3: Runtime Type Checking

# ❌ Wrong assumption - TypedDict doesn't validate at runtime!
def process_user(user: User):
    # This won't catch type errors at runtime!
    print(user["name"])

# ✅ Add runtime validation if needed!
def process_user_safe(user: User):
    if "name" not in user:
        raise ValueError("⚠️ User must have a name!")
    if not isinstance(user["name"], str):
        raise TypeError("⚠️ Name must be a string!")
    print(user["name"])

🛠️ Best Practices

🎯 Be Specific: Define exact types, avoid Any
📝 Use Descriptive Names: UserProfile not UP
🛡️ Separate Required/Optional: Use inheritance for clarity
🎨 Group Related Types: Keep TypedDicts organized
✨ Add Validation: Consider runtime checks for external data

🧪 Hands-On Exercise

🎯 Challenge: Build a Task Management System

Create a type-safe task management application:

📋 Requirements:

✅ Tasks with title, description, status, and priority
🏷️ Categories and tags for organization
👤 User assignment with roles
📅 Due dates and reminders
🎨 Each task needs an emoji based on category!

🚀 Bonus Points:

Add subtasks support
Implement task dependencies
Create a progress tracking system

💡 Solution

🔍 Click to see solution

# 🎯 Our type-safe task management system!
from typing import TypedDict, List, Optional, Literal, Dict
from datetime import datetime

class User(TypedDict):
    id: str
    name: str
    role: Literal["admin", "member", "viewer"]
    emoji: str

class Subtask(TypedDict):
    id: str
    title: str
    completed: bool

class Task(TypedDict):
    id: str
    title: str
    description: str
    status: Literal["todo", "in_progress", "review", "done"]
    priority: Literal["low", "medium", "high", "critical"]
    category: Literal["feature", "bug", "docs", "refactor"]
    tags: List[str]
    assignee: Optional[User]
    due_date: Optional[str]
    subtasks: List[Subtask]
    dependencies: List[str]  # Task IDs
    emoji: str

class TaskManager:
    def __init__(self):
        self.tasks: Dict[str, Task] = {}
        self.task_counter = 0
        
        # Category emoji mapping
        self.category_emojis = {
            "feature": "✨",
            "bug": "🐛",
            "docs": "📚",
            "refactor": "🔧"
        }
    
    # ➕ Create new task
    def create_task(self, 
                   title: str,
                   description: str,
                   category: Literal["feature", "bug", "docs", "refactor"],
                   priority: Literal["low", "medium", "high", "critical"] = "medium") -> Task:
        self.task_counter += 1
        task_id = f"TASK-{self.task_counter:04d}"
        
        task: Task = {
            "id": task_id,
            "title": title,
            "description": description,
            "status": "todo",
            "priority": priority,
            "category": category,
            "tags": [],
            "assignee": None,
            "due_date": None,
            "subtasks": [],
            "dependencies": [],
            "emoji": self.category_emojis[category]
        }
        
        self.tasks[task_id] = task
        print(f"✅ Created task: {task['emoji']} {title} [{task_id}]")
        return task
    
    # 👤 Assign task to user
    def assign_task(self, task_id: str, user: User) -> None:
        if task_id in self.tasks:
            self.tasks[task_id]["assignee"] = user
            print(f"📌 Assigned {self.tasks[task_id]['title']} to {user['emoji']} {user['name']}")
    
    # 📊 Add subtask
    def add_subtask(self, task_id: str, subtask_title: str) -> None:
        if task_id in self.tasks:
            subtask: Subtask = {
                "id": f"{task_id}-SUB-{len(self.tasks[task_id]['subtasks']) + 1}",
                "title": subtask_title,
                "completed": False
            }
            self.tasks[task_id]["subtasks"].append(subtask)
            print(f"📝 Added subtask: {subtask_title}")
    
    # 🎯 Get completion percentage
    def get_task_progress(self, task_id: str) -> float:
        if task_id not in self.tasks:
            return 0.0
        
        task = self.tasks[task_id]
        if task["status"] == "done":
            return 100.0
        
        if not task["subtasks"]:
            status_progress = {
                "todo": 0,
                "in_progress": 50,
                "review": 75,
                "done": 100
            }
            return status_progress[task["status"]]
        
        completed = sum(1 for st in task["subtasks"] if st["completed"])
        return (completed / len(task["subtasks"])) * 100
    
    # 📋 Display task summary
    def display_task(self, task_id: str) -> None:
        if task_id not in self.tasks:
            print("❌ Task not found!")
            return
        
        task = self.tasks[task_id]
        progress = self.get_task_progress(task_id)
        
        print(f"\n📋 Task: {task['emoji']} {task['title']} [{task_id}]")
        print(f"📝 Description: {task['description']}")
        print(f"📊 Status: {task['status']} | Priority: {task['priority']}")
        print(f"🏷️ Category: {task['category']}")
        
        if task["assignee"]:
            print(f"👤 Assignee: {task['assignee']['emoji']} {task['assignee']['name']}")
        
        if task["subtasks"]:
            print(f"📌 Subtasks ({len([st for st in task['subtasks'] if st['completed']])}/{len(task['subtasks'])}):")
            for st in task["subtasks"]:
                check = "✅" if st["completed"] else "⬜"
                print(f"  {check} {st['title']}")
        
        print(f"📊 Progress: {progress:.0f}%")

# 🎮 Test it out!
manager = TaskManager()

# Create users
alice: User = {"id": "USR001", "name": "Alice", "role": "admin", "emoji": "👩‍💻"}
bob: User = {"id": "USR002", "name": "Bob", "role": "member", "emoji": "👨‍💻"}

# Create tasks
task1 = manager.create_task(
    "Implement TypedDict validation",
    "Add runtime validation for TypedDict schemas",
    "feature",
    "high"
)

manager.assign_task(task1["id"], alice)
manager.add_subtask(task1["id"], "Research validation libraries")
manager.add_subtask(task1["id"], "Implement validator function")
manager.add_subtask(task1["id"], "Write unit tests")

manager.display_task(task1["id"])

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

✅ Create TypedDict schemas with confidence 💪
✅ Structure complex data with type safety 🛡️
✅ Use inheritance and composition for flexible types 🎯
✅ Implement runtime validation when needed 🐛
✅ Build type-safe applications with Python! 🚀

Remember: TypedDict brings the best of static typing to Python’s dynamic world! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered TypedDict!

Here’s what to do next:

💻 Practice with the exercises above
🏗️ Add TypedDict to your existing projects
📚 Explore related topics: Protocol, NamedTuple, dataclasses
🌟 Share your type-safe Python journey with others!

Remember: Every Python expert started as a beginner. Keep coding, keep learning, and most importantly, have fun! 🚀

Happy coding! 🎉🚀✨

Prerequisites

What you'll learn