mpat 0.2.1__tar.gz → 0.2.2__tar.gz

{mpat-0.2.1 → mpat-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpat
-Version: 0.2.1
+Version: 0.2.2
 Summary: Lockfile-based upstream drift tracking for Python monkeypatches
 Author: Daniel Yudelevich
 License-Expression: MIT
@@ -133,11 +133,15 @@ able to import the target.
 modules = ["myapp.patches"]
 ```
 
+Or the same keys, without the `[tool.mpat]` prefix, in a standalone `mpat.toml`
+next to it. `mpat.toml` wins when both exist.
+
 ```
 mpat lock     # fingerprint everything, write mpat.lock, commit it
 mpat check    # exit 1 unless every target is ok
 mpat check --json
 mpat show somelib.client.Client.request
+mpat diff somelib.client.Client.request
 ```
 
 `mpat lock` and `mpat check` import the modules listed in `[tool.mpat] modules`
@@ -227,7 +231,7 @@ change, fix or delete the patch, run `mpat lock`, commit.
 
 ## Declare without code
 
-A watch needs no Python at all. Declare it in `pyproject.toml` and `mpat lock`,
+A watch needs no Python at all. Declare it in `pyproject.toml` (or `mpat.toml`) and `mpat lock`,
 `mpat check` and the pytest plugin pick it up alongside the modules:
 
 ```toml
@@ -273,7 +277,12 @@ override has been applied in that process. A workaround with any logic in it
 is still `@patch`.
 
 A project can have `modules`, `[[tool.mpat.watch]]` and `[[tool.mpat.override]]`
-entries in any combination. A target declared twice, in code and in
+entries in any combination. `modules` is imported before the TOML entries
+resolve, so it is also where a shim that has to run before a watched target can
+be imported at all belongs: a project whose TOML watches target a library that
+only imports once a shim is in place keeps that shim module in `modules`.
+Emptying the list is a configuration error (exit 2) naming the target that could
+not be imported, not a traceback. A target declared twice, in code and in
 `pyproject.toml` or in both TOML forms, is refused rather than silently
 merged, so there is no precedence to remember.
 

{mpat-0.2.1 → mpat-0.2.2}/README.md

@@ -112,11 +112,15 @@ able to import the target.
 modules = ["myapp.patches"]
 ```
 
+Or the same keys, without the `[tool.mpat]` prefix, in a standalone `mpat.toml`
+next to it. `mpat.toml` wins when both exist.
+
 ```
 mpat lock     # fingerprint everything, write mpat.lock, commit it
 mpat check    # exit 1 unless every target is ok
 mpat check --json
 mpat show somelib.client.Client.request
+mpat diff somelib.client.Client.request
 ```
 
 `mpat lock` and `mpat check` import the modules listed in `[tool.mpat] modules`
@@ -206,7 +210,7 @@ change, fix or delete the patch, run `mpat lock`, commit.
 
 ## Declare without code
 
-A watch needs no Python at all. Declare it in `pyproject.toml` and `mpat lock`,
+A watch needs no Python at all. Declare it in `pyproject.toml` (or `mpat.toml`) and `mpat lock`,
 `mpat check` and the pytest plugin pick it up alongside the modules:
 
 ```toml
@@ -252,7 +256,12 @@ override has been applied in that process. A workaround with any logic in it
 is still `@patch`.
 
 A project can have `modules`, `[[tool.mpat.watch]]` and `[[tool.mpat.override]]`
-entries in any combination. A target declared twice, in code and in
+entries in any combination. `modules` is imported before the TOML entries
+resolve, so it is also where a shim that has to run before a watched target can
+be imported at all belongs: a project whose TOML watches target a library that
+only imports once a shim is in place keeps that shim module in `modules`.
+Emptying the list is a configuration error (exit 2) naming the target that could
+not be imported, not a traceback. A target declared twice, in code and in
 `pyproject.toml` or in both TOML forms, is refused rather than silently
 merged, so there is no precedence to remember.
 

{mpat-0.2.1 → mpat-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mpat"
-version = "0.2.1"
+version = "0.2.2"
 description = "Lockfile-based upstream drift tracking for Python monkeypatches"
 readme = "README.md"
 license = "MIT"

{mpat-0.2.1 → mpat-0.2.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "mpat"
-version = "0.2.1"
+version = "0.2.2"
 description = "Lockfile-based upstream drift tracking for Python monkeypatches"
 readme = "README.md"
 license = "MIT"

{mpat-0.2.1 → mpat-0.2.2}/src/mpat/__init__.py

@@ -7,6 +7,7 @@ from mpat._errors import (
     KindMismatch,
     LockError,
     MpatError,
+    TargetImportError,
     TargetNotFound,
     UnsupportedTarget,
     UpstreamDriftError,
@@ -14,7 +15,7 @@ from mpat._errors import (
 )
 from mpat._until import Probe, Until, Version
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 __all__ = [
     "AlreadyPatched",
@@ -23,6 +24,7 @@ __all__ = [
     "LockError",
     "MpatError",
     "Probe",
+    "TargetImportError",
     "TargetNotFound",
     "UnsupportedTarget",
     "Until",

{mpat-0.2.1 → mpat-0.2.2}/src/mpat/_api.py

@@ -14,12 +14,13 @@ from mpat._config import runtime_config
 from mpat._errors import (
     AlreadyPatched,
     KindMismatch,
+    TargetNotFound,
     UnsupportedTarget,
     UpstreamDriftError,
     UpstreamDriftWarning,
 )
 from mpat._fingerprint import OK, compare, fingerprint
-from mpat._lock import runtime_lock
+from mpat._lock import expand, runtime_lock
 from mpat._registry import (
     ENV_ON,
     ON_DRIFT_WARN,
@@ -92,23 +93,48 @@ def _check_declaration_forbidden(canonical: str, depends_on: Sequence[str]) -> N
         check_forbidden(canonical_target(dep), allow=allow)
 
 
-def _drift_status(decl: Declaration, resolved: Resolved) -> str:
+def _dependency(target: str) -> Resolved | None:
+    try:
+        return resolve(target)
+    except (TargetNotFound, ImportError):
+        return None
+
+
+def _drifted(decl: Declaration, resolved: Resolved) -> list[tuple[str, str]]:
     lock = runtime_lock()
-    if lock is None or decl.target not in lock.entries:
-        return OK
-    return compare(
-        locked=lock.entries[decl.target].fingerprint,
-        current=fingerprint(resolved, track_value=decl.track_value),
-    )
+    if lock is None:
+        return []
+    found: list[tuple[str, str]] = []
+    for wanted in expand([decl]):
+        entry = lock.entries.get(wanted.target)
+        if entry is None:
+            continue
+        current = resolved if wanted.target == decl.target else _dependency(wanted.target)
+        if current is None:
+            continue
+        status = compare(
+            locked=entry.fingerprint,
+            current=fingerprint(current, track_value=wanted.track_value),
+        )
+        if status != OK:
+            found.append((wanted.target, status))
+    return found
+
+
+def _drift_detail(decl: Declaration, drifted: Sequence[tuple[str, str]]) -> str:
+    if len(drifted) == 1 and drifted[0][0] == decl.target:
+        return drifted[0][1]
+    return ", ".join(f"{target}: {status}" for target, status in drifted)
 
 
 def _handle_drift(decl: Declaration, resolved: Resolved) -> bool:
     """Return True when the patch should still be applied."""
-    status = _drift_status(decl, resolved)
-    if status == OK:
+    drifted = _drifted(decl, resolved)
+    if not drifted:
         return True
     action = ON_DRIFT_RAISE if os.environ.get(STRICT_ENV) == ENV_ON else decl.on_drift
-    message = f"{decl.target}: upstream drift ({status}) since mpat.lock. {decl.note}".rstrip()
+    detail = _drift_detail(decl, drifted)
+    message = f"{decl.target}: upstream drift ({detail}) since mpat.lock. {decl.note}".rstrip()
     if action == ON_DRIFT_RAISE:
         raise UpstreamDriftError(message)
     warnings.warn(message, UpstreamDriftWarning, stacklevel=_WARN_STACKLEVEL)

{mpat-0.2.1 → mpat-0.2.2}/src/mpat/_cli.py

@@ -9,8 +9,8 @@ from collections.abc import Sequence
 from datetime import date
 from pathlib import Path
 
-from mpat._config import Config, load_config
-from mpat._errors import LockError, MpatError
+from mpat._config import CONFIG_FILENAME, PYPROJECT, Config, load_config
+from mpat._errors import LockError, MpatError, TargetNotFound
 from mpat._fingerprint import (
     BODY,
     MOVED,
@@ -18,6 +18,8 @@ from mpat._fingerprint import (
     OK,
     SIGNATURE,
     VALUE,
+    Fingerprint,
+    compare,
     fingerprint,
 )
 from mpat._lock import (
@@ -53,6 +55,7 @@ _NO_DECLARATIONS = "no declarations found"
 _NO_SOURCE_MARKER = " [signature-only]"
 _NO_SOURCE_NOTICE = "no source available, only the signature is locked"
 _NO_DIST = "(no distribution)"
+_MISSING_CELL = "(missing)"
 _DRIFT_STATUSES = (MISSING, MOVED, SIGNATURE, BODY, VALUE, NO_SOURCE)
 _FOOTERS: tuple[tuple[tuple[str, ...], str], ...] = (
     ((UNLOCKED,), "unlocked: run 'mpat lock'"),
@@ -68,12 +71,11 @@ _FOOTERS: tuple[tuple[tuple[str, ...], str], ...] = (
 def _require_config() -> Config:
     config = load_config()
     if config is None:
-        raise MpatError("no pyproject.toml found in the current directory or its parents")
-    if not config.declares_anything:
         raise MpatError(
-            "[tool.mpat] in pyproject.toml lists no modules and no watch entries; "
-            "nothing to collect"
+            f"no {PYPROJECT} or {CONFIG_FILENAME} found in the current directory or its parents"
         )
+    if not config.declares_anything:
+        raise MpatError(f"{config.where} lists no modules and no watch entries; nothing to collect")
     return config
 
 
@@ -185,6 +187,31 @@ def cmd_show(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
+def _diff_lines(locked: Fingerprint, current: Fingerprint | None) -> list[str]:
+    lines: list[str] = []
+    for name, before in dataclasses.asdict(locked).items():
+        after = _MISSING_CELL if current is None else getattr(current, name)
+        if before != after:
+            lines.append(f"{name}: {before} -> {after}")
+    return lines
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    config = _require_config()
+    entry = _existing_lock(config.root).entries.get(args.target)
+    if entry is None:
+        raise MpatError(f"{args.target}: not in {LOCK_FILENAME}")
+    try:
+        current = fingerprint(resolve(args.target), track_value=entry.track_value)
+    except TargetNotFound:
+        current = None
+    status = MISSING if current is None else compare(locked=entry.fingerprint, current=current)
+    print(f"status: {status}")
+    for line in _diff_lines(entry.fingerprint, current):
+        print(line)
+    return EXIT_OK if status == OK else EXIT_DRIFT
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="mpat")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -196,6 +223,9 @@ def _parser() -> argparse.ArgumentParser:
     show_parser = sub.add_parser("show", help="print fingerprint and source of a target")
     show_parser.add_argument("target")
     show_parser.set_defaults(fn=cmd_show)
+    diff_parser = sub.add_parser("diff", help="show which locked fields of a target changed")
+    diff_parser.add_argument("target")
+    diff_parser.set_defaults(fn=cmd_diff)
     return parser
 
 

mpat-0.2.2/src/mpat/_config.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import functools
+import tomllib
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from mpat._errors import MpatError
+
+PYPROJECT = "pyproject.toml"
+CONFIG_FILENAME = "mpat.toml"
+CONFIG_FILENAMES = (CONFIG_FILENAME, PYPROJECT)
+TOOL_SECTION = "mpat"
+WATCH_KEY = "watch"
+OVERRIDE_KEY = "override"
+
+_MODULES = "modules"
+_ALLOW = "allow"
+_SECTION_KEYS = frozenset({_MODULES, _ALLOW, WATCH_KEY, OVERRIDE_KEY})
+_TARGET = "target"
+_DEPENDS_ON = "depends_on"
+_REVIEW_BY = "review_by"
+_NOTE = "note"
+_VALUE = "value"
+_UNTIL = "until"
+_TOML_SCALARS = (int, float, str, bool)
+_WATCH_FIELDS: dict[str, type | tuple[type, ...]] = {
+    _TARGET: str,
+    _DEPENDS_ON: list,
+    _UNTIL: str,
+    _REVIEW_BY: date,
+    _NOTE: str,
+}
+_OVERRIDE_FIELDS: dict[str, type | tuple[type, ...]] = {
+    _TARGET: str,
+    _VALUE: _TOML_SCALARS,
+    _REVIEW_BY: date,
+    _NOTE: str,
+}
+
+
+@dataclass(frozen=True)
+class WatchSpec:
+    target: str
+    depends_on: tuple[str, ...] = ()
+    until: str | None = None
+    review_by: date | None = None
+    note: str = ""
+
+
+@dataclass(frozen=True)
+class OverrideSpec:
+    target: str
+    value: int | float | str | bool
+    note: str = ""
+    review_by: date | None = None
+
+
+@dataclass(frozen=True)
+class _Source:
+    """Where the section came from: the file, and how its keys are spelled there."""
+
+    path: Path
+    prefix: str
+    section: str
+
+    @property
+    def name(self) -> str:
+        return self.path.name
+
+    def table(self, key: str) -> str:
+        return f"[[{self.prefix}{key}]]"
+
+
+_MPAT_TOML_SOURCE = {"prefix": "", "section": ""}
+_PYPROJECT_SOURCE = {"prefix": f"tool.{TOOL_SECTION}.", "section": f"[tool.{TOOL_SECTION}] "}
+
+
+@dataclass(frozen=True)
+class Config:
+    root: Path
+    path: Path
+    modules: tuple[str, ...]
+    allow: tuple[str, ...]
+    declared: bool = False
+    watches: tuple[WatchSpec, ...] = ()
+    overrides: tuple[OverrideSpec, ...] = ()
+
+    @property
+    def declares_anything(self) -> bool:
+        return bool(self.modules or self.watches or self.overrides)
+
+    @property
+    def where(self) -> str:
+        if self.path.name == CONFIG_FILENAME:
+            return CONFIG_FILENAME
+        return f"[tool.{TOOL_SECTION}] in {PYPROJECT}"
+
+
+def config_path(root: Path) -> Path | None:
+    for name in CONFIG_FILENAMES:
+        if (root / name).is_file():
+            return root / name
+    return None
+
+
+def find_config_file(start: Path) -> Path | None:
+    for candidate in (start, *start.parents):
+        path = config_path(candidate)
+        if path is not None:
+            return path
+    return None
+
+
+def find_project_root(start: Path) -> Path | None:
+    path = find_config_file(start)
+    return None if path is None else path.parent
+
+
+def _entry_error(source: _Source, key: str, label: str, problem: str) -> MpatError:
+    return MpatError(f"{source.name}: {source.table(key)} {label}: {problem}")
+
+
+def _typed_fields(
+    source: _Source,
+    key: str,
+    label: str,
+    data: Mapping[str, Any],
+    fields: Mapping[str, type | tuple[type, ...]],
+) -> None:
+    for name, value in data.items():
+        if name not in fields:
+            raise _entry_error(source, key, label, f"unknown key {name!r}")
+        if not isinstance(value, fields[name]):
+            raise _entry_error(
+                source,
+                key,
+                label,
+                f"{name} must be {_type_name(fields[name])}, got {type(value).__name__}",
+            )
+
+
+def _type_name(expected: type | tuple[type, ...]) -> str:
+    if isinstance(expected, tuple):
+        return " or ".join(t.__name__ for t in expected)
+    return expected.__name__
+
+
+def _entries(
+    source: _Source, section: Mapping[str, Any], key: str
+) -> Iterator[tuple[str, dict[str, Any]]]:
+    raw = section.get(key, [])
+    if not isinstance(raw, list):
+        raise MpatError(
+            f"{source.name}: {source.prefix}{key} must be an array of tables, "
+            f"got {type(raw).__name__}"
+        )
+    for index, data in enumerate(raw):
+        if not isinstance(data, dict):
+            raise _entry_error(
+                source, key, f"#{index}", f"must be a table, got {type(data).__name__}"
+            )
+        target = data.get(_TARGET)
+        label = f"#{index}" if not isinstance(target, str) else f"#{index} ({target})"
+        if _TARGET not in data:
+            raise _entry_error(source, key, label, f"missing {_TARGET}")
+        yield label, data
+
+
+def _watch_spec(source: _Source, label: str, data: dict[str, Any]) -> WatchSpec:
+    _typed_fields(source, WATCH_KEY, label, data, _WATCH_FIELDS)
+    depends_on = data.get(_DEPENDS_ON, [])
+    if not all(isinstance(dep, str) for dep in depends_on):
+        raise _entry_error(source, WATCH_KEY, label, f"{_DEPENDS_ON} must be a list of str")
+    return WatchSpec(
+        target=data[_TARGET],
+        depends_on=tuple(depends_on),
+        until=data.get(_UNTIL),
+        review_by=data.get(_REVIEW_BY),
+        note=data.get(_NOTE, ""),
+    )
+
+
+def _override_spec(source: _Source, label: str, data: dict[str, Any]) -> OverrideSpec:
+    _typed_fields(source, OVERRIDE_KEY, label, data, _OVERRIDE_FIELDS)
+    if _VALUE not in data:
+        raise _entry_error(source, OVERRIDE_KEY, label, f"missing {_VALUE}")
+    return OverrideSpec(
+        target=data[_TARGET],
+        value=data[_VALUE],
+        note=data.get(_NOTE, ""),
+        review_by=data.get(_REVIEW_BY),
+    )
+
+
+def _unique_targets(source: _Source, specs: Sequence[WatchSpec | OverrideSpec]) -> None:
+    seen: set[str] = set()
+    for spec in specs:
+        if spec.target in seen:
+            raise MpatError(f"{source.name}: {spec.target} is declared twice")
+        seen.add(spec.target)
+
+
+def _table(
+    source: _Source, data: Mapping[str, Any], key: str, *, parent: str = ""
+) -> Mapping[str, Any]:
+    value = data.get(key, {})
+    if not isinstance(value, dict):
+        name = f"{parent}.{key}" if parent else key
+        raise MpatError(f"{source.name}: {name} must be a table, got {type(value).__name__}")
+    return value
+
+
+def _known_keys(source: _Source, section: Mapping[str, Any]) -> None:
+    for key in section:
+        if key not in _SECTION_KEYS:
+            raise MpatError(f"{source.name}: {source.section}unknown key {key!r}")
+
+
+def _str_list(source: _Source, section: Mapping[str, Any], key: str) -> tuple[str, ...]:
+    value = section.get(key, [])
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise MpatError(f"{source.name}: {source.section}{key} must be a list of str")
+    return tuple(value)
+
+
+def _section(path: Path) -> tuple[_Source, Mapping[str, Any], bool]:
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    if path.name == CONFIG_FILENAME:
+        return _Source(path=path, **_MPAT_TOML_SOURCE), data, True
+    source = _Source(path=path, **_PYPROJECT_SOURCE)
+    tool = _table(source, data, "tool")
+    return source, _table(source, tool, TOOL_SECTION, parent="tool"), TOOL_SECTION in tool
+
+
+def load_config(start: Path | None = None) -> Config | None:
+    path = find_config_file(start or Path.cwd())
+    if path is None:
+        return None
+    source, section, declared = _section(path)
+    _known_keys(source, section)
+    watches = tuple(
+        _watch_spec(source, label, entry) for label, entry in _entries(source, section, WATCH_KEY)
+    )
+    overrides = tuple(
+        _override_spec(source, label, entry)
+        for label, entry in _entries(source, section, OVERRIDE_KEY)
+    )
+    _unique_targets(source, (*watches, *overrides))
+    return Config(
+        root=path.parent,
+        path=path,
+        modules=_str_list(source, section, _MODULES),
+        allow=_str_list(source, section, _ALLOW),
+        declared=declared,
+        watches=watches,
+        overrides=overrides,
+    )
+
+
+@functools.cache
+def runtime_config() -> Config | None:
+    return load_config()
+
+
+def reset_caches() -> None:
+    runtime_config.cache_clear()

{mpat-0.2.1 → mpat-0.2.2}/src/mpat/_errors.py

@@ -6,6 +6,10 @@ class TargetNotFound(MpatError):
     pass
 
 
+class TargetImportError(MpatError, ImportError):
+    pass
+
+
 class UnsupportedTarget(MpatError):
     pass
 

{mpat-0.2.1 → mpat-0.2.2}/src/mpat/_fingerprint.py

@@ -62,19 +62,28 @@ def _iter_defs(
                 yield from _iter_defs(handler.body)
 
 
+def _first_line(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) -> int:
+    return min([node.lineno, *(d.lineno for d in node.decorator_list)])
+
+
 def _definition_node(
-    tree: ast.Module, qualname: str
+    tree: ast.Module, qualname: str, *, lineno: int | None = None
 ) -> ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | None:
     if "<locals>" in qualname:
         return None
     body: list[ast.stmt] = tree.body
     node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | None = None
-    for name in qualname.split("."):
+    *parents, leaf = qualname.split(".")
+    for name in parents:
         node = next((n for n in _iter_defs(body) if n.name == name), None)
         if node is None:
             return None
         body = node.body
-    return node
+    candidates = [n for n in _iter_defs(body) if n.name == leaf]
+    if not candidates:
+        return None
+    at_line = [n for n in candidates if _first_line(n) == lineno]
+    return at_line[0] if at_line else candidates[0]
 
 
 def _hash(node: ast.AST) -> str:
@@ -91,14 +100,21 @@ def _source_file(obj: Any) -> str | None:
     return None
 
 
+_SOURCE_FAILURES = (OSError, UnicodeDecodeError, SyntaxError, ValueError)
+
+
 def _source_hash(obj: Any, file: str) -> str | None:
-    tree = ast.parse(Path(file).read_text(encoding="utf-8"))
+    try:
+        tree = ast.parse(Path(file).read_text(encoding="utf-8"))
+    except _SOURCE_FAILURES:
+        return None
     if inspect.ismodule(obj):
         return _hash(tree)
     qualname = getattr(obj, "__qualname__", None)
     if not qualname:
         return None
-    node = _definition_node(tree, qualname)
+    code = getattr(obj, "__code__", None)
+    node = _definition_node(tree, qualname, lineno=getattr(code, "co_firstlineno", None))
     return None if node is None else _hash(node)
 
 

{mpat-0.2.1 → mpat-0.2.2}/src/mpat/_generated.py

@@ -20,7 +20,8 @@ UNCONFIGURED_ROLE = "config"
 UNCONFIGURED_STATUS = "unconfigured"
 UNCONFIGURED_NOTE = (
     "[tool.mpat] declares nothing; add modules, [[tool.mpat.watch]] or "
-    "[[tool.mpat.override]] to pyproject.toml"
+    "[[tool.mpat.override]] to pyproject.toml, or the same keys without the "
+    "tool.mpat prefix to mpat.toml"
 )
 
 

{mpat-0.2.1 → mpat-0.2.2}/src/mpat/_registry.py

@@ -8,7 +8,7 @@ from datetime import date
 from pathlib import Path
 from typing import Any
 
-from mpat._config import PYPROJECT, Config, OverrideSpec, WatchSpec
+from mpat._config import CONFIG_FILENAMES, Config, OverrideSpec, WatchSpec
 from mpat._errors import MpatError
 from mpat._targets import check_forbidden
 from mpat._until import Until, until_from_string
@@ -98,8 +98,8 @@ def _check_forbidden(target: str, depends_on: Sequence[str], *, allow: Sequence[
         check_forbidden(dep, allow=allow)
 
 
-def watch_declaration(spec: WatchSpec, *, root: Path) -> Declaration:
-    declared_in = str(root / PYPROJECT)
+def watch_declaration(spec: WatchSpec, *, path: Path) -> Declaration:
+    declared_in = str(path)
     return Declaration(
         target=spec.target,
         role=ROLE_WATCH,
@@ -113,8 +113,8 @@ def watch_declaration(spec: WatchSpec, *, root: Path) -> Declaration:
     )
 
 
-def override_declaration(spec: OverrideSpec, *, root: Path) -> Declaration:
-    declared_in = str(root / PYPROJECT)
+def override_declaration(spec: OverrideSpec, *, path: Path) -> Declaration:
+    declared_in = str(path)
     return Declaration(
         target=spec.target,
         role=ROLE_WATCH,
@@ -130,19 +130,19 @@ def override_declaration(spec: OverrideSpec, *, root: Path) -> Declaration:
 
 
 def config_declarations(config: Config) -> list[Declaration]:
-    """Build the declarations pyproject.toml makes, checked against the denylist."""
+    """Build the declarations the configuration file makes, checked against the denylist."""
     for spec in config.watches:
         _check_forbidden(spec.target, spec.depends_on, allow=config.allow)
     for spec in config.overrides:
         _check_forbidden(spec.target, (), allow=config.allow)
     return [
-        *(watch_declaration(spec, root=config.root) for spec in config.watches),
-        *(override_declaration(spec, root=config.root) for spec in config.overrides),
+        *(watch_declaration(spec, path=config.path) for spec in config.watches),
+        *(override_declaration(spec, path=config.path) for spec in config.overrides),
     ]
 
 
 def from_config(decl: Declaration) -> bool:
-    return Path(decl.declared_in).name == PYPROJECT
+    return Path(decl.declared_in).name in CONFIG_FILENAMES
 
 
 def _register_config(config: Config) -> None:
@@ -150,14 +150,14 @@ def _register_config(config: Config) -> None:
     for decl in config_declarations(config):
         if decl.target in from_code:
             raise MpatError(
-                f"{decl.target}: declared twice: {PYPROJECT} and "
+                f"{decl.target}: declared twice: {config.path.name} and "
                 f"{from_code[decl.target].declared_in}"
             )
         register(decl)
 
 
 def collect_declarations(config: Config, *, apply: bool) -> list[Declaration]:
-    """Import the patch modules, add what pyproject.toml declares, and return it all.
+    """Import the patch modules, add what the configuration file declares, and return it all.
 
     apply=True imports the modules the way the application does, so the patches
     take effect and a module cached by this import is the patched one. apply=False

{mpat-0.2.1 → mpat-0.2.2}/src/mpat/_targets.py

@@ -7,7 +7,12 @@ from collections.abc import Sequence
 from dataclasses import dataclass
 from typing import Any
 
-from mpat._errors import ForbiddenTarget, TargetNotFound, UnsupportedTarget
+from mpat._errors import (
+    ForbiddenTarget,
+    TargetImportError,
+    TargetNotFound,
+    UnsupportedTarget,
+)
 
 DEFAULT_DENY: tuple[str, ...] = (
     "mpat",
@@ -50,19 +55,29 @@ def canonical_target(target: str | object) -> str:
     return f"{module}.{qualname}"
 
 
-def _import_prefix(parts: list[str]) -> tuple[types.ModuleType, list[str]]:
+def _import_prefix(parts: list[str], *, target: str) -> tuple[types.ModuleType, list[str]]:
     for i in range(len(parts), 0, -1):
         name = ".".join(parts[:i])
         try:
             return importlib.import_module(name), parts[i:]
         except ModuleNotFoundError as exc:
             if exc.name is None or not name.startswith(exc.name):
-                raise
+                raise _import_failed(target=target, exc=exc) from exc
+        except ImportError as exc:
+            raise _import_failed(target=target, exc=exc) from exc
     raise TargetNotFound(f"no importable module prefix in {'.'.join(parts)!r}")
 
 
+def _import_failed(*, target: str, exc: ImportError) -> TargetImportError:
+    return TargetImportError(
+        f"{target!r}: importing it raised {type(exc).__name__}: {exc}. "
+        f"If another module has to be imported first for this target to import, "
+        f"list that module in [tool.mpat] modules."
+    )
+
+
 def resolve(target: str) -> Resolved:
-    module, rest = _import_prefix(target.split("."))
+    module, rest = _import_prefix(target.split("."), target=target)
     if not rest:
         raise TargetNotFound(f"{target!r} is a module, not an attribute of one")
     parent: Any = module
@@ -112,7 +127,7 @@ def check_forbidden(target: str, *, allow: Sequence[str] = ()) -> None:
         if _matches(target, denied):
             raise ForbiddenTarget(
                 f"{target!r} matches denylist entry {denied!r}; "
-                "add it to [tool.mpat] allow in pyproject.toml to override"
+                "add it to allow in [tool.mpat] or mpat.toml to override"
             )
 
 

mpat-0.2.1/src/mpat/_config.py

@@ -1,181 +0,0 @@
-from __future__ import annotations
-
-import functools
-import tomllib
-from collections.abc import Iterator, Mapping, Sequence
-from dataclasses import dataclass
-from datetime import date
-from pathlib import Path
-from typing import Any
-
-from mpat._errors import MpatError
-
-PYPROJECT = "pyproject.toml"
-TOOL_SECTION = "mpat"
-WATCH_KEY = "watch"
-OVERRIDE_KEY = "override"
-
-_TARGET = "target"
-_DEPENDS_ON = "depends_on"
-_REVIEW_BY = "review_by"
-_NOTE = "note"
-_VALUE = "value"
-_UNTIL = "until"
-_TOML_SCALARS = (int, float, str, bool)
-_WATCH_FIELDS: dict[str, type | tuple[type, ...]] = {
-    _TARGET: str,
-    _DEPENDS_ON: list,
-    _UNTIL: str,
-    _REVIEW_BY: date,
-    _NOTE: str,
-}
-_OVERRIDE_FIELDS: dict[str, type | tuple[type, ...]] = {
-    _TARGET: str,
-    _VALUE: _TOML_SCALARS,
-    _REVIEW_BY: date,
-    _NOTE: str,
-}
-
-
-@dataclass(frozen=True)
-class WatchSpec:
-    target: str
-    depends_on: tuple[str, ...] = ()
-    until: str | None = None
-    review_by: date | None = None
-    note: str = ""
-
-
-@dataclass(frozen=True)
-class OverrideSpec:
-    target: str
-    value: int | float | str | bool
-    note: str = ""
-    review_by: date | None = None
-
-
-@dataclass(frozen=True)
-class Config:
-    root: Path
-    modules: tuple[str, ...]
-    allow: tuple[str, ...]
-    declared: bool = False
-    watches: tuple[WatchSpec, ...] = ()
-    overrides: tuple[OverrideSpec, ...] = ()
-
-    @property
-    def declares_anything(self) -> bool:
-        return bool(self.modules or self.watches or self.overrides)
-
-
-def find_project_root(start: Path) -> Path | None:
-    for candidate in (start, *start.parents):
-        if (candidate / PYPROJECT).is_file():
-            return candidate
-    return None
-
-
-def _entry_error(key: str, label: str, problem: str) -> MpatError:
-    return MpatError(f"{PYPROJECT}: [[tool.{TOOL_SECTION}.{key}]] {label}: {problem}")
-
-
-def _typed_fields(
-    key: str, label: str, data: Mapping[str, Any], fields: Mapping[str, type | tuple[type, ...]]
-) -> None:
-    for name, value in data.items():
-        if name not in fields:
-            raise _entry_error(key, label, f"unknown key {name!r}")
-        if not isinstance(value, fields[name]):
-            raise _entry_error(
-                key, label, f"{name} must be {_type_name(fields[name])}, got {type(value).__name__}"
-            )
-
-
-def _type_name(expected: type | tuple[type, ...]) -> str:
-    if isinstance(expected, tuple):
-        return " or ".join(t.__name__ for t in expected)
-    return expected.__name__
-
-
-def _entries(section: Mapping[str, Any], key: str) -> Iterator[tuple[str, dict[str, Any]]]:
-    raw = section.get(key, [])
-    if not isinstance(raw, list):
-        raise MpatError(
-            f"{PYPROJECT}: tool.{TOOL_SECTION}.{key} must be an array of tables, "
-            f"got {type(raw).__name__}"
-        )
-    for index, data in enumerate(raw):
-        if not isinstance(data, dict):
-            raise _entry_error(key, f"#{index}", f"must be a table, got {type(data).__name__}")
-        target = data.get(_TARGET)
-        label = f"#{index}" if not isinstance(target, str) else f"#{index} ({target})"
-        if _TARGET not in data:
-            raise _entry_error(key, label, f"missing {_TARGET}")
-        yield label, data
-
-
-def _watch_spec(label: str, data: dict[str, Any]) -> WatchSpec:
-    _typed_fields(WATCH_KEY, label, data, _WATCH_FIELDS)
-    depends_on = data.get(_DEPENDS_ON, [])
-    if not all(isinstance(dep, str) for dep in depends_on):
-        raise _entry_error(WATCH_KEY, label, f"{_DEPENDS_ON} must be a list of str")
-    return WatchSpec(
-        target=data[_TARGET],
-        depends_on=tuple(depends_on),
-        until=data.get(_UNTIL),
-        review_by=data.get(_REVIEW_BY),
-        note=data.get(_NOTE, ""),
-    )
-
-
-def _override_spec(label: str, data: dict[str, Any]) -> OverrideSpec:
-    _typed_fields(OVERRIDE_KEY, label, data, _OVERRIDE_FIELDS)
-    if _VALUE not in data:
-        raise _entry_error(OVERRIDE_KEY, label, f"missing {_VALUE}")
-    return OverrideSpec(
-        target=data[_TARGET],
-        value=data[_VALUE],
-        note=data.get(_NOTE, ""),
-        review_by=data.get(_REVIEW_BY),
-    )
-
-
-def _unique_targets(specs: Sequence[WatchSpec | OverrideSpec]) -> None:
-    seen: set[str] = set()
-    for spec in specs:
-        if spec.target in seen:
-            raise MpatError(
-                f"{PYPROJECT}: {spec.target} is declared twice in [tool.{TOOL_SECTION}]"
-            )
-        seen.add(spec.target)
-
-
-def load_config(start: Path | None = None) -> Config | None:
-    root = find_project_root(start or Path.cwd())
-    if root is None:
-        return None
-    data = tomllib.loads((root / PYPROJECT).read_text(encoding="utf-8"))
-    tool = data.get("tool", {})
-    section = tool.get(TOOL_SECTION, {})
-    watches = tuple(_watch_spec(label, entry) for label, entry in _entries(section, WATCH_KEY))
-    overrides = tuple(
-        _override_spec(label, entry) for label, entry in _entries(section, OVERRIDE_KEY)
-    )
-    _unique_targets((*watches, *overrides))
-    return Config(
-        root=root,
-        modules=tuple(section.get("modules", ())),
-        allow=tuple(section.get("allow", ())),
-        declared=TOOL_SECTION in tool,
-        watches=watches,
-        overrides=overrides,
-    )
-
-
-@functools.cache
-def runtime_config() -> Config | None:
-    return load_config()
-
-
-def reset_caches() -> None:
-    runtime_config.cache_clear()