sethserver.com Subscribe
None

Python Type Hints Tutorial: Catch Bugs Before Production with mypy

By Seth Black • Updated: March 18, 2026

Python · 4 min read

Like this kind of writing? Get one email a week with notes on startups, AI, and the occasional strong opinion about Python: subscribe to the newsletter.

I used to think type hints were just Python cosplay. You know: "Look mom, my dynamic language has types now." Then I debugged a production issue at 11 PM where someone passed a string to a function expecting an integer, and I got less smug.

Type hints don't make Python statically typed. They don't change runtime behavior. They're closer to a manual. And yes, I'm the guy who reads the manual. I joke that my superpower is the ability to RTFM, but it's not really a joke. It's how I avoid breaking prod when a dependency updates.

Type hints are documentation that can yell at you

The nice part is the hint sits right next to the code. No wiki page. No "tribal knowledge." Just... there.

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

That -> str is small, but it answers a question instantly. Same for variables:

age: int = 30
pi: float = 3.14159
is_python_awesome: bool = True

If you're on a team, this saves a Slack thread. If you're solo, it saves Future You from opening the file, staring at user_scores, and muttering "what the hell was I thinking."

The real value shows up in the messy parts

Most bugs don't live in greet(). They live in the glue code. The "take this JSON, convert it, store it, read it back, transform it, ship it" pipeline.

That's where more specific hints help.

from typing import Dict, List, Optional, Union

user_scores: Dict[str, int] = {"Alice": 95, "Bob": 87}

def process_input(value: Optional[str] = None) -> None:
    if value is None:
        return
    print(value.strip())

def multiply(a: Union[int, float], b: Union[int, float]) -> Union[int, float]:
    return a * b

I like Optional because it forces you to stare at None and admit it exists. Union is great for the "this is numeric-ish" reality of real code.

You can go further with callables and generics:

from typing import Callable, List, TypeVar

def apply_operation(x: int, y: int, operation: Callable[[int, int], int]) -> int:
    return operation(x, y)

T = TypeVar("T")

def first_element(lst: List[T]) -> T:
    return lst[0]

That Callable signature is a tiny contract. It tells the reader what kind of function you're expecting without needing a whole framework around it.

"Hallucinations" taught me to like static checks

Early on with LLMs, I watched GPT-3 confidently explain that pandas DataFrames have a .explode_into_confetti() method. My reaction: "That's not real. I checked. Twice."

Static type checking is the opposite vibe. It's boring. It's picky. It refuses to be impressed by your confidence.

Enter mypy:

pip install mypy
mypy your_file.py

If you do this:

def add_numbers(a: int, b: int) -> int:
    return a + b

add_numbers("5", 3)

mypy will say something like:

error: Argument 1 to "add_numbers" has incompatible type "str"; expected "int"

That's a bug caught before runtime. Before you push. Before someone files a ticket with "urgent" in all caps.

The "mechanical pieces" build confidence

I think about type hints the same way I think about logging, error handling, test cases, and database backups. Mechanical stuff. Not glamorous. But it buys you freedom.

You can ship the hack today and fix it next sprint, because you left yourself a trail of types that show exactly what breaks.

Type hints help with:

Don't turn your codebase into a type museum

I'm not into type hinting everything. Some code is a one-off script. Some code is a prototype. Some code is weird and dynamic and doesn't want your rules.

Start where it hurts:

Type aliases also help keep things readable:

from typing import Dict, Tuple, List

UserID = int
Username = str
UserData = Dict[UserID, Tuple[Username, List[str]]]

If you want duck typing without inheritance, Protocol is worth reading the manual on. (Yes, I said it.)

Type hints aren't magic. They're just a way to write down what you were already thinking. And if you need runtime validation with automatic type coercion and error messages, Pydantic handles data validation without manual isinstance checks scattered everywhere.

And if you're still skeptical, that's fine. Run mypy once on a real codebase. It'll either find nothing (congrats), or it'll find something you wish you'd caught last week.

-Sethers

Share this post
Newsletter

One email, once a week.

Notes on databases, systems, and the occasional strong opinion about Python. No spam, unsubscribe anytime.

Seth Black
Written by

Seth Black

Engineer and founder based in Texas. Writes about databases, AI, and running things in production. Embeds in small teams as lead engineer.

More from Python

View all →
Python

OpenAI Bought Astral - and my fav tool uv

Mar 23, 2026
Python

Python Pydantic Validation: Stop Writing Manual Checks

Mar 04, 2026
Python

Python asyncio Recipes

Mar 04, 2026