Metadata-Version: 2.4
Name: blackbox-recorder
Version: 0.4.2
Summary: A zero-configuration execution recorder for Python
Author-email: Harshit Ghosh <harshitghosh7@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Harshit-code-tech/BLACKBOX
Project-URL: Repository, https://github.com/Harshit-code-tech/BLACKBOX
Project-URL: Issues, https://github.com/Harshit-code-tech/BLACKBOX/issues
Keywords: tracing,debugging,execution,recorder,settrace,flight-recorder
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# blackbox-recorder

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/blackbox-recorder)](https://pypi.org/project/blackbox-recorder/)
[![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)](https://github.com/Harshit-code-tech/BLACKBOX)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/Harshit-code-tech/BLACKBOX/blob/main/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 blackbox-recorder
```

### Use (3 lines)

```python
import blackbox_recorder

blackbox_recorder.start()
# ... your code runs here ...
blackbox_recorder.stop()
blackbox_recorder.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: `blackbox-recorder 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](https://github.com/Harshit-code-tech/BLACKBOX/blob/main/API_DOCUMENTATION.md)**

**Quick links:**
- [Core Functions](https://github.com/Harshit-code-tech/BLACKBOX/blob/main/API_DOCUMENTATION.md#core-functions): `start()`, `stop()`, `report()`, `timeline()`, `save_report()`, `save_json()`, `configure()`
- [Context Manager](https://github.com/Harshit-code-tech/BLACKBOX/blob/main/API_DOCUMENTATION.md#context-manager): `Recorder`
- [Async Support](https://github.com/Harshit-code-tech/BLACKBOX/blob/main/API_DOCUMENTATION.md#async-support): `get_async_tracer()`
- [Low-Level Classes](https://github.com/Harshit-code-tech/BLACKBOX/blob/main/API_DOCUMENTATION.md#low-level-classes): `Tracer`, `ExecutionData`, `TimelineEvent`, `AsyncTracer`, `Config`
- [CLI Reference](https://github.com/Harshit-code-tech/BLACKBOX/blob/main/API_DOCUMENTATION.md#cli-reference): `blackbox-recorder run` with examples
- [Use Cases](https://github.com/Harshit-code-tech/BLACKBOX/blob/main/API_DOCUMENTATION.md#common-use-cases): Debugging, performance, production, testing
- [Troubleshooting & FAQ](https://github.com/Harshit-code-tech/BLACKBOX/blob/main/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.2
* **Stability:** Alpha
* **License:** MIT
* **Python:** 3.9+
* **Dependencies:** Zero (stdlib only)
* **Tests:** 124 passing (unit + integration)
* **Repository:** [github.com/Harshit-code-tech/BLACKBOX](https://github.com/Harshit-code-tech/BLACKBOX)
* **PyPI:** [pypi.org/project/blackbox-recorder](https://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.


