blackbox-recorder 0.4.0

A zero-configuration execution recorder for Python

blackboxpy

A zero‑configuration execution recorder for Python.

Know what your code actually did , even when it fails silently.

---

Problem

Python code can fail silently:

• exceptions are swallowed (try/except: pass)
• functions return None unexpectedly
• control flow diverges from what you expected

Logs and debuggers only help if you already know where to look.

blackboxpy answers a different question:

After my program ran, what actually happened?

Not guesses. Not logs you forgot to add. Actual execution evidence.

---

Quick Start

Install

pip install blackboxpy

Use (3 lines)

import blackboxpy

blackboxpy.start()
# ... your code runs here ...
blackboxpy.stop()
blackboxpy.report()

Output

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.

---

What It Is (and Is Not)

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.

---

Features

v0.1: Core

• Records function calls, timing, exceptions, returns
• Captures swallowed exceptions
• Human‑readable summary report
• Save reports to file (with append mode)

v0.2: Insight

• Chronological execution timeline
• Shallow argument capture
• Shallow return value capture
• JSON export

v0.3: Control

• CLI: blackboxpy run script.py
• Module include/exclude filters
• configure() API

v0.4: Scale

• Async/await support
• Sampling mode (trace a fraction of calls)
• Automatic disk persistence

All versions are backward‑compatible.

---

API Reference

For complete and detailed API documentation (including all function signatures, parameters, examples, classes, CLI options, use cases, and troubleshooting), see:

📖 Full API Documentation

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: blackboxpy run with examples
• Use Cases: Debugging, performance, production, testing
• Troubleshooting & FAQ: 13 Q&As

---

Intended Users

• Backend developers
• Script authors
• Data engineers
• Anyone debugging code without perfect logs

Not designed for high‑traffic production systems (yet).

---

Non‑Goals

• Replacing debuggers
• Replacing logging
• Real‑time visualization
• Distributed tracing

---

Project Info

• Version: 0.4.0
• Stability: Alpha
• License: MIT
• Python: 3.9+
• Dependencies: Zero (stdlib only)
• Tests: 124 passing (unit + integration)
• Homepage: github.com/Harshit-code-tech/blackboxpy

---

blackboxpy records what your Python code actually did , especially when it failed quietly , without requiring you to prepare for failure in advance.