Added ability to insert a Node instance into an Edge with some options

It's not super clean (lots of duplication) but it works for now and can be cleaned up later.

Author: JackAtOmenApps

django_postgresql_dag/models.py

@@ -5,6 +5,7 @@
 query. These queries also topologically sort the ids by generation.
 """
 
+from copy import deepcopy
 from django.apps import apps
 from django.db import models, connection
 from django.db.models import Case, When
@@ -467,6 +468,108 @@ def sort(self, edges, **kwargs):
         # ToDo: Implement
         pass
 
+    def insert_node(self, edge, node, clone_to_rootside=False, clone_to_leafside=False, pre_save=None, post_save=None):
+        """
+        Inserts a node into an existing Edge instance. Returns a tuple of the newly created rootside_edge (parent to
+        the inserted node) and leafside_edge (child to the inserted node).
+
+        Process:
+        1. Add a new Edge from the parent Node of the current Edge instance to the provided Node instance,
+           optionally cloning properties of the existing Edge.
+        2. Add a new Edge from the provided Node instance to the child Node of the current Edge instance,
+           optionally cloning properties of the existing Edge.
+        3. Remove the original Edge instance.
+
+        The instance will still exist in memory, though not in database
+        (https://docs.djangoproject.com/en/3.1/ref/models/instances/#refreshing-objects-from-database).
+        Recommend running the following after conducting the deletion:
+            `del instancename`
+
+        Cloning will fail if a field has unique=True, so a pre_save function can be passed into this method
+        Likewise, a post_save function can be passed in to rebuild relationships. For instance, if you have a `name`
+        field that is unique and generated automatically in the model's save() method, you could pass in a the following
+        `pre_save` function to clear the name prior to saving the new Edge instance(s):
+
+        def pre_save(new_edge):
+            new_edge.name = ""
+            return new_edge
+
+        A more complete example, where we have models named NetworkEdge & NetworkNode, and we want to insert a new
+        Node (n2) into Edge e1, while copying e1's field properties (except `name`) to the newly created rootside Edge
+        instance (n1 to n2) is shown below.
+
+        Original        Final
+
+        n1  o           n1  o
+            |                 \
+            |                  o n2
+            |                 /
+        n3  o           n3  o
+
+        ##################################################################################
+        from myapp.models import NetworkEdge, NetworkNode
+
+        n1 = NetworkNode.objects.create(name="n1")
+        n2 = NetworkNode.objects.create(name="n2")
+        n3 = NetworkNode.objects.create(name="n3")
+
+        # Connect n3 to n1
+        n1.add_child(n3)
+
+        e1 = NetworkEdge.objects.last()
+
+        # function to clear the `name` field, which is autogenerated and must be unique
+        def pre_save(new_edge):
+            new_edge.name = ""
+            return new_edge
+
+        NetworkEdge.objects.insert_node(e1, n2, clone_to_rootside=True, pre_save=pre_save)
+        ##################################################################################
+        """
+
+        rootside_edge = None
+        leafside_edge = None
+
+        # Attach the root-side edge
+        if clone_to_rootside:
+            rootside_edge = deepcopy(edge)
+            rootside_edge.pk = None
+            rootside_edge.parent = edge.parent
+            rootside_edge.child = node
+
+            if callable(pre_save):
+                rootside_edge = pre_save(rootside_edge)
+            
+            rootside_edge.save()
+
+            if callable(post_save):
+                rootside_edge = post_save(rootside_edge)
+
+        else:
+            edge.parent.add_child(node)
+
+        # Attach the leaf-side edge
+        if clone_to_leafside:
+            leafside_edge = deepcopy(edge)
+            leafside_edge.pk = None
+            leafside_edge.parent = node
+            leafside_edge.child = edge.child
+
+            if callable(pre_save):
+                leafside_edge = pre_save(leafside_edge)
+
+            leafside_edge.save()
+
+            if callable(post_save):
+                leafside_edge = post_save(leafside_edge)
+
+        else:
+            edge.child.add_parent(node)
+
+        # Remove the original edge in the database. Still remains in memory, though, as noted above. 
+        edge.delete()
+        return rootside_edge, leafside_edge
+
 
 def edge_factory(
     node_model,