A zero‑configuration execution recorder for Python.
Know what your code actually did, even when it fails silently.
Python code can fail silently:
- exceptions are swallowed (
try/except: pass) - functions return
Noneunexpectedly - control flow diverges from what you expected
Logs and debuggers only help if you already know where to look.
Blackbox-Recorder answers a different question:
After my program ran, what actually happened?
Not guesses. Not logs you forgot to add. Actual execution evidence.
pip install blackbox-recorderimport blackbox_recorder
blackbox_recorder.start()
# ... your code runs here ...
blackbox_recorder.stop()
blackbox_recorder.report()Execution Summary
----------------------------------------------------------------------
process_data | called 3x | avg 12.3ms | 1 exception(s)
validate_input | called 6x | avg 0.1ms | ok
transform_payload | called 5x | avg 0.4ms | returned None 1x
Exceptions
----------------------------------------------------------------------
process_data → ValueError('invalid format')
No configuration. No code changes. Just evidence.
| It IS | It is NOT |
|---|---|
| A passive execution recorder | A debugger |
| Zero‑configuration | A profiler |
| Post‑mortem friendly | An observability platform |
| Lightweight and local | An AI tool |
| Zero dependencies (stdlib only) | Distributed tracing system |
Think flight recorder, not live cockpit controls.
Note: Only uses Python standard library. No external packages required.
- Records function calls, timing, exceptions, returns
- Captures swallowed exceptions
- Human‑readable summary report
- Save reports to file (with append mode)
- Chronological execution timeline
- Shallow argument capture
- Shallow return value capture
- JSON export
- CLI:
blackbox-recorder run script.py - Module include/exclude filters
configure()API
- Async/await support
- Sampling mode (trace a fraction of calls)
- Automatic disk persistence
All versions are backward‑compatible.
For complete and detailed API documentation (including all function signatures, parameters, examples, classes, CLI options, use cases, and troubleshooting), see:
Quick links:
- Core Functions:
start(),stop(),report(),timeline(),save_report(),save_json(),configure() - Context Manager:
Recorder - Async Support:
get_async_tracer() - Low-Level Classes:
Tracer,ExecutionData,TimelineEvent,AsyncTracer,Config - CLI Reference:
blackbox-recorder runwith examples - Use Cases: Debugging, performance, production, testing
- Troubleshooting & FAQ: 13 Q&As
- Backend developers
- Script authors
- Data engineers
- Anyone debugging code without perfect logs
Not designed for high‑traffic production systems (yet).
- Replacing debuggers
- Replacing logging
- Real‑time visualization
- Distributed tracing
- Version: 0.4.2
- Stability: Alpha
- License: MIT
- Python: 3.9+
- Dependencies: Zero (stdlib only)
- Tests: 124 passing (unit + integration)
- Repository: github.com/Harshit-code-tech/BLACKBOX
- PyPI: pypi.org/project/blackbox-recorder
blackbox-recorder records what your Python code actually did, especially when it failed quietly, without requiring you to prepare for failure in advance.