Install & Compatibility
Where this runs
tested against v0.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.002s · 19MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Vertex, Edge, Graph
✓ from grandalf.graphs import Vertex, Edge, Graph
These are fundamental components for defining graphs.
SugiyamaLayout, ForceDirectedLayout
✓ from grandalf.layouts import SugiyamaLayout, ForceDirectedLayout
These are the main layout algorithms provided by Grandalf.
digraph_core
✓ from grandalf.digraph import digraph_core
Often used internally or for specific graph representations with layouts like Sugiyama.
This quickstart demonstrates how to define a graph, assign initial dimensions to its vertices, and then apply the Sugiyama layout algorithm. After the layout is computed, each `Vertex` object's `view` attribute will be updated with calculated `(x, y)` coordinates, representing its position on the 2D plane. Grandalf only provides these coordinates; actual drawing requires integration with a separate graphics toolkit.
from grandalf.graphs import Vertex, Edge, Graph
from grandalf.layouts import SugiyamaLayout
# Define nodes (vertices)
V = [Vertex(data) for data in range(10)]
# Define edges for a simple graph
X = [(0, 1), (0, 2), (1, 3), (2, 3), (4, 5), (4, 6), (5, 7), (6, 7), (3, 8), (7, 9)]
E = [Edge(V[u], V[v]) for u, v in X]
# Create a graph instance
g = Graph(V, E)
# Assign placeholder dimensions (width, height) to vertices;
# x,y will be set by the layout algorithm.
for v in V:
v.view = [0, 0, 20, 20] # [x, y, width, height]
# Iterate through graph components (e.g., for Sugiyama, it processes connected components)
for gr in g.sugiyama():
# Instantiate the Sugiyama layout algorithm for the current component
lay = SugiyamaLayout(gr)
# Initialize and run the layout steps
lay.init_all()
lay.algo_graph_layered()
lay.algo_node_coordinatization()
lay.algo_edge_routing()
print(f"--- Layout for Graph Component ---")
for v in gr.V:
# After layout, v.view[0] and v.view[1] contain the calculated (x, y) coordinates
print(f" Vertex {v.data}: (x={v.view[0]}, y={v.view[1]})")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'grandalf'
The `grandalf` package is not installed in the Python environment or there's a typo in the import statement.
fixEnsure the package is installed using pip: `pip install grandalf`. If installed, check for typos in `import grandalf` or `from grandalf.blah import Foo`.
AttributeError: 'NoneType' object has no attribute 'xy' (or 'width'/'height')
This error typically occurs when attempting to access layout coordinates (`xy`), width, or height from a node's `.view` attribute when the node's `.view` attribute has not been properly initialized or assigned, often required by `grandalf`'s layout engines to understand node dimensions for placement.
fixBefore running a layout, ensure that every `Vertex` object in your `graph_core` has a `.view` attribute, and that this `.view` object provides `width` and `height` properties, and will be assigned an `xy` tuple after layout. For example:
```python
from grandalf.graphs import Vertex
v = Vertex('my_node')
v.view = type('dummy', (object,), {'width': 10, 'height': 10})()
``` AttributeError: 'module' object has no attribute 'graphs' (or 'layouts')
This usually indicates an incorrect import statement where a submodule like `graphs` or `layouts` is expected directly under the `grandalf` module, but the way it's being accessed is wrong, or the file name for the user's script is conflicting with a module name.
fixCorrect the import statement to specifically import from the submodules, for example:
```python
from grandalf.graphs import Graph, Vertex, Edge
from grandalf.layouts import SugiyamaLayout
```
Also, ensure your Python script is not named `grandalf.py` as this would cause a circular import issue.
Exception: Graph contains cycles and SugiyamaLayout requires a DAG.
The `SugiyamaLayout` algorithm in `grandalf` is designed for Directed Acyclic Graphs (DAGs). If the input graph contains cycles, the layout algorithm cannot proceed as expected. The documentation explicitly states: 'The algorithm works only for directed acyclic graphs (DAG)'.
fixBefore applying `SugiyamaLayout`, ensure your graph is acyclic. If it contains cycles, you must first identify and break these cycles (e.g., by identifying a feedback arc set) or use a layout algorithm that can handle cyclic graphs, such as the `ForceDirectedLayout` if `grandalf` implements it (version 0.8 supports a 'force-driven or energy minimization approach').
ImportError: cannot import name 'Graph' from 'grandalf' (unknown location)
The 'Graph', 'Vertex', and 'Edge' classes are located within the 'grandalf.graphs' submodule, not directly under the 'grandalf' package.
fixfrom grandalf.graphs import Graph, Vertex, Edge
Upgrade
Version history
0.8latest on PyPI · released Jan 10, 2023
Audit
Dependencies
pyparsingrequiredRequired for core functionality, listed as install_requires.
numpyoptionalSuggested for the directed-constrained layout, optional.
plyoptionalSuggested for importing graphs from Graphviz dot files, optional.