modern-python-guidance 0.3.8__tar.gz → 0.4.0__tar.gz

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] — 2026-06-03
+
+### Added
+
+- `mpg check <file>` command: scan a Python file for outdated patterns using regex matching against guide definitions. Reports matches with line numbers, guide IDs, and inline snippets. Linter exit-code convention (0=clean, 1=findings, 2=error). Supports `--python-version` filtering, `--format json|human`, and `--exit-zero`. JSON envelope includes `file`, `mpg_version`, `matches`, and `summary` with `guide_ids` for batched `mpg retrieve`. (closes #21)
+- `detect_patterns` field in guide frontmatter: 3-value semantics — curated regex list (26 guides), explicit opt-out `[]` (15 guides), or absent `None` (auto-extraction fallback for future guides). All patterns validated at parse time via `re.compile`.
+- `CheckError` exception in check module for clean library-level error handling (file not found, binary file, read errors). CLI catches and converts to exit code 2.
+- Structural tests: all 41 guides must have `detect_patterns` present, patterns must compile, must match at least one BAD line, and must NOT match any GOOD line.
+- 205 new tests (886 total). Coverage: 92%+.
+
 ## [0.3.8] — 2026-06-02
 
 ### Added

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.3.8
+Version: 0.4.0
 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
@@ -139,6 +139,11 @@ mpg detect-version
 # Filter by category
 mpg search "timeout" --category async
 
+# Scan a file for outdated patterns
+mpg check app.py
+mpg check app.py --format json | jq '.summary.guide_ids'
+mpg check app.py --exit-zero  # always exit 0
+
 # JSON output (default when piped, explicit with --format)
 mpg search "typing" --format json | jq '.[0].id'
 ```

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/README.md

@@ -107,6 +107,11 @@ mpg detect-version
 # Filter by category
 mpg search "timeout" --category async
 
+# Scan a file for outdated patterns
+mpg check app.py
+mpg check app.py --format json | jq '.summary.guide_ids'
+mpg check app.py --exit-zero  # always exit 0
+
 # JSON output (default when piped, explicit with --format)
 mpg search "typing" --format json | jq '.[0].id'
 ```

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.3.8"
+version = "0.4.0"
 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.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/async/async-timeout-context.md

@@ -11,6 +11,8 @@ aliases:
   - asyncio.timeout
 python: ">=3.11"
 frequency: medium
+detect-patterns:
+  - "asyncio\.wait_for\("
 ---
 
 # Use asyncio.timeout Instead of wait_for

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/async/exception-groups.md

@@ -14,6 +14,7 @@ aliases:
 python: ">=3.11"
 frequency: medium
 pep: 654
+detect-patterns:
 ---
 
 # Use except* for Exception Groups

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/async/taskgroup-over-gather.md

@@ -12,6 +12,8 @@ aliases:
   - gather
 python: ">=3.11"
 frequency: high
+detect-patterns:
+  - "asyncio\.gather\("
 ---
 
 # Use asyncio.TaskGroup Instead of asyncio.gather

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/data-structures/dataclass-modern.md

@@ -14,6 +14,7 @@ aliases:
   - dataclasses
 python: ">=3.10"
 frequency: high
+detect-patterns:
 ---
 
 # Use Modern Dataclass Features

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/data-structures/dict-merge-operator.md

@@ -14,6 +14,7 @@ aliases:
 python: ">=3.9"
 frequency: medium
 pep: 584
+detect-patterns:
 ---
 
 # Use | Operator for Dict Merging

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/data-structures/match-case-patterns.md

@@ -14,6 +14,7 @@ aliases:
 python: ">=3.10"
 frequency: medium
 pep: 634
+detect-patterns:
 ---
 
 # Use Structural Pattern Matching

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/django/django-async-views.md

@@ -13,6 +13,8 @@ aliases:
   - async-orm
 python: ">=3.9"
 frequency: medium
+detect-patterns:
+  - "from asgiref\.sync import sync_to_async"
 ---
 
 # Use Native Async Views

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/django/django-check-constraints.md

@@ -12,6 +12,7 @@ aliases:
   - check-constraint
 python: ">=3.9"
 frequency: low
+detect-patterns:
 ---
 
 # Use condition Instead of check in CheckConstraint

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/django/django-json-field.md

@@ -13,6 +13,8 @@ aliases:
   - contrib-jsonfield
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "from django\.contrib\.postgres\.fields import.*JSONField"
 ---
 
 # Use Built-in JSONField

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/fastapi/fastapi-annotated-depends.md

@@ -13,6 +13,8 @@ aliases:
   - dependency injection
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "= Depends\("
 ---
 
 # Use Annotated for Dependency Injection

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/fastapi/fastapi-lifespan.md

@@ -14,6 +14,8 @@ aliases:
   - shutdown
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "\.on_event\("
 ---
 
 # Use Lifespan Context Manager

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

@@ -13,6 +13,7 @@ aliases:
   - typed state
 python: ">=3.9"
 frequency: medium
+detect-patterns:
 ---
 
 # Use TypedDict or dataclass for App State

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/httpx/httpx-async-client-reuse.md

@@ -14,6 +14,8 @@ aliases:
   - requests
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "async with httpx\.AsyncClient\(\) as"
 ---
 
 # Reuse httpx.AsyncClient

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/httpx/httpx-streaming.md

@@ -13,6 +13,7 @@ aliases:
   - large response
 python: ">=3.9"
 frequency: medium
+detect-patterns:
 ---
 
 # Use httpx Streaming for Large Responses

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/pydantic/pydantic-v2-config.md

@@ -13,6 +13,8 @@ aliases:
   - ConfigDict
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "class Config:"
 ---
 
 # Use model_config Instead of class Config

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/pydantic/pydantic-v2-model-api.md

@@ -14,6 +14,10 @@ aliases:
   - model_validate
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "\.parse_obj\("
+  - "\.parse_raw\("
+  - "\.from_orm\("
 ---
 
 # Use Pydantic V2 Model API

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/pydantic/pydantic-v2-serialization.md

@@ -13,6 +13,8 @@ aliases:
   - json_encoders
 python: ">=3.9"
 frequency: medium
+detect-patterns:
+  - "json_encoders"
 ---
 
 # Use field_serializer for Custom Serialization

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/pydantic/pydantic-v2-validators.md

@@ -13,6 +13,9 @@ aliases:
   - model_validator
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "@validator\("
+  - "@root_validator"
 ---
 
 # Use Pydantic V2 Validators

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/pytest/pytest-parametrize.md

@@ -12,6 +12,7 @@ aliases:
   - test-loop
 python: ">=3.9"
 frequency: high
+detect-patterns:
 ---
 
 # Use pytest.mark.parametrize

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/pytest/pytest-raises-match.md

@@ -13,6 +13,7 @@ aliases:
   - exception-match
 python: ">=3.9"
 frequency: medium
+detect-patterns:
 ---
 
 # Use pytest.raises with match

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/pytest/pytest-tmp-path.md

@@ -13,6 +13,8 @@ aliases:
   - temp-directory
 python: ">=3.9"
 frequency: medium
+detect-patterns:
+  - "def test_.*\btmpdir\b"
 ---
 
 # Use tmp_path Instead of tmpdir

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/sqlalchemy/sqlalchemy-2-style.md

@@ -13,6 +13,8 @@ aliases:
   - legacy-query
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "\.query\([A-Z]"
 ---
 
 # Use SQLAlchemy 2.0 Query Style

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/sqlalchemy/sqlalchemy-async-session.md

@@ -13,6 +13,7 @@ aliases:
   - async-sessionmaker
 python: ">=3.9"
 frequency: medium
+detect-patterns:
 ---
 
 # Use AsyncSession for Async Database Access

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/sqlalchemy/sqlalchemy-mapped-column.md

@@ -13,6 +13,9 @@ aliases:
   - declarative-base
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "from sqlalchemy import .*\bColumn\b"
+  - "declarative_base\("
 ---
 
 # Use Mapped and mapped_column

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/stdlib/datetime-utc.md

@@ -13,6 +13,9 @@ aliases:
   - datetime.utcfromtimestamp
 python: ">=3.11"
 frequency: high
+detect-patterns:
+  - "datetime\.utcnow\("
+  - "datetime\.utcfromtimestamp\("
 ---
 
 # Use datetime.now(UTC) Instead of utcnow()

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/stdlib/pathlib-over-os-path.md

@@ -13,6 +13,8 @@ aliases:
   - os.path.exists
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "os\.path\."
 ---
 
 # Use pathlib.Path Instead of os.path

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/stdlib/removeprefix-removesuffix.md

@@ -14,6 +14,7 @@ aliases:
 python: ">=3.9"
 frequency: medium
 pep: 616
+detect-patterns:
 ---
 
 # Use str.removeprefix/removesuffix

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/stdlib/template-strings.md

@@ -16,6 +16,7 @@ aliases:
 python: ">=3.14"
 frequency: medium
 pep: 750
+detect-patterns:
 ---
 
 # Use Template Strings for Structured String Processing

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/stdlib/tomllib-builtin.md

@@ -14,6 +14,8 @@ aliases:
 python: ">=3.11"
 frequency: medium
 pep: 680
+detect-patterns:
+  - "import toml\b"
 ---
 
 # Use Built-in tomllib

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/toolchain/no-pickle.md

@@ -14,6 +14,9 @@ aliases:
   - shelve
 python: ">=3.9"
 frequency: medium
+detect-patterns:
+  - "import pickle"
+  - "pickle\.(load|loads|dump|dumps)\("
 ---
 
 # Avoid pickle for Untrusted Data

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/toolchain/pyproject-toml-over-setup.md

@@ -15,6 +15,8 @@ aliases:
 python: ">=3.7"
 frequency: high
 pep: 621
+detect-patterns:
+  - "from setuptools import"
 ---
 
 # Use pyproject.toml Instead of setup.py

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/toolchain/ruff-over-flake8.md

@@ -19,6 +19,7 @@ aliases:
   - formatter
 python: ">=3.7"
 frequency: high
+detect-patterns:
 ---
 
 # Use Ruff Instead of Flake8 + isort + Black

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/toolchain/safe-subprocess.md

@@ -14,6 +14,9 @@ aliases:
   - subprocess.run
 python: ">=3.9"
 frequency: high
+detect-patterns:
+  - "os\.system\("
+  - "shell\s*=\s*True"
 ---
 
 # Use subprocess Safely

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/toolchain/uv-over-pip.md

@@ -16,6 +16,7 @@ aliases:
   - venv
 python: ">=3.8"
 frequency: high
+detect-patterns:
 ---
 
 # Use uv Instead of pip

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/typing/deferred-annotations.md

@@ -14,6 +14,8 @@ aliases:
 python: ">=3.14"
 frequency: high
 pep: 649
+detect-patterns:
+  - "from __future__ import annotations"
 ---
 
 # Drop `from __future__ import annotations` on Python 3.14+

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/typing/override-decorator.md

@@ -12,6 +12,7 @@ aliases:
 python: ">=3.12"
 frequency: medium
 pep: 698
+detect-patterns:
 ---
 
 # Use @override to Mark Method Overrides

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/typing/paramspec-decorators.md

@@ -14,6 +14,8 @@ aliases:
 python: ">=3.10"
 frequency: medium
 pep: 612
+detect-patterns:
+  - "Callable\[\.\.\."
 ---
 
 # Use ParamSpec for Typed Decorators

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/typing/type-parameter-syntax.md

@@ -14,6 +14,8 @@ aliases:
 python: ">=3.12"
 frequency: medium
 pep: 695
+detect-patterns:
+  - "from typing import .*\bGeneric\b"
 ---
 
 # Use PEP 695 Type Parameter Syntax

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/typing/typeis-vs-typeguard.md

@@ -14,6 +14,8 @@ aliases:
 python: ">=3.13"
 frequency: low
 pep: 742
+detect-patterns:
+  - "-> TypeGuard\["
 ---
 
 # Use TypeIs for Precise Type Narrowing

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/typing/union-syntax.md

@@ -14,6 +14,8 @@ aliases:
 python: ">=3.10"
 frequency: high
 pep: 604
+detect-patterns:
+  - "from typing import .*\b(Optional|Union)\b"
 ---
 
 # Use X | Y Union Syntax

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/skills/modern-python-guidance/guides/typing/use-builtin-generics.md

@@ -16,6 +16,8 @@ aliases:
 python: ">=3.9"
 frequency: high
 pep: 585
+detect-patterns:
+  - "from typing import .*\b(List|Dict|Set|Tuple|FrozenSet|Type|Deque|DefaultDict|OrderedDict|Counter|ChainMap)\b"
 ---
 
 # Use Built-in Generic Types

{modern_python_guidance-0.3.8 → modern_python_guidance-0.4.0}/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.8"
+__version__ = "0.4.0"

modern_python_guidance-0.4.0/src/modern_python_guidance/check.py

@@ -0,0 +1,146 @@
+"""Scan a Python file for outdated patterns against guide definitions."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from modern_python_guidance.compat import version_compatible
+from modern_python_guidance.guide_index import Guide, GuideIndex, _code_lines
+
+FREQ_RANK = {"high": 0, "medium": 1, "low": 2}
+
+
+class CheckError(Exception):
+    """Raised for unrecoverable file-level errors (not found, binary, unreadable)."""
+
+
+_MAX_LINE_LEN = 10_240
+_BINARY_PROBE_SIZE = 8192
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+_CTRL_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+
+
+@dataclass
+class CheckMatch:
+    line: int
+    source_line: str
+    guide_id: str
+    guide_title: str
+    category: str
+    frequency: str
+    snippet: str
+
+
+def check_file(
+    path: Path,
+    index: GuideIndex,
+    *,
+    python_version: str | None = None,
+) -> list[CheckMatch]:
+    _validate_file(path)
+    text = _read_file(path)
+    if not text:
+        return []
+
+    patterns = _build_patterns(index, python_version=python_version)
+    if not patterns:
+        return []
+
+    matches: list[CheckMatch] = []
+    for lineno, line in enumerate(text.splitlines(), 1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if len(line) > _MAX_LINE_LEN:
+            continue
+
+        for compiled, guide in patterns:
+            if compiled.search(line):
+                matches.append(
+                    CheckMatch(
+                        line=lineno,
+                        source_line=line,
+                        guide_id=guide.meta.id,
+                        guide_title=guide.meta.title,
+                        category=guide.meta.category,
+                        frequency=guide.meta.frequency,
+                        snippet=guide.snippet,
+                    )
+                )
+                break
+
+    return matches
+
+
+def _validate_file(path: Path) -> None:
+    if not path.exists():
+        raise CheckError(f"file not found: {path}")
+    if not path.is_file():
+        raise CheckError(f"not a file: {path}")
+
+
+def _read_file(path: Path) -> str:
+    try:
+        raw = path.read_bytes()
+    except OSError as e:
+        raise CheckError(f"cannot read {path}: {e}") from e
+
+    probe = raw[:_BINARY_PROBE_SIZE]
+    if b"\x00" in probe:
+        raise CheckError(f"binary file: {path}")
+
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return raw.decode("utf-8", errors="replace")
+
+
+def _build_patterns(
+    index: GuideIndex,
+    *,
+    python_version: str | None = None,
+) -> list[tuple[re.Pattern[str], Guide]]:
+    entries: list[tuple[re.Pattern[str], Guide]] = []
+
+    for guide in index.guides.values():
+        if python_version and not version_compatible(guide.meta.python, python_version):
+            continue
+
+        raw_patterns = _get_patterns(guide)
+        for pat_str in raw_patterns:
+            try:
+                compiled = re.compile(pat_str)
+                entries.append((compiled, guide))
+            except re.error:
+                pass
+
+    entries.sort(key=lambda e: (e[1].meta.layer, FREQ_RANK.get(e[1].meta.frequency, 2)))
+    return entries
+
+
+def _get_patterns(guide: Guide) -> list[str]:
+    if guide.meta.detect_patterns is not None:
+        return guide.meta.detect_patterns
+    return _auto_extract_patterns(guide)
+
+
+def _auto_extract_patterns(guide: Guide) -> list[str]:
+    bad_lines = _code_lines(guide.body, "## BAD")
+    patterns: list[str] = []
+    for line in bad_lines:
+        stripped = line.strip()
+        if stripped.startswith(("from ", "import ")):
+            escaped = re.escape(stripped)
+            patterns.append(escaped)
+        elif stripped.startswith("@"):
+            parts = stripped.split("(", 1)
+            escaped = re.escape(parts[0])
+            patterns.append(escaped)
+    return patterns
+
+
+def sanitize_line(text: str) -> str:
+    text = _ANSI_RE.sub("", text)
+    return _CTRL_RE.sub("", text)