modern-python-guidance 0.2.1__tar.gz → 0.2.3__tar.gz

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.3] — 2026-05-28
+
+### Fixed
+
+- `fastapi-typed-state` guide: added missing Version Notes section (closes #13)
+- `fastapi-typed-state` and `fastapi-lifespan` guides: corrected minimum version from FastAPI >= 0.93.0 to >= 0.94.0 (lifespan state dict requires Starlette >= 0.26.0, which FastAPI 0.93.0 excludes)
+
+## [0.2.2] — 2026-05-28
+
+### Changed
+
+- Search response (MCP + CLI) now includes `tags`, `python`, `frequency`, and `snippet` fields for richer agent decision-making without requiring a follow-up retrieve call
+- `dataclass-modern` guide rewritten: BAD/GOOD examples now center on immutable value objects (`frozen=True, slots=True, kw_only=True`), with decision criteria for when to use each flag; frequency upgraded to `high`
+- README benchmark highlight now specifies "via Agent Skills" to accurately reflect the delivery method used in the A/B evaluation
+
+### Added
+
+- Snippet extraction: every guide produces a one-liner BAD → GOOD transformation preview (e.g. `@dataclass → @dataclass(frozen=True, slots=True, kw_only=True)`)
+- 6 new tests: snippet non-empty invariant, exact fixture assertions, MCP/CLI enriched key validation
+
 ## [0.2.1] — 2026-05-27
 
 ### Changed
@@ -68,6 +88,9 @@ Initial release.
 - Strict YAML-subset frontmatter parser (no PyYAML dependency)
 - GitHub Actions CI (pytest + ruff on Python 3.11, 3.12, 3.13)
 
+[0.2.3]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.3
+[0.2.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.2
+[0.2.1]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.1
 [0.2.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.2.0
 [0.1.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.2
 [0.1.1]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.1

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.2.1
+Version: 0.2.3
 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
@@ -40,7 +40,7 @@ Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 versio
 
 ## Highlights
 
-- **Measurable impact**: +14.7pp overall improvement in A/B benchmark with 38 scored items ([details](docs/benchmark-evaluation.md)). Largest variant (FastAPI, 32 items): Control 60.4% → Treatment 82.3%
+- **Measurable impact**: +14.7pp overall improvement in A/B benchmark via Agent Skills (38 scored items, [details](docs/benchmark-evaluation.md)). Largest variant (FastAPI, 32 items): Control 60.4% → Treatment 82.3%
 - **39 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

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/README.md

@@ -9,7 +9,7 @@ Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 versio
 
 ## Highlights
 
-- **Measurable impact**: +14.7pp overall improvement in A/B benchmark with 38 scored items ([details](docs/benchmark-evaluation.md)). Largest variant (FastAPI, 32 items): Control 60.4% → Treatment 82.3%
+- **Measurable impact**: +14.7pp overall improvement in A/B benchmark via Agent Skills (38 scored items, [details](docs/benchmark-evaluation.md)). Largest variant (FastAPI, 32 items): Control 60.4% → Treatment 82.3%
 - **39 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

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.2.1"
+version = "0.2.3"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
 license = "Apache-2.0 OR MIT"

modern_python_guidance-0.2.3/skills/modern-python-guidance/guides/data-structures/dataclass-modern.md

@@ -0,0 +1,85 @@
+---
+id: dataclass-modern
+title: Use Modern Dataclass Features (frozen, slots, kw_only)
+category: data-structures
+layer: 1
+tags:
+  - dataclass
+  - slots
+  - kw_only
+  - frozen
+  - immutable
+aliases:
+  - dataclass
+  - dataclasses
+python: ">=3.10"
+frequency: high
+---
+
+# Use Modern Dataclass Features
+
+Since Python 3.10, dataclasses support `frozen=True`, `slots=True`, and `kw_only=True` for immutable value objects with better performance.
+
+## BAD
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class AppConfig:
+    db_host: str
+    db_port: int
+    debug: bool = False
+
+config = AppConfig("localhost", 5432)
+config.db_host = "evil.example.com"  # mutable — accidental or malicious mutation
+config.typo_field = True  # silently creates new attribute
+```
+
+## GOOD
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AppConfig:
+    db_host: str
+    db_port: int
+    debug: bool = False
+
+config = AppConfig(db_host="localhost", db_port=5432)
+config.db_host = "evil"  # FrozenInstanceError
+config.typo_field = True  # AttributeError
+```
+
+## Why
+
+### When to use each flag
+
+| Flag | Use when | Effect |
+|------|----------|--------|
+| `frozen=True` | Value objects, configs, DTOs, dict keys | Immutable + hashable |
+| `slots=True` | Always (unless you need `__dict__`) | 20-35% less memory, faster access, blocks typo attrs |
+| `kw_only=True` | 3+ fields, or fields of same type | Forces named args, prevents ordering bugs |
+
+### When NOT to use
+
+- **`frozen`**: Skip when you need mutable builder pattern or in-place updates in tight loops
+- **`slots`**: Skip when you need `__dict__` introspection, multiple inheritance with conflicting slots, or dynamic attribute assignment
+- **`kw_only`**: Skip for 1-2 field classes where positional is unambiguous (e.g., `Point(x, y)`)
+
+### Decision checklist
+
+1. Is this a value object, config, or DTO? → Add `frozen=True`
+2. Do you need `__dict__` or multiple inheritance? → If no, add `slots=True`
+3. Are there 3+ fields or fields of the same type? → Add `kw_only=True`
+
+## Version Notes
+
+- 3.10+: `slots=True`, `kw_only=True`
+- 3.10+: Per-field `kw_only` via `field(kw_only=True)`
+- 3.7-3.9: Basic `@dataclass` and `frozen=True` only (no slots/kw_only)
+
+## References
+
+- [dataclasses documentation](https://docs.python.org/3/library/dataclasses.html)

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/skills/modern-python-guidance/guides/fastapi/fastapi-lifespan.md

@@ -68,7 +68,7 @@ async def root(request: Request):
 
 ## Version Notes
 
-- Works on Python 3.9+ with FastAPI >= 0.93.0
+- Works on Python 3.9+ with FastAPI >= 0.94.0 (lifespan state dict requires Starlette >= 0.26.0)
 - `AsyncIterator` moved from `typing` to `collections.abc` in 3.9
 
 ## References

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/skills/modern-python-guidance/guides/fastapi/fastapi-typed-state.md

@@ -70,6 +70,11 @@ async def root(request: Request):
 - `dataclass` or `TypedDict` documents the expected shape
 - Resource cleanup is guaranteed by the context manager
 
+## Version Notes
+
+- Lifespan state dict requires FastAPI >= 0.94.0 (Starlette >= 0.26.0)
+- `@dataclass(slots=True)` requires Python 3.10+; use plain `@dataclass` on 3.9
+
 ## References
 
 - [FastAPI Lifespan State](https://fastapi.tiangolo.com/advanced/events/#lifespan-state)

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/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.2.0"
+__version__ = "0.2.3"

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/src/modern_python_guidance/cli.py

@@ -122,9 +122,13 @@ def _cmd_search(args: argparse.Namespace) -> None:
                 "title": r.meta.title,
                 "category": r.meta.category,
                 "layer": r.meta.layer,
+                "tags": r.meta.tags,
+                "python": r.meta.python,
+                "frequency": r.meta.frequency,
                 "score": r.score,
                 "token_estimate": r.token_estimate,
                 "fuzzy": r.fuzzy,
+                "snippet": r.snippet,
             }
             for r in results
         ]

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/src/modern_python_guidance/guide_index.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import importlib.resources
 import logging
 from dataclasses import dataclass, field
+from itertools import zip_longest
 from pathlib import Path
 
 from modern_python_guidance.frontmatter import FrontmatterError, GuideMeta, parse_frontmatter
@@ -17,6 +18,7 @@ class Guide:
     meta: GuideMeta
     body: str
     source_path: str
+    snippet: str = ""
 
 
 @dataclass
@@ -68,6 +70,7 @@ def build_index(guides_dir: Path | None = None) -> GuideIndex:
                 meta=meta,
                 body=body,
                 source_path=str(md_file),
+                snippet=_extract_snippet(body),
             )
         except FrontmatterError as e:
             log.warning("Skipping %s: %s", md_file, e)
@@ -78,6 +81,42 @@ def build_index(guides_dir: Path | None = None) -> GuideIndex:
     return index
 
 
+def _extract_snippet(body: str) -> str:
+    """Extract a BAD → GOOD one-liner from guide body.
+
+    Finds the first pair of lines from BAD and GOOD code blocks that differ,
+    which best conveys the transformation the guide teaches.
+    """
+    bad_lines = _code_lines(body, "## BAD")
+    good_lines = _code_lines(body, "## GOOD")
+    if not bad_lines or not good_lines:
+        return ""
+    for b, g in zip_longest(bad_lines, good_lines, fillvalue=""):
+        if b != g:
+            return f"{b} → {g}" if b and g else (b or g)
+    return f"{bad_lines[0]} → {good_lines[0]}"
+
+
+def _code_lines(body: str, heading: str) -> list[str]:
+    """Return all non-empty code lines from the first fence under a heading."""
+    parts = body.split(heading + "\n")
+    if len(parts) < 2:
+        return []
+    section = parts[1].split("\n## ")[0]
+    in_fence = False
+    lines: list[str] = []
+    for line in section.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            if not in_fence:
+                in_fence = True
+                continue
+            break
+        if in_fence and stripped:
+            lines.append(stripped)
+    return lines
+
+
 def _find_guides_dir() -> Path:
     try:
         skills_pkg = importlib.resources.files("modern_python_guidance") / "skills"

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/src/modern_python_guidance/mcp_server.py

@@ -252,9 +252,13 @@ def _tool_search(arguments: dict) -> dict:
             "title": r.meta.title,
             "category": r.meta.category,
             "layer": r.meta.layer,
+            "tags": r.meta.tags,
+            "python": r.meta.python,
+            "frequency": r.meta.frequency,
             "score": r.score,
             "token_estimate": r.token_estimate,
             "fuzzy": r.fuzzy,
+            "snippet": r.snippet,
         }
         for r in results
     ]

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/src/modern_python_guidance/search.py

@@ -28,6 +28,7 @@ class SearchResult:
     meta: GuideMeta
     token_estimate: int
     fuzzy: bool = False
+    snippet: str = ""
 
 
 def search(
@@ -64,6 +65,7 @@ def search(
                 score=score,
                 meta=meta,
                 token_estimate=token_estimate(guide.body),
+                snippet=guide.snippet,
             ))
 
     results.sort(key=lambda r: (-r.score, r.guide_id))
@@ -143,6 +145,7 @@ def _fuzzy_fallback(
                 meta=guide.meta,
                 token_estimate=token_estimate(guide.body),
                 fuzzy=True,
+                snippet=guide.snippet,
             ))
 
     results.sort(key=lambda r: (-r.score, r.guide_id))

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/tests/test_cli_integration.py

@@ -50,6 +50,18 @@ class TestSearch:
         data = json.loads(r.stdout)
         assert all(d["category"] == "fastapi" for d in data)
 
+    def test_search_enriched_keys(self):
+        r = run_cli("search", "pydantic validator", "--format", "json")
+        assert r.returncode == 0
+        data = json.loads(r.stdout)
+        expected_keys = {
+            "id", "title", "category", "layer", "tags", "python",
+            "frequency", "score", "token_estimate", "fuzzy", "snippet",
+        }
+        assert set(data[0].keys()) == expected_keys
+        assert isinstance(data[0]["tags"], list)
+        assert "→" in data[0]["snippet"]
+
 
 class TestRetrieve:
     def test_retrieve_single(self):

{modern_python_guidance-0.2.1 → modern_python_guidance-0.2.3}/tests/test_mcp_server.py

@@ -99,6 +99,26 @@ class TestSearchGuides:
         assert isinstance(data, list)
         assert len(data) >= 1
 
+    def test_search_enriched_keys(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "search_guides",
+                "arguments": {"query": "pydantic validator"},
+            }},
+        )
+        data = json.loads(responses[1]["result"]["content"][0]["text"])
+        expected_keys = {
+            "id", "title", "category", "layer", "tags", "python",
+            "frequency", "score", "token_estimate", "fuzzy", "snippet",
+        }
+        assert set(data[0].keys()) == expected_keys
+        assert isinstance(data[0]["tags"], list)
+        assert isinstance(data[0]["python"], str)
+        assert isinstance(data[0]["frequency"], str)
+        assert isinstance(data[0]["snippet"], str)
+        assert "→" in data[0]["snippet"]
+
     def test_search_empty_query(self):
         responses = _run_mcp(
             *_init_handshake(),

modern_python_guidance-0.2.3/tests/test_search.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from modern_python_guidance.guide_index import _extract_snippet, build_index
+from modern_python_guidance.search import search
+
+GUIDES_DIR = Path(__file__).parent.parent / "skills" / "modern-python-guidance" / "guides"
+
+
+@pytest.fixture
+def index():
+    return build_index(GUIDES_DIR)
+
+
+class TestBasicSearch:
+    def test_search_by_tag(self, index):
+        results = search(index, "typing")
+        assert len(results) >= 1
+        assert results[0].guide_id == "use-builtin-generics"
+
+    def test_search_by_alias(self, index):
+        results = search(index, "typing.List")
+        assert len(results) >= 1
+        assert results[0].guide_id == "use-builtin-generics"
+
+    def test_search_by_title_word(self, index):
+        results = search(index, "lifespan")
+        assert len(results) >= 1
+        assert results[0].guide_id == "fastapi-lifespan"
+
+    def test_search_by_category(self, index):
+        results = search(index, "asyncio", category="async")
+        assert all(r.meta.category == "async" for r in results)
+
+    def test_search_returns_token_estimate(self, index):
+        results = search(index, "typing")
+        assert all(r.token_estimate > 0 for r in results)
+
+
+class TestVersionFilter:
+    def test_version_excludes_incompatible(self, index):
+        results = search(index, "asyncio taskgroup", python_version="3.9")
+        ids = [r.guide_id for r in results]
+        assert "taskgroup-over-gather" not in ids
+
+    def test_version_includes_compatible(self, index):
+        results = search(index, "asyncio taskgroup", python_version="3.11")
+        ids = [r.guide_id for r in results]
+        assert "taskgroup-over-gather" in ids
+
+
+class TestFuzzyFallback:
+    def test_fuzzy_on_no_match(self, index):
+        results = search(index, "genercs")
+        assert len(results) > 0
+        assert results[0].fuzzy is True
+
+    def test_truly_irrelevant_query(self, index):
+        results = search(index, "javascript react angular")
+        assert all(r.fuzzy for r in results) or len(results) == 0
+
+
+class TestDeterminism:
+    def test_same_score_sorted_by_id(self, index):
+        results = search(index, "pydantic")
+        assert len(results) >= 2
+        assert not any(r.fuzzy for r in results)
+        same_score_groups: dict[float, list[str]] = {}
+        for r in results:
+            same_score_groups.setdefault(r.score, []).append(r.guide_id)
+        for group in same_score_groups.values():
+            assert group == sorted(group)
+
+
+class TestSnippet:
+    def test_all_guides_have_snippet(self, index):
+        results = search(index, "python", limit=50)
+        for r in results:
+            guide = index.get(r.guide_id)
+            assert guide is not None
+            assert guide.snippet, f"{r.guide_id} has empty snippet"
+
+    def test_all_guides_non_empty_snippet(self):
+        idx = build_index(GUIDES_DIR)
+        for guide_id, guide in idx.guides.items():
+            assert guide.snippet, f"{guide_id} has empty snippet"
+
+    def test_snippet_in_search_result(self, index):
+        results = search(index, "pydantic validator")
+        assert len(results) >= 1
+        r = results[0]
+        assert r.snippet
+        assert "→" in r.snippet
+
+    def test_snippet_exact_fixtures(self, index):
+        fixtures = {
+            "pydantic-v2-validators": (
+                "from pydantic import BaseModel, validator, root_validator"
+                " → "
+                "from pydantic import BaseModel, field_validator, model_validator"
+            ),
+            "dataclass-modern": "@dataclass → @dataclass(frozen=True, slots=True, kw_only=True)",
+            "use-builtin-generics": (
+                "from typing import Dict, List, Optional, Set, Tuple"
+                " → "
+                "def process(items: list[str]) -> dict[str, int]:"
+            ),
+            "taskgroup-over-gather": (
+                "results = await asyncio.gather("
+                " → "
+                "async with asyncio.TaskGroup() as tg:"
+            ),
+        }
+        for guide_id, expected in fixtures.items():
+            guide = index.get(guide_id)
+            assert guide is not None, f"{guide_id} not found"
+            assert guide.snippet == expected, (
+                f"{guide_id}: expected {expected!r}, got {guide.snippet!r}"
+            )
+
+
+class TestSnippetExtraction:
+    def test_unequal_bad_longer(self):
+        body = (
+            "## BAD\n```python\nline_a\nline_b\nline_c\n```\n"
+            "## GOOD\n```python\nline_x\n```\n"
+        )
+        snippet = _extract_snippet(body)
+        assert snippet == "line_a → line_x"
+
+    def test_unequal_good_longer(self):
+        body = (
+            "## BAD\n```python\nline_a\n```\n"
+            "## GOOD\n```python\nline_x\nline_y\nline_z\n```\n"
+        )
+        snippet = _extract_snippet(body)
+        assert snippet == "line_a → line_x"
+
+    def test_late_differing_line(self):
+        body = (
+            "## BAD\n```python\nimport foo\nresult = old_call()\n```\n"
+            "## GOOD\n```python\nimport foo\nresult = new_call()\n```\n"
+        )
+        snippet = _extract_snippet(body)
+        assert snippet == "result = old_call() → result = new_call()"
+
+    def test_diff_beyond_eight_lines(self):
+        shared = "\n".join(f"line_{i}" for i in range(9))
+        body = (
+            f"## BAD\n```python\n{shared}\nold_call()\n```\n"
+            f"## GOOD\n```python\n{shared}\nnew_call()\n```\n"
+        )
+        snippet = _extract_snippet(body)
+        assert snippet == "old_call() → new_call()"
+
+    def test_trailing_only_in_bad(self):
+        body = (
+            "## BAD\n```python\nshared\nextra_bad\n```\n"
+            "## GOOD\n```python\nshared\n```\n"
+        )
+        snippet = _extract_snippet(body)
+        assert snippet == "extra_bad"
+
+    def test_trailing_only_in_good(self):
+        body = (
+            "## BAD\n```python\nshared\n```\n"
+            "## GOOD\n```python\nshared\nextra_good\n```\n"
+        )
+        snippet = _extract_snippet(body)
+        assert snippet == "extra_good"
+
+    def test_all_lines_identical(self):
+        body = (
+            "## BAD\n```python\nsame\n```\n"
+            "## GOOD\n```python\nsame\n```\n"
+        )
+        snippet = _extract_snippet(body)
+        assert snippet == "same → same"
+
+    def test_heading_boundary_not_prefix_match(self):
+        body = (
+            "## BADLY_NAMED\n```python\nwrong\n```\n"
+            "## BAD\n```python\ncorrect_bad\n```\n"
+            "## GOOD\n```python\ncorrect_good\n```\n"
+        )
+        snippet = _extract_snippet(body)
+        assert snippet == "correct_bad → correct_good"
+
+    def test_first_fence_only(self):
+        body = (
+            "## BAD\n```python\nfirst_bad\n```\n"
+            "```python\nsecond_bad\n```\n"
+            "## GOOD\n```python\nfirst_good\n```\n"
+        )
+        snippet = _extract_snippet(body)
+        assert snippet == "first_bad → first_good"
+
+    def test_no_bad_section(self):
+        body = "## GOOD\n```python\ncode\n```\n"
+        snippet = _extract_snippet(body)
+        assert snippet == ""
+
+    def test_no_good_section(self):
+        body = "## BAD\n```python\ncode\n```\n"
+        snippet = _extract_snippet(body)
+        assert snippet == ""
+
+
+class TestEdgeCases:
+    def test_empty_query(self, index):
+        results = search(index, "")
+        assert results == []
+
+    def test_long_query_truncated(self, index):
+        results = search(index, "x " * 1000)
+        assert isinstance(results, list)
+
+    def test_limit(self, index):
+        results = search(index, "python", limit=2)
+        assert len(results) <= 2

modern_python_guidance-0.2.1/skills/modern-python-guidance/guides/data-structures/dataclass-modern.md

@@ -1,73 +0,0 @@
----
-id: dataclass-modern
-title: Use Modern Dataclass Features (slots, kw_only)
-category: data-structures
-layer: 1
-tags:
-  - dataclass
-  - slots
-  - kw_only
-aliases:
-  - dataclass
-  - dataclasses
-python: ">=3.10"
-frequency: medium
----
-
-# Use Modern Dataclass Features
-
-Since Python 3.10, dataclasses support `slots=True` and `kw_only=True` for better performance and safer APIs.
-
-## BAD
-
-```python
-from dataclasses import dataclass
-
-@dataclass
-class Point:
-    x: float
-    y: float
-    z: float = 0.0
-
-# No slots: allows typos on attributes
-p = Point(1.0, 2.0)
-p.w = 3.0  # silently creates new attribute (typo for 'z')
-
-# Positional args: easy to mix up x and y
-p = Point(2.0, 1.0)  # is this (x=2, y=1) or (x=1, y=2)?
-```
-
-## GOOD
-
-```python
-from dataclasses import dataclass
-
-@dataclass(slots=True, kw_only=True)
-class Point:
-    x: float
-    y: float
-    z: float = 0.0
-
-p = Point(x=1.0, y=2.0)
-p.w = 3.0  # AttributeError: 'Point' has no attribute 'w'
-
-# kw_only forces explicit names — no positional confusion
-p = Point(x=2.0, y=1.0)  # intent is clear
-```
-
-## Why
-
-- `slots=True`: 20-35% less memory, faster attribute access, prevents typo attributes
-- `kw_only=True`: forces named arguments, eliminates positional ordering bugs
-- `frozen=True` + `slots=True`: fast immutable value objects
-- Combine for production data classes: `@dataclass(slots=True, frozen=True, kw_only=True)`
-
-## Version Notes
-
-- 3.10+: `slots=True`, `kw_only=True`
-- 3.10+: Per-field `kw_only` via `field(kw_only=True)`
-- 3.7-3.9: Basic `@dataclass` without slots/kw_only
-
-## References
-
-- [dataclasses documentation](https://docs.python.org/3/library/dataclasses.html)

modern_python_guidance-0.2.1/tests/test_search.py

@@ -1,89 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-import pytest
-
-from modern_python_guidance.guide_index import build_index
-from modern_python_guidance.search import search
-
-GUIDES_DIR = Path(__file__).parent.parent / "skills" / "modern-python-guidance" / "guides"
-
-
-@pytest.fixture
-def index():
-    return build_index(GUIDES_DIR)
-
-
-class TestBasicSearch:
-    def test_search_by_tag(self, index):
-        results = search(index, "typing")
-        assert len(results) >= 1
-        assert results[0].guide_id == "use-builtin-generics"
-
-    def test_search_by_alias(self, index):
-        results = search(index, "typing.List")
-        assert len(results) >= 1
-        assert results[0].guide_id == "use-builtin-generics"
-
-    def test_search_by_title_word(self, index):
-        results = search(index, "lifespan")
-        assert len(results) >= 1
-        assert results[0].guide_id == "fastapi-lifespan"
-
-    def test_search_by_category(self, index):
-        results = search(index, "asyncio", category="async")
-        assert all(r.meta.category == "async" for r in results)
-
-    def test_search_returns_token_estimate(self, index):
-        results = search(index, "typing")
-        assert all(r.token_estimate > 0 for r in results)
-
-
-class TestVersionFilter:
-    def test_version_excludes_incompatible(self, index):
-        results = search(index, "asyncio taskgroup", python_version="3.9")
-        ids = [r.guide_id for r in results]
-        assert "taskgroup-over-gather" not in ids
-
-    def test_version_includes_compatible(self, index):
-        results = search(index, "asyncio taskgroup", python_version="3.11")
-        ids = [r.guide_id for r in results]
-        assert "taskgroup-over-gather" in ids
-
-
-class TestFuzzyFallback:
-    def test_fuzzy_on_no_match(self, index):
-        results = search(index, "genercs")
-        assert len(results) > 0
-        assert results[0].fuzzy is True
-
-    def test_truly_irrelevant_query(self, index):
-        results = search(index, "javascript react angular")
-        assert all(r.fuzzy for r in results) or len(results) == 0
-
-
-class TestDeterminism:
-    def test_same_score_sorted_by_id(self, index):
-        results = search(index, "pydantic")
-        assert len(results) >= 2
-        assert not any(r.fuzzy for r in results)
-        same_score_groups: dict[float, list[str]] = {}
-        for r in results:
-            same_score_groups.setdefault(r.score, []).append(r.guide_id)
-        for group in same_score_groups.values():
-            assert group == sorted(group)
-
-
-class TestEdgeCases:
-    def test_empty_query(self, index):
-        results = search(index, "")
-        assert results == []
-
-    def test_long_query_truncated(self, index):
-        results = search(index, "x " * 1000)
-        assert isinstance(results, list)
-
-    def test_limit(self, index):
-        results = search(index, "python", limit=2)
-        assert len(results) <= 2