Metadata-Version: 2.4
Name: pyvis-optimized
Version: 4.3.1
Summary: A Python network graph visualization library - Optimized Edition
Author-email: Jose Unpingco <datascience@westhealth.org>
Maintainer: PyVis Contributors
License: BSD
Project-URL: Homepage, https://github.com/razinkele/pyvis
Project-URL: Documentation, https://github.com/razinkele/pyvis#readme
Project-URL: Repository, https://github.com/razinkele/pyvis
Project-URL: Bug Tracker, https://github.com/razinkele/pyvis/issues
Project-URL: Changelog, https://github.com/razinkele/pyvis/blob/master/CHANGELOG.md
Keywords: network,visualization,graph,networkx,vis.js,interactive
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE_BSD.txt
Requires-Dist: jinja2>=2.9.6
Requires-Dist: networkx>=1.11
Requires-Dist: jsonpickle>=1.4.1
Provides-Extra: shiny
Requires-Dist: shiny>=0.6.0; extra == "shiny"
Requires-Dist: htmltools; extra == "shiny"
Provides-Extra: notebook
Requires-Dist: ipython>=5.3.0; extra == "notebook"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: playwright>=1.40; extra == "test"
Requires-Dist: pytest-playwright>=0.4; extra == "test"
Requires-Dist: numpy; extra == "test"
Provides-Extra: all
Requires-Dist: pyvis-optimized[dev,notebook,shiny,test]; extra == "all"
Dynamic: license-file

# PyVis — Interactive Network Visualization for Python

![](docs/tut.gif?raw=true)

PyVis is a Python library for creating and visualizing interactive network graphs, built on top of the [vis.js](https://visjs.github.io/vis-network/docs/network/) JavaScript library. This edition adds type-safe configuration, Shiny for Python integration, security hardening, and performance optimizations over the [upstream project](https://github.com/WestHealth/pyvis).

## Features

- **Interactive visualizations** — Pan, zoom, drag nodes, hover tooltips, all in the browser
- **NetworkX integration** — Convert NetworkX graphs directly with `from_nx()`
- **Type-safe options** — 44 Python dataclasses covering 100% of the vis-network configuration surface
- **Shiny for Python** — Full bidirectional integration with event handling, viewport control, and live data updates
- **Multiple physics engines** — Barnes-Hut, Force Atlas 2, repulsion, and hierarchical repulsion
- **Jupyter support** — Render networks inline in Jupyter notebooks
- **Security hardened** — Jinja2 autoescape prevents XSS, input validation on file operations
- **Runtime validation** — Type-safe options with `__post_init__` checks for opacity, font alignment, and more

## Installation

**Requires Python >= 3.9**

```bash
pip install pyvis-optimized
```

With optional dependencies:

```bash
pip install pyvis-optimized[shiny]     # Shiny for Python integration
pip install pyvis-optimized[notebook]  # Jupyter/IPython notebook support
pip install pyvis-optimized[dev]       # Development tools (pytest, black, mypy)
pip install pyvis-optimized[test]      # Test dependencies (pytest, playwright)
pip install pyvis-optimized[all]       # Everything
```

The conda package always includes IPython; on PyPI it is the `notebook` extra.

Or from source:

```bash
pip install .
```

### Dependencies

| Package | Purpose |
|---------|---------|
| [networkx](https://networkx.github.io/) >= 1.11 | Graph data structures |
| [jinja2](https://jinja.palletsprojects.com/) >= 2.9.6 | HTML template rendering |
| [jsonpickle](https://jsonpickle.github.io/) >= 1.4.1 | JSON serialization |

Optional: [ipython](https://ipython.org/) >= 5.3.0 (`pyvis-optimized[notebook]`), [shiny](https://shiny.posit.co/py/) >= 0.6.0 and [htmltools](https://pypi.org/project/htmltools/) (`pyvis-optimized[shiny]`)

## Quick Start

```python
from pyvis.network import Network

net = Network()
net.add_node(1, label="Node 1", color="#97c2fc")
net.add_node(2, label="Node 2", color="#ffcc00")
net.add_edge(1, 2, width=2)
net.show("basic.html", notebook=False)
```

### From NetworkX

```python
import networkx as nx
from pyvis.network import Network

G = nx.karate_club_graph()
net = Network()
net.from_nx(G)
net.show("karate.html", notebook=False)
```

## Type-Safe Options

Configure every aspect of your network visualization with Python dataclasses that provide IDE autocompletion and type checking:

```python
from pyvis.network import Network
from pyvis.types import (
    NetworkOptions, NodeOptions, EdgeOptions, PhysicsOptions,
    BarnesHut, LayoutOptions, InteractionOptions, Font
)

options = NetworkOptions(
    nodes=NodeOptions(
        shape="dot",
        font=Font(size=14, color="#333333"),
    ),
    edges=EdgeOptions(
        smooth=True,
        color="#848484",
    ),
    physics=PhysicsOptions(
        solver="barnesHut",
        barnesHut=BarnesHut(gravitationalConstant=-3000),
    ),
    interaction=InteractionOptions(
        hover=True,
        tooltipDelay=200,
    ),
)

net = Network()
net.set_options(options)
net.add_node(1, label="A")
net.add_node(2, label="B")
net.add_edge(1, 2)
net.show("typed.html", notebook=False)
```

The `pyvis.types` module provides 44 dataclasses covering nodes, edges, physics, layout, interaction, configuration, and manipulation — the full vis-network API surface.

## Shiny for Python Integration

Build interactive web applications with bidirectional communication between Python and the network:

```python
from shiny import App, ui, render, reactive
from pyvis.network import Network
from pyvis.shiny import (
    output_pyvis_network, render_pyvis_network,
    PyVisNetworkController
)

app_ui = ui.page_fluid(
    output_pyvis_network("network", height="600px"),
    ui.input_action_button("fit", "Fit to View"),
    ui.output_text_verbatim("selected")
)

def server(input, output, session):
    ctrl = PyVisNetworkController("network", session)

    @render_pyvis_network
    def network():
        net = Network(cdn_resources="remote")
        net.add_node(1, label="Node 1")
        net.add_node(2, label="Node 2")
        net.add_edge(1, 2)
        return net

    @reactive.effect
    @reactive.event(input.fit)
    def _():
        ctrl.fit()

    @render.text
    def selected():
        event = input.network_selectNode()
        return f"Selected: {event['nodeId']}" if event else "Click a node"

app = App(app_ui, server)
```

### Shiny Capabilities

| Category | Functions |
|----------|-----------|
| **Events** | click, doubleClick, selectNode, selectEdge, hoverNode, dragStart, zoom, stabilized, and more |
| **Selection** | select_nodes, select_edges, unselect_all |
| **Viewport** | fit, focus, move_to |
| **Physics** | start_physics, stop_physics, stabilize |
| **Data** | add/update/remove nodes and edges, get_positions, get_all_data |
| **Clustering** | cluster_by_connection, cluster_by_hubsize, open_cluster |
| **Theming** | set_options, set_theme |

See the [Shiny Integration Guide](docs/SHINY_INTEGRATION_GUIDE.md) for complete documentation.

## Documentation

- **[API Reference](docs/API_REFERENCE.md)** — Complete reference for Network class, typed options (44 dataclasses), Shiny integration, and all public methods
- **[Shiny Integration Guide](docs/SHINY_INTEGRATION_GUIDE.md)** — Detailed guide for using PyVis with Shiny for Python

## Testing

```bash
pytest pyvis/tests/ --ignore=pyvis/tests/test_html.py -v
```

That command runs 480 tests covering core network operations, typed options, Shiny integration, security, error handling, and regression tests for edge cases. The full suite is 484 (run `pytest --co` for the current count); the four extra are the Playwright browser tests in `test_html.py`, which need `pip install pyvis-optimized[test]` followed by `python -m playwright install chromium`.

## Versioning

Version is managed from a single source of truth: `pyvis/_version.py`. Use the bump script for releases:

```bash
python auto_version.py          # bump from conventional commits, update CHANGELOG, commit, tag
python auto_version.py minor    # explicit bump; CHANGELOG still built from commits
python auto_version.py --no-commit   # dry run: update files only
```

## Project Structure

```
pyvis/
    network.py          # Main Network class
    node.py             # Node representation
    edge.py             # Edge representation
    _version.py         # Single source of truth for version
    utils.py            # Validation utilities
    types/              # Type-safe dataclass options (44 classes)
    shiny/              # Shiny for Python integration
        wrapper.py      # Controller, standalone functions, rendering
        bindings.js     # JavaScript binding for vis-network
    tests/              # 484 tests across 28 modules (see `pytest --co` for current count)
auto_version.py         # Version bump + changelog + tag script
```

## License

BSD License. Based on [WestHealth/pyvis](https://github.com/WestHealth/pyvis).
