modern-python-guidance 0.3.1__tar.gz → 0.3.2__tar.gz

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.2] — 2026-05-29
+
+### Added
+
+- `deferred-annotations` guide (PEP 649): drop unnecessary `from __future__ import annotations` on Python 3.14+ projects where annotations are lazily evaluated by default (closes #28)
+- `template-strings` guide (PEP 750): use t-strings with processing functions for safe SQL/HTML parameterization instead of f-string interpolation (closes #28)
+- Guide count: 39 → 41. Layer 1 coverage: 16 → 18
+
+### Fixed
+
+- `setup_mcp` now catches `OSError` from `subprocess.run`, matching `uninstall_mcp` behavior — an unexecutable `claude` binary produces a clean error message instead of a traceback (closes #65)
+- MCP `retrieve_guides` schema `maxItems` and runtime guard updated from 39 to 41 to allow retrieval of all guides
+
 ## [0.3.1] — 2026-05-29
 
 ### Added
@@ -117,6 +130,8 @@ Initial release.
 - Strict YAML-subset frontmatter parser (no PyYAML dependency)
 - GitHub Actions CI (pytest + ruff on Python 3.11, 3.12, 3.13)
 
+[0.3.2]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.3.2
+[0.3.1]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.3.1
 [0.3.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.3.0
 [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

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/CONTRIBUTING.md

@@ -15,7 +15,7 @@ src/modern_python_guidance/
 
 skills/modern-python-guidance/
 ├── SKILL.md            # Agent Skills plugin entry point
-└── guides/             # 39 guide files by category
+└── guides/             # 41 guide files by category
 ```
 
 See [docs/design.md](docs/design.md) for the full design document.

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.3.1
+Version: 0.3.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
@@ -36,12 +36,12 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/modern-python-guidance.svg)](https://pypi.org/project/modern-python-guidance/)
 [![License](https://img.shields.io/github/license/yottayoshida/modern-python-guidance.svg)](LICENSE)
 
-Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.
+Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 41 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.
 
 ## Highlights
 
 - **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
+- **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
 - **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
@@ -144,15 +144,15 @@ mpg search "typing" --format json | jq '.[0].id'
 
 ## Guide coverage
 
-39 guides across 3 layers:
+41 guides across 3 layers:
 
 | Layer | Categories | Count | Examples |
 |-------|-----------|-------|---------|
-| **1 — stdlib** | typing, async, stdlib, data-structures | 16 | `list` over `List`, `match`/`case`, `TaskGroup` |
+| **1 — stdlib** | typing, async, stdlib, data-structures | 18 | `list` over `List`, `match`/`case`, `TaskGroup`, deferred annotations, t-strings |
 | **2 — frameworks** | pydantic, fastapi, httpx, django, sqlalchemy, pytest | 18 | Pydantic V2 migration, SQLAlchemy 2.0 style, `Annotated[Depends]` |
 | **3 — toolchain** | toolchain | 5 | `uv` over `pip`, `ruff` over flake8, `pickle` avoidance |
 
-Run `mpg list` to see all 39 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
+Run `mpg list` to see all 41 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
 
 ## Version-aware filtering
 

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/README.md

@@ -5,12 +5,12 @@
 [![Python](https://img.shields.io/pypi/pyversions/modern-python-guidance.svg)](https://pypi.org/project/modern-python-guidance/)
 [![License](https://img.shields.io/github/license/yottayoshida/modern-python-guidance.svg)](LICENSE)
 
-Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 39 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.
+Stop your AI from writing `typing.List`, `@validator`, and `setup.py`. 41 version-aware BAD/GOOD pattern guides that teach AI coding agents to write modern Python — delivered via MCP, CLI, or Agent Skills.
 
 ## Highlights
 
 - **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
+- **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
 - **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
@@ -113,15 +113,15 @@ mpg search "typing" --format json | jq '.[0].id'
 
 ## Guide coverage
 
-39 guides across 3 layers:
+41 guides across 3 layers:
 
 | Layer | Categories | Count | Examples |
 |-------|-----------|-------|---------|
-| **1 — stdlib** | typing, async, stdlib, data-structures | 16 | `list` over `List`, `match`/`case`, `TaskGroup` |
+| **1 — stdlib** | typing, async, stdlib, data-structures | 18 | `list` over `List`, `match`/`case`, `TaskGroup`, deferred annotations, t-strings |
 | **2 — frameworks** | pydantic, fastapi, httpx, django, sqlalchemy, pytest | 18 | Pydantic V2 migration, SQLAlchemy 2.0 style, `Annotated[Depends]` |
 | **3 — toolchain** | toolchain | 5 | `uv` over `pip`, `ruff` over flake8, `pickle` avoidance |
 
-Run `mpg list` to see all 39 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
+Run `mpg list` to see all 41 guides, or [browse them on GitHub](skills/modern-python-guidance/guides/).
 
 ## Version-aware filtering
 

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/docs/design.md

@@ -52,7 +52,7 @@ LLMs frequently generate outdated Python patterns: `typing.List` instead of `lis
 │  typing/ async/ stdlib/ data-structures/                │
 │  pydantic/ fastapi/ httpx/ toolchain/                   │
 │  django/ sqlalchemy/ pytest/                            │
-│  (39 guide files)                                       │
+│  (41 guide files)                                       │
 └─────────────────────────────────────────────────────────┘
 ```
 

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.3.1"
+version = "0.3.2"
 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.1 → modern_python_guidance-0.3.2}/skills/modern-python-guidance/SKILL.md

@@ -55,11 +55,11 @@ Pre-generation design patterns that Ruff cannot auto-fix. Apply these transforma
 - `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 39 guides by category
+## All 41 guides by category
 
-- **typing** (6): `use-builtin-generics`, `union-syntax`, `type-parameter-syntax`, `override-decorator`, `typeis-vs-typeguard`, `paramspec-decorators`
+- **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** (4): `datetime-utc`, `pathlib-over-os-path`, `tomllib-builtin`, `removeprefix-removesuffix`
+- **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`

modern_python_guidance-0.3.2/skills/modern-python-guidance/guides/stdlib/template-strings.md

@@ -0,0 +1,70 @@
+---
+id: template-strings
+title: Use Template Strings (t-strings) for Structured String Processing
+category: stdlib
+layer: 1
+tags:
+  - strings
+  - templates
+  - security
+  - sql
+aliases:
+  - t-string
+  - 't"'
+  - Template
+  - string.templatelib
+python: ">=3.14"
+frequency: medium
+pep: 750
+---
+
+# Use Template Strings for Structured String Processing
+
+Python 3.14 introduces t-strings (PEP 750): a `t"..."` prefix that produces a `Template` object instead of a `str`. Pass the `Template` to a processing function that separates literal text from interpolated values, enabling safe parameterization for SQL, HTML, shell commands, and other injection-sensitive contexts.
+
+## BAD
+
+```python
+def query_user(db, user_id: str) -> dict:
+    sql = f"SELECT * FROM users WHERE id = '{user_id}'"
+    return db.execute(sql).fetchone()
+```
+
+## GOOD
+
+```python
+from string.templatelib import Interpolation
+
+def sql(template) -> tuple[str, list]:
+    parts, params = [], []
+    for item in template:
+        if isinstance(item, Interpolation):
+            parts.append("?")
+            params.append(item.value)
+        else:
+            parts.append(item)
+    return "".join(parts), params
+
+def query_user(db, user_id: str) -> dict:
+    query, params = sql(t"SELECT * FROM users WHERE id = {user_id}")
+    return db.execute(query, params).fetchone()
+```
+
+## Why
+
+- f-strings produce a final `str` with interpolated values already baked in, making it impossible to distinguish user input from literal SQL after the fact
+- t-strings produce a `Template` that preserves the structure: literal segments as strings, interpolated values as `Interpolation` objects with `value`, `expression`, `conversion`, and `format_spec` attributes
+- A processing function can then route each interpolated value through proper escaping or parameterization, preventing injection by construction
+- t-strings do NOT make strings safe by themselves -- safety comes entirely from the processing function that receives the `Template`
+
+## Version Notes
+
+- 3.14+: `t"..."` syntax and `string.templatelib` module (`Template`, `Interpolation`)
+- Pre-3.14: Use parameterized queries directly (`db.execute("SELECT ... WHERE id = ?", [user_id])`) or template engines with auto-escaping
+- For simple string formatting where injection is not a concern, f-strings remain the appropriate choice
+- `Template` objects do not render to `str` automatically -- a processing function is always required
+
+## References
+
+- [PEP 750 -- Template Strings](https://peps.python.org/pep-0750/)
+- [string.templatelib documentation](https://docs.python.org/3/library/string.templatelib.html)

modern_python_guidance-0.3.2/skills/modern-python-guidance/guides/typing/deferred-annotations.md

@@ -0,0 +1,63 @@
+---
+id: deferred-annotations
+title: 'Drop "from __future__ import annotations" on Python 3.14+'
+category: typing
+layer: 1
+tags:
+  - type-hints
+  - annotations
+  - forward-reference
+aliases:
+  - "from __future__ import annotations"
+  - "__future__.annotations"
+  - ForwardRef
+python: ">=3.14"
+frequency: high
+pep: 649
+---
+
+# Drop `from __future__ import annotations` on Python 3.14+
+
+On Python 3.14+, annotations are lazily evaluated by default (PEP 649). The `from __future__ import annotations` import is no longer needed for forward references in 3.14-only projects.
+
+## BAD
+
+```python
+from __future__ import annotations
+
+class Tree:
+    left: Tree | None = None
+    right: Tree | None = None
+
+    def children(self) -> list[Tree]:
+        return [c for c in (self.left, self.right) if c]
+```
+
+## GOOD
+
+```python
+class Tree:
+    left: Tree | None = None
+    right: Tree | None = None
+
+    def children(self) -> list[Tree]:
+        return [c for c in (self.left, self.right) if c]
+```
+
+## Why
+
+- Python 3.14 evaluates annotations lazily by default, so forward references like `Tree` inside the `Tree` class body just work
+- The future import forces all-string semantics (PEP 563), which is different from 3.14's lazy evaluation and can interact poorly with runtime annotation consumers
+- Removing the unnecessary import keeps the module cleaner and avoids the subtle behavioral difference between stringified and lazily-evaluated annotations
+
+## Version Notes
+
+- 3.14+: Annotations are lazily evaluated by default. Remove `from __future__ import annotations` in 3.14-only projects
+- Pre-3.14: The future import remains the correct way to enable string annotations for forward references
+- `from __future__ import annotations` is deprecated but NOT removed in 3.14. It still works but forces all-string semantics. Removal is not expected before Python 3.13 EOL (~2029)
+- Libraries that read annotations at runtime (`typing.get_type_hints()`, Pydantic, FastAPI, attrs) may need updates for 3.14's lazy evaluation. Verify library compatibility before removing the import in projects that depend on runtime annotation inspection
+
+## References
+
+- [PEP 649 -- Deferred Evaluation of Annotations Using Descriptors](https://peps.python.org/pep-0649/)
+- [PEP 749 -- Implementing PEP 649](https://peps.python.org/pep-0749/)

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/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.1"
+__version__ = "0.3.2"

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/src/modern_python_guidance/mcp_server.py

@@ -121,8 +121,8 @@ TOOLS = [
                 "guide_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Guide IDs to retrieve (max 39)",
-                    "maxItems": 39,
+                    "description": "Guide IDs to retrieve (max 41)",
+                    "maxItems": 41,
                 },
                 "python_version": {
                     "type": "string",
@@ -269,8 +269,8 @@ def _tool_retrieve(arguments: dict) -> dict:
     guide_ids = arguments.get("guide_ids", [])
     if not guide_ids:
         return _tool_result("guide_ids is required and must not be empty", is_error=True)
-    if len(guide_ids) > 39:
-        return _tool_result("guide_ids exceeds maximum of 39", is_error=True)
+    if len(guide_ids) > 41:
+        return _tool_result("guide_ids exceeds maximum of 41", is_error=True)
 
     pv = arguments.get("python_version")
     err = _validate_python_version(pv)

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/src/modern_python_guidance/setup_cmd.py

@@ -92,6 +92,9 @@ def setup_mcp(
     except subprocess.TimeoutExpired:
         print("Error: 'claude mcp add' timed out after 30 seconds.", file=sys.stderr)
         return False
+    except OSError as e:
+        print(f"Error: failed to run 'claude mcp add': {e}", file=sys.stderr)
+        return False
 
     if result.returncode != 0:
         stderr_text = result.stderr.decode(errors="replace").strip()

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/tests/test_setup.py

@@ -131,6 +131,22 @@ class TestSetupMcp:
         assert ok is False
         assert "failed" in capsys.readouterr().err
 
+    def test_oserror_fails_gracefully(self, capsys: pytest.CaptureFixture[str]):
+        """V-036: claude on PATH but unexecutable (OSError) -> failure, no traceback."""
+        with (
+            patch(
+                "modern_python_guidance.setup_cmd.shutil.which",
+                return_value="/usr/bin/claude",
+            ),
+            patch(
+                "modern_python_guidance.setup_cmd.subprocess.run",
+                side_effect=OSError("Exec format error"),
+            ),
+        ):
+            ok = setup_mcp()
+        assert ok is False
+        assert "failed to run" in capsys.readouterr().err
+
     def test_dry_run(self, capsys: pytest.CaptureFixture[str]):
         """V-010: dry-run does not invoke subprocess."""
         with (

{modern_python_guidance-0.3.1 → modern_python_guidance-0.3.2}/tests/test_skill_sync.py

@@ -66,12 +66,12 @@ class TestV001SkillGuideSync:
             )
 
     def test_catalog_heading_exists(self, skill_text):
-        assert "## All 39 guides by category" in skill_text, (
+        assert "## All 41 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 39 guides by category")[-1]
+        catalog_section = skill_text.split("## All 41 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, (
@@ -79,14 +79,14 @@ class TestV001SkillGuideSync:
             )
 
     def test_catalog_count_matches(self, guide_index, skill_text):
-        assert "39 guides" in skill_text
-        assert len(guide_index) == 39, (
-            f"SKILL.md says 39 guides but found {len(guide_index)}"
+        assert "41 guides" in skill_text
+        assert len(guide_index) == 41, (
+            f"SKILL.md says 41 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 39 guides by category")[-1]
+        catalog_section = skill_text.split("## All 41 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, (