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

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

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.3] — 2026-06-04
+
+### Fixed
+
+- MCP server crash on malformed `params` and `arguments`: non-dict values now return JSON-RPC -32602 instead of `TypeError`. `serve()` catch-all returns -32603 on unexpected errors. Notification messages (no `id`) are silently dropped per JSON-RPC 2.0 spec. (closes #91)
+- `mpg check` false positives in multi-line docstrings: `check_file()` now uses `tokenize` to identify multi-line string token ranges and skips those lines. Single-line strings on code lines are still scanned. Tokenize failure (syntax errors, indentation errors) falls back to scanning all lines. (closes #92)
+- Invalid PEP 440 specifiers in guide `python:` field silently treated as all-version compatible: `_build_meta()` now validates with `SpecifierSet` at parse time, raising `FrontmatterError`. Runtime `version_compatible()` narrows except from `(InvalidSpecifier, Exception)` to `(InvalidSpecifier, InvalidVersion)`. (closes #93)
+
+### Added
+
+- 53 new tests (987 total).
+
 ## [0.4.2] — 2026-06-04
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.4.2
+Version: 0.4.3
 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

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

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

{modern_python_guidance-0.4.2 → modern_python_guidance-0.4.3}/src/modern_python_guidance/check.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import io
 import re
+import tokenize as _tokenize
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -33,6 +35,23 @@ class CheckMatch:
     snippet: str
 
 
+def _string_lines(text: str) -> frozenset[int]:
+    """Line numbers belonging to multi-line STRING tokens (docstrings etc.)."""
+    skip: set[int] = set()
+    try:
+        tokens = _tokenize.generate_tokens(io.StringIO(text).readline)
+        string_types = {_tokenize.STRING}
+        fstring_mid = getattr(_tokenize, "FSTRING_MIDDLE", None)
+        if fstring_mid is not None:
+            string_types.add(fstring_mid)
+        for tok in tokens:
+            if tok.type in string_types and tok.end[0] > tok.start[0]:
+                skip.update(range(tok.start[0], tok.end[0] + 1))
+    except (_tokenize.TokenError, SyntaxError):
+        return frozenset()
+    return frozenset(skip)
+
+
 def check_file(
     path: Path,
     index: GuideIndex,
@@ -48,8 +67,11 @@ def check_file(
     if not patterns:
         return []
 
+    skip = _string_lines(text)
     matches: list[CheckMatch] = []
     for lineno, line in enumerate(text.splitlines(), 1):
+        if lineno in skip:
+            continue
         stripped = line.strip()
         if not stripped or stripped.startswith("#"):
             continue

{modern_python_guidance-0.4.2 → modern_python_guidance-0.4.3}/src/modern_python_guidance/compat.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import re
 
 from packaging.specifiers import InvalidSpecifier, SpecifierSet
-from packaging.version import Version
+from packaging.version import InvalidVersion, Version
 
 VERSION_RE = re.compile(r"^\d+\.\d+$")
 
@@ -14,7 +14,7 @@ def version_compatible(guide_python: str, target: str) -> bool:
     try:
         spec = SpecifierSet(guide_python)
         return Version(f"{target}.0") in spec
-    except (InvalidSpecifier, Exception):
+    except (InvalidSpecifier, InvalidVersion):
         return True
 
 

{modern_python_guidance-0.4.2 → modern_python_guidance-0.4.3}/src/modern_python_guidance/frontmatter.py

@@ -13,6 +13,8 @@ import re
 from dataclasses import dataclass, field
 from typing import Any
 
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+
 _KEY_RE = re.compile(r"^([a-z][a-z0-9_-]*)\s*:\s*(.*)")
 _LIST_ITEM_RE = re.compile(r"^  - (.+)")
 _FENCE = "---"
@@ -123,6 +125,12 @@ def _build_meta(raw: dict[str, Any]) -> GuideMeta:
         if isinstance(raw[str_field], list):
             raise FrontmatterError(f"'{str_field}' must be a scalar value, not a list")
 
+    python_value = str(raw["python"])
+    try:
+        SpecifierSet(python_value)
+    except InvalidSpecifier as e:
+        raise FrontmatterError(f"invalid python specifier '{python_value}': {e}") from e
+
     freq = raw["frequency"]
     if freq not in VALID_FREQUENCIES:
         raise FrontmatterError(f"invalid frequency '{freq}', must be one of {VALID_FREQUENCIES}")
@@ -171,7 +179,7 @@ def _build_meta(raw: dict[str, Any]) -> GuideMeta:
         category=str(raw["category"]),
         layer=layer,
         tags=[str(t) for t in tags],
-        python=str(raw["python"]),
+        python=python_value,
         frequency=freq,
         aliases=[str(a) for a in aliases_raw],
         pep=pep,

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

@@ -347,6 +347,15 @@ def _handle_request(msg: dict) -> dict | None:
     params = msg.get("params", {})
     is_notification = "id" not in msg
 
+    if not isinstance(params, dict):
+        if not is_notification:
+            return _error_response(
+                req_id,
+                -32602,
+                f"Invalid params: expected object, got {type(params).__name__}",
+            )
+        return None
+
     if method == "notifications/initialized":
         return None
 
@@ -368,6 +377,13 @@ def _handle_request(msg: dict) -> dict | None:
     if method == "tools/call":
         tool_name = params.get("name", "")
         arguments = params.get("arguments", {})
+        if not isinstance(arguments, dict):
+            result = _error_response(
+                req_id,
+                -32602,
+                f"Invalid arguments: expected object, got {type(arguments).__name__}",
+            )
+            return None if is_notification else result
         tool_result = _handle_tool_call(tool_name, arguments)
         result = _result_response(req_id, tool_result)
         return None if is_notification else result
@@ -390,7 +406,14 @@ def serve(*, stdin: object = None, stdout: object = None) -> None:
         if msg is None:
             break
 
-        response = _handle_request(msg)
+        try:
+            response = _handle_request(msg)
+        except Exception:
+            log.exception("Unexpected error handling request")
+            if isinstance(msg, dict) and "id" in msg:
+                response = _error_response(msg.get("id"), -32603, "Internal error")
+            else:
+                continue
         if response is not None:
             _write_message(response, stdout)
 

{modern_python_guidance-0.4.2 → modern_python_guidance-0.4.3}/tests/test_check.py

@@ -276,6 +276,62 @@ class TestEdgeCases:
         assert len(patterns) == 0
 
 
+class TestStringLineFiltering:
+    def test_docstring_not_matched(self, tmp_path: Path, index: GuideIndex):
+        p = tmp_path / "docstring.py"
+        p.write_text(
+            "def example():\n"
+            '    """Use datetime.utcnow() for timestamps.\n'
+            "\n"
+            "    Also from typing import List is common.\n"
+            '    """\n'
+            "    return 1\n",
+            encoding="utf-8",
+        )
+        matches = check_file(p, index)
+        assert matches == []
+
+    def test_inline_string_on_code_line_still_matched(self, tmp_path: Path, index: GuideIndex):
+        p = tmp_path / "inline.py"
+        p.write_text(
+            'from typing import List\nx = "some string"\n',
+            encoding="utf-8",
+        )
+        matches = check_file(p, index)
+        ids = {m.guide_id for m in matches}
+        assert "use-builtin-generics" in ids
+
+    def test_tokenize_failure_falls_back(self, tmp_path: Path, index: GuideIndex):
+        p = tmp_path / "broken.py"
+        p.write_text(
+            'from typing import List\nx = """unterminated\n',
+            encoding="utf-8",
+        )
+        matches = check_file(p, index)
+        ids = {m.guide_id for m in matches}
+        assert "use-builtin-generics" in ids
+
+    def test_indentation_error_falls_back(self, tmp_path: Path, index: GuideIndex):
+        p = tmp_path / "indent.py"
+        p.write_text(
+            "from typing import List\nif True:\n    x = 1\n  y = 2\n",
+            encoding="utf-8",
+        )
+        matches = check_file(p, index)
+        ids = {m.guide_id for m in matches}
+        assert "use-builtin-generics" in ids
+
+    def test_single_line_string_not_skipped(self, tmp_path: Path, index: GuideIndex):
+        p = tmp_path / "singleline.py"
+        p.write_text(
+            "from typing import List  # 'example'\n",
+            encoding="utf-8",
+        )
+        matches = check_file(p, index)
+        ids = {m.guide_id for m in matches}
+        assert "use-builtin-generics" in ids
+
+
 class TestFreqRank:
     def test_all_frequencies_covered(self):
         assert "high" in FREQ_RANK

{modern_python_guidance-0.4.2 → modern_python_guidance-0.4.3}/tests/test_compat.py

@@ -33,6 +33,18 @@ class TestVersionCompatible:
     def test_patch_level_target(self):
         assert version_compatible(">=3.9", "3.11.1") is True
 
+    def test_unexpected_error_propagates(self, monkeypatch):
+        def _boom(self, *a, **kw):
+            raise RuntimeError("unexpected")
+
+        fake = type("Boom", (), {"__init__": _boom, "__contains__": _boom})
+        monkeypatch.setattr(
+            "modern_python_guidance.compat.SpecifierSet",
+            fake,
+        )
+        with pytest.raises(RuntimeError, match="unexpected"):
+            version_compatible(">=3.9", "3.12")
+
 
 class TestTokenEstimate:
     def test_empty_string(self):

{modern_python_guidance-0.4.2 → modern_python_guidance-0.4.3}/tests/test_frontmatter.py

@@ -346,6 +346,49 @@ Body.
         parse_frontmatter(text)
 
 
+def test_invalid_python_specifier_rejected():
+    text = """\
+---
+id: bad-spec
+title: Bad Specifier
+category: typing
+layer: 1
+tags:
+  - test
+python: "not-a-valid-specifier"
+frequency: high
+---
+
+Body.
+"""
+    with pytest.raises(FrontmatterError, match="invalid python specifier"):
+        parse_frontmatter(text)
+
+
+@pytest.mark.parametrize(
+    "specifier",
+    [">=3.9", ">=3.11", ">=3.9,<3.13", ">=3.11,<3.14", ""],
+    ids=["ge39", "ge311", "range39_13", "range311_14", "empty"],
+)
+def test_valid_python_specifiers_accepted(specifier: str):
+    text = f"""\
+---
+id: valid-spec
+title: Valid Specifier
+category: typing
+layer: 1
+tags:
+  - test
+python: "{specifier}"
+frequency: high
+---
+
+Body.
+"""
+    meta, _ = parse_frontmatter(text)
+    assert meta.python == specifier
+
+
 def test_detect_patterns_non_list_rejected():
     text = """\
 ---

{modern_python_guidance-0.4.2 → modern_python_guidance-0.4.3}/tests/test_guide_structure.py

@@ -210,6 +210,15 @@ class TestDetectPatterns:
                 )
 
 
+class TestPythonSpecifiers:
+    def test_all_guides_have_valid_specifiers(self, guide_file: Path):
+        from packaging.specifiers import SpecifierSet
+
+        text = guide_file.read_text(encoding="utf-8")
+        meta, _ = parse_frontmatter(text)
+        SpecifierSet(meta.python)
+
+
 class TestGuideInventory:
     def test_no_duplicate_ids(self):
         seen: dict[str, Path] = {}

{modern_python_guidance-0.4.2 → modern_python_guidance-0.4.3}/tests/test_mcp_server.py

@@ -386,6 +386,37 @@ class TestProtocol:
         assert result["isError"] is True
 
 
+class TestMalformedParams:
+    def test_non_dict_params_returns_error_and_server_continues(self):
+        responses = _run_mcp(
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": "bad"},
+            {"jsonrpc": "2.0", "id": 2, "method": "initialize", "params": {}},
+        )
+        assert len(responses) == 2
+        assert responses[0]["error"]["code"] == -32602
+        assert responses[0]["id"] == 1
+        assert "expected object" in responses[0]["error"]["message"]
+        assert "protocolVersion" in responses[1]["result"]
+
+    def test_non_dict_arguments_returns_error_and_server_continues(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "tools/call",
+                "params": {"name": "search_guides", "arguments": "not-a-dict"},
+            },
+            {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}},
+        )
+        error = responses[1].get("error")
+        assert error is not None
+        assert error["code"] == -32602
+        assert "expected object" in error["message"]
+        assert responses[2]["id"] == 2
+        assert "tools" in responses[2]["result"]
+
+
 class TestStdoutPollution:
     def test_no_non_jsonrpc_output(self):
         stdin_data = _build_session(

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

@@ -362,6 +362,49 @@ class TestHandleRequest:
         assert resp["error"]["code"] == -32600
         assert "expected JSON object" in resp["error"]["message"]
 
+    @pytest.mark.parametrize(
+        "params",
+        [None, "hello", "", [1, 2], 42, 0, 3.14, True, False],
+        ids=["none", "string", "empty-string", "list", "int", "zero", "float", "true", "false"],
+    )
+    def test_non_dict_params_returns_invalid_params(self, params):
+        msg = {"jsonrpc": "2.0", "id": 10, "method": "initialize", "params": params}
+        resp = mcp._handle_request(msg)
+        assert resp["jsonrpc"] == "2.0"
+        assert resp["id"] == 10
+        assert resp["error"]["code"] == -32602
+        assert "expected object" in resp["error"]["message"]
+
+    def test_non_dict_params_notification_returns_none(self):
+        msg = {"jsonrpc": "2.0", "method": "initialize", "params": "bad"}
+        assert mcp._handle_request(msg) is None
+
+    def test_non_dict_arguments_returns_invalid_params(self):
+        msg = {
+            "jsonrpc": "2.0",
+            "id": 11,
+            "method": "tools/call",
+            "params": {"name": "search_guides", "arguments": "bad"},
+        }
+        resp = mcp._handle_request(msg)
+        assert resp["id"] == 11
+        assert resp["error"]["code"] == -32602
+        assert "expected object" in resp["error"]["message"]
+
+    def test_non_dict_arguments_notification_returns_none(self):
+        msg = {
+            "jsonrpc": "2.0",
+            "method": "tools/call",
+            "params": {"name": "search_guides", "arguments": [1, 2]},
+        }
+        assert mcp._handle_request(msg) is None
+
+    def test_unknown_method_with_bad_params_returns_invalid_params(self):
+        """Centralized params check runs before method dispatch."""
+        msg = {"jsonrpc": "2.0", "id": 12, "method": "nonexistent", "params": 42}
+        resp = mcp._handle_request(msg)
+        assert resp["error"]["code"] == -32602
+
 
 # --- serve ---
 
@@ -421,3 +464,72 @@ class TestServe:
         assert responses[0]["id"] is None
         assert responses[1]["id"] == 1
         assert "protocolVersion" in responses[1]["result"]
+
+    def test_non_dict_params_recovery(self):
+        lines = (
+            json.dumps({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": "bad"})
+            + "\n"
+            + json.dumps({"jsonrpc": "2.0", "id": 2, "method": "initialize", "params": {}})
+            + "\n"
+        )
+        sin = io.StringIO(lines)
+        sout = io.StringIO()
+        mcp.serve(stdin=sin, stdout=sout)
+        responses = [json.loads(line) for line in sout.getvalue().strip().split("\n")]
+        assert len(responses) == 2
+        assert responses[0]["error"]["code"] == -32602
+        assert responses[0]["id"] == 1
+        assert responses[1]["id"] == 2
+        assert "protocolVersion" in responses[1]["result"]
+
+    def test_catch_all_returns_internal_error(self, monkeypatch):
+        def boom(msg):
+            raise RuntimeError("unexpected")
+
+        monkeypatch.setattr(mcp, "_handle_request", boom)
+        req = {"jsonrpc": "2.0", "id": 99, "method": "initialize", "params": {}}
+        sin = io.StringIO(json.dumps(req) + "\n")
+        sout = io.StringIO()
+        mcp.serve(stdin=sin, stdout=sout)
+        resp = json.loads(sout.getvalue().strip())
+        assert resp["id"] == 99
+        assert resp["error"]["code"] == -32603
+        assert resp["error"]["message"] == "Internal error"
+
+    def test_catch_all_notification_no_response(self, monkeypatch):
+        def boom(msg):
+            raise RuntimeError("unexpected")
+
+        monkeypatch.setattr(mcp, "_handle_request", boom)
+        req = {"jsonrpc": "2.0", "method": "initialize", "params": {}}
+        sin = io.StringIO(json.dumps(req) + "\n")
+        sout = io.StringIO()
+        mcp.serve(stdin=sin, stdout=sout)
+        assert sout.getvalue() == ""
+
+    def test_catch_all_then_recovery(self, monkeypatch):
+        call_count = 0
+
+        original = mcp._handle_request
+
+        def boom_once(msg):
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                raise RuntimeError("first call fails")
+            return original(msg)
+
+        monkeypatch.setattr(mcp, "_handle_request", boom_once)
+        lines = (
+            json.dumps({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}})
+            + "\n"
+            + json.dumps({"jsonrpc": "2.0", "id": 2, "method": "initialize", "params": {}})
+            + "\n"
+        )
+        sin = io.StringIO(lines)
+        sout = io.StringIO()
+        mcp.serve(stdin=sin, stdout=sout)
+        responses = [json.loads(line) for line in sout.getvalue().strip().split("\n")]
+        assert len(responses) == 2
+        assert responses[0]["error"]["code"] == -32603
+        assert "protocolVersion" in responses[1]["result"]