Metadata-Version: 2.1
Name: trio-vis
Version: 0.0.1
Summary: Structured Concurrency visualizer for trio
Home-page: https://github.com/ianchen-tw/trio-vis
License: MIT
Author: Ian Chen
Author-email: ianre657@gmail.com
Requires-Python: >=3.6.1,<4.0
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Plugins
Classifier: Framework :: Trio
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 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Dist: attrs (>=21.2.0,<22.0.0)
Requires-Dist: pydantic (>=1.8.2,<2.0.0)
Requires-Dist: rich (>=9.13.0,<10.0.0)
Requires-Dist: trio (>=0.18.0,<0.19.0)
Requires-Dist: trio-typing (>=0.5.0,<0.6.0)
Requires-Dist: typing-extensions (>=3,<4)
Project-URL: Repository, https://github.com/ianchen-tw/trio-vis
Description-Content-Type: text/markdown

# trio-vis

`trio-vis` is a plugin for visualizing the scope history of your Trio project.

![showcase](res/showcase.png)

## How to use

[sc-vis]: https://ianchen-tw.github.io/sc-vis
[trio-vis-pip]: https://pypi.org/project/trio-vis/

1. Install `trio-vis` via `pip install trio-vis` ([trio-vis-pip])
2. In your source code, register `SC_Monitor()` as an Instrument while running `trio`

    ```python
    from trio_vis import SC_Monitor
    trio.run(my_main_funciton, instruments=[SC_Monitor()])
    ```

3. After your program finished(or exited), the scope history would be stored in `./sc-logs.json`
4. Upload your log file to [sc-visualiver][sc-vis], this is a twin project which focuses on visualization work.
5. See your visualization result and help us improve.

## Configuration

Import `VisConfig` from `trio_vis`, and provide it as an argument while making your `SC_Monitor` object.

```python
from trio_vis import SC_Monitor, VisConfig
cfg = VisConfig(print_task_tree=True)
trio.run(my_main_funciton, instruments=[SC_Monitor(config=cfg)])
```

## What does it do

[ins-api]: https://trio.readthedocs.io/en/stable/reference-lowlevel.html#instrument-api

`trio-vis` utilize the [Instrument API][ins-api] to monitor the lifetime of scopes (`Task`,`Nursery`).
Since the [Instrument API][ins-api] doesn't provide callbacks for `Nursery`, we make inferences on our own.

## Why visualize

[trio]: https://github.com/python-trio/trio
[trio-issue-413]: https://github.com/python-trio/trio/issues/413

[curio]: https://github.com/dabeaz/curio
[curio-monitor]: https://github.com/dabeaz/curio/blob/master/curio/monitor.py

Derived from [curio], [trio] combines the idea of Structured Concurrency with existing single-threaded event-driven architecture. Which does make concurrent programs more manageable.

To make trio comparable with curio, contributors of trio also want to mimic the feature of [curio-monitor] to monitor the current system running state. This idea could be traced back to [trio-issue-413].

Since then, projects have been developed (shown below).

However, **trio is not curio**, at least lifetimes of scopes are structured by nature. I argue that by utilizing the feature of Structured Concurrency, we could visualize programs better.
Developers could easily conceptualize their program, and bring their developing experience to the next level.

### Previous work

+ [python-trio/trio-monitor]: officail project developed under trio, however it use the old InstruementAPI
+ [syncrypt/trio-inspector]: is a webmonitor to visualize the current state of the program
+ [Tronic/trio-web-monitor]: a experiment to unified all previous work, developed by [Tronic](https://github.com/Tronic)
+ [oremanj/trio-monitor]

[python-trio/trio-monitor]:https://github.com/python-trio/trio-monitor
[Tronic/trio-web-monitor]:https://github.com/Tronic/trio-web-monitor
[syncrypt/trio-inspector]:https://github.com/syncrypt/trio-inspector
[oremanj/trio-monitor]:https://github.com/oremanj/trio-monitor

## Future plan

This project is in an early developing stage. Stay tuned for future update.

