modern-python-guidance 0.4.3__tar.gz → 0.4.5__tar.gz

{modern_python_guidance-0.4.3 → modern_python_guidance-0.4.5}/.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4

{modern_python_guidance-0.4.3 → modern_python_guidance-0.4.5}/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.5] — 2026-06-06
+
+### Fixed
+
+- MCP `retrieve_guides` maxItems hardcoded to 41: replaced with `_guide_limit()` that derives the limit from actual guide count at runtime. `_get_tools()` dynamically injects `maxItems` and description into the `tools/list` schema. Adding new guides no longer requires updating `mcp_server.py`. (closes #98)
+- `docs/design.md` out of sync with v0.4.4 implementation: consolidated overlapping non-goals, added `check`/`setup`/`uninstall` to CLI architecture diagram, added `check.py`, `setup_cmd.py`, `uninstall_cmd.py`, `mcp_server.py` to module responsibility table, fixed Layer 1 guide count from 16 to 18. (closes #99)
+
+### Added
+
+- 1 new test (1000 total).
+
+## [0.4.4] — 2026-06-05
+
+### Added
+
+- Poetry constraint parsing: `detect_version()` now extracts the minimum Python version from `[tool.poetry.dependencies].python` instead of only logging a warning. Supported forms: caret (`^3.10`), tilde (`~3.11`), PEP 440 (`>=3.10,<3.14`), and dict-form (`{version = "^3.10"}`). Union operators (`||`) and unsupported formats warn and fall through to `.python-version` / default. (closes #95)
+- Python 3.14 added to CI test matrix as a regular (non-allowed-failure) entry. Python 3.14 has been GA since 2025-10-07; pyproject.toml classifiers already declared support. (closes #94)
+- 12 new tests (999 total).
+
 ## [0.4.3] — 2026-06-04
 
 ### Fixed

{modern_python_guidance-0.4.3 → modern_python_guidance-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.4.3
+Version: 0.4.5
 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
@@ -166,8 +166,9 @@ Guides specify their minimum Python version. The CLI auto-detects your project's
 
 1. `--python-version` flag
 2. `pyproject.toml` `requires-python`
-3. `.python-version` file
-4. Default: 3.11
+3. `pyproject.toml` Poetry `python` constraint (`^3.10`, `~3.11`, `>=3.10,<3.14`)
+4. `.python-version` file
+5. Default: 3.11
 
 ```bash
 # Only shows guides compatible with Python 3.9

{modern_python_guidance-0.4.3 → modern_python_guidance-0.4.5}/README.md

@@ -134,8 +134,9 @@ Guides specify their minimum Python version. The CLI auto-detects your project's
 
 1. `--python-version` flag
 2. `pyproject.toml` `requires-python`
-3. `.python-version` file
-4. Default: 3.11
+3. `pyproject.toml` Poetry `python` constraint (`^3.10`, `~3.11`, `>=3.10,<3.14`)
+4. `.python-version` file
+5. Default: 3.11
 
 ```bash
 # Only shows guides compatible with Python 3.9

{modern_python_guidance-0.4.3 → modern_python_guidance-0.4.5}/docs/design.md

@@ -14,16 +14,16 @@ LLMs frequently generate outdated Python patterns: `typing.List` instead of `lis
 
 ## Non-goals
 
-- Automated code transformation (this is a reference tool, not a codemod)
+- Automated code transformation / codemod (the `check` command scans for outdated patterns via regex + tokenize, but does not rewrite code)
 - Language Server Protocol integration
-- Pattern detection in source code (no AST analysis)
 
 ## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────┐
 │ CLI (cli.py)                                            │
-│  search │ retrieve │ list │ detect-version              │
+│  search │ retrieve │ list │ detect-version │ check      │
+│  setup │ uninstall                                      │
 ├─────────┴──────────┴──────┴─────────────────────────────┤
 │                                                         │
 │  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  │
@@ -67,6 +67,10 @@ LLMs frequently generate outdated Python patterns: `typing.List` instead of `lis
 | `retrieve.py` | Renders guide content as JSON with version-match flag and token estimate |
 | `version_detect.py` | Detects target Python version from `--python-version` flag, `pyproject.toml` (`requires-python`), `.python-version` file, or default (3.11) |
 | `compat.py` | `version_compatible()` using `packaging.specifiers` and `token_estimate()` (chars / 4) |
+| `check.py` | Scan a Python file for outdated patterns against guide definitions (regex + tokenize, not AST) |
+| `setup_cmd.py` | Automate MCP server registration and Agent Skills symlink creation |
+| `uninstall_cmd.py` | Reverse `mpg setup`: deregister the MCP server and remove the Skills symlink |
+| `mcp_server.py` | MCP server — JSON-RPC 2.0 over stdio, zero external dependencies |
 
 ## Guide format
 
@@ -150,10 +154,9 @@ Fuzzy results are marked with `fuzzy: true` in the output.
 
 1. `--python-version` CLI flag (explicit override)
 2. `pyproject.toml` `[project].requires-python` (PEP 621)
-3. `.python-version` file (pyenv/asdf convention)
-4. Default: `3.11`
-
-Poetry's caret syntax (`^3.11`) is detected but not parsed — the tool logs a warning and suggests using `--python-version` or adding `[project].requires-python`.
+3. `pyproject.toml` `[tool.poetry.dependencies].python` — caret (`^3.10`), tilde (`~3.11`), and PEP 440 (`>=3.10,<3.14`) constraints are parsed to extract the minimum version. Dict-form (`{version = "^3.10"}`) is also supported. Union operators (`||`) are not supported and fall through with a warning.
+4. `.python-version` file (pyenv/asdf convention)
+5. Default: `3.11`
 
 ## Output format
 
@@ -198,7 +201,7 @@ The CLI defaults to JSON when piped and human-readable when attached to a TTY. T
 
 | Layer | Scope | Categories | Count |
 |-------|-------|-----------|-------|
-| 1 — stdlib | Python standard library | typing, async, stdlib, data-structures | 16 |
+| 1 — stdlib | Python standard library | typing, async, stdlib, data-structures | 18 |
 | 2 — frameworks | Third-party frameworks | pydantic, fastapi, httpx, django, sqlalchemy, pytest | 18 |
 | 3 — toolchain | Development tools | toolchain | 5 |
 

{modern_python_guidance-0.4.3 → modern_python_guidance-0.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.4.3"
+version = "0.4.5"
 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.4.3 → modern_python_guidance-0.4.5}/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.4.3"
+__version__ = "0.4.5"

{modern_python_guidance-0.4.3 → modern_python_guidance-0.4.5}/src/modern_python_guidance/mcp_server.py

@@ -26,6 +26,30 @@ def _get_index() -> GuideIndex:
     return _index
 
 
+def _guide_limit() -> int:
+    return len(_get_index())
+
+
+def _get_tools() -> list[dict]:
+    n = _guide_limit()
+    tools = list(TOOLS)
+    tools[1] = {
+        **TOOLS[1],
+        "inputSchema": {
+            **TOOLS[1]["inputSchema"],
+            "properties": {
+                **TOOLS[1]["inputSchema"]["properties"],
+                "guide_ids": {
+                    **TOOLS[1]["inputSchema"]["properties"]["guide_ids"],
+                    "maxItems": n,
+                    "description": f"Guide IDs to retrieve (max {n})",
+                },
+            },
+        },
+    }
+    return tools
+
+
 # --- JSON-RPC framing (newline-delimited JSON) ---
 
 
@@ -122,8 +146,7 @@ TOOLS = [
                 "guide_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Guide IDs to retrieve (max 41)",
-                    "maxItems": 41,
+                    "description": "Guide IDs to retrieve",
                 },
                 "python_version": {
                     "type": "string",
@@ -270,8 +293,9 @@ 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) > 41:
-        return _tool_result("guide_ids exceeds maximum of 41", is_error=True)
+    limit = _guide_limit()
+    if len(guide_ids) > limit:
+        return _tool_result(f"guide_ids exceeds maximum of {limit}", is_error=True)
 
     pv = arguments.get("python_version")
     err = _validate_python_version(pv)
@@ -371,7 +395,7 @@ def _handle_request(msg: dict) -> dict | None:
         return None if is_notification else result
 
     if method == "tools/list":
-        result = _result_response(req_id, {"tools": TOOLS})
+        result = _result_response(req_id, {"tools": _get_tools()})
         return None if is_notification else result
 
     if method == "tools/call":

{modern_python_guidance-0.4.3 → modern_python_guidance-0.4.5}/src/modern_python_guidance/version_detect.py

@@ -3,8 +3,9 @@
 Precedence chain:
   1. CLI --python-version flag (explicit override)
   2. pyproject.toml [project].requires-python (PEP 621)
-  3. .python-version file (pyenv/asdf)
-  4. Default: 3.11
+  3. pyproject.toml [tool.poetry.dependencies].python (caret/tilde/PEP 440)
+  4. .python-version file (pyenv/asdf)
+  5. Default: 3.11
 """
 
 from __future__ import annotations
@@ -24,6 +25,7 @@ DEFAULT_VERSION = "3.11"
 _KNOWN_MINORS = [Version(f"3.{minor}") for minor in range(7, 20)]
 
 _POETRY_CARET_RE = re.compile(r"\^(\d+\.\d+)")
+_POETRY_TILDE_RE = re.compile(r"~(\d+\.\d+)")
 
 
 def detect_version(
@@ -68,21 +70,54 @@ def _from_pyproject(path: Path) -> str | None:
 
     poetry_python = data.get("tool", {}).get("poetry", {}).get("dependencies", {}).get("python")
     if poetry_python:
-        m = _POETRY_CARET_RE.search(str(poetry_python))
-        if m:
-            log.warning(
-                "Poetry caret version '%s' is not PEP 440 — cannot parse precisely. "
-                "Use --python-version or add [project].requires-python to pyproject.toml.",
-                poetry_python,
-            )
-        else:
-            log.warning(
-                "Poetry python constraint '%s' detected but not supported. "
-                "Use --python-version or add [project].requires-python.",
-                poetry_python,
-            )
+        result = _parse_poetry_python(poetry_python)
+        if result is not None:
+            return result
+
+    return None
+
+
+def _parse_poetry_python(value: str | dict) -> str | None:
+    if isinstance(value, dict):
+        value = value.get("version")
+        if not value:
+            log.warning("Poetry python constraint has no 'version' key")
+            return None
+
+    if not isinstance(value, str):
+        log.warning("Poetry python constraint has unexpected type %s", type(value).__name__)
+        return None
+
+    poetry_str = value
+
+    if "||" in poetry_str:
+        log.warning(
+            "Poetry union constraint '%s' is not supported. "
+            "Use --python-version or add [project].requires-python.",
+            poetry_str,
+        )
         return None
 
+    m = _POETRY_CARET_RE.search(poetry_str)
+    if m:
+        log.info("Parsed Poetry caret constraint '%s' → %s", poetry_str, m.group(1))
+        return m.group(1)
+
+    m = _POETRY_TILDE_RE.search(poetry_str)
+    if m:
+        log.info("Parsed Poetry tilde constraint '%s' → %s", poetry_str, m.group(1))
+        return m.group(1)
+
+    result = _min_version_from_specifier(poetry_str)
+    if result is not None:
+        log.info("Parsed Poetry PEP 440 constraint '%s' → %s", poetry_str, result)
+        return result
+
+    log.warning(
+        "Poetry python constraint '%s' detected but not supported. "
+        "Use --python-version or add [project].requires-python.",
+        poetry_str,
+    )
     return None
 
 

{modern_python_guidance-0.4.3 → modern_python_guidance-0.4.5}/tests/test_mcp_unit.py

@@ -217,16 +217,18 @@ class TestToolFunctions:
         assert data["results"][0]["id"] == "use-builtin-generics"
         assert data["not_found"][0]["id"] == "zzz-fake"
 
-    def test_retrieve_exactly_41_allowed(self):
-        ids = [f"fake-{i}" for i in range(41)]
+    def test_retrieve_at_limit_allowed(self):
+        limit = len(mcp._get_index())
+        ids = [f"fake-{i}" for i in range(limit)]
         r = mcp._tool_retrieve({"guide_ids": ids})
         assert r.get("isError") is not True
 
-    def test_retrieve_42_rejected(self):
-        ids = [f"fake-{i}" for i in range(42)]
+    def test_retrieve_over_limit_rejected(self):
+        limit = len(mcp._get_index())
+        ids = [f"fake-{i}" for i in range(limit + 1)]
         r = mcp._tool_retrieve({"guide_ids": ids})
         assert r["isError"] is True
-        assert "41" in r["content"][0]["text"]
+        assert str(limit) in r["content"][0]["text"]
 
     def test_retrieve_invalid_version(self):
         r = mcp._tool_retrieve({"guide_ids": ["use-builtin-generics"], "python_version": "x"})
@@ -318,6 +320,14 @@ class TestHandleRequest:
         assert "tools" in resp["result"]
         assert len(resp["result"]["tools"]) == 4
 
+    def test_tools_list_dynamic_max_items(self):
+        expected = len(mcp._get_index())
+        tools = mcp._get_tools()
+        retrieve = tools[1]
+        schema = retrieve["inputSchema"]["properties"]["guide_ids"]
+        assert schema["maxItems"] == expected
+        assert str(expected) in schema["description"]
+
     def test_tools_call(self):
         msg = {
             "jsonrpc": "2.0",

{modern_python_guidance-0.4.3 → modern_python_guidance-0.4.5}/tests/test_version_detect.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 from pathlib import Path
 
 import pytest
@@ -44,13 +45,87 @@ class TestPyprojectToml:
         (tmp_project / "pyproject.toml").write_text('[project]\nrequires-python = ">=3.11.4"\n')
         assert detect_version(project_dir=tmp_project) == "3.11"
 
-    def test_poetry_caret_warns_and_falls_through(self, tmp_project: Path, caplog):
+    def test_poetry_caret(self, tmp_project: Path, caplog):
         (tmp_project / "pyproject.toml").write_text(
             '[tool.poetry.dependencies]\npython = "^3.10"\n'
         )
-        result = detect_version(project_dir=tmp_project)
-        assert result == DEFAULT_VERSION
-        assert "Poetry caret version" in caplog.text
+        with caplog.at_level(logging.INFO):
+            assert detect_version(project_dir=tmp_project) == "3.10"
+        assert "Parsed Poetry caret" in caplog.text
+
+    def test_poetry_caret_with_patch(self, tmp_project: Path):
+        (tmp_project / "pyproject.toml").write_text(
+            '[tool.poetry.dependencies]\npython = "^3.10.2"\n'
+        )
+        assert detect_version(project_dir=tmp_project) == "3.10"
+
+    def test_poetry_tilde(self, tmp_project: Path, caplog):
+        (tmp_project / "pyproject.toml").write_text(
+            '[tool.poetry.dependencies]\npython = "~3.11"\n'
+        )
+        with caplog.at_level(logging.INFO):
+            assert detect_version(project_dir=tmp_project) == "3.11"
+        assert "Parsed Poetry tilde" in caplog.text
+
+    def test_poetry_tilde_with_patch(self, tmp_project: Path):
+        (tmp_project / "pyproject.toml").write_text(
+            '[tool.poetry.dependencies]\npython = "~3.11.5"\n'
+        )
+        assert detect_version(project_dir=tmp_project) == "3.11"
+
+    def test_poetry_pep440_range(self, tmp_project: Path, caplog):
+        (tmp_project / "pyproject.toml").write_text(
+            '[tool.poetry.dependencies]\npython = ">=3.10,<3.14"\n'
+        )
+        with caplog.at_level(logging.INFO):
+            assert detect_version(project_dir=tmp_project) == "3.10"
+        assert "Parsed Poetry PEP 440" in caplog.text
+
+    def test_poetry_pep440_compatible(self, tmp_project: Path, caplog):
+        (tmp_project / "pyproject.toml").write_text(
+            '[tool.poetry.dependencies]\npython = "~=3.11"\n'
+        )
+        with caplog.at_level(logging.INFO):
+            assert detect_version(project_dir=tmp_project) == "3.11"
+        assert "Parsed Poetry PEP 440" in caplog.text
+        assert "Parsed Poetry tilde" not in caplog.text
+
+    def test_poetry_dict_form(self, tmp_project: Path):
+        (tmp_project / "pyproject.toml").write_text(
+            '[tool.poetry.dependencies.python]\nversion = "^3.10"\n'
+        )
+        assert detect_version(project_dir=tmp_project) == "3.10"
+
+    def test_poetry_dict_no_version_key(self, tmp_project: Path, caplog):
+        (tmp_project / "pyproject.toml").write_text(
+            "[tool.poetry.dependencies.python]\noptional = true\n"
+        )
+        assert detect_version(project_dir=tmp_project) == DEFAULT_VERSION
+        assert "no 'version' key" in caplog.text
+
+    def test_poetry_union_warns(self, tmp_project: Path, caplog):
+        (tmp_project / "pyproject.toml").write_text(
+            '[tool.poetry.dependencies]\npython = "^3.10 || ^3.12"\n'
+        )
+        assert detect_version(project_dir=tmp_project) == DEFAULT_VERSION
+        assert "union constraint" in caplog.text
+
+    def test_poetry_unsupported_warns(self, tmp_project: Path, caplog):
+        (tmp_project / "pyproject.toml").write_text('[tool.poetry.dependencies]\npython = "*"\n')
+        assert detect_version(project_dir=tmp_project) == DEFAULT_VERSION
+        assert "not supported" in caplog.text
+
+    def test_poetry_major_only_warns(self, tmp_project: Path, caplog):
+        (tmp_project / "pyproject.toml").write_text('[tool.poetry.dependencies]\npython = "^3"\n')
+        assert detect_version(project_dir=tmp_project) == DEFAULT_VERSION
+        assert "not supported" in caplog.text
+
+    def test_poetry_list_type_warns(self, tmp_project: Path, caplog):
+        (tmp_project / "pyproject.toml").write_text(
+            '[tool.poetry.dependencies]\npython = ["^3.10", "^3.12"]\n'
+        )
+        assert detect_version(project_dir=tmp_project) == DEFAULT_VERSION
+        assert "unexpected type" in caplog.text
 
     def test_malformed_toml(self, tmp_project: Path, caplog):
         (tmp_project / "pyproject.toml").write_text("this is not valid toml [[[")
@@ -91,12 +166,17 @@ class TestPrecedence:
         (tmp_project / ".python-version").write_text("3.10\n")
         assert detect_version(project_dir=tmp_project) == "3.12"
 
-    def test_poetry_falls_to_python_version_file(self, tmp_project: Path):
+    def test_poetry_wins_over_python_version_file(self, tmp_project: Path):
         (tmp_project / "pyproject.toml").write_text(
             '[tool.poetry.dependencies]\npython = "^3.10"\n'
         )
         (tmp_project / ".python-version").write_text("3.11\n")
-        assert detect_version(project_dir=tmp_project) == "3.11"
+        assert detect_version(project_dir=tmp_project) == "3.10"
+
+    def test_poetry_unsupported_falls_to_python_version_file(self, tmp_project: Path):
+        (tmp_project / "pyproject.toml").write_text('[tool.poetry.dependencies]\npython = "*"\n')
+        (tmp_project / ".python-version").write_text("3.12\n")
+        assert detect_version(project_dir=tmp_project) == "3.12"
 
 
 class TestDefault: