Python as backend code, not notebook code

The mental model: code is read far more than it is run

In a notebook the reader is you, five minutes from now. In a backend the reader is a teammate, a reviewer, a future you who has forgotten everything, and increasingly an AI coding tool that will only be as good as the structure you give it. Each tool in this lesson exists to make code easier to read correctly: functions name a step, classes name a thing, type hints state a promise, exceptions state what can go wrong, and a virtual environment states exactly what the code depends on.

Functions: one job, explicit inputs, explicit outputs

A good function takes everything it needs as parameters and gives back a value. It does not quietly read global variables or print its result.

# Notebook habit: hidden inputs, printed output, nothing reusable
prices = [499, 1299, 199]
total = 0
for p in prices:
    total += p
print("Total with GST:", total * 1.18)

# Backend habit: inputs are parameters, the result is returned
GST_RATE = 0.18

def total_with_gst(prices: list[float], rate: float = GST_RATE) -> float:
    """Sum the prices and add GST. Rounded to 2 decimals for display."""
    if rate < 0:
        raise ValueError(f"GST rate cannot be negative, got {rate}")
    return round(sum(prices) * (1 + rate), 2)

print(total_with_gst([499, 1299, 199]))   # 2356.46
print(total_with_gst([100], rate=0.05))   # 105.0

2356.46
105.0

Three things changed. The function can be called from anywhere, including a test. The constant has a name, so nobody wonders what 1.18 means. And bad input fails loudly with a message that says what was wrong, instead of producing a silently wrong number.

A useful rule: if you cannot describe what a function does in one sentence without the word "and", split it.

Classes: when data and behaviour belong together

Beginners either avoid classes entirely or wrap everything in one. Use a class when several values always travel together and some operations only make sense on them. For plain bundles of data, a dataclass gives you a clean constructor, a readable repr, and equality for free.

from dataclasses import dataclass, field
from datetime import datetime, timezone

@dataclass
class Ticket:
    id: int
    title: str
    priority: str = "normal"            # default value
    tags: list[str] = field(default_factory=list)   # never use a bare [] as a default
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))

    def escalate(self) -> None:
        if self.priority == "urgent":
            raise ValueError(f"Ticket {self.id} is already urgent")
        self.priority = "urgent"

t = Ticket(id=42, title="Invoice sync failing")
t.escalate()
print(t.priority, t.tags)          # urgent []
ts = datetime(2026, 1, 1, tzinfo=timezone.utc)
print(Ticket(1, "a", created_at=ts) == Ticket(1, "a", created_at=ts))  # True: equality compares fields

urgent []
True

The field(default_factory=list) line matters. A plain tags: list[str] = [] is rejected by dataclasses precisely because a mutable default would be shared across every instance, one of Python's classic traps. You will see the same trap in ordinary functions below.

Type hints: a promise the tools can check

Python does not enforce type hints at runtime. They are documentation that a checker such as mypy or pyright can verify, and that your editor and AI assistant use to understand your code. They also force you to decide what a function really returns.

from typing import Optional

def find_user_email(user_id: int) -> Optional[str]:
    ...

Optional[str] (or str | None in Python 3.10+) says out loud that this can return nothing, so every caller must handle that case. Without the hint, the None path is a bug waiting for production traffic. A few hints you will use constantly:

• list[str], dict[str, int], tuple[int, int] for built-in containers (Python 3.9+).
• str | None for "might be missing".
• Literal["low", "normal", "urgent"] from typing when only certain values are allowed.
• TypedDict or a dataclass for structured records instead of loose dicts. Later in the course, Pydantic models play this role for API inputs and LLM outputs.

Run a checker to see the value: pip install mypy then mypy your_file.py. It will catch, for example, passing a str where an int was promised, before any user does.

Exceptions: decide where failure is handled

An exception is a message from deep inside the program saying "I cannot do what you asked". The skill is choosing where to catch it. Catch an exception only where you can do something useful: retry, return a clear error to the user, or add context and re-raise.

import json

class ConfigError(Exception):
    """Raised when the app's configuration is missing or invalid."""

def load_config(text: str) -> dict:
    try:
        data = json.loads(text)
    except json.JSONDecodeError as e:
        # Add context, keep the original cause attached with "from e"
        raise ConfigError(f"Config is not valid JSON (line {e.lineno})") from e
    if "api_url" not in data:
        raise ConfigError("Config is missing the required key 'api_url'")
    return data

for raw in ['{"api_url": "https://example.com"}', '{"api_url": ', '{}']:
    try:
        print("loaded:", load_config(raw))
    except ConfigError as err:
        print("config problem:", err)

loaded: {'api_url': 'https://example.com'}
config problem: Config is not valid JSON (line 1)
config problem: Config is missing the required key 'api_url'

Two anti-patterns to unlearn now:

try:
    do_something()
except Exception:
    pass          # the error is gone forever, and so is your debugging afternoon

try:
    result = call_api()
except:           # bare except also catches Ctrl+C and system exit
    result = None

If you truly must catch broadly, at the very top of a request handler for instance, log the full error with logging.exception(...) so the traceback is kept.

The mutable default trap, once and for all

def add_tag(tag, tags=[]):        # the [] is created ONCE, when the function is defined
    tags.append(tag)
    return tags

print(add_tag("a"))   # ['a']
print(add_tag("b"))   # ['a', 'b']  <- surprise: shared list

def add_tag_fixed(tag: str, tags: list[str] | None = None) -> list[str]:
    tags = [] if tags is None else tags
    tags.append(tag)
    return tags

print(add_tag_fixed("a"), add_tag_fixed("b"))   # ['a'] ['b']

['a']
['a', 'b']
['a'] ['b']

Virtual environments: your dependencies, written down

Your laptop has one Python with whatever you have ever pip installed. The server has a different one. A virtual environment is a folder holding a private Python and its own packages for one project, so "works on my machine" becomes "works on any machine that follows the README".

# create and activate (macOS / Linux)
python3 -m venv .venv
source .venv/bin/activate

# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1

# install, then record exact versions
pip install fastapi uvicorn
pip freeze > requirements.txt

# anyone else, later:
pip install -r requirements.txt

Add .venv/ to .gitignore; you commit the list of dependencies, never the folder. Many teams now use uv, a much faster tool that does the same job (uv venv, uv pip install, uv add). The concept is identical, so learn the concept first.

Basic packaging: make your code importable

Once a project has more than one file, structure it so modules import each other cleanly and tests can import them too:

notes-api/
  pyproject.toml
  README.md
  src/
    notes_api/
      __init__.py
      models.py
      service.py
      main.py
  tests/
    test_service.py

A minimal pyproject.toml declares the project and its dependencies:

[project]
name = "notes-api"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["fastapi>=0.110", "uvicorn>=0.29"]

[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"

Then pip install -e . installs your own package in "editable" mode, so from notes_api.service import create_note works from tests and scripts, and edits take effect without reinstalling.

How this shows up in FDE work

On a client engagement you will often inherit a script that "mostly works": one 600-line file, globals everywhere, except: pass around the API call, no requirements file. Your first useful hour is usually to pin the dependencies in a virtual environment, split the script into named functions, and replace silent failures with explicit exceptions and logs. That turns "the agent sometimes does nothing" into a traceback that points at the real cause, and it is exactly the work this lesson trains.