📘 Type Checking: Running Mypy

🎯 Introduction

Welcome to this exciting tutorial on type checking with mypy! 🎉 In this guide, we’ll explore how to catch bugs before they bite by using Python’s most popular static type checker.

You’ll discover how mypy can transform your Python development experience by finding errors at development time instead of runtime. Whether you’re building web APIs 🌐, data pipelines 📊, or command-line tools 🛠️, understanding mypy is essential for writing robust, maintainable code.

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

📚 Understanding Type Checking with Mypy

🤔 What is Mypy?

Mypy is like having a helpful friend who reads your code before you run it 🕵️‍♂️. Think of it as a spell-checker for your Python code that catches type-related mistakes before they cause problems in production!

In Python terms, mypy performs static type checking - analyzing your code without running it. This means you can:

• ✨ Catch type errors before runtime
• 🚀 Get better IDE support and autocomplete
• 🛡️ Make refactoring safer and easier

💡 Why Use Mypy?

Here’s why developers love mypy:

1. Early Bug Detection 🐛: Find errors during development
2. Better Documentation 📖: Types serve as inline documentation
3. Confident Refactoring 🔧: Change code without fear
4. Team Collaboration 🤝: Clear interfaces between components

Real-world example: Imagine building an e-commerce API 🛒. With mypy, you can ensure that price calculations always use the right data types, preventing those nasty “TypeError: unsupported operand type(s)” in production!

🔧 Basic Syntax and Usage

📝 Installing and Running Mypy

Let’s start with the basics:

# 👋 First, install mypy!
# pip install mypy

# 🎨 Create a simple Python file: hello.py
def greet(name: str) -> str:
    """Say hello to someone! 🎉"""
    return f"Hello, {name}! Welcome to type checking!"

# 🎯 This will cause a type error
result = greet(123)  # 💥 Oops! We're passing a number instead of a string
print(result)

Now let’s run mypy:

# 🚀 Run mypy on your file
mypy hello.py

# 📝 Mypy output:
# hello.py:7: error: Argument 1 to "greet" has incompatible type "int"; expected "str"

💡 Explanation: Mypy caught the error before we even ran the code! It noticed we’re passing an integer to a function expecting a string.

🎯 Common Mypy Commands

Here are the most useful mypy commands:

# 🏗️ Check a single file
mypy script.py

# 📦 Check an entire package
mypy my_package/

# 🎨 Check with strict mode (catch more issues)
mypy --strict script.py

# 🔄 Show error codes (helpful for suppressing specific warnings)
mypy --show-error-codes script.py

# 📊 Generate an HTML report
mypy --html-report ./mypy_report script.py

💡 Practical Examples

🛒 Example 1: Type-Safe Shopping Cart

Let’s build a shopping cart with proper type checking:

# 🛍️ shopping_cart.py
from typing import List, Dict, Optional
from decimal import Decimal

class Product:
    """A product in our store 🏪"""
    def __init__(self, id: str, name: str, price: Decimal, emoji: str) -> None:
        self.id = id
        self.name = name
        self.price = price
        self.emoji = emoji  # Every product needs an emoji! 

class ShoppingCart:
    """Type-safe shopping cart 🛒"""
    def __init__(self) -> None:
        self.items: List[Product] = []
        self.discount_code: Optional[str] = None
    
    def add_item(self, product: Product) -> None:
        """Add item to cart ➕"""
        self.items.append(product)
        print(f"Added {product.emoji} {product.name} to cart!")
    
    def apply_discount(self, code: str) -> bool:
        """Apply discount code 🎟️"""
        valid_codes = ["SAVE10", "PYTHON20", "MYPY15"]
        if code in valid_codes:
            self.discount_code = code
            print(f"✅ Discount code {code} applied!")
            return True
        print(f"❌ Invalid discount code: {code}")
        return False
    
    def calculate_total(self) -> Decimal:
        """Calculate total with type safety 💰"""
        subtotal = sum(item.price for item in self.items)
        
        # Apply discount if exists
        if self.discount_code == "SAVE10":
            return subtotal * Decimal("0.9")
        elif self.discount_code == "PYTHON20":
            return subtotal * Decimal("0.8")
        elif self.discount_code == "MYPY15":
            return subtotal * Decimal("0.85")
        
        return subtotal

# 🎮 Let's test our type-safe cart!
cart = ShoppingCart()
book = Product("1", "Python Type Checking Guide", Decimal("29.99"), "📘")
coffee = Product("2", "Developer Coffee", Decimal("4.99"), "☕")

cart.add_item(book)
cart.add_item(coffee)

# ❌ This would be caught by mypy:
# cart.add_item("not a product")  # Type error!

# ✅ This is type-safe:
cart.apply_discount("MYPY15")
total = cart.calculate_total()
print(f"Total: ${total:.2f} 💳")

Run mypy to check:

mypy shopping_cart.py
# Success: no issues found in 1 source file ✅

🎮 Example 2: Game Score Validator

Let’s create a type-safe game scoring system:

# 🏆 game_scores.py
from typing import Dict, List, Literal, TypedDict, Union
from datetime import datetime

# 🎯 Define strict types for our game
GameMode = Literal["easy", "medium", "hard", "extreme"]
PlayerLevel = Literal[1, 2, 3, 4, 5]

class ScoreEntry(TypedDict):
    """Type-safe score entry 📊"""
    player_name: str
    score: int
    level: PlayerLevel
    mode: GameMode
    timestamp: datetime
    achievements: List[str]

class GameScoreValidator:
    """Validates and manages game scores 🎮"""
    def __init__(self) -> None:
        self.high_scores: Dict[GameMode, List[ScoreEntry]] = {
            "easy": [],
            "medium": [],
            "hard": [],
            "extreme": []
        }
    
    def validate_score(self, entry: ScoreEntry) -> Union[str, None]:
        """Validate a score entry 🔍"""
        # Type checking ensures these checks are comprehensive
        if entry["score"] < 0:
            return "❌ Score cannot be negative!"
        
        if entry["score"] > 1_000_000:
            return "❌ Score seems unrealistic (>1M)"
        
        if len(entry["player_name"]) < 3:
            return "❌ Player name too short"
        
        if entry["level"] < 1 or entry["level"] > 5:
            return "❌ Invalid player level"
        
        return None  # ✅ Valid!
    
    def add_score(self, entry: ScoreEntry) -> bool:
        """Add a validated score 🏆"""
        error = self.validate_score(entry)
        if error:
            print(error)
            return False
        
        # Type system ensures mode is valid
        self.high_scores[entry["mode"]].append(entry)
        
        # Sort by score (highest first)
        self.high_scores[entry["mode"]].sort(
            key=lambda x: x["score"], 
            reverse=True
        )
        
        print(f"✅ Score added for {entry['player_name']}!")
        return True
    
    def get_top_scores(self, mode: GameMode, limit: int = 5) -> List[ScoreEntry]:
        """Get top scores for a game mode 🌟"""
        return self.high_scores[mode][:limit]

# 🎮 Test our type-safe game system
validator = GameScoreValidator()

# ✅ Valid score entry
good_score: ScoreEntry = {
    "player_name": "PythonMaster",
    "score": 42000,
    "level": 3,
    "mode": "medium",
    "timestamp": datetime.now(),
    "achievements": ["🌟 First Victory", "💎 Combo Master"]
}

validator.add_score(good_score)

# ❌ This would be caught by mypy:
# bad_score: ScoreEntry = {
#     "player_name": "Cheater",
#     "score": "not a number",  # Type error!
#     "level": 99,  # Invalid level!
#     "mode": "super_easy",  # Invalid mode!
#     "timestamp": "yesterday",  # Wrong type!
#     "achievements": "just one"  # Should be a list!
# }

🚀 Advanced Concepts

🧙‍♂️ Configuring Mypy with mypy.ini

When you’re ready to level up, create a configuration file:

# mypy.ini
[mypy]
# 🎯 Enable strict mode gradually
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True
disallow_incomplete_defs = True
check_untyped_defs = True
disallow_untyped_decorators = True
no_implicit_optional = True
warn_redundant_casts = True
warn_unused_ignores = True
warn_no_return = True
warn_unreachable = True
strict_equality = True

# 🎨 Pretty output
pretty = True
show_error_codes = True
show_error_context = True

# 📦 Ignore missing imports for third-party libraries
[mypy-requests.*]
ignore_missing_imports = True

[mypy-pandas.*]
ignore_missing_imports = True

🏗️ Gradual Typing Strategy

For existing projects, adopt mypy gradually:

# 🚀 gradual_typing.py
from typing import Any, cast

# Phase 1: Start with Any for complex types
def legacy_function(data: Any) -> Any:
    """Old function we're gradually typing 🔄"""
    # TODO: Add proper types later
    return data["result"]

# Phase 2: Add basic types
def improved_function(data: dict[str, Any]) -> str:
    """Better typed version 📈"""
    return str(data.get("result", ""))

# Phase 3: Full typing with validation
from typing import TypedDict

class DataPayload(TypedDict):
    result: str
    status: int
    timestamp: float

def fully_typed_function(data: DataPayload) -> str:
    """Fully typed with validation! 🎉"""
    if data["status"] != 200:
        raise ValueError(f"Bad status: {data['status']}")
    return data["result"]

# 🛡️ Use cast when you know better than mypy
external_data = {"result": "success", "status": 200, "timestamp": 1234567890.0}
typed_data = cast(DataPayload, external_data)
result = fully_typed_function(typed_data)

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: The “Any” Escape Hatch

# ❌ Wrong way - bypassing type safety!
from typing import Any

def process_data(data: Any) -> Any:
    """This could hide so many bugs! 😰"""
    return data.do_something()  # No type checking here!

# ✅ Correct way - be specific!
from typing import Protocol

class Processable(Protocol):
    """Define what we expect 🎯"""
    def do_something(self) -> str: ...

def process_data(data: Processable) -> str:
    """Now mypy helps us! 🛡️"""
    return data.do_something()

🤯 Pitfall 2: Ignoring Optional Types

# ❌ Dangerous - might be None!
def get_user_age(user_id: str) -> int:
    user = find_user(user_id)  # Could return None!
    return user.age  # 💥 AttributeError if user is None!

# ✅ Safe - handle None properly!
from typing import Optional

def get_user_age(user_id: str) -> Optional[int]:
    user = find_user(user_id)
    if user is None:
        print(f"⚠️ User {user_id} not found!")
        return None
    return user.age  # ✅ Safe now!

🛠️ Best Practices

1. 🎯 Start Gradually: Use --follow-imports=skip initially
2. 📝 Type Public APIs First: Focus on function signatures
3. 🛡️ Enable Strict Mode Progressively: One flag at a time
4. 🎨 Use Type Aliases: Make complex types readable
5. ✨ Leverage Protocols: For duck typing with safety

🧪 Hands-On Exercise

🎯 Challenge: Build a Type-Safe Task Manager

Create a task management system with full type checking:

📋 Requirements:

• ✅ Tasks with title, status, priority, and due date
• 🏷️ Categories with emoji identifiers
• 👤 User assignment with role validation
• 📊 Statistics calculation with type safety
• 🎨 Each task must have an emoji status indicator!

🚀 Bonus Points:

• Add task dependencies
• Implement deadline warnings
• Create a type-safe query system

💡 Solution

# 🎯 Type-safe task manager!
from typing import Dict, List, Optional, Literal, TypedDict
from datetime import datetime, timedelta
from enum import Enum

# 🎨 Define our type system
TaskStatus = Literal["pending", "in_progress", "completed", "cancelled"]
Priority = Literal["low", "medium", "high", "urgent"]
UserRole = Literal["viewer", "contributor", "manager", "admin"]

class TaskEmoji(Enum):
    """Status emojis 🎨"""
    PENDING = "⏳"
    IN_PROGRESS = "🔄"
    COMPLETED = "✅"
    CANCELLED = "❌"
    
class Category(TypedDict):
    """Task category with emoji 🏷️"""
    name: str
    emoji: str
    color: str

class User(TypedDict):
    """User with role 👤"""
    id: str
    name: str
    role: UserRole
    
class Task(TypedDict):
    """Complete task definition 📝"""
    id: str
    title: str
    description: str
    status: TaskStatus
    priority: Priority
    category: Category
    assignee: Optional[User]
    due_date: Optional[datetime]
    created_at: datetime
    dependencies: List[str]  # Task IDs

class TaskManager:
    """Type-safe task management system 🎯"""
    def __init__(self) -> None:
        self.tasks: Dict[str, Task] = {}
        self.task_counter: int = 0
        
    def create_task(
        self, 
        title: str, 
        description: str,
        priority: Priority,
        category: Category,
        assignee: Optional[User] = None,
        due_date: Optional[datetime] = None,
        dependencies: Optional[List[str]] = None
    ) -> Task:
        """Create a new task with validation 📝"""
        # Validate assignee permissions
        if assignee and assignee["role"] == "viewer":
            raise ValueError("❌ Viewers cannot be assigned tasks!")
            
        # Validate dependencies exist
        if dependencies:
            for dep_id in dependencies:
                if dep_id not in self.tasks:
                    raise ValueError(f"❌ Dependency {dep_id} not found!")
        
        self.task_counter += 1
        task_id = f"TASK-{self.task_counter:04d}"
        
        task: Task = {
            "id": task_id,
            "title": title,
            "description": description,
            "status": "pending",
            "priority": priority,
            "category": category,
            "assignee": assignee,
            "due_date": due_date,
            "created_at": datetime.now(),
            "dependencies": dependencies or []
        }
        
        self.tasks[task_id] = task
        print(f"✅ Created task {task_id}: {title}")
        return task
    
    def update_status(self, task_id: str, new_status: TaskStatus) -> bool:
        """Update task status with validation 🔄"""
        if task_id not in self.tasks:
            print(f"❌ Task {task_id} not found!")
            return False
            
        task = self.tasks[task_id]
        
        # Check dependencies
        if new_status == "completed":
            for dep_id in task["dependencies"]:
                dep_task = self.tasks.get(dep_id)
                if dep_task and dep_task["status"] != "completed":
                    print(f"❌ Cannot complete: dependency {dep_id} not done!")
                    return False
        
        old_status = task["status"]
        task["status"] = new_status
        
        # Get emoji for new status
        emoji = TaskEmoji[new_status.upper()].value
        print(f"{emoji} Task {task_id}: {old_status} → {new_status}")
        return True
    
    def get_deadline_warnings(self) -> List[Task]:
        """Get tasks due soon ⏰"""
        warnings: List[Task] = []
        now = datetime.now()
        warning_threshold = now + timedelta(days=2)
        
        for task in self.tasks.values():
            if (task["status"] != "completed" and 
                task["due_date"] and 
                task["due_date"] <= warning_threshold):
                warnings.append(task)
        
        return sorted(warnings, key=lambda t: t["due_date"] or now)
    
    def get_statistics(self) -> Dict[str, int]:
        """Calculate task statistics 📊"""
        stats: Dict[str, int] = {
            "total": len(self.tasks),
            "pending": 0,
            "in_progress": 0,
            "completed": 0,
            "cancelled": 0,
            "overdue": 0
        }
        
        now = datetime.now()
        for task in self.tasks.values():
            stats[task["status"]] += 1
            if (task["due_date"] and 
                task["due_date"] < now and 
                task["status"] not in ["completed", "cancelled"]):
                stats["overdue"] += 1
        
        return stats

# 🎮 Test it out!
manager = TaskManager()

# Create categories
dev_category: Category = {"name": "Development", "emoji": "💻", "color": "blue"}
bug_category: Category = {"name": "Bug Fix", "emoji": "🐛", "color": "red"}

# Create users
alice: User = {"id": "alice", "name": "Alice", "role": "manager"}
bob: User = {"id": "bob", "name": "Bob", "role": "contributor"}

# Create tasks
task1 = manager.create_task(
    title="Setup mypy configuration",
    description="Configure mypy for the project",
    priority="high",
    category=dev_category,
    assignee=alice,
    due_date=datetime.now() + timedelta(days=1)
)

task2 = manager.create_task(
    title="Fix type errors",
    description="Fix all mypy errors in codebase",
    priority="urgent",
    category=bug_category,
    assignee=bob,
    dependencies=[task1["id"]]
)

# Update status
manager.update_status(task1["id"], "completed")
manager.update_status(task2["id"], "in_progress")

# Check warnings
warnings = manager.get_deadline_warnings()
if warnings:
    print(f"⚠️ {len(warnings)} tasks due soon!")

# Get stats
stats = manager.get_statistics()
print(f"📊 Stats: {stats}")

🎓 Key Takeaways

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

• ✅ Install and run mypy with confidence 💪
• ✅ Configure mypy for your projects 🛡️
• ✅ Write type-safe Python code that catches bugs early 🎯
• ✅ Debug type errors like a pro 🐛
• ✅ Gradually adopt typing in existing codebases! 🚀

Remember: Type checking is your friend, not your enemy! It’s here to help you write better, more maintainable code. 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered running mypy for type checking!

Here’s what to do next:

1. 💻 Install mypy and try it on your own projects
2. 🏗️ Start with basic type annotations and gradually increase strictness
3. 📚 Move on to our next tutorial on advanced type annotations
4. 🌟 Share your type-safe code with the Python community!

Remember: Every Python expert started without types. Adding them is a journey, not a destination. Keep coding, keep learning, and most importantly, have fun with type safety! 🚀

Happy type checking! 🎉🚀✨