Software } Engineering Fundamentals

When you install packages globally, you're playing with fire. Two projects might need different versions of the same package. World breaks, your code breaks with it.

A virtual environment creates an isolated Python installation per project. Each project gets its own set of dependencies, locked at specific versions. When you switch projects, you switch worlds entirely.

The cost of not using virtualenvs: "dependency hell," where upgrades in one project break another, and you spend hours debugging phantom issues caused by version conflicts.

# create and activate a virtual environment
python3 -m venv .venv

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

pip install fastapi httpx python-dotenv
deactivate   # leave the environment

Reproducibility means: if your colleague clones your code, they can recreate your exact setup. Without a lock file, they install packages, get different versions, and encounter bugs that never appeared on your machine.

requirements.txt or pyproject.toml defines dependencies. Lock files (poetry.lock, uv.lock) pin exact versions. Your CI/CD system uses both to build identical environments every time.

Why it matters: team collaboration without "works on my machine" excuses. Production deployments that mirror development.

# requirements.txt — simple, explicit versions
fastapi==0.115.0
httpx==0.27.2
python-dotenv==1.0.1

pip install -r requirements.txt

# or, with a modern dependency manager
poetry add fastapi httpx python-dotenv
poetry install   # reads poetry.lock, reproducible every time

Hardcode a database URL in your code, deploy to staging, oops it still points to production. Change it in code, you need a new deployment.

Environment variables separate configuration from code. Same binary runs everywhere, configured by its environment.

Real-world scenario: your API key expires. With env vars, you update one config file. Without, you hunt through codebases for hardcoded strings.

# .env
DATABASE_URL=postgresql://user:pass@localhost:5432/app
API_KEY=sk-...

# config.py
from dotenv import load_dotenv
import os

load_dotenv()
DATABASE_URL = os.getenv("DATABASE_URL")
API_KEY = os.getenv("API_KEY")

Python is dynamically typed. Variables can change types mid-execution. This flexibility becomes chaos in larger codebases.

Type hints are documentation that tools can understand. IDEs use them for autocomplete and error detection. Static type checkers find bugs before code runs.

Example of value: def get_user(id: int) -> User prevents passing a string ID from propagating bugs 10 call sites deeper.

from dataclasses import dataclass

@dataclass
class User:
    id: int
    name: str

def get_user(user_id: int) -> User:
    ...

# a type checker (mypy / pyright) catches this before runtime
get_user("123")  # error: expected int, got str

print() is debugging. Logging is production observability. Logs track what the system did, when, and why.

Structured logging (JSON or key-value) lets log aggregation tools search and alert. You can trace a slow request across 5 services by following request IDs through logs.

When you need it: system behaves differently in production. Logs show the difference.

import logging, json

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("app")

def log_event(event: str, **fields):
    logger.info(json.dumps({"event": event, **fields}))

log_event("request_completed", request_id="abc123", latency_ms=214, status=200)

Failures in distributed systems are inevitable. Networks fail. Databases timeout. Users send bad data.

Good error handling answers:

1. Did this operation fail completely?
2. Was anything else affected?
3. How should the caller respond?

Critical distinction: catch specific exceptions, not broad Exception. Broad catches hide programming errors and make debugging impossible.

import httpx

def fetch_user(user_id: int) -> dict:
    try:
        response = httpx.get(f"https://api.example.com/users/{user_id}", timeout=5)
        response.raise_for_status()
        return response.json()
    except httpx.TimeoutException:
        raise RuntimeError(f"Timed out fetching user {user_id}")
    except httpx.HTTPStatusError as e:
        raise RuntimeError(f"User {user_id} fetch failed: {e.response.status_code}")

Code organization affects how easily you can find and modify things. No structure means "I'll remember where I put that function," which never works beyond todo.txt.

Standard layouts (src/ layout vs flat layout) create mental models. New developers navigate faster. Refactoring happens with confidence.

Cognitive benefit: spend 5 minutes finding files instead of 2 hours remembering where you hid them.

An API is a contract between systems. Both sides agree: send X, receive Y. If the sender changes X without telling the receiver, the contract breaks.

REST APIs use HTTP methods and URLs to express intent. /users/123 DELETE means "delete user 123." Clear verbs prevent accidental data loss.

Why contracts matter: frontend can work while backend is being built. Third parties can depend on your service. Changes happen deliberately, not accidentally.

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.delete("/users/{user_id}")
def delete_user(user_id: int):
    if user_id not in users_db:
        raise HTTPException(status_code=404, detail="User not found")
    del users_db[user_id]
    return {"status": "deleted", "user_id": user_id}

Synchronous code waits for each operation to finish. A slow database query blocks everything.

Async code: when waiting for I/O, yield control to other tasks. Single thread handles many operations efficiently.

When it matters: 1000 concurrent API requests vs 1000 threads. Memory usage drops from gigabytes to megabytes. Response times stay low under load.

import asyncio, httpx

async def fetch(client: httpx.AsyncClient, url: str) -> dict:
    response = await client.get(url)
    return response.json()

async def fetch_all(urls: list[str]) -> list[dict]:
    async with httpx.AsyncClient() as client:
        return await asyncio.gather(*(fetch(client, u) for u in urls))

results = asyncio.run(fetch_all(urls))   # 1000 requests, one thread, low memory