mpat 0.2.0__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpat
-Version: 0.2.0
+Version: 0.2.2
 Summary: Lockfile-based upstream drift tracking for Python monkeypatches
 Author: Daniel Yudelevich
 License-Expression: MIT
@@ -78,10 +78,11 @@ patching. It tracks the body of functions and classes, the getter of a
 property, and the value of scalar constants and tuples of scalars. Every other
 attribute, including dicts, lists and custom descriptors, is recorded as
 existence only, so mutating a watched registry's contents will not fail
-`mpat check`; watch the function or class that populates it instead. `until`
-turns the patch off once upstream is fixed; `Version` takes a requirement
-string, `Probe` takes a zero-argument callable, and both combine with `|` and
-`&`. `review_by` is a nag date only. `on_drift="warn" | "skip" | "raise"`
+`mpat check`; watch the function or class that populates it instead.
+`watch(..., track_value=False)` records that a scalar exists and its kind but not
+its value, for settings your application assigns itself; if you want the value
+pinned, put the assignment and the `watch()` in the same module.
+`review_by` is a nag date only. `on_drift="warn" | "skip" | "raise"`
 decides what happens at import when the lock no longer matches; `MPAT_STRICT=1`
 forces `raise`. Passing a target as an object instead of a dotted string works
 too, resolved through `__module__` and `__qualname__`. Two dotted targets that
@@ -89,6 +90,41 @@ name the same attribute of the same owner are refused as aliases, but the same
 inherited method on two sibling subclasses is not an alias: each patch lands on
 its own class and the base class is left alone.
 
+Say when a workaround can go. `until` is accepted by `patch` and by `watch`:
+`Version` takes a requirement string, `Probe` takes a zero-argument callable,
+and both combine with `|` and `&`. On a patch it also turns the patch off once
+satisfied. On a watch it has no runtime effect, because a watch applies
+nothing, but either way the generated `still-needed[<target>]` test fails the
+day upstream is fixed. That makes a `watch` with `until` the replacement for a
+hand-written "still needed" test around a workaround that is not a `@patch`
+target, such as a per-instance `setattr` wrapper or an attribute your code
+creates on an upstream object:
+
+```python
+watch(
+    "ontospy.core.ontospy.Ontospy",
+    until=Version("ontospy>=2.2") | Probe(ontospy_still_needs_shim),
+    note="data/upstream_shims.py adds .namespaces; see ontospy#120",
+)
+```
+
+`patch` imports the target when the decorator runs. For an optional dependency
+that is the wrong moment, so `when_imported=True` defers it:
+
+```python
+@patch("optionallib.Client.request", when_imported=True)
+def request(original, self, *args, **kwargs):
+    ...
+```
+
+The declaration registers without importing anything. A post-import hook
+applies the patch the first time `optionallib` is imported, or right away if it
+already is, and the `until`, drift and kind checks run at that point. If
+`optionallib` is never imported, nothing happens. `mpat.apply_all()` imports
+every module a deferred patch is still waiting on, for code that wants the
+patches in place before it starts. Locking is unchanged: `mpat lock` has to be
+able to import the target.
+
 ## Lock and check
 
 ```toml
@@ -97,11 +133,15 @@ its own class and the base class is left alone.
 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`
@@ -189,6 +229,63 @@ change.
 Run `mpat check` on dependency-bump MRs. When it fails, read the upstream
 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` (or `mpat.toml`) and `mpat lock`,
+`mpat check` and the pytest plugin pick it up alongside the modules:
+
+```toml
+[[tool.mpat.watch]]
+target = "qdrant_client.async_qdrant_remote.AsyncQdrantRemote.query_points"
+depends_on = ["qdrant_client.async_qdrant_remote.AsyncQdrantRemote.scroll"]
+review_by = 2026-12-01
+note = "protobuf timeout wrapper in data/qdrant.py relies on this shape"
+```
+
+`target` is required; `depends_on`, `review_by` and `note` mean what they mean
+on `watch()`. `until` is a string: a requirement with a version specifier such
+as `until = "ontospy>=2.2"` becomes `Version`, and a dotted path such as
+`until = "data.upstream_shims.ontospy_still_needs_shim"` becomes a `Probe`
+that imports the callable when first evaluated. The entry is locked with `declared_in = "pyproject.toml"`, the
+denylist applies to it and its `depends_on`, and a malformed entry is a
+configuration error (exit 2) that names the entry.
+
+A patch that only assigns a scalar needs no code either:
+
+```toml
+[[tool.mpat.override]]
+target = "engineio.payload.Payload.max_decode_packets"
+value = 500
+note = "engineio default 16 500s long-polling clients (zauberzeug/nicegui#209)"
+review_by = 2026-12-01
+```
+
+```python
+# the only line the application needs, at startup
+import mpat
+
+mpat.apply_overrides()
+```
+
+`apply_overrides()` assigns every override once per process, after checking
+that the target is an existing attribute of exactly the value's type: `bool`
+is not `int` here, so `value = true` on an int attribute or `value = 1` on a
+bool one raises `UnsupportedTarget`. Each override is also a watch with
+`track_value = false`, so `mpat lock` records that the attribute exists and
+is a scalar, never its value, and `mpat check` is green whether or not the
+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. `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.
+
 ## pytest
 
 Install mpat, add `[tool.mpat]`, run pytest. The tests register themselves:
@@ -199,19 +296,25 @@ mpat::still-needed[somelib.client.Client.request] PASSED
 ```
 
 One `drift` item per declared or locked target, one `still-needed` item per
-patch with `until`. They belong to no file of yours, so they are collected by
+patch or watch with `until`. They belong to no file of yours, so they are collected by
 `pytest` and by `pytest <dir>`, and left out when you name a file or a nodeid:
 `pytest tests/test_client.py` runs what you asked for and nothing else. Disable
 them everywhere with `--no-mpat`, or `mpat = false` under
 `[tool.pytest.ini_options]`. `pytest-xdist` works: the items are ordered by
 target, so every worker collects the same list.
 
+In a monorepo with one `pyproject.toml` per service, `pytest services/api/tests`
+from the repository root finds the service's `[tool.mpat]` by walking up from
+the directory you named, and collects its items as `mpat[services/api]::...`.
+Name several service directories and each gets its own set, read from its own
+`mpat.lock`.
+
 Collecting them imports your patch modules the way your application does, so the
 patches are active for the rest of the test session exactly as in production.
 
-A project with `[tool.mpat]` and an empty `modules` gets a single failing
-`mpat::unconfigured` item rather than a green run, so a typo in the module list
-cannot turn the safety net green. A project with no `[tool.mpat]` at all collects
+A project with `[tool.mpat]` but no `modules` and no `[[tool.mpat.watch]]`
+entries gets a single failing `mpat::unconfigured` item rather than a green run,
+so a typo in the module list cannot turn the safety net green. A project with no `[tool.mpat]` at all collects
 nothing.
 
 The explicit form still works and wins when both are present:

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

@@ -57,10 +57,11 @@ patching. It tracks the body of functions and classes, the getter of a
 property, and the value of scalar constants and tuples of scalars. Every other
 attribute, including dicts, lists and custom descriptors, is recorded as
 existence only, so mutating a watched registry's contents will not fail
-`mpat check`; watch the function or class that populates it instead. `until`
-turns the patch off once upstream is fixed; `Version` takes a requirement
-string, `Probe` takes a zero-argument callable, and both combine with `|` and
-`&`. `review_by` is a nag date only. `on_drift="warn" | "skip" | "raise"`
+`mpat check`; watch the function or class that populates it instead.
+`watch(..., track_value=False)` records that a scalar exists and its kind but not
+its value, for settings your application assigns itself; if you want the value
+pinned, put the assignment and the `watch()` in the same module.
+`review_by` is a nag date only. `on_drift="warn" | "skip" | "raise"`
 decides what happens at import when the lock no longer matches; `MPAT_STRICT=1`
 forces `raise`. Passing a target as an object instead of a dotted string works
 too, resolved through `__module__` and `__qualname__`. Two dotted targets that
@@ -68,6 +69,41 @@ name the same attribute of the same owner are refused as aliases, but the same
 inherited method on two sibling subclasses is not an alias: each patch lands on
 its own class and the base class is left alone.
 
+Say when a workaround can go. `until` is accepted by `patch` and by `watch`:
+`Version` takes a requirement string, `Probe` takes a zero-argument callable,
+and both combine with `|` and `&`. On a patch it also turns the patch off once
+satisfied. On a watch it has no runtime effect, because a watch applies
+nothing, but either way the generated `still-needed[<target>]` test fails the
+day upstream is fixed. That makes a `watch` with `until` the replacement for a
+hand-written "still needed" test around a workaround that is not a `@patch`
+target, such as a per-instance `setattr` wrapper or an attribute your code
+creates on an upstream object:
+
+```python
+watch(
+    "ontospy.core.ontospy.Ontospy",
+    until=Version("ontospy>=2.2") | Probe(ontospy_still_needs_shim),
+    note="data/upstream_shims.py adds .namespaces; see ontospy#120",
+)
+```
+
+`patch` imports the target when the decorator runs. For an optional dependency
+that is the wrong moment, so `when_imported=True` defers it:
+
+```python
+@patch("optionallib.Client.request", when_imported=True)
+def request(original, self, *args, **kwargs):
+    ...
+```
+
+The declaration registers without importing anything. A post-import hook
+applies the patch the first time `optionallib` is imported, or right away if it
+already is, and the `until`, drift and kind checks run at that point. If
+`optionallib` is never imported, nothing happens. `mpat.apply_all()` imports
+every module a deferred patch is still waiting on, for code that wants the
+patches in place before it starts. Locking is unchanged: `mpat lock` has to be
+able to import the target.
+
 ## Lock and check
 
 ```toml
@@ -76,11 +112,15 @@ its own class and the base class is left alone.
 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`
@@ -168,6 +208,63 @@ change.
 Run `mpat check` on dependency-bump MRs. When it fails, read the upstream
 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` (or `mpat.toml`) and `mpat lock`,
+`mpat check` and the pytest plugin pick it up alongside the modules:
+
+```toml
+[[tool.mpat.watch]]
+target = "qdrant_client.async_qdrant_remote.AsyncQdrantRemote.query_points"
+depends_on = ["qdrant_client.async_qdrant_remote.AsyncQdrantRemote.scroll"]
+review_by = 2026-12-01
+note = "protobuf timeout wrapper in data/qdrant.py relies on this shape"
+```
+
+`target` is required; `depends_on`, `review_by` and `note` mean what they mean
+on `watch()`. `until` is a string: a requirement with a version specifier such
+as `until = "ontospy>=2.2"` becomes `Version`, and a dotted path such as
+`until = "data.upstream_shims.ontospy_still_needs_shim"` becomes a `Probe`
+that imports the callable when first evaluated. The entry is locked with `declared_in = "pyproject.toml"`, the
+denylist applies to it and its `depends_on`, and a malformed entry is a
+configuration error (exit 2) that names the entry.
+
+A patch that only assigns a scalar needs no code either:
+
+```toml
+[[tool.mpat.override]]
+target = "engineio.payload.Payload.max_decode_packets"
+value = 500
+note = "engineio default 16 500s long-polling clients (zauberzeug/nicegui#209)"
+review_by = 2026-12-01
+```
+
+```python
+# the only line the application needs, at startup
+import mpat
+
+mpat.apply_overrides()
+```
+
+`apply_overrides()` assigns every override once per process, after checking
+that the target is an existing attribute of exactly the value's type: `bool`
+is not `int` here, so `value = true` on an int attribute or `value = 1` on a
+bool one raises `UnsupportedTarget`. Each override is also a watch with
+`track_value = false`, so `mpat lock` records that the attribute exists and
+is a scalar, never its value, and `mpat check` is green whether or not the
+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. `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.
+
 ## pytest
 
 Install mpat, add `[tool.mpat]`, run pytest. The tests register themselves:
@@ -178,19 +275,25 @@ mpat::still-needed[somelib.client.Client.request] PASSED
 ```
 
 One `drift` item per declared or locked target, one `still-needed` item per
-patch with `until`. They belong to no file of yours, so they are collected by
+patch or watch with `until`. They belong to no file of yours, so they are collected by
 `pytest` and by `pytest <dir>`, and left out when you name a file or a nodeid:
 `pytest tests/test_client.py` runs what you asked for and nothing else. Disable
 them everywhere with `--no-mpat`, or `mpat = false` under
 `[tool.pytest.ini_options]`. `pytest-xdist` works: the items are ordered by
 target, so every worker collects the same list.
 
+In a monorepo with one `pyproject.toml` per service, `pytest services/api/tests`
+from the repository root finds the service's `[tool.mpat]` by walking up from
+the directory you named, and collects its items as `mpat[services/api]::...`.
+Name several service directories and each gets its own set, read from its own
+`mpat.lock`.
+
 Collecting them imports your patch modules the way your application does, so the
 patches are active for the rest of the test session exactly as in production.
 
-A project with `[tool.mpat]` and an empty `modules` gets a single failing
-`mpat::unconfigured` item rather than a green run, so a typo in the module list
-cannot turn the safety net green. A project with no `[tool.mpat]` at all collects
+A project with `[tool.mpat]` but no `modules` and no `[[tool.mpat.watch]]`
+entries gets a single failing `mpat::unconfigured` item rather than a green run,
+so a typo in the module list cannot turn the safety net green. A project with no `[tool.mpat]` at all collects
 nothing.
 
 The explicit form still works and wins when both are present:

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

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

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

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

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

@@ -1,12 +1,13 @@
 """mpat: lockfile-based upstream drift tracking for Python monkeypatches."""
 
-from mpat._api import patch, watch
+from mpat._api import apply_all, apply_overrides, patch, watch
 from mpat._errors import (
     AlreadyPatched,
     ForbiddenTarget,
     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.0"
+__version__ = "0.2.2"
 
 __all__ = [
     "AlreadyPatched",
@@ -23,12 +24,15 @@ __all__ = [
     "LockError",
     "MpatError",
     "Probe",
+    "TargetImportError",
     "TargetNotFound",
     "UnsupportedTarget",
     "Until",
     "UpstreamDriftError",
     "UpstreamDriftWarning",
     "Version",
+    "apply_all",
+    "apply_overrides",
     "patch",
     "watch",
 ]

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

@@ -9,15 +9,25 @@ from collections.abc import AsyncIterator, Callable, Iterator, Sequence
 from datetime import date
 from typing import Any, Protocol, TypeVar
 
+from mpat import _hooks
 from mpat._config import runtime_config
-from mpat._errors import AlreadyPatched, KindMismatch, UpstreamDriftError, UpstreamDriftWarning
+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,
     ROLE_PATCH,
     ROLE_WATCH,
     STATUS_APPLIED,
+    STATUS_DEFERRED,
     STATUS_SKIPPED_DRIFT,
     STATUS_SKIPPED_UNTIL,
     STATUS_WATCHED,
@@ -25,7 +35,10 @@ from mpat._registry import (
     Declaration,
     applied_for,
     collect_mode,
+    config_declarations,
     mark_applied,
+    override_originals,
+    record_override,
     register,
 )
 from mpat._targets import (
@@ -41,7 +54,6 @@ from mpat._targets import (
 )
 from mpat._until import Until
 
-ON_DRIFT_WARN = "warn"
 ON_DRIFT_SKIP = "skip"
 ON_DRIFT_RAISE = "raise"
 ON_DRIFT_VALUES = (ON_DRIFT_WARN, ON_DRIFT_SKIP, ON_DRIFT_RAISE)
@@ -81,20 +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))
+    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)
@@ -161,6 +201,46 @@ def _wrap(fn: Callable[..., Any], original: Any, decl: Declaration) -> Callable[
     return wrapper
 
 
+def _check_kind(fn: Replacement, resolved: Resolved) -> None:
+    if callable_kind(fn) != callable_kind(resolved.obj):
+        raise KindMismatch(
+            f"{resolved.target}: original is {callable_kind(resolved.obj)}, "
+            f"replacement is {callable_kind(fn)}"
+        )
+
+
+def _resolve_patchable(canonical: str) -> Resolved:
+    resolved = resolve(canonical)
+    check_supported(resolved)
+    return resolved
+
+
+def _apply(*, decl: Declaration, fn: Replacement, resolved: Resolved) -> None:
+    if decl.until is not None and decl.until():
+        decl.status = STATUS_SKIPPED_UNTIL
+        log.info("%s: not applied, until=%r is satisfied. %s", decl.target, decl.until, decl.note)
+        return
+    if not _handle_drift(decl, resolved):
+        decl.status = STATUS_SKIPPED_DRIFT
+        return
+    original = _live_original(resolved, decl)
+    wrapper = _wrap(fn=fn, original=original, decl=decl)
+    replacement = resolved.descriptor(wrapper) if resolved.descriptor else wrapper
+    setattr(resolved.parent, resolved.attr, replacement)
+    mark_applied(id(original), decl)
+    decl.status = STATUS_APPLIED
+
+
+def _apply_deferred(*, decl: Declaration, fn: Replacement) -> None:
+    resolved = _resolve_patchable(decl.target)
+    _check_kind(fn, resolved)
+    _apply(decl=decl, fn=fn, resolved=resolved)
+
+
+def _top_level(canonical: str) -> str:
+    return canonical.partition(".")[0]
+
+
 def patch(
     target: str | object,
     *,
@@ -169,21 +249,18 @@ def patch(
     on_drift: str = ON_DRIFT_WARN,
     review_by: date | None = None,
     note: str = "",
+    when_imported: bool = False,
 ) -> Callable[[F], F]:
     if on_drift not in ON_DRIFT_VALUES:
         raise ValueError(f"on_drift must be one of {ON_DRIFT_VALUES}, got {on_drift!r}")
     canonical = canonical_target(target)
     _check_declaration_forbidden(canonical, depends_on)
-    resolved = resolve(canonical)
-    check_supported(resolved)
+    resolved = None if when_imported else _resolve_patchable(canonical)
     declared_in = _caller_file()
 
     def decorator(fn: F) -> F:
-        if callable_kind(fn) != callable_kind(resolved.obj):
-            raise KindMismatch(
-                f"{canonical}: original is {callable_kind(resolved.obj)}, "
-                f"replacement is {callable_kind(fn)}"
-            )
+        if resolved is not None:
+            _check_kind(fn, resolved)
         decl = Declaration(
             target=canonical,
             role=ROLE_PATCH,
@@ -198,30 +275,57 @@ def patch(
         register(decl)
         if collect_mode():
             return fn
-        if until is not None and until():
-            decl.status = STATUS_SKIPPED_UNTIL
-            log.info("%s: not applied, until=%r is satisfied. %s", canonical, until, note)
+        if resolved is not None:
+            _apply(decl=decl, fn=fn, resolved=resolved)
             return fn
-        if not _handle_drift(decl, resolved):
-            decl.status = STATUS_SKIPPED_DRIFT
-            return fn
-        original = _live_original(resolved, decl)
-        wrapper = _wrap(fn=fn, original=original, decl=decl)
-        replacement = resolved.descriptor(wrapper) if resolved.descriptor else wrapper
-        setattr(resolved.parent, resolved.attr, replacement)
-        mark_applied(id(original), decl)
-        decl.status = STATUS_APPLIED
+        decl.status = STATUS_DEFERRED
+        _hooks.when_imported(
+            _top_level(canonical), functools.partial(_apply_deferred, decl=decl, fn=fn)
+        )
         return fn
 
     return decorator
 
 
+def apply_all() -> None:
+    """Import every module a `when_imported=True` patch is still waiting on."""
+    _hooks.import_pending()
+
+
+def apply_overrides() -> None:
+    """Assign every `[[tool.mpat.override]]` value, once per process."""
+    config = runtime_config()
+    if config is None:
+        return
+    declarations = config_declarations(config)
+    for decl in declarations:
+        register(decl)
+    if collect_mode():
+        return
+    done = override_originals()
+    by_target = {decl.target: decl for decl in declarations}
+    for spec in config.overrides:
+        if spec.target in done:
+            continue
+        resolved = resolve(spec.target)
+        _handle_drift(by_target[spec.target], resolved)
+        if type(resolved.static) is not type(spec.value):
+            raise UnsupportedTarget(
+                f"{spec.target}: override value is {type(spec.value).__name__}, "
+                f"attribute is {type(resolved.static).__name__}"
+            )
+        record_override(spec.target, resolved.static)
+        setattr(resolved.parent, resolved.attr, spec.value)
+
+
 def watch(
     target: str | object,
     *,
     depends_on: Sequence[str] = (),
+    until: Until | None = None,
     review_by: date | None = None,
     note: str = "",
+    track_value: bool = True,
 ) -> None:
     canonical = canonical_target(target)
     _check_declaration_forbidden(canonical, depends_on)
@@ -231,12 +335,13 @@ def watch(
         target=canonical,
         role=ROLE_WATCH,
         depends_on=tuple(depends_on),
-        until=None,
+        until=until,
         on_drift=ON_DRIFT_WARN,
         review_by=review_by,
         note=note,
         declared_in=declared_in,
         identity=(declared_in, f"watch:{canonical}"),
+        track_value=track_value,
     )
     register(decl)
     if collect_mode():