heterograph is a Python library for building, querying, and visualizing heterogeneous directed graphs ("heterographs"). It provides a convenient, Pythonic API for managing vertices, edges, and their properties, supports common graph traversals, and includes rich visualization tools for notebooks and the web.
The project is designed for exploratory graph modeling and analysis, especially when you need structured metadata on vertices and edges and interactive inspection of graph topology.
-
Heterogeneous directed graphs
- Vertices and edges with arbitrary, typed properties
- Explicit in-/out-neighbour management
-
Graph algorithms
- Depth-first search (DFS) traversal utilities
- Topology and neighbourhood queries
-
Visualization
- Interactive web-based viewer (Flask + D3)
- Notebook-friendly display helpers
- Optional Graphviz export for static diagrams
-
Extensible design
- Custom initialization hooks for graphs, vertices, and edges
- Property system (
HGraphProps) for clean metadata handling
heterograph/
├── heterograph/
│ ├── hgraph.py # Core HGraph implementation
│ ├── hgraph_props.py # Property handling for graphs, vertices, edges
│ ├── webview.py # Flask-based interactive web viewer
│ ├── utils/ # Notebook & display helpers
│ └── assets/ # Static JS/CSS assets for visualization
├── tests/ # Pytest test suite
├── environment.yml # Conda environment definition
├── pyproject.toml # Build & packaging configuration
├── LICENSE
└── README.md
Clone this repository, then create the environment from the repository root:
conda env create -f environment.yml
conda activate heterographThis installs Heterograph in editable mode, so changes to the source are available in the environment.
To install Heterograph in a separate environment, create one directly:
conda create -n my-heterograph -c ckiddo74 -c conda-forge python=3.12 heterograph
conda activate my-heterographAlternatively, define an environment.yml for your project:
name: my-heterograph
channels:
- ckiddo74
- conda-forge
dependencies:
- python=3.12
- heterographThese examples pin Python to version 3.12; choose a version supported by the published Heterograph builds if needed.
Then create and activate the environment:
conda env create -f environment.yml
conda activate my-heterographThe published package currently targets Linux x86-64.
See conda/README.md for build and publishing instructions.
from heterograph import *
# Create an empty heterograph
g = HGraph()
# Add vertices
v1 = g.add_vx()
v2 = g.add_vx()
# Add an edge
e = g.add_edge(v1, v2)# Set vertex properties
g.pmap[v1]["label"] = "Source"
g.pmap[v2]["label"] = "Target"
# Set edge properties
g.pmap[e]["weight"] = 1.0
# set graph properties
g['name'] = 'my graph'from heterograph import *
g = HGraph()
# Add vertices
v1 = g.add_vx()
v2 = g.add_vx()
g.add_edge(v1, v2)
g.view()This launches a local Flask server with an interactive graph UI (pan, zoom, inspect vertices/edges).
Run the full test suite with:
pytestTests cover:
- Vertex and edge creation
- Neighbour queries
- DFS traversal
- Graph initialization and topology
Read the Heterograph documentation. To build the HTML documentation locally, activate the development environment and run from the repository root:
cd docs
make htmlOpen docs/build/html/index.html in a browser. The build executes the
documentation notebooks and may take some time.
See environment.yml for the full dependency list.
This project is licensed under the terms of the Apache License 2.0. See LICENSE for details.
- Built on top of the excellent
graph-toollibrary - Visualization powered by Flask and D3.js