pyteman 0.1.0__py3-none-any.whl

pyteman/__init__.py

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

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/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/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/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/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

pyteman/rules.py

@@ -0,0 +1,90 @@
+from dataclasses import dataclass, field
+from typing import Optional
+import yaml
+
+from pyteman.targets import parse_target_spec, validate_target_spec
+
+class RuleError(Exception):
+    pass
+
+_EVENTS = ("entry", "exit")
+_ACTION_KINDS = ("sleep", "raise", "return_value", "return_none", "kill", "pragma", "barrier")
+_FIRE_MODES = ("always", "once_per", "countdown")
+
+@dataclass
+class Rule:
+    id: str
+    module: str
+    symbol: str
+    event: str
+    action: dict
+    fire: dict = field(default_factory=lambda: {"mode": "always"})
+    when: Optional[str] = None
+
+def parse_point(point: str) -> tuple[str, str]:
+    """Split a point string at the LAST dot: "os.path.join" -> ("os.path", "join").
+
+    Rule points deliberately resolve differently: load_rules splits at the
+    FIRST dot so "pkg.Class.method" yields module "pkg" and symbol
+    "Class.method", the attribute chain walked from the imported module.
+    """
+    if "." not in point:
+        raise RuleError(f"point must be 'module.symbol' (got {point!r})")
+    mod, _, sym = point.rpartition(".")
+    return mod, sym
+
+def load_rules(path: str) -> list:
+    with open(path) as fh:
+        raw = yaml.safe_load(fh)
+    if raw is None:
+        raw = []
+    if not isinstance(raw, list):
+        raise RuleError("ruleset must be a YAML list")
+    rules = []
+    for i, item in enumerate(raw):
+        where = f"rule #{i}"
+        if not isinstance(item, dict):
+            raise RuleError(f"{where}: mapping required")
+        for key in ("id", "point", "event", "action"):
+            if key not in item:
+                raise RuleError(f"{where}: missing {key}")
+        if item["event"] not in _EVENTS:
+            raise RuleError(f"{where}: event must be one of {_EVENTS}")
+        action = item["action"]
+        if not isinstance(action, dict) or action.get("kind") not in _ACTION_KINDS:
+            raise RuleError(f"{where}: action.kind must be one of {_ACTION_KINDS}")
+        # target: is consumed by pragma only (today). Validate loudly here so a
+        # typo'd spec dies at load, never as a silent runtime no-op.
+        if action.get("kind") == "pragma":
+            for field in ("name", "value"):
+                if field not in action:
+                    raise RuleError(f"{where}: pragma action needs '{field}'")
+        if "target" in action:
+            if action.get("kind") != "pragma":
+                raise RuleError(f"{where}: 'target' is only consumed by pragma actions")
+            try:
+                validate_target_spec(action["target"], where)
+            except ValueError as e:
+                raise RuleError(str(e)) from None
+            parsed, _ = parse_target_spec(action["target"])
+            if parsed is not None and parsed[0] == "result" and item["event"] == "entry":
+                raise RuleError(
+                    f"{where}: target 'result' can only resolve on exit events")
+        fire = item.get("fire", {"mode": "always"})
+        if not isinstance(fire, dict):
+            raise RuleError(f"{where}: fire must be a mapping")
+        if fire.get("mode") not in _FIRE_MODES:
+            raise RuleError(f"{where}: fire.mode must be one of {_FIRE_MODES}")
+        # Rule targets are "module.Class.method": the module is the first dot
+        # component and the symbol is the attribute path walked from it, so the
+        # split here is at the FIRST dot (parse_point keeps the last-dot split
+        # for module-path interpretation).
+        point = item["point"]
+        if not isinstance(point, str):
+            raise RuleError(f"{where}: point must be a string")
+        if "." not in point:
+            raise RuleError(f"point must be 'module.symbol' (got {point!r})")
+        mod, _, sym = point.partition(".")
+        rules.append(Rule(id=item["id"], module=mod, symbol=sym, event=item["event"],
+                          action=action, fire=fire, when=item.get("when")))
+    return rules

pyteman/runner/matrix.py

@@ -0,0 +1,40 @@
+import json
+import os
+import sqlite3
+
+def run_matrix(cells, run_cell, results_db, artifact_root):
+    """Run every cell once, persisting each outcome to the results db.
+
+    Returned status reflects execution outcome: done, failed (run_cell
+    raised) or skipped (a previous run already recorded done). The results
+    db is the durable record; failed cells re-run on the next invocation.
+    """
+    # The runner owns its artifact root: create it before opening the results
+    # db, so a fresh root (first run of a new matrix) works without the caller
+    # having pre-created anything.
+    os.makedirs(os.path.dirname(os.path.abspath(results_db)), exist_ok=True)
+    con = sqlite3.connect(results_db)
+    con.execute("CREATE TABLE IF NOT EXISTS results("
+                "cell_id TEXT PRIMARY KEY, status TEXT, result_json TEXT, artifact_dir TEXT)")
+    con.commit()
+    out = []
+    for cell in cells:
+        row = con.execute("SELECT status FROM results WHERE cell_id=?",
+                          (cell["id"],)).fetchone()
+        if row and row[0] == "done":
+            out.append({"cell_id": cell["id"], "status": "skipped"})
+            continue
+        adir = os.path.join(artifact_root, cell["id"])
+        os.makedirs(adir, exist_ok=True)
+        try:
+            result = run_cell(cell, adir) or {}
+            status = "done"
+        except Exception as e:
+            result = {"error": repr(e)}
+            status = "failed"
+        con.execute("INSERT OR REPLACE INTO results VALUES (?,?,?,?)",
+                    (cell["id"], status, json.dumps(result), adir))
+        con.commit()
+        out.append({"cell_id": cell["id"], "status": status, "result": result})
+    con.close()
+    return out

pyteman/runner/report.py

@@ -0,0 +1,19 @@
+import json
+import sqlite3
+
+def matrix_markdown(results_db, out_path):
+    con = sqlite3.connect(results_db)
+    rows = con.execute("SELECT cell_id, status, result_json FROM results "
+                       "ORDER BY cell_id").fetchall()
+    con.close()
+    lines = ["| cell | status | signature |", "|---|---|---|"]
+    for cid, status, rj in rows:
+        sig = ""
+        try:
+            r = json.loads(rj or "{}")
+            sig = r.get("signature", r.get("error", ""))
+        except Exception:
+            sig = "?"
+        lines.append(f"| {cid} | {status} | {sig} |")
+    with open(out_path, "w") as fh:
+        fh.write("\n".join(lines) + "\n")

pyteman/sitecustomize.py

@@ -0,0 +1,27 @@
+# src/pyteman/sitecustomize.py
+import os
+import sys
+
+def _main():
+    rules_path = os.environ.get("PYTEMAN_RULES", "").strip()
+    if not rules_path:
+        return  # INERT: no env, no effects
+    marker = os.environ.get("PYTEMAN_REQUIRE_MARKER", "").strip()
+    if marker and not os.path.isfile(marker):
+        sys.stderr.write(f"pyteman: refusing to start: marker file missing: {marker}\n")
+        sys.stderr.flush()
+        # sys.exit(2) is swallowed here: an exception escaping sitecustomize
+        # during startup hits init_import_site, which exits 1 regardless of
+        # the code. Hard-exit so the refusal status survives.
+        os._exit(2)
+    from pyteman.rules import load_rules
+    from pyteman.patcher import install
+    from pyteman.firing import open_log
+    rules = load_rules(rules_path)
+    log = open_log(os.environ.get("PYTEMAN_LOG", "pyteman.log"))
+    patcher = install(rules, log=log)
+    for modname in {r.module for r in rules}:
+        patcher.force_patch_module(modname)
+    sys._pyteman = {"patcher": patcher, "log": log}
+
+_main()

pyteman/sqlitekit/integrity.py

@@ -0,0 +1,20 @@
+# src/pyteman/sqlitekit/integrity.py
+def classify_integrity(text: str) -> dict:
+    lines = [l.strip() for l in text.strip().splitlines() if l.strip()]
+    if lines == ["ok"]:
+        return {"classes": ["CLEAN"], "raw": text}
+    classes = set()
+    damage = [l for l in lines if l != "*** in database main ***"]
+    for l in damage:
+        low = l.lower()
+        if "file is not a database" in low:
+            classes.add("NOTADB")
+        elif "malformed database schema" in low:
+            classes.add("SCHEMA")
+        elif "out of order" in low:
+            classes.add("CANONICAL_ROWID_DISORDER")
+        elif "wrong # of entries in index" in low:
+            classes.add("CANONICAL_INDEX_COUNT")
+    if damage and not classes and all("_fts" in l for l in damage):
+        classes.add("FTS_ONLY")
+    return {"classes": sorted(classes), "raw": text}

pyteman/targets.py

@@ -0,0 +1,127 @@
+# src/pyteman/targets.py
+"""Resolution of `target:` specs against the firing context.
+
+Rules sometimes need to reach state the instrumented callable holds rather
+than receives: a SessionDB carries its sqlite3.Connection as `self._conn`,
+so no argument scan can find it. An action may declare:
+
+    target: self._conn     first positional argument, then attribute walk
+    target: param:db       argument by parameter name (signature-bound,
+                           positional or keyword)
+    target: result         the exit-event return value
+
+For a method patched through its class ("pkg.Session.append"), `self` is
+the receiver; for a plain function it is simply the first argument.
+
+One parser (parse_target_spec) defines the grammar for both consumers:
+load-time validation dies loudly on a bad spec, and resolve_target turns
+runtime misses (attribute absent, parameter not passed) into
+(value=None, reason) so callers leave a firing-log note instead of
+silently no-op'ing. This module deliberately depends on nothing else in
+pyteman.
+"""
+from functools import lru_cache
+
+
+def resolve_target(ctx, spec):
+    parsed, err = _parse(spec)
+    if parsed is None:
+        return None, err
+    kind, name, dotted = parsed
+    if kind == "result":
+        if "result" not in ctx:
+            return None, "'result' is only available on exit events"
+        if ctx["result"] is None:
+            return None, "target 'result' resolved to None"
+        return ctx["result"], None
+    if kind == "param":
+        if ctx.get("_signature_unparseable"):
+            return None, "the instrumented callable has no parseable signature"
+        sig = ctx.get("_signature")
+        if sig is None:
+            return None, "param: target reached without an instrumented context"
+        try:
+            bound = sig.bind_partial(*ctx.get("args", ()), **ctx.get("kwargs", {})).arguments
+        except TypeError:
+            return None, f"arguments do not bind for parameter {name!r}"
+        if name not in bound:
+            return None, f"parameter {name!r} not passed in this call"
+        obj = bound[name]
+    else:  # self
+        args = ctx.get("args") or ()
+        if not args:
+            return None, f"{spec!r}: call has no positional arguments"
+        obj = args[0]
+    if not dotted:
+        if obj is None:
+            return None, f"target {spec!r} resolved to None"
+        return obj, None
+    for step in dotted:
+        try:
+            obj = getattr(obj, step)
+        except AttributeError:
+            return None, f"{spec!r}: no attribute {step!r} on {type(obj).__name__}"
+    if obj is None:
+        return None, f"target {spec!r} resolved to None"
+    return obj, None
+
+
+@lru_cache(maxsize=256)
+def parse_target_spec(spec):
+    """Structured form of a spec: ((kind, name, dotted), None) or (None, reason).
+
+    Cached: specs are per-rule constants resolved on every firing.
+    Raises nothing; callers decide the failure policy.
+    """
+    if not isinstance(spec, str) or not spec.strip():
+        return None, "target must be a non-empty string"
+    spec = spec.strip()
+    if spec == "result":
+        return ("result", None, ()), None
+    if spec.startswith("param:"):
+        rest = spec[len("param") + 1:]
+        name, _, tail = rest.partition(".")
+        if not name:
+            return None, "param: needs a parameter name"
+        dotted, err = _steps(tail, spec)
+        if err:
+            return None, err
+        return ("param", name, dotted), None
+    root, _, tail = spec.partition(".")
+    if root == "self":
+        dotted, err = _steps(tail, spec)
+        if err:
+            return None, err
+        return ("self", None, dotted), None
+    return None, f"target root must be self/param:<name>/result (got {root!r})"
+
+
+def _steps(tail, spec):
+    """Dotted walk steps, or an error: empty components are a typo, not a
+    spelling of a shorter walk, so 'self..a' is rejected rather than read
+    as 'self.a'."""
+    if not tail:
+        return (), None
+    steps = tuple(tail.split("."))
+    if any(not st for st in steps):
+        return None, f"bad target spec {spec!r} (empty step)"
+    return steps, None
+
+
+def _parse(spec):
+    # lru_cache requires hashables and the spec is operator-authored YAML
+    # (a string by construction); guard anyway for direct API callers.
+    try:
+        return parse_target_spec(spec)
+    except TypeError:
+        return None, "target must be a string"
+
+
+def validate_target_spec(spec, where):
+    """Load-time check; raises ValueError when the spec can never resolve.
+
+    rules.py wraps this in its RuleError so this module stays a leaf.
+    """
+    parsed, reason = _parse(spec)
+    if parsed is None:
+        raise ValueError(f"{where}: {reason}")

pyteman-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+pyteman/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+pyteman/actions.py,sha256=eIC9DnTwE2NyByR_z2ugt7f8xlbPtrR4kOmlDIT3afI,3569
+pyteman/barriers.py,sha256=Bk53xHFCvbksOxaiVdeLvjtw5PqrO0hA-1Izl1vQDgo,418
+pyteman/conditions.py,sha256=Un6jRIKgU0dRT-Lum8EB6ggQ_V1nYvsIAaASj98NvJY,383
+pyteman/firing.py,sha256=RmMgwb4A7dvnvlWGjM8wu6YVVhOZ42wNHJJOSG0dJXc,997
+pyteman/patcher.py,sha256=1_KmsgberoH_3qYkORj0hCOANdU-hj_aOQ6-Ja4yI30,5484
+pyteman/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyteman/rules.py,sha256=5RVi938gYlW3-gwaEifJTIQAI8fMgGWzqpTLXN-pb6c,3909
+pyteman/sitecustomize.py,sha256=OW1eQMJO36PoSaHpxkopwEej8ygADBYNTbCQBXGZGvY,1067
+pyteman/targets.py,sha256=39FXxoVSlZ7OKrBjW8FlYhgaYgxW7OPajCG68bOd3Tc,4726
+pyteman/runner/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyteman/runner/matrix.py,sha256=oNqHtb_z82xZS1OwdoRKsh3Fm9_-ys5fKBNzK5O9fzc,1715
+pyteman/runner/report.py,sha256=m_antIzQyPFxusbTJsjVl0vzPP6IP7aY8NcGAXhZ9GI,656
+pyteman/sqlitekit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyteman/sqlitekit/integrity.py,sha256=U31_vbizbq-i400-qJU9Y7usZ7cMahSEW6r-kVX6Kao,861
+pyteman-0.1.0.dist-info/licenses/LICENSE,sha256=VJb4m-l1fPOvTkuncEQvck6TtUUAgA56Te-XaPhAR74,1071
+pyteman-0.1.0.dist-info/METADATA,sha256=0C3p2qZrgvG16eQTVl5WAuoDdd4F4G-EG_lwOMxboIo,8104
+pyteman-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pyteman-0.1.0.dist-info/top_level.txt,sha256=o4gowPIR4Z_UOvUyeaM9DjUTe8pBbSliXOGRm_cvRUo,8
+pyteman-0.1.0.dist-info/RECORD,,

pyteman-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyteman-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyteman