modern-python-guidance 0.3.4__tar.gz → 0.3.6__tar.gz

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/.github/workflows/ci.yml

@@ -30,8 +30,11 @@ jobs:
       - name: Install dependencies
         run: uv pip install --system -e ".[dev]"
 
-      - name: Run tests
-        run: pytest --tb=short -q
+      - name: Check formatting
+        run: ruff format --check src/ tests/
 
       - name: Run linter
         run: ruff check src/ tests/
+
+      - name: Run tests
+        run: pytest --tb=short -q --cov --cov-report=term-missing

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.6] — 2026-05-31
+
+### Added
+
+- Rule-based delivery via symlink: `mpg setup` creates `.claude/rules/modern-python.md` that auto-injects modern Python guidance whenever Python-related files are touched, replacing reliance on probabilistic skill matching (closes #79)
+- `setup_rules()` / `uninstall_rules()` mirroring skills symlink pattern
+- `source.is_symlink()` security check to refuse symlink-to-symlink chains
+- CI sync test enforcing SKILL.md body == rule body consistency
+- 21 new tests (V-037 to V-060) for setup, uninstall, CI sync, and security
+
+### Changed
+
+- `--skills-only` now includes Rules (both are project-local artifacts)
+- README updated to document 4 delivery methods (was 3)
+- `--project-dir` help text updated to mention Skills/Rules symlinks
+
+## [0.3.5] — 2026-05-30
+
+### Added
+
+- CI format gate: `ruff format --check src/ tests/` runs before linter, catching formatting regressions at PR time (closes #19)
+- Coverage reporting: `pytest-cov` with branch coverage and `fail_under = 59%` ratchet threshold (closes #15)
+- Guide structure validation: 248 parametrized tests validating all 41 guides — frontmatter fields, section order, code fences, H1 title, no duplicate IDs (closes #16)
+- CONTRIBUTING.md: documented CI checks, format fix command, and guide count update step
+
+### Changed
+
+- Auto-formatted 12 existing source/test files with `ruff format` (whitespace only, no logic changes)
+- CI step order: checkout → setup → install → **format check** → linter → tests (with `--cov`)
+
 ## [0.3.4] — 2026-05-30
 
 ### Fixed

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/CONTRIBUTING.md

@@ -37,13 +37,25 @@ See [docs/design.md](docs/design.md) for the full design document.
 | `frequency` | string | `high` (LLMs do this often), `medium`, `low` |
 
 3. Write BAD/GOOD/Why/Version Notes sections
-4. Run `pytest` to verify the guide parses correctly
+4. Update `EXPECTED_GUIDE_COUNT` in `tests/test_guide_structure.py`
+5. Run `pytest` — the guide structure tests validate frontmatter, section order, and code fences automatically
 
 ## Running tests
 
 ```bash
 uv venv && source .venv/bin/activate
 uv pip install -e ".[dev]"
-pytest
-ruff check src/ tests/
+pytest                              # 510+ tests including guide structure validation
+ruff check src/ tests/              # lint
+ruff format --check src/ tests/     # format check (CI enforced)
 ```
+
+To auto-fix formatting: `ruff format src/ tests/`
+
+## CI checks
+
+All PRs run these checks on Python 3.11, 3.12, and 3.13:
+
+1. `ruff format --check` — formatting
+2. `ruff check` — linting
+3. `pytest --cov` — tests with branch coverage (`fail_under = 59%`)

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.3.4
+Version: 0.3.6
 Summary: Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python
 Project-URL: Homepage, https://github.com/yottayoshida/modern-python-guidance
 Project-URL: Repository, https://github.com/yottayoshida/modern-python-guidance
@@ -25,6 +25,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: packaging>=23.0
 Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.4.0; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -43,7 +44,7 @@ Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 41 versio
 - **Measurable impact**: AI writes modern Python 98% of the time with mpg, vs 79% without — even with vague prompts (Opus 4.8, [V5 benchmark details](docs/benchmark-v5.md))
 - **41 guides** across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
 - **Version-aware**: auto-detects your project's Python version and filters guides accordingly
-- **3 delivery methods**: MCP server, CLI, Agent Skills plugin
+- **4 delivery methods**: MCP server, CLI, Agent Skills, and Rules (auto-injects on `.py` file touch)
 - **Not Ruff**: Ruff auto-fixes syntax (`List` → `list`). mpg guides design decisions that Ruff can't touch — `TaskGroup` over `gather`, Pydantic V2 migration, SQLAlchemy 2.0 style
 
 > **Note:** The tool itself requires Python 3.11+ to run. Guides cover patterns from Python 3.9 onward, and `--python-version` filters guides for your target environment.
@@ -57,7 +58,7 @@ pip install modern-python-guidance
 mpg setup
 ```
 
-This registers the MCP server and links Agent Skills in one command. Start a new Claude Code session afterwards — newly registered MCP servers and skills take effect on the next launch.
+This registers the MCP server, links Agent Skills, and creates a Rules file (`.claude/rules/modern-python.md`) in one command. The Rules file auto-injects modern Python guidance whenever you touch Python-related files. Start a new Claude Code session afterwards — newly registered MCP servers, skills, and rules take effect on the next launch.
 
 ### CLI
 
@@ -89,7 +90,7 @@ claude mcp add mpg -- mpg mcp
 }
 ```
 
-**Agent Skills symlink (Claude Code):**
+**Agent Skills + Rules only (Claude Code):**
 ```bash
 mpg setup --skills-only
 ```
@@ -98,25 +99,25 @@ mpg setup --skills-only
 | Flag | Purpose |
 |------|---------|
 | `--mcp-only` | MCP registration only |
-| `--skills-only` | Agent Skills symlink only |
+| `--skills-only` | Project-local artifacts only (Skills + Rules) |
 | `--scope {user,local}` | MCP scope (default: user) |
-| `--project-dir PATH` | Target project for Skills symlink |
+| `--project-dir PATH` | Target project for Skills/Rules symlinks |
 | `--dry-run` | Show what would be done |
 
-**Uninstall** — reverse `mpg setup` (deregister the MCP server and unlink Agent Skills):
+**Uninstall** — reverse `mpg setup` (deregister the MCP server and unlink Agent Skills + Rules):
 ```bash
-mpg uninstall            # remove both
+mpg uninstall            # remove all
 mpg uninstall --dry-run  # preview what would be removed
 ```
 
 | Flag | Purpose |
 |------|---------|
 | `--mcp-only` | MCP deregistration only |
-| `--skills-only` | Agent Skills unlink only |
-| `--project-dir PATH` | Target project for the Skills symlink |
+| `--skills-only` | Project-local artifacts only (Skills + Rules) |
+| `--project-dir PATH` | Target project for Skills/Rules symlinks |
 | `--dry-run` | Show what would be done |
 
-`mpg uninstall` clears the MCP registration from every scope `setup` can write to (user and local), removes only the symlink mpg created (never its target or other skills), and is idempotent — running it on an already-clean state is a harmless no-op.
+`mpg uninstall` clears the MCP registration from every scope `setup` can write to (user and local), removes only the symlinks mpg created (never their targets or other files), and is idempotent — running it on an already-clean state is a harmless no-op.
 
 </details>
 

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/README.md

@@ -12,7 +12,7 @@ Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 41 versio
 - **Measurable impact**: AI writes modern Python 98% of the time with mpg, vs 79% without — even with vague prompts (Opus 4.8, [V5 benchmark details](docs/benchmark-v5.md))
 - **41 guides** across stdlib, Pydantic, FastAPI, Django, SQLAlchemy, pytest, and toolchain
 - **Version-aware**: auto-detects your project's Python version and filters guides accordingly
-- **3 delivery methods**: MCP server, CLI, Agent Skills plugin
+- **4 delivery methods**: MCP server, CLI, Agent Skills, and Rules (auto-injects on `.py` file touch)
 - **Not Ruff**: Ruff auto-fixes syntax (`List` → `list`). mpg guides design decisions that Ruff can't touch — `TaskGroup` over `gather`, Pydantic V2 migration, SQLAlchemy 2.0 style
 
 > **Note:** The tool itself requires Python 3.11+ to run. Guides cover patterns from Python 3.9 onward, and `--python-version` filters guides for your target environment.
@@ -26,7 +26,7 @@ pip install modern-python-guidance
 mpg setup
 ```
 
-This registers the MCP server and links Agent Skills in one command. Start a new Claude Code session afterwards — newly registered MCP servers and skills take effect on the next launch.
+This registers the MCP server, links Agent Skills, and creates a Rules file (`.claude/rules/modern-python.md`) in one command. The Rules file auto-injects modern Python guidance whenever you touch Python-related files. Start a new Claude Code session afterwards — newly registered MCP servers, skills, and rules take effect on the next launch.
 
 ### CLI
 
@@ -58,7 +58,7 @@ claude mcp add mpg -- mpg mcp
 }
 ```
 
-**Agent Skills symlink (Claude Code):**
+**Agent Skills + Rules only (Claude Code):**
 ```bash
 mpg setup --skills-only
 ```
@@ -67,25 +67,25 @@ mpg setup --skills-only
 | Flag | Purpose |
 |------|---------|
 | `--mcp-only` | MCP registration only |
-| `--skills-only` | Agent Skills symlink only |
+| `--skills-only` | Project-local artifacts only (Skills + Rules) |
 | `--scope {user,local}` | MCP scope (default: user) |
-| `--project-dir PATH` | Target project for Skills symlink |
+| `--project-dir PATH` | Target project for Skills/Rules symlinks |
 | `--dry-run` | Show what would be done |
 
-**Uninstall** — reverse `mpg setup` (deregister the MCP server and unlink Agent Skills):
+**Uninstall** — reverse `mpg setup` (deregister the MCP server and unlink Agent Skills + Rules):
 ```bash
-mpg uninstall            # remove both
+mpg uninstall            # remove all
 mpg uninstall --dry-run  # preview what would be removed
 ```
 
 | Flag | Purpose |
 |------|---------|
 | `--mcp-only` | MCP deregistration only |
-| `--skills-only` | Agent Skills unlink only |
-| `--project-dir PATH` | Target project for the Skills symlink |
+| `--skills-only` | Project-local artifacts only (Skills + Rules) |
+| `--project-dir PATH` | Target project for Skills/Rules symlinks |
 | `--dry-run` | Show what would be done |
 
-`mpg uninstall` clears the MCP registration from every scope `setup` can write to (user and local), removes only the symlink mpg created (never its target or other skills), and is idempotent — running it on an already-clean state is a harmless no-op.
+`mpg uninstall` clears the MCP registration from every scope `setup` can write to (user and local), removes only the symlinks mpg created (never their targets or other files), and is idempotent — running it on an already-clean state is a harmless no-op.
 
 </details>
 

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/bench/score_v5.py

@@ -1476,14 +1476,17 @@ def main() -> None:
         "c": "C (pytest)",
     }
     v_label = variant_labels.get(args.variant, args.variant)
-    print(f"=== V5 Scoring: Variant {v_label}, Run {args.run_id} ===")
-    print()
+
+    if args.output_format == "human":
+        print(f"=== V5 Scoring: Variant {v_label}, Run {args.run_id} ===")
+        print()
 
     output = {}
     for session_name in ("control", "treatment"):
         session_dir = results_dir / session_name
         if not session_dir.is_dir():
-            print(f"  [{session_name}] Directory not found, skipping.")
+            if args.output_format == "human":
+                print(f"  [{session_name}] Directory not found, skipping.")
             continue
         data = score_session(session_dir, args.variant)
         output[session_name] = data

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.3.4"
+version = "0.3.6"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
 license = "Apache-2.0 OR MIT"
@@ -34,6 +34,7 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",
+    "pytest-cov>=4.0",
     "ruff>=0.4.0",
 ]
 
@@ -48,11 +49,12 @@ Issues = "https://github.com/yottayoshida/modern-python-guidance/issues"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/modern_python_guidance"]
-only-include = ["src/modern_python_guidance", "skills"]
+only-include = ["src/modern_python_guidance", "skills", "rules"]
 
 [tool.hatch.build.targets.wheel.sources]
 "src" = ""
 "skills" = "modern_python_guidance/skills"
+"rules" = "modern_python_guidance/rules"
 
 [tool.ruff]
 target-version = "py311"
@@ -66,3 +68,17 @@ select = ["E", "F", "W", "I", "UP", "FURB", "B", "SIM", "RUF"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["modern_python_guidance"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+fail_under = 59
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.",
+    "if TYPE_CHECKING:",
+]

modern_python_guidance-0.3.6/rules/modern-python.md

@@ -0,0 +1,70 @@
+---
+paths: ["**/*.py", "*.py", "**/pyproject.toml", "**/requirements*.txt", "**/setup.py", "**/setup.cfg", "**/.python-version", "**/Pipfile"]
+---
+
+# Modern Python Guidance
+
+Pre-generation design patterns that Ruff cannot auto-fix. Apply these transformations when writing or reviewing Python code.
+
+## When to use
+
+- Writing new Python code (use modern patterns from the start)
+- Reviewing Python code (flag outdated patterns)
+- Migrating from Pydantic V1 to V2
+- Upgrading Python version (check which new features are available)
+- Replacing legacy tooling (setup.py, flake8, pip)
+
+## Embedded patterns (high-frequency, Ruff-uncovered)
+
+### Pydantic V2 (>=3.9)
+
+- `@validator("f")` → `@field_validator("f")`
+- `@root_validator` → `@model_validator(mode="after")`
+- `class Config:` → `model_config = ConfigDict(...)`
+- `orm_mode` → `from_attributes`, `allow_population_by_field_name` → `populate_by_name`
+- `.parse_obj(d)` → `.model_validate(d)`, `.parse_raw(j)` → `.model_validate_json(j)`
+- `.dict()` → `.model_dump()`, `.json()` → `.model_dump_json()`
+- `.schema()` → `.model_json_schema()`, `.copy()` → `.model_copy()`
+
+### FastAPI (>=3.9)
+
+- `@app.on_event("startup")`/`"shutdown"` → `@asynccontextmanager` lifespan + `FastAPI(lifespan=lifespan)`; yield dict becomes `request.state`
+- `db: Session = Depends(get_db)` → `DbDep = Annotated[Session, Depends(get_db)]`; reusable type alias per PEP 593
+
+### httpx
+
+- Per-request `async with httpx.AsyncClient()` → shared `AsyncClient` with `base_url`
+  - Caveat: shared client must be closed via `async with` or lifespan management
+
+### asyncio (>=3.11)
+
+- `await asyncio.gather(a(), b())` → `async with asyncio.TaskGroup() as tg:` + `tg.create_task()`; access results via `task.result()`
+  - Caveat: 3.11+ only. `TaskGroup` cancels siblings on error and raises `ExceptionGroup`; `gather` preserves return order and supports `return_exceptions=True`
+
+### SQLAlchemy 2.0 (>=3.9)
+
+- `session.query(User).filter()` → `session.execute(select(User).where())`; use `session.scalars()` for ORM results
+- `Column(Integer)` → `Mapped[int] = mapped_column()`; type inferred from annotation, nullability from `Optional`/`| None`
+- Sync `Session` with `asyncio.to_thread` → `AsyncSession` + `create_async_engine` + `async_sessionmaker`
+
+### Toolchain
+
+- `setup.py` / `setup.cfg` → `pyproject.toml` with `[build-system]` + `[project]` (PEP 621)
+- `subprocess.run(f"cmd {arg}", shell=True)` → `subprocess.run(["cmd", arg], check=True)`
+  - Caveat: `shell=True` is valid when pipes/globs are needed; use `shlex.quote()` for user input
+
+## All 41 guides by category
+
+- **typing** (7): `use-builtin-generics`, `union-syntax`, `type-parameter-syntax`, `override-decorator`, `typeis-vs-typeguard`, `paramspec-decorators`, `deferred-annotations`
+- **async** (3): `taskgroup-over-gather`, `exception-groups`, `async-timeout-context`
+- **stdlib** (5): `datetime-utc`, `pathlib-over-os-path`, `tomllib-builtin`, `removeprefix-removesuffix`, `template-strings`
+- **data-structures** (3): `dict-merge-operator`, `match-case-patterns`, `dataclass-modern`
+- **pydantic** (4): `pydantic-v2-validators`, `pydantic-v2-config`, `pydantic-v2-model-api`, `pydantic-v2-serialization`
+- **fastapi** (3): `fastapi-lifespan`, `fastapi-annotated-depends`, `fastapi-typed-state`
+- **httpx** (2): `httpx-async-client-reuse`, `httpx-streaming`
+- **django** (3): `django-json-field`, `django-async-views`, `django-check-constraints`
+- **sqlalchemy** (3): `sqlalchemy-2-style`, `sqlalchemy-mapped-column`, `sqlalchemy-async-session`
+- **pytest** (3): `pytest-parametrize`, `pytest-tmp-path`, `pytest-raises-match`
+- **toolchain** (5): `pyproject-toml-over-setup`, `uv-over-pip`, `ruff-over-flake8`, `no-pickle`, `safe-subprocess`
+
+For full code examples, use `mpg retrieve <guide-id>` or MCP tool `retrieve_guides`.

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/src/modern_python_guidance/__init__.py

@@ -1,3 +1,3 @@
 """Modern Python Guidance — version-aware BAD/GOOD pattern guides for AI coding agents."""
 
-__version__ = "0.3.4"
+__version__ = "0.3.6"

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/src/modern_python_guidance/cli.py

@@ -36,7 +36,9 @@ def main(argv: list[str] | None = None) -> None:
     p_search.add_argument("--category", help="Filter by category")
     p_search.add_argument("--limit", type=int, default=10, help="Max results (default: 10)")
     p_search.add_argument(
-        "--format", choices=["json", "human"], default=None,
+        "--format",
+        choices=["json", "human"],
+        default=None,
         help="Output format (default: json when piped, human when TTY)",
     )
 
@@ -45,7 +47,9 @@ def main(argv: list[str] | None = None) -> None:
     p_retrieve.add_argument("ids", help="Comma-separated guide IDs")
     p_retrieve.add_argument("--python-version", help="Target Python version")
     p_retrieve.add_argument(
-        "--format", choices=["json", "human"], default=None,
+        "--format",
+        choices=["json", "human"],
+        default=None,
         help="Output format (default: json when piped, human when TTY)",
     )
 
@@ -54,7 +58,9 @@ def main(argv: list[str] | None = None) -> None:
     p_list.add_argument("--category", help="Filter by category")
     p_list.add_argument("--python-version", help="Filter by Python version")
     p_list.add_argument(
-        "--format", choices=["json", "human"], default=None,
+        "--format",
+        choices=["json", "human"],
+        default=None,
         help="Output format (default: json when piped, human when TTY)",
     )
 
@@ -67,27 +73,41 @@ def main(argv: list[str] | None = None) -> None:
 
     # setup
     p_setup = subparsers.add_parser(
-        "setup", help="Register MCP server and link Agent Skills",
+        "setup",
+        help="Register MCP server and link Agent Skills + Rules",
     )
     p_setup.add_argument("--mcp-only", action="store_true", help="MCP registration only")
-    p_setup.add_argument("--skills-only", action="store_true", help="Skills symlink only")
     p_setup.add_argument(
-        "--scope", choices=["user", "local"], default="user",
+        "--skills-only", action="store_true", help="Project-local artifacts only (Skills + Rules)"
+    )
+    p_setup.add_argument(
+        "--scope",
+        choices=["user", "local"],
+        default="user",
         help="MCP scope (default: user)",
     )
     p_setup.add_argument(
-        "--project-dir", type=Path, help="Project directory for Skills symlink",
+        "--project-dir",
+        type=Path,
+        help="Project directory for Skills/Rules symlinks",
     )
     p_setup.add_argument("--dry-run", action="store_true", help="Show what would be done")
 
     # uninstall
     p_uninstall = subparsers.add_parser(
-        "uninstall", help="Reverse 'setup': deregister MCP server and unlink Agent Skills",
+        "uninstall",
+        help="Reverse 'setup': deregister MCP server and unlink Agent Skills + Rules",
     )
     p_uninstall.add_argument("--mcp-only", action="store_true", help="MCP deregistration only")
-    p_uninstall.add_argument("--skills-only", action="store_true", help="Skills unlink only")
     p_uninstall.add_argument(
-        "--project-dir", type=Path, help="Project directory for Skills symlink",
+        "--skills-only",
+        action="store_true",
+        help="Project-local artifacts only (Skills + Rules)",
+    )
+    p_uninstall.add_argument(
+        "--project-dir",
+        type=Path,
+        help="Project directory for Skills/Rules symlinks",
     )
     p_uninstall.add_argument("--dry-run", action="store_true", help="Show what would be done")
 

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/src/modern_python_guidance/frontmatter.py

@@ -75,9 +75,7 @@ def _parse_raw(lines: list[str]) -> dict[str, Any]:
             if current_key is None:
                 raise FrontmatterError("list item without preceding key", line=i)
             if not isinstance(data[current_key], list):
-                raise FrontmatterError(
-                    f"list item for non-list key '{current_key}'", line=i
-                )
+                raise FrontmatterError(f"list item for non-list key '{current_key}'", line=i)
             data[current_key].append(_parse_scalar(list_match.group(1).strip()))
             continue
 

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/src/modern_python_guidance/mcp_server.py

@@ -340,11 +340,14 @@ def _handle_request(msg: dict) -> dict | None:
         return None
 
     if method == "initialize":
-        result = _result_response(req_id, {
-            "protocolVersion": PROTOCOL_VERSION,
-            "capabilities": {"tools": {}},
-            "serverInfo": {"name": "modern-python-guidance", "version": __version__},
-        })
+        result = _result_response(
+            req_id,
+            {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "modern-python-guidance", "version": __version__},
+            },
+        )
         return None if is_notification else result
 
     if method == "tools/list":

{modern_python_guidance-0.3.4 → modern_python_guidance-0.3.6}/src/modern_python_guidance/search.py

@@ -60,19 +60,25 @@ def search(
 
         if score > 0:
             score += FREQ_BOOST.get(meta.frequency, 0.0)
-            results.append(SearchResult(
-                guide_id=guide_id,
-                score=score,
-                meta=meta,
-                token_estimate=token_estimate(guide.body),
-                snippet=guide.snippet,
-            ))
+            results.append(
+                SearchResult(
+                    guide_id=guide_id,
+                    score=score,
+                    meta=meta,
+                    token_estimate=token_estimate(guide.body),
+                    snippet=guide.snippet,
+                )
+            )
 
     results.sort(key=lambda r: (-r.score, r.guide_id))
 
     if not results:
         return _fuzzy_fallback(
-            index, query, python_version=python_version, category=category, limit=limit,
+            index,
+            query,
+            python_version=python_version,
+            category=category,
+            limit=limit,
         )
 
     return results[:limit]
@@ -139,14 +145,16 @@ def _fuzzy_fallback(
                 continue
             seen.add(guide_id)
             guide = candidates[guide_id]
-            results.append(SearchResult(
-                guide_id=guide_id,
-                score=round(ratio, 3),
-                meta=guide.meta,
-                token_estimate=token_estimate(guide.body),
-                fuzzy=True,
-                snippet=guide.snippet,
-            ))
+            results.append(
+                SearchResult(
+                    guide_id=guide_id,
+                    score=round(ratio, 3),
+                    meta=guide.meta,
+                    token_estimate=token_estimate(guide.body),
+                    fuzzy=True,
+                    snippet=guide.snippet,
+                )
+            )
 
     results.sort(key=lambda r: (-r.score, r.guide_id))
-    return results[:min(limit, FUZZY_MAX)]
+    return results[: min(limit, FUZZY_MAX)]