Python Patterns

Tooling opinions, concurrency decisions, async guardrails, profiling workflow, and packaging.

Style Guide

Source: Google Python Style Guide. Only rules linters/formatters cannot enforce.

Naming

• _internal prefix for module-internal names
• Avoid single-char names except counters (i, j), exceptions (e), file handles (f)
• Names describe purpose, not type: user_list not l, count not n
• Boolean variables/functions: is_, has_, can_, should_ prefix
• Avoid generic names: data, info, temp, val — be specific
• Module names: short, lowercase, no dashes — utilities not my-utils

Docstrings

• Google-style with Args:/Returns:/Raises: sections
• Every public module, function, class, and method

Practices

• No mutable default args; use None + assign inside
• No assert for validation — use raise ValueError
• Logging: % formatting not f-strings (logger.info('Val: %s', val))
• Comprehensions: simple only, no multiple for clauses
• Lambda: one-liners only, prefer named functions
• with for all file/resource handling
• Max function length ~40 lines
• No staticmethod; limit classmethod to named constructors
• Properties: only trivial computations

Tooling Defaults

ruff config opinions

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP"]

uv Workflows

# New project
uv init my-project && cd my-project
uv python pin 3.12

# Deps (updates pyproject.toml + uv.lock in one step)
uv add fastapi uvicorn
uv add --dev pytest ruff

# Run without activating venv
uv run pytest
uv run python app.py

# CI/deploy: fail if lockfile stale
uv sync --frozen

# Upgrade
uv lock --upgrade-package requests
uv lock --upgrade  # all deps

uv Key Opinions

• Always commit uv.lock -- reproducible builds
• Use uv run instead of activating venvs -- simpler, works in scripts/CI
• --frozen in CI -- fail if lockfile is stale rather than silently resolving
• Pin Python version with .python-version file
• Export for compat: uv export --format requirements-txt > requirements.txt

uv Gotchas

• uv add modifies pyproject.toml AND uv.lock in one step (unlike poetry two-step)
• uv sync creates .venv if it doesn't exist
• Cache is global (~/.cache/uv) -- shared across projects, rarely needs clearing
• uv pip install is pip-compat interface; uv add is project-level -- don't mix them

uv Docker (multi-stage)

FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-editable

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app/.venv .venv
COPY . .
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "app.py"]

uv CI Pattern

- uses: astral-sh/setup-uv@v2
  with: { enable-cache: true }
- run: uv python install 3.12
- run: uv sync --all-extras --dev
- run: uv run pytest

uv Workspace (monorepo)

[tool.uv.workspace]
members = ["packages/*"]

Project Scaffolding

• Always use src/ layout -- prevents importing uninstalled code, cleaner test isolation
• Single source of truth: pyproject.toml for everything (no setup.py, setup.cfg)
• Version: setuptools-scm for git-tag-based, or __version__ in __init__.py
• Dependency ranges: "requests>=2.28,<3" -- avoid exact pins except in lockfiles
• Type stubs: include py.typed marker for PEP 561

Project Type Selection

Concurrency Decision Framework

Async Gotchas

Blocking the loop kills performance

# WRONG - blocks event loop, all coroutines stall
async def bad():
    time.sleep(1)

# RIGHT - offload blocking work
async def good():
    await asyncio.get_event_loop().run_in_executor(None, time.sleep, 1)

gather vs TaskGroup

• asyncio.gather(*tasks, return_exceptions=True) -- fan-out, collect all results
• asyncio.TaskGroup() (3.11+) -- structured concurrency, cancels siblings on first exception
• Prefer TaskGroup for correctness; use gather when you need partial results

Semaphore for rate limiting

sem = asyncio.Semaphore(10)
async def rate_limited_fetch(url: str) -> bytes:
    async with sem:
        async with aiohttp.ClientSession() as s:
            async with s.get(url) as r:
                return await r.read()

Cancellation must be handled

async def cancelable_task():
    try:
        while True:
            await asyncio.sleep(1)
    except asyncio.CancelledError:
        # cleanup here
        raise  # re-raise to propagate

Connection pool sizing

connector = aiohttp.TCPConnector(limit=100, limit_per_host=10)
async with aiohttp.ClientSession(connector=connector) as session:
    ...

Profiling Strategy

Profiling workflow

1. Measure first -- never optimize without a profile
2. cProfile to find hot functions (sort by cumtime)
3. line_profiler on the hot function to find hot lines
4. Fix algorithmic issues before micro-optimizations
5. Re-profile to verify improvement

tracemalloc for leak detection

tracemalloc.start()
snap1 = tracemalloc.take_snapshot()
# ... run suspect code ...
snap2 = tracemalloc.take_snapshot()
for stat in snap2.compare_to(snap1, 'lineno')[:10]:
    print(stat)

Performance Patterns

Caching decisions

Gotcha: @lru_cache requires hashable args -- use tuple not dict.

slots for many instances

class Point:
    __slots__ = ['x', 'y']
    def __init__(self, x, y):
        self.x = x
        self.y = y
# ~40% less memory per instance vs regular class

Batch I/O operations

# SLOW: commit per insert
for item in items:
    cursor.execute("INSERT ...", item)
    conn.commit()

# FAST: single commit
cursor.executemany("INSERT ...", items)
conn.commit()

Packaging

• Build backend: hatchling for libraries, setuptools for apps that don't publish
• Entry points: [project.scripts] for CLIs, [project.entry-points] for plugins

Publishing workflow

uv pip install build twine
python -m build
twine check dist/*
twine upload --repository testpypi dist/*  # test first
twine upload dist/*