from_dot feature (#1489)

* First draft

Built a basic grammar and wired it up with functions to parse it and added it in the pymodule.

Next steps:
1) Fix the grammar, make it robust.

2) Add tests and documentations

* Updating grammar

* from_dot feature

* Updates based on comments

1) Added a new function to use stable graph with is_directed as a parameter to avoid creating python object every time.

2) Added more tests to include round trip from to_dot and from_dot for graph and digraph.

* fixing clippy

* Updates based on review

* Fix Clippy warning

* Keep MSRV

* Add stubs

* Only modify deps for pest

---------

Co-authored-by: Ivan Carvalho <[email protected]>

Author: Krishn1412

Cargo.lock

@@ -64,6 +64,8 @@ serde_json = "1.0"
 smallvec = { version = "1.0", features = ["union"] }
 rustworkx-core = { path = "rustworkx-core", version = "=0.17.1" }
 flate2 = "1.0.35"
+pest = "=2.7.15"
+pest_derive = "=2.7.15"
 
 [dependencies.pyo3]
 version = "0.24"

Cargo.toml

@@ -0,0 +1,21 @@
+features:
+  - |
+    Added feature for importing graphs from the GraphViz DOT format via the new
+    :func:`~rustworkx.from_dot` function. This function takes a DOT string and
+    constructs either a :class:`~rustworkx.PyGraph` or
+    :class:`~rustworkx.PyDiGraph` object, automatically detecting the graph type
+    from the DOT input. Node attributes, edge attributes, and graph-level
+    attributes are preserved.For example::
+
+      import rustworkx
+
+      dot_str = '''
+      digraph {
+        0 [label="a", color=red];
+        1 [label="b", color=blue];
+        0 -> 1 [weight=1];
+      }
+      '''
+      g = rustworkx.from_dot(dot_str)
+      assert len(g.nodes()) == 2
+      assert len(g.edges()) == 1

releasenotes/notes/from-dot-b9f092537c7bce94.yaml

@@ -99,7 +99,7 @@ fn assign_label<E>(
         assign_label(
             endpoints[mate[&base]],
             1,
-            mate.get(&base).map(|p| (p ^ 1)),
+            mate.get(&base).map(|p| p ^ 1),
             num_nodes,
             in_blossoms,
             labels,

rustworkx-core/src/max_weight_matching.rs

@@ -169,6 +169,7 @@ from .rustworkx import GraphMLKey as GraphMLKey
 from .rustworkx import digraph_node_link_json as digraph_node_link_json
 from .rustworkx import graph_node_link_json as graph_node_link_json
 from .rustworkx import from_node_link_json_file as from_node_link_json_file
+from .rustworkx import from_dot as from_dot
 from .rustworkx import parse_node_link_json as parse_node_link_json
 from .rustworkx import digraph_bellman_ford_shortest_paths as digraph_bellman_ford_shortest_paths
 from .rustworkx import graph_bellman_ford_shortest_paths as graph_bellman_ford_shortest_paths

rustworkx/__init__.pyi

@@ -751,6 +751,9 @@ def from_node_link_json_file(
     node_attrs: Callable[[dict[str, str]], _S] | None = ...,
     edge_attrs: Callable[[dict[str, str]], _T] | None = ...,
 ) -> PyDiGraph[_S, _T] | PyGraph[_S, _T]: ...
+def from_dot(
+    dot_str: str,
+) -> PyDiGraph[_S, _T] | PyGraph[_S, _T]: ...
 
 # Shortest Path
 

rustworkx/rustworkx.pyi

@@ -0,0 +1,43 @@
+WHITESPACE = _{ " " | "\t" | "\r" | "\n" }
+COMMENT = _{ "#" ~ (!NEWLINE ~ ANY)* | "//" ~ (!NEWLINE ~ ANY)* | "/*" ~ (!"*/" ~ ANY)* ~ "*/" }
+NEWLINE = _{ "\n" | "\r\n" }
+
+graph_file = { SOI ~ strict? ~ graph_type ~ id? ~ "{" ~ stmt_list? ~ "}" ~ EOI }
+
+strict = { "strict" }
+graph_type = { "graph" | "digraph" }
+
+id = _{ number | identifier | quoted_id | html_id }
+
+number = @{ ASCII_DIGIT+ }
+identifier = @{ (ASCII_ALPHANUMERIC | "_" | "." | "/" | "\\" | "-")+ }
+quoted_id = @{ "\"" ~ (("\\\"" | (!"\"" ~ ANY))*) ~ "\"" }
+html_id = @{ "<" ~ (!">" ~ ANY)* ~ ">" }
+
+stmt_list = { (stmt ~ (";" | NEWLINE)*)* }
+
+stmt = _{
+      edge_stmt
+    | node_stmt
+    | attr_stmt
+    | assignment
+    | subgraph
+}
+
+node_stmt = { node_id ~ attr_list* }
+edge_stmt = { edge_point ~ (edge_op ~ edge_point)+ ~ attr_list* }
+
+edge_op = { "->" | "--" }
+
+edge_point = { node_id | subgraph }
+
+attr_stmt = { ("graph" | "node" | "edge") ~ attr_list+ }
+
+attr_list = { "[" ~ a_list? ~ "]" }
+a_list = { (id ~ ("=" ~ id)? ~ ("," | ";")?)* }
+
+assignment = { id ~ "=" ~ id }
+
+subgraph = { "subgraph" ~ id? ~ "{" ~ stmt_list? ~ "}" }
+
+node_id = { id ~ (":" ~ id)? ~ (":" ~ id)? }