astblock 0.1.0__py3-none-any.whl

astblock/__init__.py

@@ -0,0 +1,29 @@
+"""astblock: block individual statements from running, using an AST-fingerprint blocklist."""
+
+from ._blocklist import ACTIONS, Blocklist, Rule
+from ._errors import BlockedStatementError, BlocklistError
+from ._fingerprint import Statement, find_statements, fingerprint_source
+from ._hook import ENV_VAR, install, install_from_env, is_installed, uninstall
+from ._runtime import hits, reset_hits
+from ._transform import compile_with_blocklist
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ACTIONS",
+    "ENV_VAR",
+    "BlockedStatementError",
+    "Blocklist",
+    "BlocklistError",
+    "Rule",
+    "Statement",
+    "compile_with_blocklist",
+    "find_statements",
+    "fingerprint_source",
+    "hits",
+    "install",
+    "install_from_env",
+    "is_installed",
+    "reset_hits",
+    "uninstall",
+]

astblock/__main__.py

@@ -0,0 +1,168 @@
+"""Command-line interface.
+
+    python -m astblock list myapp.billing [--line 42]
+    python -m astblock check blocklist.json
+    python -m astblock run --blocklist blocklist.json -m myapp [args...]
+    python -m astblock run --blocklist blocklist.json script.py [args...]
+"""
+
+from __future__ import annotations
+
+import argparse
+import builtins
+import importlib.util
+import json
+import os
+import runpy
+import sys
+import types
+
+from ._blocklist import ACTIONS, Blocklist
+from ._errors import BlocklistError
+from ._fingerprint import fingerprint_source
+from ._hook import ENV_VAR, install
+from ._transform import compile_with_blocklist
+
+
+def _looks_like_path(target: str) -> bool:
+    return target.endswith(".py") or os.sep in target or (os.altsep or os.sep) in target
+
+
+def _locate(target: str, module: str | None) -> tuple[str, str]:
+    """Return (module_name, source_path) for a module name or a file path."""
+    if _looks_like_path(target):
+        return module or "__main__", target
+    spec = importlib.util.find_spec(target)
+    if spec is None or not spec.origin or not spec.origin.endswith(".py"):
+        raise LookupError(f"cannot find Python source for module {target!r}")
+    return module or target, spec.origin
+
+
+def _read(path: str) -> bytes:
+    with open(path, "rb") as handle:
+        return handle.read()
+
+
+def _first_line(source_lines: list[str], lineno: int, width: int = 60) -> str:
+    text = source_lines[lineno - 1].strip() if 0 < lineno <= len(source_lines) else ""
+    return text if len(text) <= width else text[: width - 3] + "..."
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    module, path = _locate(args.target, args.module)
+    source = _read(path)
+    statements = fingerprint_source(source, module, path)
+    lines = source.decode("utf-8", errors="replace").splitlines()
+    if args.line is not None:
+        statements = [s for s in statements if s.lineno == args.line]
+    if args.json:
+        rules = [{"module": s.module, "fingerprint": s.fingerprint, "action": args.action}
+                 for s in statements]
+        print(json.dumps({"version": 1, "rules": rules}, indent=2))
+        return 0
+    print(f"# module: {module}   file: {path}")
+    if module == "__main__":
+        print("# (pass --module NAME if this file is imported rather than run as a script)")
+    for s in statements:
+        print(f"{s.lineno:>5}  {s.fingerprint}  {(s.scope or '<module>'):<24}  "
+              f"{_first_line(lines, s.lineno)}")
+    return 0
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    blocklist = Blocklist.load(args.blocklist)
+    problems = 0
+    for name in sorted(blocklist.modules):
+        try:
+            module, path = _locate(name, None) if name != "__main__" else (None, None)
+        except (LookupError, ImportError) as exc:
+            print(f"MISSING  {name}: {exc}")
+            problems += 1
+            continue
+        if path is None:
+            print(f"SKIP     __main__: rules for scripts can't be checked by module name")
+            continue
+        source = _read(path)
+        lines = source.decode("utf-8", errors="replace").splitlines()
+        found = {s.fingerprint: s for s in fingerprint_source(source, module, path)}
+        for fingerprint, rule in blocklist.rules_for(name).items():
+            statement = found.get(fingerprint)
+            if statement is None:
+                print(f"STALE    {name} {fingerprint}: matches no statement")
+                problems += 1
+            else:
+                print(f"OK       {name} {fingerprint} [{rule.action}] line "
+                      f"{statement.lineno}: {_first_line(lines, statement.lineno)}")
+    return 1 if problems else 0
+
+
+def _run_script(path: str, argv: list[str], blocklist: Blocklist) -> None:
+    path = os.path.abspath(path)
+    code = compile_with_blocklist(_read(path), path, "__main__", blocklist)
+    main = types.ModuleType("__main__")
+    main.__file__ = path
+    main.__builtins__ = builtins
+    sys.modules["__main__"] = main
+    sys.argv = [path, *argv]
+    sys.path[0] = os.path.dirname(path)
+    exec(code, main.__dict__)
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    source = args.blocklist or os.environ.get(ENV_VAR)
+    if not source:
+        print(f"astblock run: pass --blocklist or set {ENV_VAR}", file=sys.stderr)
+        return 2
+    blocklist = install(source)
+    rest = list(args.args)
+    if args.module:
+        if args.script is not None:
+            rest.insert(0, args.script)
+        sys.argv = [args.module, *rest]
+        runpy.run_module(args.module, run_name="__main__", alter_sys=True)
+    elif args.script:
+        _run_script(args.script, rest, blocklist)
+    else:
+        print("astblock run: give a script path or -m MODULE", file=sys.stderr)
+        return 2
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="python -m astblock",
+                                     description="Block individual statements from running.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_list = sub.add_parser("list", help="show statements and their fingerprints")
+    p_list.add_argument("target", help="module name (myapp.billing) or path to a .py file")
+    p_list.add_argument("--module", help="module name to fingerprint a file path as")
+    p_list.add_argument("--line", type=int, help="only statements starting on this line")
+    p_list.add_argument("--json", action="store_true", help="print as blocklist JSON")
+    p_list.add_argument("--action", choices=ACTIONS, default="raise",
+                        help="action to use with --json (default: raise)")
+    p_list.set_defaults(func=cmd_list)
+
+    p_check = sub.add_parser("check", help="verify every rule still matches the code")
+    p_check.add_argument("blocklist")
+    p_check.set_defaults(func=cmd_check)
+
+    p_run = sub.add_parser("run", help="run a script or module with a blocklist applied")
+    p_run.add_argument("--blocklist", help=f"blocklist JSON file (default: ${ENV_VAR})")
+    p_run.add_argument("-m", dest="module", help="run a module, like python -m")
+    p_run.add_argument("script", nargs="?")
+    p_run.add_argument("args", nargs=argparse.REMAINDER)
+    p_run.set_defaults(func=cmd_run)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except (BlocklistError, LookupError, OSError, SyntaxError) as exc:
+        print(f"astblock: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

astblock/_blocklist.py

@@ -0,0 +1,145 @@
+"""Blocklist rules and their JSON file format.
+
+Example file::
+
+    {
+      "version": 1,
+      "rules": [
+        {
+          "module": "myapp.billing",
+          "fingerprint": "3f9a0c1d2e4b5a67",
+          "action": "skip",
+          "reason": "INC-1234: duplicate charge email"
+        }
+      ]
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import asdict, dataclass
+from typing import Iterable, Iterator, Mapping
+
+from ._errors import BlocklistError
+from ._fingerprint import FINGERPRINT_LENGTH
+
+ACTIONS = ("raise", "skip")
+FILE_VERSION = 1
+
+_FINGERPRINT_RE = re.compile(rf"^[0-9a-f]{{{FINGERPRINT_LENGTH}}}$")
+_RULE_KEYS = {"module", "fingerprint", "action", "reason"}
+
+
+@dataclass(frozen=True)
+class Rule:
+    """Block one statement in one module.
+
+    ``action`` is ``"raise"`` (raise BlockedStatementError when reached, the
+    default) or ``"skip"`` (do nothing and carry on with the next statement).
+    """
+
+    module: str
+    fingerprint: str
+    action: str = "raise"
+    reason: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.module, str) or not self.module:
+            raise BlocklistError(f"rule module must be a non-empty string, got {self.module!r}")
+        if not isinstance(self.fingerprint, str) or not _FINGERPRINT_RE.match(self.fingerprint):
+            raise BlocklistError(
+                f"rule fingerprint must be {FINGERPRINT_LENGTH} lowercase hex characters, "
+                f"got {self.fingerprint!r}"
+            )
+        if self.action not in ACTIONS:
+            raise BlocklistError(f"rule action must be one of {ACTIONS}, got {self.action!r}")
+        if self.reason is not None and not isinstance(self.reason, str):
+            raise BlocklistError(f"rule reason must be a string, got {self.reason!r}")
+
+
+class Blocklist:
+    """A set of rules, indexed by module and fingerprint."""
+
+    def __init__(self, rules: Iterable[Rule] = ()) -> None:
+        self._by_module: dict[str, dict[str, Rule]] = {}
+        for rule in rules:
+            self.add(rule)
+
+    def add(self, rule: Rule) -> None:
+        self._by_module.setdefault(rule.module, {})[rule.fingerprint] = rule
+
+    @property
+    def modules(self) -> frozenset[str]:
+        return frozenset(self._by_module)
+
+    def rules_for(self, module: str) -> Mapping[str, Rule]:
+        return dict(self._by_module.get(module, {}))
+
+    def __iter__(self) -> Iterator[Rule]:
+        for rules in self._by_module.values():
+            yield from rules.values()
+
+    def __len__(self) -> int:
+        return sum(len(rules) for rules in self._by_module.values())
+
+    def __repr__(self) -> str:
+        return f"Blocklist({len(self)} rules in {len(self._by_module)} modules)"
+
+    # -- serialisation -------------------------------------------------
+
+    @classmethod
+    def from_dict(cls, data: object) -> "Blocklist":
+        if not isinstance(data, dict):
+            raise BlocklistError("blocklist must be a JSON object")
+        unknown = set(data) - {"version", "rules"}
+        if unknown:
+            raise BlocklistError(f"unknown top-level keys: {sorted(unknown)}")
+        if data.get("version", FILE_VERSION) != FILE_VERSION:
+            raise BlocklistError(f"unsupported blocklist version {data.get('version')!r}")
+        raw_rules = data.get("rules", [])
+        if not isinstance(raw_rules, list):
+            raise BlocklistError("'rules' must be a list")
+        rules = []
+        for position, raw in enumerate(raw_rules):
+            if not isinstance(raw, dict):
+                raise BlocklistError(f"rule #{position} must be an object")
+            unknown = set(raw) - _RULE_KEYS
+            if unknown:
+                raise BlocklistError(f"rule #{position} has unknown keys: {sorted(unknown)}")
+            missing = {"module", "fingerprint"} - set(raw)
+            if missing:
+                raise BlocklistError(f"rule #{position} is missing: {sorted(missing)}")
+            try:
+                rules.append(Rule(**raw))
+            except BlocklistError as exc:
+                raise BlocklistError(f"rule #{position}: {exc}") from None
+        return cls(rules)
+
+    @classmethod
+    def from_json(cls, text: str) -> "Blocklist":
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise BlocklistError(f"invalid JSON: {exc}") from None
+        return cls.from_dict(data)
+
+    @classmethod
+    def load(cls, path: str | os.PathLike[str]) -> "Blocklist":
+        try:
+            with open(path, encoding="utf-8") as handle:
+                text = handle.read()
+        except OSError as exc:
+            raise BlocklistError(f"cannot read blocklist {os.fspath(path)!r}: {exc}") from None
+        return cls.from_json(text)
+
+    def to_dict(self) -> dict:
+        rules = []
+        for rule in self:
+            entry = asdict(rule)
+            if entry["reason"] is None:
+                del entry["reason"]
+            rules.append(entry)
+        return {"version": FILE_VERSION, "rules": rules}

astblock/_errors.py

@@ -0,0 +1,19 @@
+"""Exception types raised by astblock."""
+
+from __future__ import annotations
+
+
+class BlocklistError(ValueError):
+    """Raised when a blocklist is malformed or cannot be loaded."""
+
+
+class BlockedStatementError(RuntimeError):
+    """Raised at runtime when execution reaches a statement blocked with action="raise"."""
+
+    def __init__(self, fingerprint: str, reason: str | None = None) -> None:
+        self.fingerprint = fingerprint
+        self.reason = reason
+        message = f"statement {fingerprint} is blocked by astblock"
+        if reason:
+            message += f" ({reason})"
+        super().__init__(message)

astblock/_fingerprint.py

@@ -0,0 +1,135 @@
+"""Stable fingerprints for individual statements.
+
+A fingerprint identifies one statement by *what it is and where it lives*,
+not by its line number, so it survives reformatting, comment edits and code
+being added above it. It is a hash of:
+
+* the module name (``myapp.billing``),
+* the enclosing scope (``Invoice.total`` for a statement inside that method),
+* a canonical serialisation of the statement's AST (no positions),
+* an occurrence index, so identical statements in the same scope differ.
+
+Any change to the statement itself, or moving it to another function,
+produces a different fingerprint. That is deliberate: a blocklist rule
+should stop matching when the code it was written against has changed.
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+from dataclasses import dataclass, field
+from typing import Iterator, List
+
+FINGERPRINT_VERSION = "1"
+FINGERPRINT_LENGTH = 16
+
+_SCOPE_NODES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+
+# Compiler directives rather than runtime actions; replacing them would change
+# how the surrounding code is compiled, so they are never blockable.
+_UNBLOCKABLE = (ast.Global, ast.Nonlocal)
+
+
+@dataclass(frozen=True)
+class Statement:
+    """One blockable statement found in a module."""
+
+    fingerprint: str
+    module: str
+    scope: str
+    lineno: int
+    end_lineno: int | None
+    node: ast.stmt = field(compare=False, repr=False)
+    block: List[ast.stmt] = field(compare=False, repr=False)
+    index: int = field(compare=False, repr=False)
+
+
+def _canon(value: object) -> str:
+    """Serialise an AST without positions, skipping empty/None fields.
+
+    Skipping empty fields keeps fingerprints stable across Python versions
+    that add new optional fields (for example ``type_params`` in 3.12).
+    """
+    if isinstance(value, ast.AST):
+        parts = []
+        for name in value._fields:
+            child = getattr(value, name, None)
+            if child is None or (isinstance(child, list) and not child):
+                continue
+            parts.append(f"{name}={_canon(child)}")
+        return f"{type(value).__name__}({','.join(parts)})"
+    if isinstance(value, list):
+        return "[" + ",".join(_canon(item) for item in value) + "]"
+    return f"{type(value).__name__}:{value!r}"
+
+
+def _hash(module: str, scope: str, canon: str, occurrence: int) -> str:
+    payload = "\0".join(
+        (f"astblock-v{FINGERPRINT_VERSION}", module, scope, canon, str(occurrence))
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:FINGERPRINT_LENGTH]
+
+
+def _is_future_import(node: ast.stmt) -> bool:
+    return isinstance(node, ast.ImportFrom) and node.module == "__future__"
+
+
+def _child_blocks(node: ast.AST) -> Iterator[List[ast.stmt]]:
+    """Yield every statement list directly inside ``node``.
+
+    Covers ``body``/``orelse``/``finalbody`` and also the bodies of
+    ``except`` handlers and ``match`` cases, which are not statements
+    themselves but contain statement lists.
+    """
+    for name in node._fields:
+        value = getattr(node, name, None)
+        if not isinstance(value, list) or not value:
+            continue
+        if isinstance(value[0], ast.stmt):
+            yield value
+            continue
+        for item in value:
+            body = getattr(item, "body", None)
+            if isinstance(body, list) and body and isinstance(body[0], ast.stmt):
+                yield body
+
+
+def find_statements(tree: ast.Module, module: str) -> list[Statement]:
+    """Return every blockable statement in ``tree``, in source order."""
+    found: list[Statement] = []
+    seen: dict[tuple[str, str], int] = {}
+
+    def visit(block: List[ast.stmt], scope: list[str]) -> None:
+        scope_name = ".".join(scope)
+        for index, node in enumerate(block):
+            if not isinstance(node, _UNBLOCKABLE) and not _is_future_import(node):
+                canon = _canon(node)
+                key = (scope_name, canon)
+                occurrence = seen.get(key, 0)
+                seen[key] = occurrence + 1
+                found.append(
+                    Statement(
+                        fingerprint=_hash(module, scope_name, canon, occurrence),
+                        module=module,
+                        scope=scope_name,
+                        lineno=node.lineno,
+                        end_lineno=getattr(node, "end_lineno", None),
+                        node=node,
+                        block=block,
+                        index=index,
+                    )
+                )
+            inner = scope + [node.name] if isinstance(node, _SCOPE_NODES) else scope
+            for child in _child_blocks(node):
+                visit(child, inner)
+
+    visit(tree.body, [])
+    return found
+
+
+def fingerprint_source(
+    source: str | bytes, module: str, filename: str = "<unknown>"
+) -> list[Statement]:
+    """Parse ``source`` and return its blockable statements."""
+    return find_statements(ast.parse(source, filename=filename), module)

astblock/_hook.py

@@ -0,0 +1,111 @@
+"""Import hook that compiles targeted modules with the blocklist applied.
+
+Only modules named in the blocklist are intercepted; everything else imports
+exactly as normal. Targeted modules are always compiled from source and their
+bytecode is never cached, so a stale ``.pyc`` can't bypass a rule and a
+patched ``.pyc`` never outlives the blocklist.
+"""
+
+from __future__ import annotations
+
+import importlib.abc
+import importlib.machinery
+import logging
+import os
+import sys
+from types import CodeType
+
+from ._blocklist import Blocklist
+from ._transform import compile_with_blocklist
+
+logger = logging.getLogger("astblock")
+
+ENV_VAR = "ASTBLOCK_FILE"
+
+_finder: "_BlockingFinder | None" = None
+
+
+class _BlockingLoader(importlib.machinery.SourceFileLoader):
+    def __init__(self, fullname: str, path: str, blocklist: Blocklist) -> None:
+        super().__init__(fullname, path)
+        self._blocklist = blocklist
+
+    def get_code(self, fullname: str) -> CodeType:
+        source = self.get_data(self.path)
+        return compile_with_blocklist(source, self.path, fullname, self._blocklist)
+
+
+class _BlockingFinder(importlib.abc.MetaPathFinder):
+    def __init__(self, blocklist: Blocklist) -> None:
+        self.blocklist = blocklist
+
+    def find_spec(self, fullname, path, target=None):
+        if fullname not in self.blocklist.modules:
+            return None
+        spec = None
+        for finder in sys.meta_path:
+            if finder is self or not hasattr(finder, "find_spec"):
+                continue
+            spec = finder.find_spec(fullname, path, target)
+            if spec is not None:
+                break
+        if spec is None:
+            return None
+        loader = spec.loader
+        if isinstance(loader, importlib.machinery.SourceFileLoader) and not isinstance(
+            loader, _BlockingLoader
+        ):
+            spec.loader = _BlockingLoader(fullname, loader.path, self.blocklist)
+        else:
+            logger.warning(
+                "astblock: cannot apply rules to %s: it is not loaded from a .py "
+                "source file (loader: %r)", fullname, loader)
+        return spec
+
+
+def install(blocklist: Blocklist | str | os.PathLike[str]) -> Blocklist:
+    """Start applying ``blocklist`` to modules imported from now on.
+
+    Accepts a Blocklist or a path to a blocklist JSON file. Replaces any
+    previously installed blocklist. Returns the installed Blocklist.
+    """
+    global _finder
+    if not isinstance(blocklist, Blocklist):
+        blocklist = Blocklist.load(blocklist)
+    uninstall()
+    already = sorted(name for name in blocklist.modules if name in sys.modules)
+    if already:
+        logger.warning(
+            "astblock: already imported, rules won't apply to these until the "
+            "process restarts: %s", ", ".join(already))
+    _finder = _BlockingFinder(blocklist)
+    sys.meta_path.insert(0, _finder)
+    return blocklist
+
+
+def uninstall() -> None:
+    """Stop intercepting imports. Modules already imported stay patched."""
+    global _finder
+    if _finder is not None:
+        try:
+            sys.meta_path.remove(_finder)
+        except ValueError:
+            pass
+        _finder = None
+
+
+def is_installed() -> bool:
+    return _finder is not None and _finder in sys.meta_path
+
+
+def install_from_env(var: str = ENV_VAR) -> Blocklist | None:
+    """Install the blocklist named by ``$ASTBLOCK_FILE``, if set.
+
+    A blocklist that is set but unreadable or invalid raises BlocklistError
+    rather than being ignored: running unpatched when an emergency patch was
+    requested is worse than failing to start.
+    """
+    path = os.environ.get(var)
+    if not path:
+        return None
+    return install(path)

astblock/_runtime.py

@@ -0,0 +1,43 @@
+"""Runtime side of a blocked statement.
+
+Every blocked statement is rewritten into a call to :func:`blocked`, so that
+hits are counted and logged and ``raise`` rules can raise. This module is
+imported by rewritten code, so it must stay small and dependency-free.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections import Counter
+
+from ._errors import BlockedStatementError
+
+logger = logging.getLogger("astblock")
+
+_hits: Counter[str] = Counter()
+_lock = threading.Lock()
+
+
+def blocked(fingerprint: str, action: str, reason: str | None) -> None:
+    with _lock:
+        _hits[fingerprint] += 1
+        first = _hits[fingerprint] == 1
+    # Log the first hit loudly and later hits quietly, so a blocked statement
+    # inside a hot loop doesn't flood the logs.
+    level = logging.WARNING if first else logging.DEBUG
+    logger.log(level, "astblock: blocked statement %s reached (action=%s, reason=%s)",
+               fingerprint, action, reason)
+    if action == "raise":
+        raise BlockedStatementError(fingerprint, reason)
+
+
+def hits() -> dict[str, int]:
+    """Return how many times each blocked statement has been reached."""
+    with _lock:
+        return dict(_hits)
+
+
+def reset_hits() -> None:
+    with _lock:
+        _hits.clear()

astblock/_transform.py

@@ -0,0 +1,76 @@
+"""Rewrite blocked statements and compile the result."""
+
+from __future__ import annotations
+
+import ast
+import logging
+from types import CodeType
+from typing import Mapping
+
+from ._blocklist import Blocklist, Rule
+from ._fingerprint import find_statements
+
+logger = logging.getLogger("astblock")
+
+_NEW_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)
+
+
+def _contains_yield(node: ast.AST) -> bool:
+    """True if ``node`` yields on behalf of its enclosing function."""
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, (ast.Yield, ast.YieldFrom)):
+            return True
+        if not isinstance(child, _NEW_SCOPES) and _contains_yield(child):
+            return True
+    return False
+
+
+def _replacement(node: ast.stmt, rule: Rule) -> ast.stmt:
+    call = (
+        "__import__('astblock._runtime', fromlist=['blocked']).blocked("
+        f"{rule.fingerprint!r}, {rule.action!r}, {rule.reason!r})"
+    )
+    if _contains_yield(node) and not isinstance(node, _NEW_SCOPES):
+        # Removing a function's only ``yield`` would silently turn a generator
+        # into a plain function. Keep an unreachable yield so it stays one.
+        source = f"if False:\n    yield\nelse:\n    {call}"
+    else:
+        source = call
+    new = ast.parse(source).body[0]
+    for child in ast.walk(new):
+        ast.copy_location(child, node)
+    return new
+
+
+def apply_rules(tree: ast.Module, module: str, rules: Mapping[str, Rule]) -> set[str]:
+    """Replace blocked statements in ``tree`` in place.
+
+    Returns the fingerprints that matched a statement.
+    """
+    matched: set[str] = set()
+    for statement in find_statements(tree, module):
+        rule = rules.get(statement.fingerprint)
+        if rule is None:
+            continue
+        matched.add(statement.fingerprint)
+        statement.block[statement.index] = _replacement(statement.node, rule)
+    return matched
+
+
+def compile_with_blocklist(
+    source: str | bytes, filename: str, module: str, blocklist: Blocklist
+) -> CodeType:
+    """Compile ``source`` as ``module`` with the blocklist's rules applied."""
+    tree = ast.parse(source, filename=filename)
+    rules = blocklist.rules_for(module)
+    if rules:
+        matched = apply_rules(tree, module, rules)
+        if matched:
+            logger.warning("astblock: blocked %d statement(s) in %s: %s",
+                           len(matched), module, ", ".join(sorted(matched)))
+        stale = sorted(set(rules) - matched)
+        if stale:
+            logger.warning(
+                "astblock: %d rule(s) for %s matched nothing (code changed since the "
+                "rule was written?): %s", len(stale), module, ", ".join(stale))
+    return compile(tree, filename, "exec", dont_inherit=True)

astblock-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: astblock
+Version: 0.1.0
+Summary: Block individual Python statements from running, using an AST-fingerprint blocklist.
+Project-URL: Homepage, https://github.com/troyteodoro/astblock
+Project-URL: Source, https://github.com/troyteodoro/astblock
+Project-URL: Issues, https://github.com/troyteodoro/astblock/issues
+Author-email: Troy Teodoro <troyteodoro00@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ast,feature-flag,import-hook,incident-response,mitigation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# astblock
+
+Switch off individual Python statements without editing or redeploying the code.
+
+You write a small JSON blocklist naming statements by an AST fingerprint. When
+the program starts with that blocklist, each blocked statement is rewritten at
+import time so that it either **skips** (does nothing) or **raises**
+`BlockedStatementError`. Everything not on the list is compiled exactly as normal.
+
+The intended use is emergency mitigation: a third-party call that hangs, a
+side effect that fires twice, a code path that corrupts data. It lets you turn
+that one statement off with a config change and a restart, while the proper fix
+goes through your normal release process.
+
+## Workflow
+
+```console
+# 1. Find the statement's fingerprint
+$ python -m astblock list shop.checkout --line 15
+   15  ebfa39018db86a24  checkout   notify_partner_api(order)
+
+# 2. Generate a rule (then add a reason)
+$ python -m astblock list shop.checkout --line 15 --json --action skip > blocklist.json
+
+# 3. Verify every rule matches the code you're about to run
+$ python -m astblock check blocklist.json
+OK       shop.checkout ebfa39018db86a24 [skip] line 15: notify_partner_api(order)
+
+# 4. Run with it
+$ python -m astblock run --blocklist blocklist.json -m shop.checkout
+```
+
+`examples/` contains this exact scenario.
+
+## Activating it in an application
+
+Pick one:
+
+- **CLI wrapper:** `python -m astblock run --blocklist FILE -m yourapp` or
+  `... run --blocklist FILE script.py`.
+- **One line at the top of your entry point**, before your own modules are
+  imported: `import astblock; astblock.install_from_env()`. It does nothing
+  unless `ASTBLOCK_FILE` is set.
+- **No code change:** a `.pth` file in site-packages containing the single line
+  `import astblock; astblock.install_from_env()` runs at interpreter startup.
+  This is powerful, so only do it in environments you control.
+
+If `ASTBLOCK_FILE` is set but the file is missing or invalid, startup fails
+rather than running unpatched.
+
+## Fingerprints
+
+A fingerprint is a hash of the module name, the enclosing function/class path,
+the statement's AST (without positions), and an occurrence index for identical
+statements in the same scope. So it:
+
+- survives reformatting, comment changes and code added above it;
+- changes if the statement itself changes or moves to another function, so an
+  old rule stops matching instead of hitting the wrong code. Stale rules are
+  logged at import time and reported by `astblock check`.
+
+Generate fingerprints with the same Python minor version you run in
+production: AST shapes occasionally change between versions.
+
+## Blocklist format
+
+```json
+{
+  "version": 1,
+  "rules": [
+    {
+      "module": "shop.checkout",
+      "fingerprint": "ebfa39018db86a24",
+      "action": "skip",
+      "reason": "Partner API outage, INC-2231"
+    }
+  ]
+}
+```
+
+`action` is `"raise"` (the default) or `"skip"`. Scripts run directly use the
+module name `__main__`; code run with `-m pkg.mod` uses `pkg.mod`.
+
+## Semantics and limits: read before using in an incident
+
+- **Skipping is not free.** A skipped assignment leaves the name undefined, a
+  skipped `return` falls through to the following code, and a skipped `def` or
+  `import` removes the name entirely. Block the narrowest statement that does
+  the job, and prefer `raise` where the caller already handles errors.
+- Blocking a compound statement (`if`, `for`, `with`, `def`) blocks all of it.
+- If you block a function's only `yield`, it stays a generator (it just yields nothing).
+- **Import time only.** Rules apply when a module is imported, so the process
+  must restart. Modules imported before `install()` are not patched, and a
+  warning names them.
+- Only modules loaded from `.py` source are patchable, not extension modules or
+  pyc-only distributions. Targeted modules are always compiled from source and
+  never cached, so a stale `.pyc` can't bypass a rule.
+- Hits are logged to the `astblock` logger (first hit at WARNING, later hits at
+  DEBUG) and counted in `astblock.hits()`.
+- **Security:** whoever can write the blocklist can disable any statement,
+  including an authorization check. Treat the file and the `ASTBLOCK_FILE`
+  variable with the same care as your deploy credentials.
+
+## Python API
+
+```python
+import astblock
+
+astblock.install("blocklist.json")        # or a Blocklist object
+astblock.fingerprint_source(src, "mod")   # -> list[Statement]
+astblock.hits()                           # {fingerprint: count}
+astblock.uninstall()
+```
+
+## Development
+
+```console
+pip install -e ".[test]"
+pytest
+```

astblock-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+astblock/__init__.py,sha256=Ijq768eXgpUZ4FDjijDhhiTGsyrFg8BLemBpreGKgJM,791
+astblock/__main__.py,sha256=l6eQl7Ify5w6JlKD8BPjR0VMHo24mf4ifM6z-sE77qY,6576
+astblock/_blocklist.py,sha256=OVLNRWdDQh2PqUbN7W3motZEkX5UQpBAM98b1IGTlQo,5071
+astblock/_errors.py,sha256=ZeF7tqPgUJy9zruAkH8U5qOJMVsNGXdY5CX8RAryvmE,624
+astblock/_fingerprint.py,sha256=RMGjEW62jCRdO2sysGn4asjmmv1sgWc7UbdkDJkBc-U,4975
+astblock/_hook.py,sha256=7Tub4zi459LCdcFBtohormCyGTp3iBKB8fNOEgRPuIM,3698
+astblock/_runtime.py,sha256=oeCgnGxbbj0YA_ssNgl4pbyHVkSxYQwOshkK5gTU2D4,1282
+astblock/_transform.py,sha256=evQqtaNjPhhMyKZ4Tp2Aur_LfStm3sJvRaOidtqR34s,2760
+astblock/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+astblock-0.1.0.dist-info/METADATA,sha256=R7d29ieG4Zop9APUvThGZPjMKdbkSNhUFG7bJMF2IZ8,5774
+astblock-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+astblock-0.1.0.dist-info/entry_points.txt,sha256=mA-8LoZ2QlATQjx3LUaX4Ku8Pj7yIEexEcA5puaQaOw,52
+astblock-0.1.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+astblock-0.1.0.dist-info/RECORD,,

astblock-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

astblock-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+astblock = astblock.__main__:main

astblock-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.