rustworkx Python
Produce rustworkx code whose graph kind, index lifecycle, payload semantics,
parallel-edge policy, callback contract, and algorithm result mapping are
explicit and tested.
Core object model
| Object |
Meaning |
Use it when |
PyGraph |
Undirected indexed graph. |
Direction does not matter. |
PyDiGraph |
Directed indexed graph. |
Edge orientation matters. |
PyDAG |
Directed graph that checks/prevents cycles according to its contract. |
Acyclicity is an invariant, not merely an algorithm precondition. |
| node index |
Integer handle into graph storage. |
Address topology; never confuse it with payload identity. |
| edge index |
Integer handle for one edge. |
Preserve parallel-edge identity and update/remove exact edges. |
| node/edge payload |
Arbitrary Python object, often called “weight” in APIs. |
Store domain data; it is not automatically an algorithmic cost. |
Indices are stable for the lifetime of an item but are not guaranteed
contiguous; removals leave holes and later insertions may reuse an index. Keep a
domain-ID→node-index mapping when callers identify nodes by business keys. Do
not use list position or enumerate graph.nodes() as an index map. Open
indices, payloads, and ownership for the mapping rules.
Ordered workflow
- State direction, cycle, self-loop, and parallel-edge requirements.
- Define domain identity separately from integer graph indices.
- Choose payload shapes and the callback that converts edge payload to a
numeric cost when an algorithm needs one.
- Build topology while retaining returned indices/mappings.
- Select the exact
graph_* or digraph_* algorithm family and verify its
return type and unreachable-node behavior.
- Translate index-keyed results back to domain IDs only at the public boundary.
- Test removals/holes, parallel edges, direction, missing paths, callback
failures, and equal-cost ambiguity; benchmark only the real workload.
Decision map
- Use
multigraph=False only when at most one edge per endpoint pair is the
domain rule. Adding a duplicate then updates the existing edge payload rather
than preserving another relationship.
- Use edge indices when parallel edges require later provenance or mutation.
- Use
graph_* functions for PyGraph and digraph_* functions for directed
graphs when the API provides type-specific families. Do not guess symmetry.
- Map an arbitrary edge payload to the numeric cost the algorithm expects. For
digraph_dijkstra_shortest_path_lengths, pass edge_cost_fn as the third
positional argument: the documented signature makes it positional-only. A
payload named “weight” can still be a dict, object, or label. Inspect other
algorithm signatures instead of copying this call shape blindly.
- Use conversion only after listing what must survive: domain IDs, graph attrs,
parallel keys, isolated nodes, direction, and payload identity.
- Use rustworkx for measured performance-sensitive graph computation or an
existing rustworkx boundary. Prefer NetworkX when its broader API/ecosystem is
the actual requirement and no performance evidence justifies conversion.
Read operations and algorithms for construction,
result types, mappings, callbacks, conversion, and traversal-control details.
Canonical anchor
from dataclasses import dataclass
import rustworkx as rx
@dataclass(frozen=True)
class Arc:
cost: float
route_id: str
def build_routes(
route_ids: list[str],
arcs: list[tuple[str, str, Arc]],
) -> tuple[rx.PyDiGraph, dict[str, int]]:
graph = rx.PyDiGraph(multigraph=True)
index_by_id = {route_id: graph.add_node(route_id) for route_id in route_ids}
for source, target, arc in arcs:
graph.add_edge(index_by_id[source], index_by_id[target], arc)
return graph, index_by_id
The payload is a domain object; an algorithm must receive lambda arc: arc.cost. The map preserves business identity even if indices have holes.
High-risk rules
- Never serialize or persist node indices as permanent domain IDs unless graph
lifecycle and reuse are explicitly controlled.
- Do not assume
nodes() position equals an index. Use node_indices() and
get_node_data(index) or retained mappings.
- Do not assume removing a node compacts the graph. Test any code that iterates
a numeric range.
- Do not call an algorithm with the payload object where it expects a numeric
edge cost callback. Define missing, negative, and nonfinite cost policies.
- Keep directed predecessor/successor semantics distinct. Do not convert to
undirected just to make an algorithm call succeed.
- In a multigraph, endpoint lookup can return several edges. Preserve/select by
edge index under an explicit rule.
- Callback-heavy algorithms cross the Python boundary; validate callback return
types and benchmark rather than assuming every rustworkx call is faster.
- Conversion from NetworkX can change identity representation and multigraph
details. Assert a semantic round trip, not only node/edge counts.
- Traversal visitors can stop or prune traversal through control exceptions or
return contracts that are version-sensitive. Inspect installed docs.
Version grounding and completion
The official API index currently labels rustworkx 0.18.1. The package is not
installed in the foundry, so that is a documentation baseline only. Check the
installed version with rustworkx.__version__, then inspect graph constructors and the exact algorithm signature
before coding. Read verification.
Completion requires graph-class and index-lifecycle correctness; explicit
payload-to-cost semantics; safe result mapping; tests with holes, parallel
edges, no-path/direction cases, and callbacks; and measured evidence for any
performance claim.
References
- Indices, payloads, and ownership
- Operations and algorithms
- Verification and grounding
1---2name: rustworkx-python3description: Use for writing, reviewing, debugging, testing, or optimizing Python rustworkx graph code. Trigger on PyGraph, PyDiGraph, PyDAG, stable node or edge indices, payloads/weights, rustworkx algorithms, graph conversion, or performance-sensitive Python graph analysis. Do not use for NetworkX-only code, Rust petgraph code, graph databases, or tensor/GNN workloads.4argument-hint: "[rustworkx graph task, code, conversion, or error]"5metadata:6 source: https://skillmd.com/skills/schattenspiegel/rustworkx-python7---89# rustworkx Python1011Produce rustworkx code whose graph kind, index lifecycle, payload semantics,12parallel-edge policy, callback contract, and algorithm result mapping are13explicit and tested.1415## Core object model1617| Object | Meaning | Use it when |18|---|---|---|19| `PyGraph` | Undirected indexed graph. | Direction does not matter. |20| `PyDiGraph` | Directed indexed graph. | Edge orientation matters. |21| `PyDAG` | Directed graph that checks/prevents cycles according to its contract. | Acyclicity is an invariant, not merely an algorithm precondition. |22| node index | Integer handle into graph storage. | Address topology; never confuse it with payload identity. |23| edge index | Integer handle for one edge. | Preserve parallel-edge identity and update/remove exact edges. |24| node/edge payload | Arbitrary Python object, often called “weight” in APIs. | Store domain data; it is not automatically an algorithmic cost. |2526Indices are stable for the lifetime of an item but are not guaranteed27contiguous; removals leave holes and later insertions may reuse an index. Keep a28domain-ID→node-index mapping when callers identify nodes by business keys. Do29not use list position or enumerate `graph.nodes()` as an index map. Open30[indices, payloads, and ownership](references/object-model.md) for the mapping rules.3132## Ordered workflow33341. State direction, cycle, self-loop, and parallel-edge requirements.352. Define domain identity separately from integer graph indices.363. Choose payload shapes and the callback that converts edge payload to a37 numeric cost when an algorithm needs one.384. Build topology while retaining returned indices/mappings.395. Select the exact `graph_*` or `digraph_*` algorithm family and verify its40 return type and unreachable-node behavior.416. Translate index-keyed results back to domain IDs only at the public boundary.427. Test removals/holes, parallel edges, direction, missing paths, callback43 failures, and equal-cost ambiguity; benchmark only the real workload.4445## Decision map4647- Use `multigraph=False` only when at most one edge per endpoint pair is the48 domain rule. Adding a duplicate then updates the existing edge payload rather49 than preserving another relationship.50- Use edge indices when parallel edges require later provenance or mutation.51- Use `graph_*` functions for `PyGraph` and `digraph_*` functions for directed52 graphs when the API provides type-specific families. Do not guess symmetry.53- Map an arbitrary edge payload to the numeric cost the algorithm expects. For54 `digraph_dijkstra_shortest_path_lengths`, pass `edge_cost_fn` as the third55 positional argument: the documented signature makes it positional-only. A56 payload named “weight” can still be a dict, object, or label. Inspect other57 algorithm signatures instead of copying this call shape blindly.58- Use conversion only after listing what must survive: domain IDs, graph attrs,59 parallel keys, isolated nodes, direction, and payload identity.60- Use rustworkx for measured performance-sensitive graph computation or an61 existing rustworkx boundary. Prefer NetworkX when its broader API/ecosystem is62 the actual requirement and no performance evidence justifies conversion.6364Read [operations and algorithms](references/operations.md) for construction,65result types, mappings, callbacks, conversion, and traversal-control details.6667## Canonical anchor6869```python70from dataclasses import dataclass7172import rustworkx as rx737475@dataclass(frozen=True)76class Arc:77 cost: float78 route_id: str798081def build_routes(82 route_ids: list[str],83 arcs: list[tuple[str, str, Arc]],84) -> tuple[rx.PyDiGraph, dict[str, int]]:85 graph = rx.PyDiGraph(multigraph=True)86 index_by_id = {route_id: graph.add_node(route_id) for route_id in route_ids}87 for source, target, arc in arcs:88 graph.add_edge(index_by_id[source], index_by_id[target], arc)89 return graph, index_by_id90```9192The payload is a domain object; an algorithm must receive `lambda arc:93arc.cost`. The map preserves business identity even if indices have holes.9495## High-risk rules9697- Never serialize or persist node indices as permanent domain IDs unless graph98 lifecycle and reuse are explicitly controlled.99- Do not assume `nodes()` position equals an index. Use `node_indices()` and100 `get_node_data(index)` or retained mappings.101- Do not assume removing a node compacts the graph. Test any code that iterates102 a numeric range.103- Do not call an algorithm with the payload object where it expects a numeric104 edge cost callback. Define missing, negative, and nonfinite cost policies.105- Keep directed predecessor/successor semantics distinct. Do not convert to106 undirected just to make an algorithm call succeed.107- In a multigraph, endpoint lookup can return several edges. Preserve/select by108 edge index under an explicit rule.109- Callback-heavy algorithms cross the Python boundary; validate callback return110 types and benchmark rather than assuming every rustworkx call is faster.111- Conversion from NetworkX can change identity representation and multigraph112 details. Assert a semantic round trip, not only node/edge counts.113- Traversal visitors can stop or prune traversal through control exceptions or114 return contracts that are version-sensitive. Inspect installed docs.115116## Version grounding and completion117118The official API index currently labels rustworkx 0.18.1. The package is not119installed in the foundry, so that is a documentation baseline only. Check the120installed version with `rustworkx.__version__`, then inspect graph constructors and the exact algorithm signature121before coding. Read [verification](references/verification.md).122123Completion requires graph-class and index-lifecycle correctness; explicit124payload-to-cost semantics; safe result mapping; tests with holes, parallel125edges, no-path/direction cases, and callbacks; and measured evidence for any126performance claim.127128## References129130- [Indices, payloads, and ownership](references/object-model.md)131- [Operations and algorithms](references/operations.md)132- [Verification and grounding](references/verification.md)