pyteman 0.1.0__tar.gz

pyteman-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paolo Antinori
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyteman-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: pyteman
+Version: 0.1.0
+Summary: Rule-based runtime fault injection for Python, inspired by Byteman
+Author: Paolo Antinori
+License: MIT License
+        
+        Copyright (c) 2026 Paolo Antinori
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/RisorseArtificiali/pyteman
+Project-URL: Repository, https://github.com/RisorseArtificiali/pyteman
+Project-URL: Issues, https://github.com/RisorseArtificiali/pyteman/issues
+Keywords: fault-injection,testing,chaos,byteman,sqlite,reproducer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# pyteman
+
+Rule-based runtime fault injection for Python, inspired by Byteman.
+
+Wrap a function with a YAML rule that fires on entry or exit, under a
+condition. The action can inject a sleep, raise an exception, override the
+return value, switch a SQLite PRAGMA on a connection passed to the call,
+kill the process at the exact injection point (`os._exit`), or hold a named
+barrier so two threads meet in the interleaving you want. Each firing is
+logged with a sequence number, so you can reconstruct the interleaving after
+the run.
+
+## Activation contract (safety)
+
+- Put the directory containing `sitecustomize.py` on the PYTHONPATH of TEST
+  runs only; that is `src/pyteman`, not `src`. Python imports `sitecustomize`
+  as a top-level module from whichever directory holds it. `pyteman.*` itself
+  resolves for normal imports via the editable install.
+- Without `PYTEMAN_RULES` set, the sitecustomize does nothing.
+- With `PYTEMAN_REQUIRE_MARKER=<file>` set, pyteman refuses to start unless
+  that marker file exists. It writes a refusal message to stderr and exits
+  with code 2 via `os._exit`. The hard exit is deliberate: a `SystemExit`
+  raised inside sitecustomize escapes into interpreter startup, and the
+  interpreter dies with a Fatal Python error and status 1 instead of your
+  exit code. Callers use the marker to pin execution to scratch directories.
+  Never install sitecustomize into production venvs or images.
+
+## Ruleset example
+
+```yaml
+- id: hold-commit
+  point: hermes_state.SessionDB._execute_write
+  event: entry
+  when: "fires > 3 and kwargs.get('sid', '').startswith('stress-')"
+  action: {kind: sleep, ms: 250}
+  fire: {mode: once_per, key: "kwargs.get('sid')"}
+- id: crash-at-commit
+  point: hermes_state.SessionDB.commit
+  event: exit
+  action: {kind: kill, exit_code: 70}
+  fire: {mode: countdown, n: 50}
+```
+
+The module is everything before the FIRST dot of `point`; the remainder is an
+attribute path walked from the module, and the final component is the patched
+attribute. `hermes_state.SessionDB._execute_write` resolves to module
+`hermes_state` with attribute path `SessionDB._execute_write`.
+
+Conditions see `args`, `kwargs`, `fires`, and on exit events also
+`result`/`exc`. They are trusted operator input for test tooling.
+
+Actions: `sleep`, `raise`, `return_value`, `return_none`, `pragma` (reaches
+attribute-held connections through `target:` specs, see docs/targeting.md),
+`kill` (`os._exit`), `barrier` (role `wait` or `open`).
+
+`return_value`/`return_none` follow Byteman RETURN semantics and depend on the
+event. On an ENTRY event the wrapped body is skipped entirely and the override
+value is returned in its place. On an EXIT event the original body has already
+run and the override swaps the result it produced.
+
+Fire gating uses `fire: {mode: ...}` with three modes. `always` is the
+default. `once_per <key-expr>` consumes its key only when the condition
+passes. `countdown n` fires on call n+1.
+
+## Runner and sqlitekit
+
+`pyteman.runner.matrix.run_matrix(cells, run_cell, results_db, artifact_root)`
+runs cells sequentially and resumes across re-runs via the results SQLite;
+`pyteman.runner.report.matrix_markdown` renders the outcome table.
+`pyteman.sqlitekit.integrity.classify_integrity` parses `PRAGMA
+integrity_check` output into typed signatures (CLEAN / FTS_ONLY /
+CANONICAL_INDEX_COUNT / CANONICAL_ROWID_DISORDER / SCHEMA / NOTADB).
+
+## Patchable-target contract
+
+Rules can patch two shapes of callable:
+
+- Plain module-level functions: `point: mymodule.my_function`.
+- Instance methods, addressed through the class:
+  `point: mymodule.MyClass.my_method` (resolution as in the Ruleset example
+  above).
+
+Not supported: `classmethod`, `staticmethod`, and other descriptor-based
+attributes. Patching replaces the class attribute, so descriptor binding is
+lost. Calls through the instance pass `self` into the wrapper, so you usually
+get a TypeError, not a silent no-op. If you need them, wrap an inner plain
+function instead.
+
+The `pragma` action reaches its `sqlite3.Connection` in two ways. Without a
+`target:` it scans the call's direct arguments and keyword values. With a
+`target:` spec it resolves state the callable holds instead of receives:
+
+```yaml
+- id: flip-sync
+  point: myapp.session.SessionDB.append
+  event: entry
+  action:
+    kind: pragma
+    name: synchronous
+    value: "OFF"
+    target: self._conn
+```
+
+`self` is the first positional argument (the receiver for a patched method)
+with an optional dotted attribute walk; `param:<name>` binds an argument by
+name through the real signature; `result` is the exit-event return value.
+Spec syntax is validated when the ruleset loads, and a spec that resolves
+for no call leaves an `outcome` record in the firing log instead of
+silently doing nothing. The full grammar and failure policy live in
+`docs/targeting.md`.
+
+## Import-hook name matching
+
+Patching happens when the target module is imported. The import hook matches
+the module name Python passes to `import`, so rules must name the target's
+absolute TOP-LEVEL module as it is imported directly: `import mymodule` or
+`from mymodule import thing`. Two shapes do not match:
+
+- Relative imports (`from . import x` inside a package) never reach the hook.
+  importlib resolves them internally; the hook only sees the outer top-level
+  import. No rule-module renaming can match them.
+- Submodule imports (`import package.mymodule`) do not match a rule on the
+  submodule. The hook sees the full dotted name, but a ruleset cannot express
+  a dotted module, because the point splits at the first dot. The form
+  `from package import mymodule` does match a rule anchored on the parent
+  (`point: package.mymodule.func`). The hook sees `package`, and the symbol
+  walk descends into the submodule attribute.
+
+## Status
+
+Pre-release; born out of a real SQLite corruption investigation.
+
+## License
+
+MIT; see [LICENSE](LICENSE).

pyteman-0.1.0/README.md

@@ -0,0 +1,135 @@
+# pyteman
+
+Rule-based runtime fault injection for Python, inspired by Byteman.
+
+Wrap a function with a YAML rule that fires on entry or exit, under a
+condition. The action can inject a sleep, raise an exception, override the
+return value, switch a SQLite PRAGMA on a connection passed to the call,
+kill the process at the exact injection point (`os._exit`), or hold a named
+barrier so two threads meet in the interleaving you want. Each firing is
+logged with a sequence number, so you can reconstruct the interleaving after
+the run.
+
+## Activation contract (safety)
+
+- Put the directory containing `sitecustomize.py` on the PYTHONPATH of TEST
+  runs only; that is `src/pyteman`, not `src`. Python imports `sitecustomize`
+  as a top-level module from whichever directory holds it. `pyteman.*` itself
+  resolves for normal imports via the editable install.
+- Without `PYTEMAN_RULES` set, the sitecustomize does nothing.
+- With `PYTEMAN_REQUIRE_MARKER=<file>` set, pyteman refuses to start unless
+  that marker file exists. It writes a refusal message to stderr and exits
+  with code 2 via `os._exit`. The hard exit is deliberate: a `SystemExit`
+  raised inside sitecustomize escapes into interpreter startup, and the
+  interpreter dies with a Fatal Python error and status 1 instead of your
+  exit code. Callers use the marker to pin execution to scratch directories.
+  Never install sitecustomize into production venvs or images.
+
+## Ruleset example
+
+```yaml
+- id: hold-commit
+  point: hermes_state.SessionDB._execute_write
+  event: entry
+  when: "fires > 3 and kwargs.get('sid', '').startswith('stress-')"
+  action: {kind: sleep, ms: 250}
+  fire: {mode: once_per, key: "kwargs.get('sid')"}
+- id: crash-at-commit
+  point: hermes_state.SessionDB.commit
+  event: exit
+  action: {kind: kill, exit_code: 70}
+  fire: {mode: countdown, n: 50}
+```
+
+The module is everything before the FIRST dot of `point`; the remainder is an
+attribute path walked from the module, and the final component is the patched
+attribute. `hermes_state.SessionDB._execute_write` resolves to module
+`hermes_state` with attribute path `SessionDB._execute_write`.
+
+Conditions see `args`, `kwargs`, `fires`, and on exit events also
+`result`/`exc`. They are trusted operator input for test tooling.
+
+Actions: `sleep`, `raise`, `return_value`, `return_none`, `pragma` (reaches
+attribute-held connections through `target:` specs, see docs/targeting.md),
+`kill` (`os._exit`), `barrier` (role `wait` or `open`).
+
+`return_value`/`return_none` follow Byteman RETURN semantics and depend on the
+event. On an ENTRY event the wrapped body is skipped entirely and the override
+value is returned in its place. On an EXIT event the original body has already
+run and the override swaps the result it produced.
+
+Fire gating uses `fire: {mode: ...}` with three modes. `always` is the
+default. `once_per <key-expr>` consumes its key only when the condition
+passes. `countdown n` fires on call n+1.
+
+## Runner and sqlitekit
+
+`pyteman.runner.matrix.run_matrix(cells, run_cell, results_db, artifact_root)`
+runs cells sequentially and resumes across re-runs via the results SQLite;
+`pyteman.runner.report.matrix_markdown` renders the outcome table.
+`pyteman.sqlitekit.integrity.classify_integrity` parses `PRAGMA
+integrity_check` output into typed signatures (CLEAN / FTS_ONLY /
+CANONICAL_INDEX_COUNT / CANONICAL_ROWID_DISORDER / SCHEMA / NOTADB).
+
+## Patchable-target contract
+
+Rules can patch two shapes of callable:
+
+- Plain module-level functions: `point: mymodule.my_function`.
+- Instance methods, addressed through the class:
+  `point: mymodule.MyClass.my_method` (resolution as in the Ruleset example
+  above).
+
+Not supported: `classmethod`, `staticmethod`, and other descriptor-based
+attributes. Patching replaces the class attribute, so descriptor binding is
+lost. Calls through the instance pass `self` into the wrapper, so you usually
+get a TypeError, not a silent no-op. If you need them, wrap an inner plain
+function instead.
+
+The `pragma` action reaches its `sqlite3.Connection` in two ways. Without a
+`target:` it scans the call's direct arguments and keyword values. With a
+`target:` spec it resolves state the callable holds instead of receives:
+
+```yaml
+- id: flip-sync
+  point: myapp.session.SessionDB.append
+  event: entry
+  action:
+    kind: pragma
+    name: synchronous
+    value: "OFF"
+    target: self._conn
+```
+
+`self` is the first positional argument (the receiver for a patched method)
+with an optional dotted attribute walk; `param:<name>` binds an argument by
+name through the real signature; `result` is the exit-event return value.
+Spec syntax is validated when the ruleset loads, and a spec that resolves
+for no call leaves an `outcome` record in the firing log instead of
+silently doing nothing. The full grammar and failure policy live in
+`docs/targeting.md`.
+
+## Import-hook name matching
+
+Patching happens when the target module is imported. The import hook matches
+the module name Python passes to `import`, so rules must name the target's
+absolute TOP-LEVEL module as it is imported directly: `import mymodule` or
+`from mymodule import thing`. Two shapes do not match:
+
+- Relative imports (`from . import x` inside a package) never reach the hook.
+  importlib resolves them internally; the hook only sees the outer top-level
+  import. No rule-module renaming can match them.
+- Submodule imports (`import package.mymodule`) do not match a rule on the
+  submodule. The hook sees the full dotted name, but a ruleset cannot express
+  a dotted module, because the point splits at the first dot. The form
+  `from package import mymodule` does match a rule anchored on the parent
+  (`point: package.mymodule.func`). The hook sees `package`, and the symbol
+  walk descends into the submodule attribute.
+
+## Status
+
+Pre-release; born out of a real SQLite corruption investigation.
+
+## License
+
+MIT; see [LICENSE](LICENSE).

pyteman-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "pyteman"
+version = "0.1.0"
+description = "Rule-based runtime fault injection for Python, inspired by Byteman"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Paolo Antinori" }]
+requires-python = ">=3.11"
+dependencies = ["PyYAML>=6.0"]
+keywords = ["fault-injection", "testing", "chaos", "byteman", "sqlite", "reproducer"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://github.com/RisorseArtificiali/pyteman"
+Repository = "https://github.com/RisorseArtificiali/pyteman"
+Issues = "https://github.com/RisorseArtificiali/pyteman/issues"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pyteman = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pyteman-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyteman-0.1.0/src/pyteman/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pyteman-0.1.0/src/pyteman/actions.py

@@ -0,0 +1,84 @@
+# src/pyteman/actions.py
+"""Action execution for injected rules.
+
+Trusted-operator posture: rules come from operator-authored YAML used for
+local test tooling, never from untrusted input. By design, `when` condition
+expressions and `pragma` name/value strings are passed through unsanitized;
+`raise` resolves only builtin exception classes. Extending this module to
+face untrusted rule sources would require sanitizing all three.
+"""
+import builtins as _builtins
+import os
+import sqlite3
+import time
+
+from pyteman.targets import resolve_target
+
+def run_action(rule, ctx, log=None):
+    if log is not None:
+        log.record(rule, ctx, note=str(rule.action))
+    kind = rule.action["kind"]
+    if kind == "return_value":
+        ctx["_override"] = rule.action.get("value")
+        return
+    if kind == "return_none":
+        ctx["_override"] = None
+        return
+    if kind == "sleep":
+        time.sleep(int(rule.action.get("ms", 0)) / 1000.0)
+        return
+    if kind == "raise":
+        name = rule.action.get("exc", "RuntimeError")
+        exc = getattr(_builtins, name, None)
+        if not isinstance(exc, type) or not issubclass(exc, BaseException):
+            raise RuntimeError(f"unknown exception class {name}")
+        raise exc(rule.action.get("message", "pyteman injected"))
+    if kind == "pragma":
+        target_spec = rule.action.get("target")
+        con, why = (resolve_target(ctx, target_spec) if target_spec is not None
+                    else _find_connection(ctx))
+        if con is None:
+            _note(log, rule, ctx, f"pragma skipped: {why}")
+            return
+        try:
+            con.execute(f"PRAGMA {rule.action['name']}={rule.action['value']}")
+        except Exception as exc:
+            _note(log, rule, ctx, f"pragma execute failed on {type(con).__name__}: {exc}")
+        return
+    if kind == "kill":
+        os._exit(int(rule.action.get("exit_code", 70)))
+    if kind == "barrier":
+        from pyteman import barriers
+        name = rule.action["barrier"]
+        if rule.action.get("role", "wait") == "open":
+            barriers.open(name)
+            return True
+        return barriers.wait(name, timeout_s=float(rule.action.get("timeout_s", 30)))
+    raise NotImplementedError(f"unknown action kind {kind}")
+
+def _find_connection(ctx):
+    """Legacy no-target path: (con, None) or (None, reason), same protocol
+    as resolve_target so the pragma action has one miss branch."""
+    for v in list(ctx.get("args", ())) + list(ctx.get("kwargs", {}).values()):
+        if isinstance(v, sqlite3.Connection):
+            return v, None
+    return None, "no target spec and no sqlite3.Connection in the call arguments"
+
+
+def _note(log, rule, ctx, message):
+    # Unresolvable pragma targets must be visible, not silent no-ops: the
+    # firing log is the operator's only channel when the workload runs in a
+    # container. A separate outcome record (new seq) keeps the attempt and
+    # its result distinguishable; but an identical miss repeats on every
+    # call under fire: always, so record each distinct (rule, message) once
+    # per LOG INSTANCE, never per process: a second FiringLog in the same
+    # process (a reopened leg, a new test) must still see its own note.
+    if log is None:
+        return
+    noted = getattr(log, "_pyteman_noted", None)
+    if noted is None:
+        noted = log._pyteman_noted = set()
+    key = (rule.id, message)
+    if key not in noted:
+        noted.add(key)  # idempotent; a rare check-then-add race costs one duplicate line
+        log.record(rule, ctx, outcome=message)

pyteman-0.1.0/src/pyteman/barriers.py

@@ -0,0 +1,21 @@
+# src/pyteman/barriers.py
+import threading
+
+_lock = threading.Lock()
+_state = {}
+
+def wait(name, timeout_s=30.0):
+    with _lock:
+        ev = _state.setdefault(name, threading.Event())
+    if ev.is_set():
+        return True
+    return ev.wait(timeout_s)
+
+def open(name):
+    with _lock:
+        _state.setdefault(name, threading.Event()).set()
+
+def reset_all():
+    global _state
+    with _lock:
+        _state = {}

pyteman-0.1.0/src/pyteman/conditions.py

@@ -0,0 +1,7 @@
+# The eval namespace is convenience scoping, not a security boundary: rules are trusted operator input.
+_SAFE = {"len": len, "str": str, "int": int, "float": float, "bool": bool,
+         "abs": abs, "min": min, "max": max, "sorted": sorted, "isinstance": isinstance}
+_EVAL_GLOBALS = {"__builtins__": {}, **_SAFE}
+
+def eval_expr(code, ctx):
+    return eval(code, _EVAL_GLOBALS, ctx)

pyteman-0.1.0/src/pyteman/firing.py

@@ -0,0 +1,32 @@
+# src/pyteman/firing.py
+import json
+import threading
+import time
+
+class FiringLog:
+    def __init__(self, path):
+        self.path = path
+        self._seq = 0
+        self._lock = threading.Lock()
+        self._fh = open(path, "a")
+
+    def record(self, rule, ctx, note=None, outcome=None):
+        # "outcome" marks action-outcome annotations (skips, execute
+        # failures) so log consumers can tell them from firing records,
+        # which carry the action dump in "note".
+        rec = {
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%S"),
+            "rule": rule.id,
+            "event": rule.event,
+            "thread": threading.current_thread().name,
+            "note": note}
+        if outcome is not None:
+            rec["outcome"] = outcome
+        with self._lock:
+            self._seq += 1
+            rec["seq"] = self._seq
+            self._fh.write(json.dumps(rec) + "\n")
+            self._fh.flush()
+
+def open_log(path):
+    return FiringLog(path) if path else None

pyteman-0.1.0/src/pyteman/patcher.py

@@ -0,0 +1,146 @@
+import builtins
+import functools
+import sys
+
+from pyteman.actions import run_action
+from pyteman.conditions import eval_expr
+from pyteman.targets import parse_target_spec
+
+_NO_OVERRIDE = object()
+
+class Patcher:
+    def __init__(self, rules, log):
+        self.rules = rules
+        self.log = log
+        self.applied = []
+        self._orig_import = None
+        self._wrapped = []
+
+    def force_patch_module(self, modname):
+        mod = sys.modules.get(modname)
+        if mod is not None:
+            self._patch(mod, modname)
+
+    def _patch(self, mod, modname):
+        for rule in self.rules:
+            if rule.module != modname:
+                continue
+            parts = rule.symbol.split(".")
+            container = mod
+            for part in parts[:-1]:
+                container = getattr(container, part, None)
+                if container is None:
+                    break
+            if container is None or not hasattr(container, parts[-1]):
+                continue
+            name = parts[-1]
+            original = getattr(container, name)
+            if getattr(original, "_pyteman_state", None) is not None:
+                continue  # already wrapped by us: re-patching would double-count fires
+            wrapper = self._make_wrapper(rule, original)
+            setattr(container, name, wrapper)
+            self._wrapped.append((container, name, original))
+            self.applied.append(f"{modname}:{rule.symbol}")
+
+    def _make_wrapper(self, rule, original):
+        state = {"fires": 0, "seen_keys": set()}
+        when_code = compile(rule.when, f"<pyteman:{rule.id}:when>", "eval") if rule.when else None
+        key_expr = rule.fire.get("key")
+        key_code = compile(key_expr, f"<pyteman:{rule.id}:key>", "eval") if key_expr else None
+        # Install-time analysis (like when_code/key_code above): a param:
+        # target needs the real signature to bind positional-or-keyword
+        # arguments by name, so compute it once here instead of per firing
+        # and never mutate the user's callable. The kind comes from the
+        # same parser the resolver uses, so whitespace or a typo cannot
+        # make the two disagree.
+        sig = None
+        sig_unparseable = False
+        parsed, _ = parse_target_spec(str(rule.action.get("target", "")))
+        if (rule.action.get("kind") == "pragma" and parsed is not None
+                and parsed[0] == "param"):
+            try:
+                import inspect
+                sig = inspect.signature(original)
+            except (TypeError, ValueError):
+                sig = None
+                sig_unparseable = True  # param targets note-and-skip with the true cause
+
+        @functools.wraps(original)
+        def wrapped(*args, **kwargs):
+            ctx = {"args": args, "kwargs": kwargs, "fires": state["fires"]}
+            if sig is not None or sig_unparseable:
+                # Only param:-targeted rules pay for the ctx entry.
+                if sig is not None:
+                    ctx["_signature"] = sig
+                if sig_unparseable:
+                    ctx["_signature_unparseable"] = True
+            if rule.event == "entry" and _gate(rule, state, ctx, when_code, key_code):
+                run_action(rule, ctx, log=self.log)
+                override = ctx.get("_override", _NO_OVERRIDE)
+                if override is not _NO_OVERRIDE:
+                    return override
+            result = None
+            exc = None
+            try:
+                result = original(*args, **kwargs)
+            except BaseException as e:
+                exc = e
+                raise
+            finally:
+                if rule.event == "exit":
+                    ctx["result"] = result
+                    ctx["exc"] = exc
+                    if _gate(rule, state, ctx, when_code, key_code):
+                        run_action(rule, ctx, log=self.log)
+            override = ctx.get("_override", _NO_OVERRIDE)
+            return override if override is not _NO_OVERRIDE else result
+
+        wrapped._pyteman_state = state
+        return wrapped
+
+    def install_hook(self):
+        orig = builtins.__import__
+
+        def hooked(name, *a, **k):
+            mod = orig(name, *a, **k)
+            target = sys.modules.get(name)
+            if target is not None:
+                self._patch(target, name)
+            return mod
+
+        self._orig_import = orig
+        builtins.__import__ = hooked
+
+    def uninstall(self):
+        if self._orig_import is not None:
+            builtins.__import__ = self._orig_import
+            self._orig_import = None
+        for container, name, original in reversed(self._wrapped):
+            setattr(container, name, original)
+        self._wrapped.clear()
+
+
+def _gate(rule, state, ctx, when_code=None, key_code=None):
+    state["fires"] += 1
+    ctx["fires"] = state["fires"]
+    mode = rule.fire.get("mode", "always")
+    pending_key = None
+    if mode == "countdown":
+        n = int(rule.fire.get("n", 1))
+        if state["fires"] != n + 1:
+            return False
+    elif mode == "once_per":
+        pending_key = eval_expr(key_code, ctx) if key_code is not None else None
+        if pending_key in state["seen_keys"]:
+            return False
+    if when_code is not None and not eval_expr(when_code, ctx):
+        return False
+    if mode == "once_per":
+        state["seen_keys"].add(pending_key)
+    return True
+
+
+def install(rules, log=None):
+    p = Patcher(rules, log)
+    p.install_hook()
+    return p