Module 01 · Day 1
Python Fundamentals & Type Hints
What a hint promises, and what it does not
Goal today: write typed functions and see what Python does when the types are wrong.
Core Idea
Hints are for readers and tools, not for Python
- Python is dynamically typed: a variable can hold anything.
- Hints are ignored at runtime.
- A type checker (mypy, your editor) flags mismatches before you run the code.
- Runtime enforcement needs validation, which is what Pydantic does later.
Syntax
Typed function
def summarize(text: str, max_words: int = 50) -> str:
words = text.split()
return " ".join(words[:max_words])
summarize("hello world", 1) # fine
summarize("hello world", "one") # checker flags it; Python still runs it
Syntax
Hint shapes you will use constantly
list[str]
A list of strings.
dict[str, int]
String keys, int values.
str | None
A string or nothing (also Optional[str]).
-> int
Return type of a function.
From Another Language
Bridge
list[str] is List<string> and str | None is string?, but the compiler guarantee is gone. The type checker behaves like an analyzer warning, not a build error. Hints are a promise to the reader and the tooling, not a runtime contract.
Hands-On
practice_types.py (~25 min)
def word_count(text: str) -> int: ...
def top_n_words(text: str, n: int = 5) -> list[str]: ...
def find_user(users: dict[str, str], user_id: str) -> str | None: ...
- Implement all three and print a few results.
- Call one with a wrong-typed argument and watch what happens.
- Run
uv run mypy src and see the same mistakes caught before running.
Watch Out
Pitfalls
- A wrong type may not crash where you expect:
find_user(users, 1) just returns None.
- If it does crash, the error comes from inside the function, not from the hint.
- Do not go into generics or protocols yet.
Capstone Tie-In
Where this goes
Every function in the Python AI Service behind ai-knowledge-assistant will use this typed style, so Module 2's FastAPI and Pydantic work feels like "the same thing, now enforced".
Next: async/await & Pydantic