# blackboxpy

A zero‑configuration execution recorder for Python.

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

[![PyPI version](https://img.shields.io/pypi/v/blackboxpy)](https://pypi.org/project/blackboxpy/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## 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

```bash
pip install blackboxpy
```

### Use (3 lines)

```python
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](API_DOCUMENTATION.md)**

**Quick links:**
- [Core Functions](API_DOCUMENTATION.md#core-functions): `start()`, `stop()`, `report()`, `timeline()`, `save_report()`, `save_json()`, `configure()`
- [Context Manager](API_DOCUMENTATION.md#context-manager): `Recorder`
- [Async Support](API_DOCUMENTATION.md#async-support): `get_async_tracer()`
- [Low-Level Classes](API_DOCUMENTATION.md#low-level-classes): `Tracer`, `ExecutionData`, `TimelineEvent`, `AsyncTracer`, `Config`
- [CLI Reference](API_DOCUMENTATION.md#cli-reference): `blackboxpy run` with examples
- [Use Cases](API_DOCUMENTATION.md#common-use-cases): Debugging, performance, production, testing
- [Troubleshooting & FAQ](API_DOCUMENTATION.md#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](https://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.


