Merge pull request #30 from TheTrueSCU/feature/cyclic-graphs

feat: Support Cyclic Graphs and Refactor Hierarchy

Author: TheTrueSCU

README.md

@@ -129,7 +129,7 @@ The CLI automatically detects formats based on file extensions:
 ## Quick Start
 
 ```python
-from graphable.graph import Graph
+from graphable.acyclic_graph import AcyclicGraph as Graph
 from graphable.graphable import Graphable
 from graphable.views.texttree import create_topology_tree_txt
 

docs/api.rst

@@ -6,7 +6,17 @@ API Reference
    :undoc-members:
    :show-inheritance:
 
-.. automodule:: graphable.graph
+.. automodule:: graphable.acyclic_graph
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: graphable.cyclic_graph
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: graphable.graph_base
    :members:
    :undoc-members:
    :show-inheritance:

docs/usage.rst

@@ -180,6 +180,43 @@ If your graph contains cycles (which prevents it from being a DAG), ``graphable`
    # Returns a list of (source, target) tuples to remove
    suggested_breaks = graph.suggest_cycle_breaks()
 
+Cyclic Graphs
+^^^^^^^^^^^^^
+
+While the default ``Graph`` class (an alias for ``AcyclicGraph``) strictly enforces acyclicity, you can use the ``CyclicGraph`` class to work with structures that contain loops.
+
+.. code-block:: python
+
+   from graphable.cyclic_graph import CyclicGraph
+   from graphable.graphable import Graphable
+
+   a = Graphable("A")
+   b = Graphable("B")
+
+   g = CyclicGraph()
+   g.add_edge(a, b)
+   g.add_edge(b, a) # This is allowed in CyclicGraph
+
+**Converting to Acyclic**
+
+If you have a ``CyclicGraph`` and need to perform DAG-specific operations (like topological sorts or CPM), you can convert it to an ``AcyclicGraph`` by breaking cycles:
+
+.. code-block:: python
+
+   # Returns a new AcyclicGraph with minimal edge breaks
+   dag = g.to_acyclic()
+
+**Unified I/O for Cyclic Graphs**
+
+Note that the high-level ``Graph.read()`` method will raise a ``GraphCycleError`` if the input file contains cycles. If you expect your data to be cyclic, use ``CyclicGraph.read()`` instead:
+
+.. code-block:: python
+
+   from graphable.cyclic_graph import CyclicGraph
+
+   # Correctly handles files with cycles
+   g = CyclicGraph.read("cyclic_structure.json")
+
 Cycle Detection
 ^^^^^^^^^^^^^^^
 
@@ -560,14 +597,13 @@ NetworkX Integration
 
 For users who need advanced graph analysis capabilities, ``graphable`` provides seamless integration with the `NetworkX <https://networkx.org/>`_ library.
 
-If you have ``networkx`` installed, you can convert any ``graphable.Graph`` to a ``networkx.DiGraph`` using the ``to_networkx()`` method:
+If you have ``networkx`` installed, you can convert any ``graphable.acyclic_graph.AcyclicGraph`` to a ``networkx.DiGraph`` using the ``to_networkx()`` method:
 
 .. code-block:: python
 
    import networkx as nx
-   from graphable.graph import Graph
+   from graphable.acyclic_graph import AcyclicGraph as Graph
    from graphable.graphable import Graphable
-
    g = Graph()
    # ... build your graph ...
 

examples/advanced_usage.py

@@ -1,4 +1,4 @@
-from graphable.graph import Graph
+from graphable.acyclic_graph import AcyclicGraph as Graph
 from graphable.graphable import Graphable
 from graphable.views.mermaid import MermaidStylingConfig, create_topology_mermaid_mmd
 

examples/basic_usage.py

@@ -2,7 +2,7 @@
 import sys
 from pathlib import Path
 
-from graphable.graph import Graph
+from graphable.acyclic_graph import AcyclicGraph as Graph
 from graphable.graphable import Graphable
 from graphable.views.asciiflow import create_topology_ascii_flow
 from graphable.views.csv import create_topology_csv
@@ -149,12 +149,10 @@ def main():
 
     # Slicing
     upstream = g.upstream_of(ui)
-    print(f"Upstream of React: {[n.reference for n in upstream.topological_order()]}")
+    print(f"Upstream of React: {[n.reference for n in list(upstream)]}")
 
     between = g.subgraph_between(db, ui)
-    print(
-        f"Between Postgres and React: {[n.reference for n in between.topological_order()]}"
-    )
+    print(f"Between Postgres and React: {[n.reference for n in list(between)]}")
 
     # Transitive Closure
     closure = g.transitive_closure()

examples/cyclic_usage.py

@@ -0,0 +1,50 @@
+from graphable.cyclic_graph import CyclicGraph
+from graphable.graphable import Graphable
+from graphable.views.mermaid import create_topology_mermaid_mmd
+
+
+def demo_cyclic_graph():
+    """
+    Demonstrate how to work with Cyclic Graphs in graphable.
+    """
+    print("--- Graphable Cyclic Usage Demo ---")
+
+    # 1. Create nodes that form a cycle
+    # A common real-world example: circular feedback in a system
+    sensor = Graphable("Sensor")
+    controller = Graphable("Controller")
+    actuator = Graphable("Actuator")
+
+    # 2. Build the Cyclic Graph
+    g = CyclicGraph()
+
+    g.add_edge(sensor, controller, label="reads")
+    g.add_edge(controller, actuator, label="commands")
+    g.add_edge(
+        actuator, sensor, label="affects"
+    )  # Cycle: Sensor -> Controller -> Actuator -> Sensor
+
+    print(f"Graph nodes: {[n.reference for n in g]}")
+    print(f"Graph is cyclic. Number of nodes: {len(g)}")
+
+    # 3. Suggesting cycle breaks
+    print("\n--- 1. Suggesting Cycle Breaks ---")
+    breaks = g.suggest_cycle_breaks()
+    for u, v in breaks:
+        print(f"Suggested break: {u.reference} -> {v.reference}")
+
+    # 4. Converting to Acyclic
+    print("\n--- 2. Converting to Acyclic Graph ---")
+    dag = g.to_acyclic()
+    print(f"DAG nodes: {[n.reference for n in dag]}")
+
+    # Now we can perform DAG operations like topological sort
+    print(f"Topological Order: {[n.reference for n in dag.topological_order()]}")
+
+    # 5. Visualization
+    print("\n--- 3. Mermaid Representation ---")
+    print(g.render(create_topology_mermaid_mmd))
+
+
+if __name__ == "__main__":
+    demo_cyclic_graph()

examples/parser_examples.py

@@ -1,4 +1,5 @@
-from graphable.graph import Graph
+from graphable.acyclic_graph import AcyclicGraph as Graph
+from graphable.cyclic_graph import CyclicGraph
 from graphable.views.texttree import create_topology_tree_txt
 
 
@@ -55,12 +56,31 @@ def demo_csv_parsing():
     print(g.render(create_topology_tree_txt))
 
 
+def demo_cyclic_parsing():
+    print("\n--- Cyclic JSON Parsing ---")
+    # A cycle: A -> B -> A
+    json_data = """
+    {
+      "nodes": [{"id": "A"}, {"id": "B"}],
+      "edges": [
+        {"source": "A", "target": "B"},
+        {"source": "B", "target": "A"}
+      ]
+    }
+    """
+    # Note: Using CyclicGraph because Graph (AcyclicGraph) would raise an error
+    g = CyclicGraph.from_json(json_data)
+    print(f"Loaded {len(g)} nodes from cyclic JSON string.")
+    print("Nodes: " + ", ".join([n.reference for n in g]))
+
+
 def main():
     print("Graphable Parser Examples\n")
     demo_json_parsing()
     demo_yaml_parsing()
     demo_toml_parsing()
     demo_csv_parsing()
+    demo_cyclic_parsing()
 
 
 if __name__ == "__main__":

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "graphable"
-version = "0.6.1"
-description = "A lightweight, type-safe library for building, managing, and visualizing dependency graphs."
+version = "0.7.0"
+description = "A lightweight, type-safe library for building, managing, and visualizing dependency graphs (both DAG and cyclic)."
 readme = "README.md"
 authors = [
     { name = "Richard West", email = "[email protected]" }
@@ -10,7 +10,7 @@ requires-python = ">=3.13"
 dependencies = [
     "defusedxml>=0.7.1",
 ]
-keywords = ["graph", "dependency-graph", "topological-sort", "dag", "orchestration", "parallel-processing", "caching", "mermaid", "graphviz", "d2", "plantuml", "tikz", "cytoscape", "json", "csv", "networkx", "visualization"]
+keywords = ["graph", "dependency-graph", "acyclic-graph", "cyclic-graph", "dag", "orchestration", "parallel-processing", "caching", "mermaid", "graphviz", "d2", "plantuml", "tikz", "cytoscape", "json", "csv", "networkx", "visualization"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",