shortfuse

  1"""
  2<img src="banner.png" width="700" alt="Shortfuse Banner">
  3
  4**Don't just raise exceptions—kill the process.**
  5
  6`shortfuse` is a zero-tolerance "fail fast" utility for enforcing architectural boundaries.
  7It creates uncatchable traps in deprecated code paths to instantly halt execution and expose regressions.
  8
  9---
 10
 11## 💥 The "Loud" Failure Demo
 12
 13When `shortfuse` halts, it prints a banner and the stack trace to `stderr` before killing the process.
 14
 15**The Code:**
 16```python
 17import shortfuse
 18
 19def legacy_handler():
 20    # Halt execution immediately if this function is called
 21    shortfuse.halt("Legacy V1 path is forbidden.")
 22
 23legacy_handler()
 24```
 25
 26**The Output (stderr):**
 27
 28```
 29!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 30[SHORTFUSE DETONATED]: Legacy V1 path is forbidden.
 31!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 32
 33  File "demo.py", line 7, in <module>
 34    legacy_handler()
 35  File "demo.py", line 5, in legacy_handler
 36    shortfuse.halt("Legacy V1 path is forbidden.")
 37  File "/lib/shortfuse/__init__.py", line 35, in halt
 38    _die(message)
 39
 40[SHORTFUSE] Terminating process immediately via os._exit(1).
 41```
 42
 43---
 44
 45## 🛠 API Usage
 46
 47### halt(message)
 48Unconditionally stops execution. Use for dead code paths.
 49
 50```python
 51shortfuse.halt("This endpoint is removed.")
 52```
 53
 54### halt_if(condition, message)
 55Halts if the condition is True.
 56
 57```python
 58shortfuse.halt_if(user.is_admin, "Admins cannot use this view")
 59```
 60
 61### halt_unless(condition, message)
 62Halts if the condition is False.
 63
 64```python
 65shortfuse.halt_unless(config.version == 3, "Only V3 config allowed")
 66```
 67
 68### halt_if_not_none(obj, message)
 69Halts if the object is not None. Useful for ensuring optional legacy dependencies are removed.
 70
 71```python
 72shortfuse.halt_if_not_none(legacy_manager, "Manager must be None")
 73```
 74"""
 75import sys
 76import traceback
 77import os
 78
 79__version__ = "0.1.0"
 80
 81def _die(message: str) -> None:
 82    """
 83    Internal helper: prints stack trace to stderr and kills the process
 84    via os._exit(1) to prevent interception.
 85    """
 86    # Visual separation for the logs
 87    print(f"\n{'!'*60}", file=sys.stderr)
 88    print(f"[SHORTFUSE DETONATED]: {message}", file=sys.stderr)
 89    print(f"{'!'*60}\n", file=sys.stderr)
 90
 91    # Print the stack trace to stderr
 92    traceback.print_stack(file=sys.stderr)
 93
 94    print("\n[SHORTFUSE] Terminating process immediately via os._exit(1).", file=sys.stderr)
 95    sys.stdout.flush()
 96    sys.stderr.flush()
 97
 98    # Hard exit. Prevents 'except Exception', 'finally', and cleanup handlers.
 99    os._exit(1)
100
101def halt(message: str = "Execution halted by Shortfuse.") -> None:
102    """
103    Unconditionally stops execution.
104    Use for dead code paths or deprecated endpoints.
105    """
106    _die(message)
107
108def halt_if(condition: bool, message: str = "Condition met: Halting execution.") -> None:
109    """
110    Halts if the condition is True.
111    """
112    if condition:
113        _die(message)
114
115def halt_unless(condition: bool, message: str = "Condition failed: Halting execution.") -> None:
116    """
117    Halts if the condition is False.
118    """
119    if not condition:
120        _die(message)
121
122def halt_if_not_none(obj, message: str = "Object should be None") -> None:
123    """
124    Halts if the object is not None.
125    """
126    if obj is not None:
127        _die(f"{message} (Got type: {type(obj).__name__})")