modern-python-guidance 0.1.0__py3-none-any.whl

modern_python_guidance/__init__.py

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

modern_python_guidance/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m modern_python_guidance`."""
+
+from modern_python_guidance.cli import main
+
+main()

modern_python_guidance/cli.py

@@ -0,0 +1,202 @@
+"""CLI entry point for modern-python-guidance."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import signal
+import sys
+from pathlib import Path
+
+from modern_python_guidance import __version__
+from modern_python_guidance.compat import VERSION_RE, version_compatible
+from modern_python_guidance.guide_index import build_index
+from modern_python_guidance.retrieve import retrieve
+from modern_python_guidance.search import search as do_search
+from modern_python_guidance.version_detect import detect_version
+
+
+def main(argv: list[str] | None = None) -> None:
+    with contextlib.suppress(AttributeError, OSError):
+        signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+
+    parser = argparse.ArgumentParser(
+        prog="modern-python-guidance",
+        description="Version-aware BAD/GOOD pattern guides for modern Python",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # search
+    p_search = subparsers.add_parser("search", help="Search guides by keyword")
+    p_search.add_argument("query", help="Search query")
+    p_search.add_argument("--python-version", help="Target Python version (e.g. 3.11)")
+    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,
+        help="Output format (default: json when piped, human when TTY)",
+    )
+
+    # retrieve
+    p_retrieve = subparsers.add_parser("retrieve", help="Retrieve guide(s) by ID")
+    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,
+        help="Output format (default: json when piped, human when TTY)",
+    )
+
+    # list
+    p_list = subparsers.add_parser("list", help="List available guides")
+    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,
+        help="Output format (default: json when piped, human when TTY)",
+    )
+
+    # detect-version
+    p_detect = subparsers.add_parser("detect-version", help="Detect project Python version")
+    p_detect.add_argument("--project-dir", type=Path, help="Project directory (default: cwd)")
+
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(2)
+
+    pv = getattr(args, "python_version", None)
+    if pv is not None and not VERSION_RE.match(pv):
+        parser.error(f"invalid --python-version format: {pv!r} (expected N.N, e.g. 3.11)")
+
+    try:
+        if args.command == "search":
+            _cmd_search(args)
+        elif args.command == "retrieve":
+            _cmd_retrieve(args)
+        elif args.command == "list":
+            _cmd_list(args)
+        elif args.command == "detect-version":
+            _cmd_detect_version(args)
+    except BrokenPipeError:
+        sys.exit(0)
+
+
+def _resolve_format(args: argparse.Namespace) -> str:
+    if args.format is not None:
+        return args.format
+    return "human" if sys.stdout.isatty() else "json"
+
+
+def _cmd_search(args: argparse.Namespace) -> None:
+    index = build_index()
+    results = do_search(
+        index,
+        args.query,
+        python_version=args.python_version,
+        category=args.category,
+        limit=args.limit,
+    )
+
+    fmt = _resolve_format(args)
+
+    if not results:
+        if fmt == "human":
+            print("No guides found.")
+        else:
+            print("[]")
+        sys.exit(1)
+
+    if fmt == "json":
+        out = [
+            {
+                "id": r.guide_id,
+                "title": r.meta.title,
+                "category": r.meta.category,
+                "layer": r.meta.layer,
+                "score": r.score,
+                "token_estimate": r.token_estimate,
+                "fuzzy": r.fuzzy,
+            }
+            for r in results
+        ]
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        for r in results:
+            fuzzy_marker = " (fuzzy)" if r.fuzzy else ""
+            print(f"  {r.guide_id:<40} score={r.score:<6.1f} [{r.meta.category}]{fuzzy_marker}")
+
+
+def _cmd_retrieve(args: argparse.Namespace) -> None:
+    index = build_index()
+    guide_ids = [gid.strip() for gid in args.ids.split(",")]
+    results = retrieve(index, guide_ids, python_version=args.python_version)
+
+    fmt = _resolve_format(args)
+
+    if not results:
+        if fmt == "human":
+            print("No guides found.")
+        else:
+            print("[]")
+        sys.exit(1)
+
+    if fmt == "json":
+        print(json.dumps(results, indent=2, ensure_ascii=False))
+    else:
+        for r in results:
+            match_str = "YES" if r["version_match"] else "NO"
+            print(f"--- {r['id']} (version match: {match_str}) ---")
+            print(r["content"])
+            print()
+
+
+def _cmd_list(args: argparse.Namespace) -> None:
+    index = build_index()
+    metas = index.all_meta()
+
+    if args.category:
+        metas = [m for m in metas if m.category == args.category]
+
+    if args.python_version:
+        metas = [m for m in metas if version_compatible(m.python, args.python_version)]
+
+    metas.sort(key=lambda m: (m.layer, m.category, m.id))
+
+    fmt = _resolve_format(args)
+
+    if not metas:
+        if fmt == "human":
+            print("No guides found.")
+        else:
+            print("[]")
+        sys.exit(1)
+
+    if fmt == "json":
+        out = [
+            {
+                "id": m.id,
+                "title": m.title,
+                "category": m.category,
+                "layer": m.layer,
+                "python": m.python,
+                "frequency": m.frequency,
+            }
+            for m in metas
+        ]
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        current_cat = None
+        for m in metas:
+            if m.category != current_cat:
+                current_cat = m.category
+                print(f"\n[{current_cat}] (layer {m.layer})")
+            print(f"  {m.id:<40} {m.title}")
+
+
+def _cmd_detect_version(args: argparse.Namespace) -> None:
+    version = detect_version(project_dir=args.project_dir)
+    print(version)

modern_python_guidance/compat.py

@@ -0,0 +1,22 @@
+"""Shared helpers used by search, retrieve, and CLI."""
+
+from __future__ import annotations
+
+import re
+
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+from packaging.version import Version
+
+VERSION_RE = re.compile(r"^\d+\.\d+$")
+
+
+def version_compatible(guide_python: str, target: str) -> bool:
+    try:
+        spec = SpecifierSet(guide_python)
+        return Version(f"{target}.0") in spec
+    except (InvalidSpecifier, Exception):
+        return True
+
+
+def token_estimate(body: str) -> int:
+    return len(body) // 4

modern_python_guidance/frontmatter.py

@@ -0,0 +1,166 @@
+"""Strict YAML-subset frontmatter parser for guide files.
+
+Supports only:
+  - key: value (string, quoted string, integer)
+  - key:\\n  - item\\n  - item (indented list)
+
+Rejects all other YAML constructs with FrontmatterError + line number.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+_KEY_RE = re.compile(r"^([a-z][a-z0-9_-]*)\s*:\s*(.*)")
+_LIST_ITEM_RE = re.compile(r"^  - (.+)")
+_FENCE = "---"
+
+REQUIRED_FIELDS = frozenset({"id", "title", "category", "layer", "tags", "python", "frequency"})
+VALID_FREQUENCIES = frozenset({"high", "medium", "low"})
+
+
+class FrontmatterError(Exception):
+    def __init__(self, message: str, line: int | None = None):
+        self.line = line
+        prefix = f"line {line}: " if line is not None else ""
+        super().__init__(f"{prefix}{message}")
+
+
+@dataclass
+class GuideMeta:
+    id: str
+    title: str
+    category: str
+    layer: int
+    tags: list[str]
+    python: str
+    frequency: str
+    aliases: list[str] = field(default_factory=list)
+    pep: list[int] = field(default_factory=list)
+
+
+def parse_frontmatter(text: str) -> tuple[GuideMeta, str]:
+    lines = text.split("\n")
+
+    if not lines or lines[0].strip() != _FENCE:
+        raise FrontmatterError("file must start with ---", line=1)
+
+    end_idx = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == _FENCE:
+            end_idx = i
+            break
+
+    if end_idx is None:
+        raise FrontmatterError("closing --- not found")
+
+    raw = _parse_raw(lines[1:end_idx])
+    meta = _build_meta(raw)
+    body = "\n".join(lines[end_idx + 1 :]).strip()
+    return meta, body
+
+
+def _parse_raw(lines: list[str]) -> dict[str, Any]:
+    data: dict[str, Any] = {}
+    current_key: str | None = None
+
+    for i, line in enumerate(lines, start=2):
+        if not line.strip():
+            continue
+
+        list_match = _LIST_ITEM_RE.match(line)
+        if list_match:
+            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
+                )
+            data[current_key].append(_parse_scalar(list_match.group(1).strip()))
+            continue
+
+        key_match = _KEY_RE.match(line)
+        if key_match:
+            key = key_match.group(1)
+            value_str = key_match.group(2).strip()
+
+            if key in data:
+                raise FrontmatterError(f"duplicate key '{key}'", line=i)
+
+            if value_str:
+                data[key] = _parse_scalar(value_str)
+                current_key = None
+            else:
+                data[key] = []
+                current_key = key
+            continue
+
+        raise FrontmatterError(f"unsupported syntax: {line!r}", line=i)
+
+    return data
+
+
+def _parse_scalar(value: str) -> str | int:
+    if value.startswith('"') and value.endswith('"'):
+        return value[1:-1]
+
+    if value.startswith("'") and value.endswith("'"):
+        return value[1:-1]
+
+    if value.isascii() and value.isdigit():
+        return int(value)
+
+    return value
+
+
+def _build_meta(raw: dict[str, Any]) -> GuideMeta:
+    missing = REQUIRED_FIELDS - raw.keys()
+    if missing:
+        raise FrontmatterError(f"missing required fields: {', '.join(sorted(missing))}")
+
+    for str_field in ("id", "title", "category", "python", "frequency"):
+        if isinstance(raw[str_field], list):
+            raise FrontmatterError(f"'{str_field}' must be a scalar value, not a list")
+
+    freq = raw["frequency"]
+    if freq not in VALID_FREQUENCIES:
+        raise FrontmatterError(f"invalid frequency '{freq}', must be one of {VALID_FREQUENCIES}")
+
+    layer = raw["layer"]
+    if not isinstance(layer, int) or layer not in (1, 2, 3):
+        raise FrontmatterError(f"layer must be 1, 2, or 3, got {layer!r}")
+
+    pep_raw = raw.get("pep")
+    if pep_raw is None:
+        pep = []
+    elif isinstance(pep_raw, int):
+        pep = [pep_raw]
+    elif isinstance(pep_raw, list):
+        try:
+            pep = [int(p) for p in pep_raw]
+        except (ValueError, TypeError) as e:
+            raise FrontmatterError(f"pep list items must be integers: {e}") from e
+    else:
+        raise FrontmatterError(f"pep must be int or list of ints, got {pep_raw!r}")
+
+    aliases_raw = raw.get("aliases", [])
+    if not isinstance(aliases_raw, list):
+        raise FrontmatterError(f"aliases must be a list, got {aliases_raw!r}")
+
+    tags = raw["tags"]
+    if not isinstance(tags, list) or not tags:
+        raise FrontmatterError("tags must be a non-empty list")
+
+    return GuideMeta(
+        id=str(raw["id"]),
+        title=str(raw["title"]),
+        category=str(raw["category"]),
+        layer=layer,
+        tags=[str(t) for t in tags],
+        python=str(raw["python"]),
+        frequency=freq,
+        aliases=[str(a) for a in aliases_raw],
+        pep=pep,
+    )

modern_python_guidance/guide_index.py

@@ -0,0 +1,96 @@
+"""Dynamic guide scanner — builds in-memory index from guides/ directory."""
+
+from __future__ import annotations
+
+import importlib.resources
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from modern_python_guidance.frontmatter import FrontmatterError, GuideMeta, parse_frontmatter
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class Guide:
+    meta: GuideMeta
+    body: str
+    source_path: str
+
+
+@dataclass
+class GuideIndex:
+    guides: dict[str, Guide] = field(default_factory=dict)
+
+    def __len__(self) -> int:
+        return len(self.guides)
+
+    def get(self, guide_id: str) -> Guide | None:
+        return self.guides.get(guide_id)
+
+    def all_meta(self) -> list[GuideMeta]:
+        return [g.meta for g in self.guides.values()]
+
+    def categories(self) -> list[str]:
+        return sorted({g.meta.category for g in self.guides.values()})
+
+
+def build_index(guides_dir: Path | None = None) -> GuideIndex:
+    if guides_dir is None:
+        guides_dir = _find_guides_dir()
+
+    index = GuideIndex()
+
+    if not guides_dir.is_dir():
+        log.warning("Guides directory not found: %s", guides_dir)
+        return index
+
+    for md_file in sorted(guides_dir.rglob("*.md")):
+        try:
+            text = md_file.read_text(encoding="utf-8")
+            meta, body = parse_frontmatter(text)
+
+            expected_id = md_file.stem
+            if meta.id != expected_id:
+                log.warning(
+                    "Guide ID mismatch: frontmatter says '%s', filename is '%s'"
+                    " — using frontmatter ID",
+                    meta.id,
+                    expected_id,
+                )
+
+            if meta.id in index.guides:
+                log.warning("Duplicate guide ID '%s', skipping %s", meta.id, md_file)
+                continue
+
+            index.guides[meta.id] = Guide(
+                meta=meta,
+                body=body,
+                source_path=str(md_file),
+            )
+        except FrontmatterError as e:
+            log.warning("Skipping %s: %s", md_file, e)
+        except Exception as e:
+            log.warning("Unexpected error loading %s: %s", md_file, e)
+
+    log.debug("Loaded %d guides from %s", len(index), guides_dir)
+    return index
+
+
+def _find_guides_dir() -> Path:
+    try:
+        skills_pkg = importlib.resources.files("modern_python_guidance") / "skills"
+        guides_path = skills_pkg / "modern-python-guidance" / "guides"
+        traversable_path = Path(str(guides_path))
+        if traversable_path.is_dir():
+            return traversable_path
+    except (TypeError, FileNotFoundError):
+        pass
+
+    src_root = Path(__file__).resolve().parent.parent.parent
+    dev_path = src_root / "skills" / "modern-python-guidance" / "guides"
+    if dev_path.is_dir():
+        return dev_path
+
+    return Path("skills") / "modern-python-guidance" / "guides"

modern_python_guidance/retrieve.py

@@ -0,0 +1,56 @@
+"""Guide retrieval and JSON rendering."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from modern_python_guidance import __version__
+from modern_python_guidance.compat import token_estimate, version_compatible
+from modern_python_guidance.guide_index import Guide, GuideIndex
+
+
+def retrieve(
+    index: GuideIndex,
+    guide_ids: list[str],
+    *,
+    python_version: str | None = None,
+) -> list[dict[str, Any]]:
+    results: list[dict[str, Any]] = []
+
+    for guide_id in guide_ids:
+        guide = index.get(guide_id)
+        if guide is None:
+            continue
+        results.append(_render(guide, python_version=python_version))
+
+    return results
+
+
+def retrieve_json(
+    index: GuideIndex,
+    guide_ids: list[str],
+    *,
+    python_version: str | None = None,
+) -> str:
+    results = retrieve(index, guide_ids, python_version=python_version)
+    return json.dumps(results, indent=2, ensure_ascii=False)
+
+
+def _render(guide: Guide, *, python_version: str | None = None) -> dict[str, Any]:
+    ver_match = True
+    if python_version:
+        ver_match = version_compatible(guide.meta.python, python_version)
+
+    return {
+        "id": guide.meta.id,
+        "title": guide.meta.title,
+        "category": guide.meta.category,
+        "layer": guide.meta.layer,
+        "python": guide.meta.python,
+        "frequency": guide.meta.frequency,
+        "version_match": ver_match,
+        "content": guide.body,
+        "token_estimate": token_estimate(guide.body),
+        "source": f"modern-python-guidance v{__version__}",
+    }

modern_python_guidance/search.py

@@ -0,0 +1,149 @@
+"""Weighted keyword search engine for guides."""
+
+from __future__ import annotations
+
+import difflib
+from dataclasses import dataclass
+
+from modern_python_guidance.compat import token_estimate, version_compatible
+from modern_python_guidance.frontmatter import GuideMeta
+from modern_python_guidance.guide_index import Guide, GuideIndex
+
+WEIGHT_TAG = 10
+WEIGHT_ALIAS = 8
+WEIGHT_TITLE = 5
+WEIGHT_CATEGORY = 3
+
+FREQ_BOOST = {"high": 1.0, "medium": 0.5, "low": 0.0}
+
+MAX_QUERY_LEN = 500
+FUZZY_CUTOFF = 0.4
+FUZZY_MAX = 3
+
+
+@dataclass
+class SearchResult:
+    guide_id: str
+    score: float
+    meta: GuideMeta
+    token_estimate: int
+    fuzzy: bool = False
+
+
+def search(
+    index: GuideIndex,
+    query: str,
+    *,
+    python_version: str | None = None,
+    category: str | None = None,
+    limit: int = 10,
+) -> list[SearchResult]:
+    query = query[:MAX_QUERY_LEN].lower()
+    tokens = query.split()
+
+    if not tokens:
+        return []
+
+    results: list[SearchResult] = []
+
+    for guide_id, guide in index.guides.items():
+        meta = guide.meta
+
+        if category and meta.category != category:
+            continue
+
+        if python_version and not version_compatible(meta.python, python_version):
+            continue
+
+        score = _score(meta, tokens)
+
+        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),
+            ))
+
+    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,
+        )
+
+    return results[:limit]
+
+
+def _score(meta: GuideMeta, tokens: list[str]) -> float:
+    score = 0.0
+    tags_lower = [t.lower() for t in meta.tags]
+    aliases_lower = [a.lower() for a in meta.aliases]
+    title_words = meta.title.lower().split()
+
+    for token in tokens:
+        if token in tags_lower:
+            score += WEIGHT_TAG
+        if token in aliases_lower:
+            score += WEIGHT_ALIAS
+        if any(token in alias for alias in aliases_lower) and token not in aliases_lower:
+            score += WEIGHT_ALIAS * 0.5
+        if token in title_words:
+            score += WEIGHT_TITLE
+        if token == meta.category.lower():
+            score += WEIGHT_CATEGORY
+
+    return score
+
+
+def _fuzzy_fallback(
+    index: GuideIndex,
+    query: str,
+    *,
+    python_version: str | None = None,
+    category: str | None = None,
+    limit: int = FUZZY_MAX,
+) -> list[SearchResult]:
+    candidates: dict[str, Guide] = {}
+    for guide_id, guide in index.guides.items():
+        if category and guide.meta.category != category:
+            continue
+        if python_version and not version_compatible(guide.meta.python, python_version):
+            continue
+        candidates[guide_id] = guide
+
+    if not candidates:
+        return []
+
+    match_pool: list[str] = []
+    pool_to_guides: dict[str, list[str]] = {}
+
+    for guide_id, guide in candidates.items():
+        for term in [guide_id, guide.meta.title.lower()] + [t.lower() for t in guide.meta.tags]:
+            if term not in pool_to_guides:
+                match_pool.append(term)
+                pool_to_guides[term] = []
+            pool_to_guides[term].append(guide_id)
+
+    matches = difflib.get_close_matches(query, match_pool, n=FUZZY_MAX * 2, cutoff=FUZZY_CUTOFF)
+
+    seen: set[str] = set()
+    results: list[SearchResult] = []
+    for match in matches:
+        ratio = difflib.SequenceMatcher(None, query, match).ratio()
+        for guide_id in pool_to_guides[match]:
+            if guide_id in seen:
+                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,
+            ))
+
+    results.sort(key=lambda r: (-r.score, r.guide_id))
+    return results[:min(limit, FUZZY_MAX)]