implica 0.3.0__py3-none-any.whl

implica/mutations/base.py

@@ -0,0 +1,51 @@
+"""
+Mutation system for transactional graph modifications.
+
+This module defines mutations that can be applied to a graph with forward
+and backward operations, enabling transactional rollback on failures.
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..graph.graph import Graph
+
+
+class Mutation(ABC):
+    """
+    Abstract base class for graph mutations.
+
+    Each mutation must implement both forward (apply) and backward (revert)
+    operations to support transactional rollback.
+    """
+
+    @abstractmethod
+    def forward(self, graph: "Graph") -> None:
+        """
+        Apply the mutation to the graph.
+
+        Args:
+            graph: The graph to modify
+
+        Raises:
+            Exception: If the mutation cannot be applied
+        """
+        pass
+
+    @abstractmethod
+    def backward(self, graph: "Graph") -> None:
+        """
+        Revert the mutation from the graph.
+
+        This operation should undo what forward() did.
+
+        Args:
+            graph: The graph to modify
+        """
+        pass
+
+    @abstractmethod
+    def __str__(self) -> str:
+        """Return a string representation of the mutation."""
+        pass

implica/mutations/remove_edge.py

@@ -0,0 +1,54 @@
+from typing import TYPE_CHECKING
+
+from ..graph.elements import Edge
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph.graph import Graph
+
+
+class RemoveEdge(Mutation):
+    """Mutation to remove an edge from the graph."""
+
+    def __init__(self, edge_uid: str):
+        """
+        Initialize the RemoveEdge mutation.
+
+        Args:
+            edge_uid: The uid of the edge to remove
+        """
+        self.edge_uid = edge_uid
+        self._removed_edge: Edge | None = None
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Remove the edge from the graph.
+
+        Args:
+            graph: The graph to modify
+
+        Raises:
+            KeyError: If the edge doesn't exist
+        """
+        # Store the edge for rollback
+        self._removed_edge = graph.get_edge(self.edge_uid)
+
+        # Remove the edge
+        graph._remove_edge(self.edge_uid)
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Re-add the edge to the graph.
+
+        Args:
+            graph: The graph to modify
+        """
+        if self._removed_edge is None:
+            raise RuntimeError("Cannot revert RemoveEdge: edge was not stored")
+
+        # Add the edge back
+        graph._add_edge(self._removed_edge)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"RemoveEdge({self.edge_uid})"

implica/mutations/remove_many_edges.py

@@ -0,0 +1,64 @@
+from typing import TYPE_CHECKING
+
+from ..graph.elements import Edge
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph.graph import Graph
+
+
+class RemoveManyEdges(Mutation):
+    """Mutation to remove multiple edges from the graph."""
+
+    def __init__(self, edge_uids: list[str]):
+        """
+        Initialize the RemoveManyEdges mutation.
+
+        Args:
+            edge_uids: List of edge uids to remove
+        """
+        self.edge_uids = edge_uids
+        self._removed_edges: list[Edge] = []
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Remove all edges from the graph.
+
+        If any edge fails to be removed, all previously removed edges are restored.
+
+        Args:
+            graph: The graph to modify
+
+        Raises:
+            KeyError: If any edge doesn't exist
+        """
+        self._removed_edges = []
+
+        try:
+            for edge_uid in self.edge_uids:
+                # Store the edge for rollback
+                edge = graph.get_edge(edge_uid)
+                self._removed_edges.append(edge)
+
+                # Remove the edge
+                graph._remove_edge(edge_uid)
+        except Exception:
+            # Rollback: restore all edges that were removed
+            for edge in self._removed_edges:
+                graph._add_edge(edge)
+            self._removed_edges = []
+            raise
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Re-add all removed edges to the graph.
+
+        Args:
+            graph: The graph to modify
+        """
+        for edge in reversed(self._removed_edges):
+            graph._add_edge(edge)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"RemoveManyEdges(count={len(self.edge_uids)})"

implica/mutations/remove_many_nodes.py

@@ -0,0 +1,69 @@
+from typing import TYPE_CHECKING
+
+from ..graph.elements import Node, Edge
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph.graph import Graph
+
+
+class RemoveManyNodes(Mutation):
+    """Mutation to remove multiple nodes from the graph."""
+
+    def __init__(self, node_uids: list[str]):
+        """
+        Initialize the RemoveManyNodes mutation.
+
+        Args:
+            node_uids: List of node uids to remove
+        """
+        self.node_uids = node_uids
+        self._removed_data: list[tuple[Node, list[Edge]]] = []
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Remove all nodes from the graph.
+
+        If any node fails to be removed, all previously removed nodes are restored.
+
+        Args:
+            graph: The graph to modify
+
+        Raises:
+            KeyError: If any node doesn't exist
+        """
+        self._removed_data = []
+
+        try:
+            for node_uid in self.node_uids:
+                # Store the node and its edges for rollback
+                node = graph.get_node(node_uid)
+                edges = graph.get_edges_for_node(node_uid)
+                self._removed_data.append((node, edges))
+
+                # Remove the node
+                graph._remove_node(node_uid)
+        except Exception:
+            # Rollback: restore all nodes that were removed
+            for node, edges in self._removed_data:
+                graph._add_node(node)
+                for edge in edges:
+                    graph._add_edge(edge)
+            self._removed_data = []
+            raise
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Re-add all removed nodes and their edges to the graph.
+
+        Args:
+            graph: The graph to modify
+        """
+        for node, edges in reversed(self._removed_data):
+            graph._add_node(node)
+            for edge in edges:
+                graph._add_edge(edge)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"RemoveManyNodes(count={len(self.node_uids)})"

implica/mutations/remove_node.py

@@ -0,0 +1,62 @@
+from typing import TYPE_CHECKING
+
+from ..graph import Edge, Node
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph import Graph
+
+
+class RemoveNode(Mutation):
+    """Mutation to remove a node from the graph."""
+
+    def __init__(self, node_uid: str):
+        """
+        Initialize the RemoveNode mutation.
+
+        Args:
+            node_uid: The uid of the node to remove
+        """
+        self.node_uid = node_uid
+        self._removed_node: Node | None = None
+        self._removed_edges: list[Edge] = []
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Remove the node from the graph.
+
+        Also stores the node and its connected edges for potential rollback.
+
+        Args:
+            graph: The graph to modify
+
+        Raises:
+            KeyError: If the node doesn't exist
+        """
+        # Store the node and its edges for rollback
+        self._removed_node = graph.get_node(self.node_uid)
+        self._removed_edges = graph.get_edges_for_node(self.node_uid)
+
+        # Remove the node (this will also remove connected edges)
+        graph._remove_node(self.node_uid)
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Re-add the node and its edges to the graph.
+
+        Args:
+            graph: The graph to modify
+        """
+        if self._removed_node is None:
+            raise RuntimeError("Cannot revert RemoveNode: node was not stored")
+
+        # Add the node back
+        graph._add_node(self._removed_node)
+
+        # Add the edges back
+        for edge in self._removed_edges:
+            graph._add_edge(edge)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"RemoveNode({self.node_uid})"

implica/mutations/try_add_edge.py

@@ -0,0 +1,53 @@
+from typing import TYPE_CHECKING
+
+from ..graph.elements import Edge
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph.graph import Graph
+
+
+class TryAddEdge(Mutation):
+    """Mutation to add an edge to the graph, or do nothing if it already exists."""
+
+    def __init__(self, edge: Edge):
+        """
+        Initialize the TryAddEdge mutation.
+
+        Args:
+            edge: The edge to add
+        """
+        self.edge = edge
+        self._was_added: bool = False
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Try to add the edge to the graph.
+
+        If the edge already exists, this is a no-op.
+
+        Args:
+            graph: The graph to modify
+
+        Raises:
+            KeyError: If source or destination nodes don't exist
+        """
+        if graph.has_edge(self.edge.uid):
+            self._was_added = False
+        else:
+            graph._add_edge(self.edge)
+            self._was_added = True
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Remove the edge from the graph if it was added.
+
+        Args:
+            graph: The graph to modify
+        """
+        if self._was_added:
+            graph._remove_edge(self.edge.uid)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"TryAddEdge({self.edge})"

implica/mutations/try_add_node.py

@@ -0,0 +1,50 @@
+from typing import TYPE_CHECKING
+
+from ..graph import Edge, Node
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph import Graph
+
+
+class TryAddNode(Mutation):
+    """Mutation to add a node to the graph, or do nothing if it already exists."""
+
+    def __init__(self, node: Node):
+        """
+        Initialize the TryAddNode mutation.
+
+        Args:
+            node: The node to add
+        """
+        self.node = node
+        self._was_added: bool = False
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Try to add the node to the graph.
+
+        If the node already exists, this is a no-op.
+
+        Args:
+            graph: The graph to modify
+        """
+        if graph.has_node(self.node.uid):
+            self._was_added = False
+        else:
+            graph._add_node(self.node)
+            self._was_added = True
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Remove the node from the graph if it was added.
+
+        Args:
+            graph: The graph to modify
+        """
+        if self._was_added:
+            graph._remove_node(self.node.uid)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"TryAddNode({self.node})"

implica/mutations/try_remove_edge.py

@@ -0,0 +1,58 @@
+from typing import TYPE_CHECKING
+
+from ..graph.elements import Edge
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph.graph import Graph
+
+
+class TryRemoveEdge(Mutation):
+    """Mutation to remove an edge from the graph, or do nothing if it doesn't exist."""
+
+    def __init__(self, edge_uid: str):
+        """
+        Initialize the TryRemoveEdge mutation.
+
+        Args:
+            edge_uid: The uid of the edge to remove
+        """
+        self.edge_uid = edge_uid
+        self._was_removed: bool = False
+        self._removed_edge: Edge | None = None
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Try to remove the edge from the graph.
+
+        If the edge doesn't exist, this is a no-op.
+
+        Args:
+            graph: The graph to modify
+        """
+        if not graph.has_edge(self.edge_uid):
+            self._was_removed = False
+        else:
+            # Store the edge for rollback
+            self._removed_edge = graph.get_edge(self.edge_uid)
+
+            # Remove the edge
+            graph._remove_edge(self.edge_uid)
+            self._was_removed = True
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Re-add the edge if it was removed.
+
+        Args:
+            graph: The graph to modify
+        """
+        if self._was_removed:
+            if self._removed_edge is None:
+                raise RuntimeError("Cannot revert TryRemoveEdge: edge was not stored")
+
+            graph._add_edge(self._removed_edge)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"TryRemoveEdge({self.edge_uid})"

implica/mutations/try_remove_node.py

@@ -0,0 +1,62 @@
+from typing import TYPE_CHECKING
+
+from ..graph import Edge, Node
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph import Graph
+
+
+class TryRemoveNode(Mutation):
+    """Mutation to remove a node from the graph, or do nothing if it doesn't exist."""
+
+    def __init__(self, node_uid: str):
+        """
+        Initialize the TryRemoveNode mutation.
+
+        Args:
+            node_uid: The uid of the node to remove
+        """
+        self.node_uid = node_uid
+        self._was_removed: bool = False
+        self._removed_node: Node | None = None
+        self._removed_edges: list[Edge] = []
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Try to remove the node from the graph.
+
+        If the node doesn't exist, this is a no-op.
+
+        Args:
+            graph: The graph to modify
+        """
+        if not graph.has_node(self.node_uid):
+            self._was_removed = False
+        else:
+            # Store the node and its edges for rollback
+            self._removed_node = graph.get_node(self.node_uid)
+            self._removed_edges = graph.get_edges_for_node(self.node_uid)
+
+            # Remove the node
+            graph._remove_node(self.node_uid)
+            self._was_removed = True
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Re-add the node and its edges if it was removed.
+
+        Args:
+            graph: The graph to modify
+        """
+        if self._was_removed:
+            if self._removed_node is None:
+                raise RuntimeError("Cannot revert TryRemoveNode: node was not stored")
+
+            graph._add_node(self._removed_node)
+            for edge in self._removed_edges:
+                graph._add_edge(edge)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"TryRemoveNode({self.node_uid})"

implica-0.3.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Carlos Fernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.