modern-python-guidance 0.1.1__tar.gz → 0.1.2__tar.gz

{modern_python_guidance-0.1.1 → modern_python_guidance-0.1.2}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.2] — 2026-05-26
+
+### Changed
+
+- SKILL.md: replace inventory tables with 9 embedded BAD→GOOD arrow-list patterns (high-frequency × Ruff-uncovered) for pre-generation injection without MCP tool calls
+- README: Quick start example changed from `use-builtin-generics` to `pydantic-v2-validators` (Layer 2 differentiation)
+
+### Added
+
+- MIT license (dual-licensed under Apache-2.0 OR MIT)
+- `test_skill_sync.py`: 8 sync tests for SKILL.md ↔ guide file consistency (V-001/V-002/V-009/V-010)
+
 ## [0.1.1] — 2026-05-25
 
 ### Added
@@ -30,5 +42,6 @@ Initial release.
 - Strict YAML-subset frontmatter parser (no PyYAML dependency)
 - GitHub Actions CI (pytest + ruff on Python 3.11, 3.12, 3.13)
 
+[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
 [0.1.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.0

modern_python_guidance-0.1.2/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iori Yoshida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{modern_python_guidance-0.1.1 → modern_python_guidance-0.1.2}/PKG-INFO

@@ -1,18 +1,20 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.1.1
+Version: 0.1.2
 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
 Project-URL: Issues, https://github.com/yottayoshida/modern-python-guidance/issues
 Author-email: Iori Yoshida <i.yoshida@raksul.com>
-License-Expression: Apache-2.0
+License-Expression: Apache-2.0 OR MIT
 License-File: LICENSE
+License-File: LICENSE-MIT
 Keywords: ai,coding-agent,guidance,linter,modernization,python
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -45,17 +47,17 @@ LLMs often produce outdated Python — `typing.List` instead of `list`, `@valida
 pip install modern-python-guidance
 
 # Search for a pattern
-mpg search "typing list"
-#   use-builtin-generics                     score=18.0  [typing]
+mpg search "pydantic validator"
+#   pydantic-v2-validators                   score=18.0  [pydantic]
 
 # Get the full guide
-mpg retrieve use-builtin-generics
-# --- use-builtin-generics (version match: YES) ---
+mpg retrieve pydantic-v2-validators
+# --- pydantic-v2-validators (version match: YES) ---
 # ## BAD
-# from typing import List, Dict, Optional
+# @validator("name")
 # ...
 # ## GOOD
-# names: list[str] = []
+# @field_validator("name")
 # ...
 ```
 
@@ -212,4 +214,4 @@ Contributions welcome! To add a new guide:
 
 ## License
 
-Apache-2.0 — see [LICENSE](LICENSE).
+Apache-2.0 OR MIT — see [LICENSE](LICENSE) and [LICENSE-MIT](LICENSE-MIT).

{modern_python_guidance-0.1.1 → modern_python_guidance-0.1.2}/README.md

@@ -16,17 +16,17 @@ LLMs often produce outdated Python — `typing.List` instead of `list`, `@valida
 pip install modern-python-guidance
 
 # Search for a pattern
-mpg search "typing list"
-#   use-builtin-generics                     score=18.0  [typing]
+mpg search "pydantic validator"
+#   pydantic-v2-validators                   score=18.0  [pydantic]
 
 # Get the full guide
-mpg retrieve use-builtin-generics
-# --- use-builtin-generics (version match: YES) ---
+mpg retrieve pydantic-v2-validators
+# --- pydantic-v2-validators (version match: YES) ---
 # ## BAD
-# from typing import List, Dict, Optional
+# @validator("name")
 # ...
 # ## GOOD
-# names: list[str] = []
+# @field_validator("name")
 # ...
 ```
 
@@ -183,4 +183,4 @@ Contributions welcome! To add a new guide:
 
 ## License
 
-Apache-2.0 — see [LICENSE](LICENSE).
+Apache-2.0 OR MIT — see [LICENSE](LICENSE) and [LICENSE-MIT](LICENSE-MIT).

{modern_python_guidance-0.1.1 → modern_python_guidance-0.1.2}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.1.1"
+version = "0.1.2"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
-license = "Apache-2.0"
+license = "Apache-2.0 OR MIT"
 requires-python = ">=3.11"
 authors = [
     { name = "Iori Yoshida", email = "i.yoshida@raksul.com" },
@@ -18,6 +18,7 @@ classifiers = [
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
+    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",

modern_python_guidance-0.1.2/skills/modern-python-guidance/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: modern-python-guidance
+description: Version-aware BAD/GOOD pattern guides for modern Python. Use when writing, reviewing, or refactoring Python code to avoid outdated patterns (e.g. typing.List → list, @validator → @field_validator, setup.py → pyproject.toml). Triggers on "Python", "modernize", "upgrade", "deprecated", "pydantic", "fastapi", "httpx", "typing", "dataclass", "asyncio".
+---
+
+# 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`
+
+### 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 30 guides by category
+
+- **typing** (6): `use-builtin-generics`, `union-syntax`, `type-parameter-syntax`, `override-decorator`, `typeis-vs-typeguard`, `paramspec-decorators`
+- **async** (3): `taskgroup-over-gather`, `exception-groups`, `async-timeout-context`
+- **stdlib** (4): `datetime-utc`, `pathlib-over-os-path`, `tomllib-builtin`, `removeprefix-removesuffix`
+- **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`
+- **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.1.2/tests/test_skill_sync.py

@@ -0,0 +1,126 @@
+"""Sync tests: verify SKILL.md stays consistent with guide files and README.
+
+Verification IDs from /plan QA shift-left:
+  V-001  SKILL.md guide IDs reference existing guide files
+  V-002  SKILL.md token count <= 1300 (chars/4)
+  V-009  All embedded guide IDs have frequency: high
+  V-010  README Quick start guide IDs reference existing guide files
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+from modern_python_guidance.guide_index import build_index
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILL_MD = REPO_ROOT / "skills" / "modern-python-guidance" / "SKILL.md"
+README_MD = REPO_ROOT / "README.md"
+GUIDES_DIR = REPO_ROOT / "skills" / "modern-python-guidance" / "guides"
+
+EMBEDDED_GUIDE_IDS = [
+    "pydantic-v2-validators",
+    "pydantic-v2-config",
+    "pydantic-v2-model-api",
+    "fastapi-lifespan",
+    "fastapi-annotated-depends",
+    "httpx-async-client-reuse",
+    "taskgroup-over-gather",
+    "pyproject-toml-over-setup",
+    "safe-subprocess",
+]
+
+
+@pytest.fixture(scope="module")
+def guide_index():
+    return build_index(GUIDES_DIR)
+
+
+@pytest.fixture(scope="module")
+def skill_text():
+    return SKILL_MD.read_text(encoding="utf-8")
+
+
+@pytest.fixture(scope="module")
+def readme_text():
+    return README_MD.read_text(encoding="utf-8")
+
+
+def _extract_backtick_ids(text: str) -> list[str]:
+    """Extract guide IDs from backtick-quoted strings in the catalog section."""
+    return re.findall(r"`([a-z][a-z0-9-]+)`", text)
+
+
+class TestV001SkillGuideSync:
+    """V-001: SKILL.md guide IDs reference existing guide files."""
+
+    def test_embedded_guides_exist(self, guide_index):
+        for guide_id in EMBEDDED_GUIDE_IDS:
+            assert guide_index.get(guide_id) is not None, (
+                f"Embedded guide '{guide_id}' not found in guides/"
+            )
+
+    def test_catalog_heading_exists(self, skill_text):
+        assert "## All 30 guides by category" in skill_text, (
+            "Catalog heading missing from SKILL.md"
+        )
+
+    def test_catalog_ids_exist(self, skill_text, guide_index):
+        catalog_section = skill_text.split("## All 30 guides by category")[-1]
+        ids_in_catalog = _extract_backtick_ids(catalog_section)
+        for guide_id in ids_in_catalog:
+            assert guide_index.get(guide_id) is not None, (
+                f"Catalog guide '{guide_id}' not found in guides/"
+            )
+
+    def test_catalog_count_matches(self, guide_index, skill_text):
+        assert "30 guides" in skill_text
+        assert len(guide_index) == 30, (
+            f"SKILL.md says 30 guides but found {len(guide_index)}"
+        )
+
+    def test_catalog_covers_all_guides(self, skill_text, guide_index):
+        """Reverse check: every guide ID appears in the catalog section."""
+        catalog_section = skill_text.split("## All 30 guides by category")[-1]
+        catalog_ids = set(_extract_backtick_ids(catalog_section))
+        for guide_id in guide_index.guides:
+            assert guide_id in catalog_ids, (
+                f"Guide '{guide_id}' exists in guides/ but missing from catalog"
+            )
+
+
+class TestV002TokenBudget:
+    """V-002: SKILL.md token count <= 1300 (chars/4)."""
+
+    def test_token_budget(self, skill_text):
+        tokens = len(skill_text) // 4
+        assert tokens <= 1300, (
+            f"SKILL.md is {tokens} tokens (chars/4), budget is 1300"
+        )
+
+
+class TestV009EmbeddedFrequency:
+    """V-009: All embedded guide IDs have frequency: high."""
+
+    def test_all_high_frequency(self, guide_index):
+        for guide_id in EMBEDDED_GUIDE_IDS:
+            guide = guide_index.get(guide_id)
+            assert guide is not None, f"Guide '{guide_id}' not found"
+            assert guide.meta.frequency == "high", (
+                f"Embedded guide '{guide_id}' has frequency "
+                f"'{guide.meta.frequency}', expected 'high'"
+            )
+
+
+class TestV010ReadmeGuideIds:
+    """V-010: README Quick start guide IDs reference existing guide files."""
+
+    def test_readme_guide_ids_exist(self, readme_text, guide_index):
+        ids_in_readme = re.findall(r"mpg retrieve\s+([a-z][a-z0-9-]+)", readme_text)
+        for guide_id in ids_in_readme:
+            assert guide_index.get(guide_id) is not None, (
+                f"README references guide '{guide_id}' which doesn't exist"
+            )

modern_python_guidance-0.1.1/skills/modern-python-guidance/SKILL.md

@@ -1,104 +0,0 @@
----
-name: modern-python-guidance
-description: Version-aware BAD/GOOD pattern guides for modern Python. Use when writing, reviewing, or refactoring Python code to avoid outdated patterns (e.g. typing.List → list, @validator → @field_validator, setup.py → pyproject.toml). Triggers on "Python", "modernize", "upgrade", "deprecated", "pydantic", "fastapi", "httpx", "typing", "dataclass", "asyncio".
----
-
-# Modern Python Guidance
-
-Version-aware BAD → GOOD pattern guides for modern Python (3.9–3.13+).
-
-When writing or reviewing Python code, consult these guides to ensure modern idioms are used instead of deprecated or outdated patterns. Each guide shows a concrete BAD example, the modern GOOD replacement, and explains why the change matters.
-
-## 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)
-
-## Guide inventory (30 guides)
-
-### Layer 1 — Standard Library & Language Features
-
-| Category | Guide | Python | What it replaces |
-|----------|-------|--------|-----------------|
-| typing | `use-builtin-generics` | >=3.9 | `typing.List` → `list` |
-| typing | `union-syntax` | >=3.10 | `Optional[X]` → `X \| None` |
-| typing | `type-parameter-syntax` | >=3.12 | `TypeVar("T")` → `[T]` |
-| typing | `override-decorator` | >=3.12 | manual override → `@override` |
-| typing | `typeis-vs-typeguard` | >=3.13 | `TypeGuard` → `TypeIs` |
-| typing | `paramspec-decorators` | >=3.10 | untyped decorators → `ParamSpec` |
-| async | `taskgroup-over-gather` | >=3.11 | `gather()` → `TaskGroup` |
-| async | `exception-groups` | >=3.11 | multi-error handling → `except*` |
-| async | `async-timeout-context` | >=3.11 | `wait_for()` → `asyncio.timeout` |
-| stdlib | `datetime-utc` | >=3.11 | `utcnow()` → `now(UTC)` |
-| stdlib | `pathlib-over-os-path` | >=3.9 | `os.path` → `pathlib.Path` |
-| stdlib | `tomllib-builtin` | >=3.11 | `toml` package → `tomllib` |
-| stdlib | `removeprefix-removesuffix` | >=3.9 | `lstrip()`/slicing → `removeprefix()` |
-| data-structures | `dict-merge-operator` | >=3.9 | `{**d1, **d2}` → `d1 \| d2` |
-| data-structures | `match-case-patterns` | >=3.10 | nested if/isinstance → `match`/`case` |
-| data-structures | `dataclass-modern` | >=3.10 | basic dataclass → `slots=True, kw_only=True` |
-
-### Layer 2 — Popular Frameworks
-
-| Category | Guide | What it replaces |
-|----------|-------|-----------------|
-| pydantic | `pydantic-v2-model-api` | `parse_obj()` → `model_validate()` |
-| pydantic | `pydantic-v2-validators` | `@validator` → `@field_validator` |
-| pydantic | `pydantic-v2-config` | `class Config` → `model_config = ConfigDict(...)` |
-| pydantic | `pydantic-v2-serialization` | `json_encoders` → `@field_serializer` |
-| fastapi | `fastapi-lifespan` | `@on_event` → lifespan context manager |
-| fastapi | `fastapi-annotated-depends` | `Depends()` default → `Annotated[T, Depends()]` |
-| fastapi | `fastapi-typed-state` | untyped `app.state` → typed state via lifespan |
-| httpx | `httpx-async-client-reuse` | per-request client → shared `AsyncClient` |
-| httpx | `httpx-streaming` | `response.content` → `client.stream()` |
-
-### Layer 3 — Toolchain & Security
-
-| Category | Guide | What it replaces |
-|----------|-------|-----------------|
-| toolchain | `pyproject-toml-over-setup` | `setup.py` → `pyproject.toml` |
-| toolchain | `uv-over-pip` | `pip` → `uv` |
-| toolchain | `ruff-over-flake8` | flake8+isort+black → `ruff` |
-| toolchain | `no-pickle` | `pickle.load()` → safe alternatives |
-| toolchain | `safe-subprocess` | `shell=True` → list arguments |
-
-## How to look up a guide
-
-Each guide is a markdown file in `guides/<category>/<id>.md` with YAML frontmatter containing:
-- `id`: unique identifier
-- `python`: minimum Python version (e.g. `">=3.11"`)
-- `frequency`: how often LLMs generate the outdated pattern (`high`/`medium`/`low`)
-- `layer`: 1 (stdlib), 2 (frameworks), 3 (toolchain)
-
-### Reading a guide directly
-
-Open `guides/<category>/<guide-id>.md` for the full BAD/GOOD comparison.
-
-### Using the CLI
-
-```bash
-# Search by keyword
-mpg search "typing list"
-
-# Retrieve full guide content
-mpg retrieve use-builtin-generics
-
-# List all guides for a Python version
-mpg list --python-version 3.11
-
-# Detect project Python version
-mpg detect-version
-```
-
-## Integration pattern for agents
-
-When generating Python code:
-
-1. Check if the target Python version is known (from `pyproject.toml`, `.python-version`, or context)
-2. For each pattern you're about to write, check if a guide exists for a modern replacement
-3. Use the GOOD pattern instead of the BAD pattern
-4. If the target Python version is too old for the modern pattern, use the older pattern and note it
-
-Example: if writing `from typing import List` for a Python 3.9+ project, use `list` instead (see `use-builtin-generics`).