feat: initial commit

Author: adriencaccia

.github/workflows/codspeed.yml

@@ -0,0 +1,67 @@
+name: CodSpeed
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  benchmarks:
+    name: Run benchmarks
+    runs-on: codspeed-macro
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.15.0-beta.1
+          architecture: arm64-freethreaded
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Hash the dataset seed
+        # Mix a hash of the secret seed into the cache key so changing the
+        # seed invalidates the cache, without exposing the seed itself
+        # (cache keys are visible in the Actions UI).
+        id: seed-hash
+        env:
+          DATASET_SEED: ${{ secrets.DATASET_SEED }}
+        run: |
+          hash=$(printf '%s' "$DATASET_SEED" | shasum -a 256 | head -c 16)
+          echo "value=$hash" >> "$GITHUB_OUTPUT"
+
+      - name: Cache datasets
+        id: cache-datasets
+        uses: actions/cache@v4
+        with:
+          path: |
+            rounds/1_histogram/data
+            rounds/2_corruption/data
+            rounds/3_dna/data
+          key: datasets-${{ hashFiles('rounds/*/gen_data.py', 'scripts/setup.py') }}-${{ steps.seed-hash.outputs.value }}
+
+      - name: Generate datasets
+        if: steps.cache-datasets.outputs.cache-hit != 'true'
+        env:
+          DATASET_SEED: ${{ secrets.DATASET_SEED }}
+        run: uv run scripts/setup.py ${DATASET_SEED:+--seed "$DATASET_SEED"}
+
+      - name: Run correctness tests
+        run: uv run pytest -k "not test_bench"
+
+      - name: Run benchmarks
+        uses: CodSpeedHQ/action@v4
+        with:
+          mode: walltime
+          run: uv run pytest --codspeed

.gitignore

@@ -0,0 +1,16 @@
+CFP.md
+
+# Workshop datasets — generated locally via scripts/setup.py
+rounds/*/data/
+
+# Instructor-only reference implementations
+solutions/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+
+# CodSpeed
+.codspeed/

.python-version

@@ -0,0 +1 @@
+3.15t

README.md

@@ -0,0 +1,82 @@
+# Python Performance Lab: Sharpening Your Instincts
+
+A PyCon US 2026 hands-on tutorial. You optimize intentionally slow Python code
+across three rounds plus a team challenge, measuring every change with
+[CodSpeed](https://codspeed.io).
+
+## Rounds
+
+| Round                      | Topic                | Skills                                |
+| -------------------------- | -------------------- | ------------------------------------- |
+| [1](rounds/1_histogram/)   | Byte-pair histogram  | Data representation, vectorization    |
+| [2](rounds/2_corruption/)  | Corruption scanner   | Vectorization, parallelism            |
+| [3](rounds/3_dna/) (final) | DNA sequence matcher | Everything above, as a team challenge |
+
+Each round ships an intentionally slow `baseline.py` (a read-only reference),
+a `solution.py` you edit, deterministic data generators, parametrized
+correctness tests, and benchmarks that run baseline and solution
+side-by-side.
+
+## Setup
+
+You need [`uv`](https://docs.astral.sh/uv/). Python 3.15t will be downloaded directly.
+
+The order below matters: forking, logging in, and doing the first run on `main`
+register you on the live leaderboard, so every later push to your branch shows
+up as a side-by-side comparison against your own baseline.
+
+```bash
+# 1. Fork github.com/CodSpeedHQ/pyconus-2026-tutorial, then clone your fork.
+git clone https://github.com/<you>/pyconus-2026-tutorial && cd pyconus-2026-tutorial
+
+# 2. Install deps + generate the datasets (~650 MB total).
+uv sync
+uv run scripts/setup.py
+
+# 3. Install the CodSpeed CLI and log in.
+curl -L https://codspeed.io/install.sh | sh
+codspeed auth login
+
+# 4. Branch off. Every push to this branch re-runs and re-ranks you.
+git checkout -b <your-name>
+```
+
+Generate smaller datasets on lower-spec machines:
+
+```bash
+uv run scripts/setup.py --round1-mb 10 --round2-mb 32 --round3-mb 100
+```
+
+## Working on a round
+
+Every round directory ships its own `README.md`. The commands are the same
+shape every time, illustrated here for Round 1:
+
+```bash
+# Correctness tests against the small fixture.
+uv run pytest rounds/1_histogram/
+
+# Walltime benchmark against the full dataset.
+uv run pytest --codspeed rounds/1_histogram/
+
+# Same, run through the CodSpeed CLI with the walltime mode
+codspeed run --mode walltime -- uv run pytest --codspeed rounds/1_histogram/
+```
+
+Edit `solution.py` to optimize. Leave `baseline.py` alone so the side-by-side
+comparison stays meaningful. Every test and benchmark is parametrized over
+both implementations, so the output always shows `[baseline]` versus
+`[solution]`.
+
+## Layout
+
+```
+rounds/
+  1_histogram/             # baseline.py, solution.py, gen_data.py, tests.
+  2_corruption/
+  3_dna/
+scripts/
+  setup.py                 # one-shot data generation across every round.
+```
+
+Each round's `data/` directory is generated locally and gitignored.

pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "pyconus-2026-tutorial"
+version = "0.1.0"
+description = "Python Performance Lab: Sharpening Your Instincts — PyCon US 2026 tutorial"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = ["numpy>=2.0"]
+
+[dependency-groups]
+dev = ["pytest>=8.0", "pytest-codspeed>=5.0.1"]
+
+[tool.pytest.ini_options]
+testpaths = ["rounds"]
+# importlib avoids module-name collisions across the round directories
+# (every round has its own baseline.py).
+addopts = "--import-mode=importlib"

rounds/1_histogram/README.md

@@ -0,0 +1,56 @@
+# Round 1: Byte-pair histogram
+
+## Problem
+
+Given a binary payload of up to a few hundred megabytes, count the frequency
+of every **2-byte bigram**. The output is a mapping from each observed bigram
+to its occurrence count.
+
+A **bigram** is a sliding window of two adjacent bytes. For the payload
+`b"ABCD"` the bigrams are `b"AB"`, `b"BC"`, and `b"CD"`. An `N`-byte payload
+therefore contains `N - 1` bigrams. With 256 possible byte values each, the
+full universe is `256 * 256 = 65,536` distinct tokens.
+
+- Input: `data/payload.bin` (default 10 MB, biased byte distribution).
+- Output: a `dict` (or equivalent) keyed by 2-byte token, mapped to an `int` count.
+- Universe: up to 65,536 distinct bigrams.
+
+## Files
+
+| File                | Purpose                                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `baseline.py`       | Intentionally slow starting point. **Don't edit:** it is the reference for the comparison.                                |
+| `solution.py`       | **Edit this.** Starts out delegating to `baseline.py`; replace with your faster implementation.                           |
+| `gen_data.py`       | Generates `data/payload.bin` and `data/fixture/payload.bin`.                                                              |
+| `test_histogram.py` | Correctness tests and the pytest-codspeed benchmark. Every test is parametrized over both the baseline and your solution. |
+
+## Generate the data
+
+```bash
+uv run rounds/1_histogram/gen_data.py            # default 10 MB.
+uv run rounds/1_histogram/gen_data.py --size-mb 50
+```
+
+Or run `uv run scripts/setup.py` to generate every round's data in
+one go.
+
+## Verify correctness
+
+```bash
+uv run pytest rounds/1_histogram/
+```
+
+## Benchmark
+
+Walltime, locally:
+
+```bash
+uv run pytest --codspeed rounds/1_histogram/
+```
+
+Same benchmarks, run through the CodSpeed CLI for low-noise instrumented
+measurements:
+
+```bash
+codspeed run --mode walltime -- uv run pytest --codspeed rounds/1_histogram/
+```

rounds/1_histogram/__init__.py

@@ -0,0 +1,24 @@
+"""Round 1 baseline: byte-pair histogram.
+
+Counts the frequency of every 2-byte bigram (256 * 256 = 65,536 possible
+tokens) in a binary payload.
+"""
+
+
+def compute_histogram(path: str) -> dict[bytes, int]:
+    """Frequency of every 2-byte bigram in the file at ``path``."""
+    # Step 1: read the whole file into memory as a single bytes object.
+    with open(path, "rb") as f:
+        data = f.read()
+
+    # Step 2: slide a 2-byte window across the buffer. For ``b"ABCD"`` the
+    # iterations produce ``b"AB"``, ``b"BC"``, then ``b"CD"``. For each window,
+    # bump the matching bucket in a ``dict`` keyed by the bigram itself.
+    counts: dict[bytes, int] = {}
+    for i in range(len(data) - 1):
+        bigram = data[i : i + 2]
+        if bigram in counts:
+            counts[bigram] += 1
+        else:
+            counts[bigram] = 1
+    return counts

rounds/1_histogram/baseline.py

@@ -0,0 +1,82 @@
+"""Generate the Round 1 dataset: a binary payload with biased byte frequencies.
+
+Run from anywhere:
+
+    uv run rounds/1_histogram/gen_data.py            # default 10 MB
+    uv run rounds/1_histogram/gen_data.py --size-mb 50
+
+Output:
+    rounds/1_histogram/data/payload.bin           — full benchmark dataset
+    rounds/1_histogram/data/fixture_payload.bin   — tiny fixture for tests
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import random
+from pathlib import Path
+
+DATA_DIR = Path(__file__).parent / "data"
+
+FIXTURE_SIZE_BYTES = 64 * 1024  # 64 KB fixture — fast, deterministic
+
+
+def _biased_alphabet() -> bytes:
+    """Skew byte frequencies so the histogram is non-trivial.
+
+    A flat-random payload makes every bucket land near the mean, which hides
+    bugs in attendee implementations. We instead bias toward a smaller alphabet
+    with realistic-looking long tails.
+    """
+    common = b"ETAOINSHRDLU "  # frequent ASCII letters + space
+    medium = b"abcdefghijklmnopqrstuvwxyz0123456789\n"
+    rare = bytes(range(256))
+    return common * 40 + medium * 8 + rare
+
+
+def _write_payload(path: Path, size_bytes: int, seed: int) -> None:
+    rng = random.Random(seed)
+    alphabet = _biased_alphabet()
+    chunk_size = 1 << 20  # 1 MB at a time keeps peak memory low
+    remaining = size_bytes
+    with path.open("wb") as f:
+        while remaining > 0:
+            n = min(chunk_size, remaining)
+            f.write(bytes(rng.choices(alphabet, k=n)))
+            remaining -= n
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--size-mb",
+        type=int,
+        default=10,
+        help="Size of the full benchmark payload in MB (default: 10).",
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=42,
+        help="Random seed for deterministic output (default: 42).",
+    )
+    args = parser.parse_args()
+
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+    full_path = DATA_DIR / "payload.bin"
+    fixture_path = DATA_DIR / "fixture_payload.bin"
+
+    print(f"writing fixture: {fixture_path} ({FIXTURE_SIZE_BYTES} bytes)")
+    _write_payload(fixture_path, FIXTURE_SIZE_BYTES, seed=args.seed + 1)
+
+    full_size = args.size_mb * 1024 * 1024
+    print(f"writing payload: {full_path} ({args.size_mb} MB)")
+    _write_payload(full_path, full_size, seed=args.seed)
+
+    print(f"done. total on disk: {os.path.getsize(full_path) + os.path.getsize(fixture_path):,} bytes")
+
+
+if __name__ == "__main__":
+    main()

rounds/1_histogram/gen_data.py

@@ -0,0 +1,14 @@
+"""Your Round 1 solution — byte-pair histogram.
+
+**Edit this file.** It currently delegates to ``baseline.py`` so everything
+passes out of the box. Replace the body of ``compute_histogram`` with your
+own faster implementation.
+"""
+
+
+def compute_histogram(path: str) -> dict[bytes, int]:
+    """Frequency of every 2-byte bigram in the file at ``path``."""
+    # TODO: remove this delegation and write your own implementation here.
+    from .baseline import compute_histogram as _baseline
+
+    return _baseline(path)