Metadata-Version: 2.4
Name: asyncviz
Version: 0.1.0
Summary: Real-time visualization and diagnostics for Python asyncio applications.
Project-URL: Homepage, https://github.com/geghamjivanyan/asyncviz
Project-URL: Documentation, https://github.com/geghamjivanyan/asyncviz#readme
Project-URL: Issues, https://github.com/geghamjivanyan/asyncviz/issues
Project-URL: Repository, https://github.com/geghamjivanyan/asyncviz
Project-URL: Changelog, https://github.com/geghamjivanyan/asyncviz/releases
Author: Gegham Jivanyan
Maintainer: Gegham Jivanyan
License: MIT License
        
        Copyright (c) 2026 Gegham Jivanyan
        
        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: async,asyncio,concurrency,debugging,diagnostics,observability,runtime,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.32
Provides-Extra: all
Requires-Dist: build>=1.2; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: pre-commit>=3.8; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
Requires-Dist: pytest-cov>=5.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.6; extra == 'all'
Requires-Dist: twine>=5.1; extra == 'all'
Provides-Extra: build
Requires-Dist: build>=1.2; extra == 'build'
Requires-Dist: twine>=5.1; extra == 'build'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# AsyncViz

**Visual debugging for Python asyncio applications.**

Debugging asyncio is hard.

Tasks appear and disappear.
Queues silently fill up.
Blocking operations freeze the event loop.
Dependencies become impossible to follow.

Most of the time, you're left staring at logs and trying to guess what happened.

AsyncViz makes asyncio visible.

Run your application and instantly see what it is doing in real time—tasks, queues, semaphores, executors, and await relationships, all visualized in your browser.

* Task lifecycle visualization
* Dependency tracking
* Queue observability
* Executor monitoring
* Blocking detection
* Runtime recording and replay

```bash
pip install asyncviz

asyncviz run app.py
```

![AsyncViz demo](docs/images/demo.gif)

---

## Why AsyncViz?

Traditional debugging tools tell you what happened.

AsyncViz shows you what is happening.

Instead of reading logs and stack traces, you can watch tasks being created, scheduled, executed, blocked, cancelled, and completed as your application runs.

Whether you're learning asyncio, debugging production issues, or teaching asynchronous programming, AsyncViz provides visibility that Python developers typically don't have.

---

## Features

### Realtime Task Visualization

See task creation, execution, completion, cancellation, and scheduling activity as it happens.

Track how work moves through your application in real time.

---

### Dependency Graphs

Understand task relationships and execution flow.

Visualize:

* Parent-child task trees
* Gather fan-outs
* Dependency chains
* Runtime relationships

![Dependencies page](docs/images/dependencies.png)

---

### Queue Observability

Monitor queue behavior and pressure.

Track:

* Queue occupancy
* Queue saturation
* Producer activity
* Consumer activity
* Backpressure patterns

---

### Blocking Detection

Find operations that freeze the event loop.

AsyncViz detects:

* Event-loop stalls
* Blocking calls
* Freeze windows
* Runtime slowdowns

and highlights them directly inside the dashboard.

---

### Executor Monitoring

Observe:

* ThreadPoolExecutor activity
* ProcessPoolExecutor activity
* Queue depth
* Utilization
* Failures
* Slow jobs

---

### Timeline View

Explore application execution through an interactive timeline.

Visualize:

* Task creation
* Task execution
* Completion
* Cancellation
* Blocking regions

Supports:

* Zoom
* Pan
* Virtualized rendering
* Large runtime sessions

![Timeline view](docs/images/timeline.png)

---

### Runtime Recording & Replay

Capture a session and step through it later inside the dashboard.

```bash
asyncviz record app.py
asyncviz replay session-<timestamp>.avz
```

`asyncviz record` writes a portable `.avz` bundle containing every event from the run. `asyncviz replay` opens the same dashboard against that bundle, with playback controls, a lane-based timeline, scrubbing, bookmarks, and selection statistics — so the captured session can be inspected and shared without rerunning the application.

![Replay page](docs/images/replay.png)

---

## Installation

Requirements:

* Python 3.12+

Install from PyPI:

```bash
pip install asyncviz
```

---

## Quick Start

Run any asyncio script through the CLI:

```bash
asyncviz run app.py
```

…or call AsyncViz from your own code with a single function:

```python
import asyncviz

asyncviz.start()
```

Either path opens the dashboard at <http://127.0.0.1:8877> and streams live runtime activity into it.

A complete, runnable example lives under [`examples/basic/`](examples/basic/) — start there to see every dashboard page come to life.

---

## Dashboard

AsyncViz includes a built-in dashboard with dedicated views for different aspects of runtime behavior.

### Overview

High-level runtime activity and health.

![Overview page](docs/images/overview.png)

### Timeline

Task execution over time.

### Warnings

Blocking operations and runtime issues.

### Queues

Queue activity and pressure.

### Semaphores

Permit usage, waiters, and contention.

### Dependencies

Task relationships and execution graphs.

### Executors

Executor activity and performance.

### Metrics

Aggregate throughput, event rates, task counts, and runtime statistics.

### Replay

Playback of recorded sessions, with scrubbing, bookmarks, and selection statistics.

### Diagnostics

Findings, recommendations, and per-subsystem health, explained in plain language.

![Diagnostics page](docs/images/diagnostics.png)

---

## Architecture

AsyncViz consists of:

- Runtime instrumentation
- Live event streaming
- Embedded web dashboard
- Recording engine
- Replay engine

The dashboard connects to the running application through a live event stream and updates continuously as execution progresses.

---

## Use Cases

### Learning Asyncio

Understand how tasks are scheduled and executed.

### Teaching Asyncio

Demonstrate runtime behavior visually.

### Debugging

Identify bottlenecks, blocking operations, and execution issues.

### Performance Analysis

Inspect runtime behavior and execution flow.

### Development

Gain visibility into asynchronous systems during local development.

---

## Roadmap

Future work being considered for upcoming releases:

* Historical comparison between sessions
* Advanced filtering across pages
* Broader search capabilities
* Export of dashboard views and recordings
* Enhanced analytics on captured sessions

---

## Contributing

Contributions are welcome.

Bug reports, feature requests, documentation improvements, and pull requests are all appreciated.

See CONTRIBUTING.md for development guidelines.

---

## License

MIT License.
