Overview
Level 1: Foundations · Module 14: Python for TypeScript Engineers · 15 min read · Extended Track
Last updated: November 2026
In the JavaScript and Node.js world, dependency management is relatively unified: npm, pnpm, or bun reads a package.json file and downloads packages into a local node_modules directory.
Historically, Python package management was fragmented: global pip, ambiguous requirements.txt files, virtualenv, conda, and pipenv caused endless environment collision bugs.
In 2026, the Python ecosystem has achieved a modern breakthrough powered by uv (written in Rust by Astral, the creators of Ruff) and modern standard pyproject.toml (PEP 518/PEP 621). This lesson maps your Node.js muscle memory directly to modern, ultra-fast Python tooling.
1. Conceptual Mapping: Node.js to Modern Python
| Concept | Node.js / TypeScript | Legacy Python | Modern 2026 Python (uv) |
|---|---|---|---|
| Package Manifest | package.json | requirements.txt | pyproject.toml |
| Lockfile | package-lock.json / pnpm-lock.yaml | requirements-lock.txt | uv.lock |
| Package Installer | pnpm install / bun install | pip install -r reqs.txt | uv sync (10-100x faster than pip) |
| Add Dependency | pnpm add pydantic | pip install pydantic | uv add pydantic |
| Dev Dependency | pnpm add -D pytest | Manual separation | uv add --dev pytest |
| Isolated Environment | node_modules/ | .venv/ (manual create) | .venv/ (automatic via uv) |
| Script Runner | npx tsx script.ts | python script.py | uv run script.py (auto-installs venv) |
| Python Version Switch | nvm use 22 / .nvmrc | pyenv install 3.12 | uv python install 3.12 |
2. The Standard pyproject.toml File
Just like package.json, modern Python projects maintain all metadata, dependencies, and build settings in pyproject.toml:
[project]
name = "ai-gateway-service"
version = "0.1.0"
description = "FastAPI proxy service for LLM routing and token metering"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
"fastapi>=0.115.0",
"uvicorn[standard]>=0.32.0",
"pydantic>=2.9.0",
"anthropic>=0.39.0",
"numpy>=2.1.0",
]
[project.optional-dependencies]
dev = [
"pytest>=8.3.0",
"pytest-asyncio>=0.24.0",
"ruff>=0.7.0",
"mypy>=1.13.0",
]
[tool.ruff]
line-length = 100
target-version = "py311"
[tool.ruff.lint]
select = ["E", "F", "I", "UP"] # Syntax errors, formatting, import sorting, modern upgrades3. Essential uv Workflow Commands
# 1. Initialize a new project with pyproject.toml
uv init ai-service
cd ai-service
# 2. Add dependencies (updates pyproject.toml and generates uv.lock)
uv add fastapi "uvicorn[standard]" pydantic anthropic
# 3. Add development dependencies
uv add --dev pytest ruff mypy
# 4. Run scripts within the managed virtual environment without activating it!
uv run python -m uvicorn app.main:app --reload --port 8000
# 5. Execute linters and tests
uv run ruff check .
uv run pytest tests/4. Docker Multi-Stage Build with uv
Because uv installs packages up to 100x faster than legacy pip and includes caching, container build times drop from several minutes to under 5 seconds:
FROM python:3.12-slim-bookworm AS builder
# Install uv binary directly from official image
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
WORKDIR /app
# Enable bytecode compilation and frozen locks
ENV UV_COMPILE_BYTECODE=1
ENV UV_LINK_MODE=copy
# Install dependencies first for maximum Docker layer caching
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project --no-dev
# Copy application source code and install project
COPY . .
RUN uv sync --frozen --no-dev
# Final runtime image
FROM python:3.12-slim-bookworm
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY . .
ENV PATH="/app/.venv/bin:$PATH"
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]5. Interview Angle
Staff Engineer Question: "How do you prevent 'works on my machine' version drift across a team containing both macOS M-series laptops and Linux production CI runners?"
Principal Answer: We mandate
uv.lockcommitted to source control and pinrequires-python = ">=3.11". In CI/CD and Dockerfiles, we executeuv sync --frozen, which fails the build immediately if the dependencies inpyproject.tomldeviate from the cryptographic hashes inuv.lock. Furthermore,uvdownloads exact pre-built wheels matching the host architecture (e.g.,manylinux_x86_64vsmacosx_arm64), preventing local C-extension compilation discrepancies.