astblock 0.1.0__tar.gz

astblock-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[test]"
+      - run: pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pipx run build
+      - run: pipx run twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

astblock-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pipx run build
+      - run: pipx run twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write          # mints the OIDC token PyPI trusted publishing verifies
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

astblock-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/

astblock-0.1.0/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.

astblock-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,120 @@
+# 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/examples/blocklist.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "rules": [
+    {
+      "module": "shop.checkout",
+      "fingerprint": "ebfa39018db86a24",
+      "action": "skip",
+      "reason": "Partner API outage, INC-2231"
+    }
+  ]
+}

astblock-0.1.0/examples/shop/checkout.py

@@ -0,0 +1,21 @@
+"""A toy checkout flow with a statement we want to switch off in an emergency."""
+
+
+def send_receipt(order):
+    print(f"receipt emailed for order {order}")
+
+
+def notify_partner_api(order):
+    # Imagine this third-party API is down and every call hangs for 30s.
+    print(f"notified partner about order {order}")
+
+
+def checkout(order):
+    print(f"charging order {order}")
+    notify_partner_api(order)
+    send_receipt(order)
+    return "ok"
+
+
+if __name__ == "__main__":
+    print(checkout(1001))

astblock-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "astblock"
+dynamic = ["version"]
+description = "Block individual Python statements from running, using an AST-fingerprint blocklist."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Troy Teodoro", email = "troyteodoro00@gmail.com" }]
+keywords = ["ast", "import-hook", "incident-response", "mitigation", "feature-flag"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/troyteodoro/astblock"
+Source = "https://github.com/troyteodoro/astblock"
+Issues = "https://github.com/troyteodoro/astblock/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+astblock = "astblock.__main__:main"
+
+[tool.hatch.version]
+path = "src/astblock/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/astblock"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

astblock-0.1.0/src/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-0.1.0/src/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())