Metadata-Version: 2.4
Name: statelens
Version: 0.1.0
Summary: A Time Machine for Python Programs — record, inspect, and replay program execution.
Project-URL: Homepage, https://github.com/pr1yankac0des/statelens
Project-URL: Documentation, https://github.com/statelens/statelens/tree/main/docs
Project-URL: Repository, https://github.com/statelens/statelens
Project-URL: Changelog, https://github.com/statelens/statelens/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/statelens/statelens/issues
Author: StateLens Contributors
License: MIT License
        
        Copyright (c) 2026 StateLens Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: debugging,observability,profiling,replay,time-travel-debugging,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: black>=24.3.0; extra == 'dev'
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# StateLens

**A Time Machine for Python Programs.**

StateLens records how a Python program's execution evolves over time —
every function call, every line executed, every variable mutation, every
exception, every allocation — so you can replay that history *after the
program has already finished running*, instead of only staring at a final
stack trace.

Where a debugger shows you the present moment and a stack trace shows you
the point of failure, StateLens shows you the whole story:

* **What changed?** — every variable mutation, tracked automatically.
* **When did it change?** — a precise, ordered timeline of every event.
* **Why did it change?** — the full call stack and arguments at that moment.
* **Which function caused it?** — a reconstructed call tree with timing.
* **What was the state before the crash?** — not just the traceback, the
  entire program state leading up to it.
* **How did memory evolve?** — periodic memory samples across execution.
* **How did execution flow?** — a visual execution graph of the whole run.

## Install

```bash
pip install statelens
```

Requires Python 3.11+.

## Quick start

Record a script's execution:

```bash
statelens run app.py
```

This produces `session.json` — a complete recording of the program's
execution. Now generate an interactive HTML report:

```bash
statelens report session.json --open
```

Or step through the recording one event at a time in your terminal:

```bash
statelens replay session.json
```

Check that your environment is set up correctly:

```bash
statelens doctor
```

## Using the Python API directly

```python
from statelens import record_script, save_session
from statelens.storage import JSONSessionStorage

result = record_script("app.py")
save_session(result, JSONSessionStorage("session.json"))

print(f"Recorded {result.metadata.total_events} events")
print(f"Program {'succeeded' if result.succeeded else 'raised an exception'}")
```

Or trace code you're already running in-process:

```python
from statelens import Tracer, TraceConfig

tracer = Tracer(config=TraceConfig(trace_memory=True))
with tracer.trace():
    my_function()

for event in tracer.events:
    print(event.event_type, event.location)
```

### Replaying a session programmatically

```python
from statelens import load_session, ReplaySession
from statelens.storage import JSONSessionStorage

events, metadata = load_session(JSONSessionStorage("session.json"))
replay = ReplaySession(events)

while not replay.at_end:
    state = replay.state_at_current_position()
    print(state.current_location, state.variables_in_scope())
    replay.step_forward()
```

## The HTML report

`statelens report` generates a single, self-contained, dependency-free HTML
file with:

* An interactive, filterable **execution timeline**
* A collapsible **function call tree** with per-call timing
* A **variable inspector** showing every value a variable held over time
* A **memory usage graph**
* An **execution flow graph** sized by time spent per function
* An **exception viewer** with full tracebacks
* A **step-by-step replay** view with a scrubber
* Full-text **search** across functions, variables, and exceptions
* **Dark mode** and a **responsive** layout for any screen size

Because everything is inlined into one HTML file, reports can be opened
locally, emailed, or archived as CI artifacts with zero setup.

## Storage backends

StateLens ships two storage backends behind one interface:

* **JSON** (default) — human-readable, diffable, great for small-to-medium
  sessions and version control.
* **SQLite** — better suited to large sessions (heavy line tracing,
  long-running programs); pass a `.db`/`.sqlite`/`.sqlite3` path to `--output`
  or `SQLiteSessionStorage` to use it.

```bash
statelens run app.py --output session.db
```

## Plugins

StateLens has an extensible plugin architecture with four extension points:
`Exporter`, `Visualization`, `ReportSection`, and `EventProcessor`. See
[docs/plugins.md](docs/api.md#plugins) and
[CONTRIBUTING.md](CONTRIBUTING.md) for details on writing your own.

Two exporters ship built in: `csv` (flat event export) and `chrome-trace`
(open your session directly in `chrome://tracing` or
[Perfetto UI](https://ui.perfetto.dev)).

## CLI reference

```
statelens run SCRIPT [ARGS...]     Record a script's execution
statelens report SESSION           Generate an interactive HTML report
statelens replay SESSION           Step through a session in the terminal
statelens doctor                   Diagnose your environment
```

Run `statelens COMMAND --help` for full options on any subcommand.

## Documentation

* [Tutorial](docs/tutorial.md)
* [API reference](docs/api.md)
* [Examples](examples/)
* [Contributing](CONTRIBUTING.md)
* [Changelog](CHANGELOG.md)

## Development

```bash
git clone https://github.com/statelens/statelens
cd statelens
pip install -e ".[dev]"
pytest
ruff check .
mypy src/statelens
```

## License

MIT — see [LICENSE](LICENSE).
