Updated to reflect addition of insert_node and other small improvements.

Author: JackAtOmenApps

docs/methods.rst

@@ -115,10 +115,14 @@ Returns a QuerySet of all nodes that share a child with this node and self
 
 Given an ending Node instance, returns a boolean value determining whether there is a path from the current Node instance to the ending Node instance
 
+Optional keyword argument: directional (boolean: if True, path searching operates normally, in a leafward only direction. If False, search operates in both directions)
+
 **path(self, ending_node, \*\*kwargs)**
 
 Returns a QuerySet of the shortest path from self to ending node, optionally in either direction. The resulting Queryset is sorted from root-side, toward leaf-side, regardless of the relative position of starting and ending nodes.
 
+Optional keyword argument: directional (boolean: if True, path searching operates normally, in a leafward only direction. If False, search operates in both directions)
+
 **distance(self, ending_node, \*\*kwargs)**
 
 Returns the shortest hops count to the target node
@@ -139,10 +143,14 @@ Returns True if the current Node instance has no parents nor children
 
 Provided an ending_node Node instance, returns True if the current Node instance and is an ancestor of the provided Node instance
 
+Optional keyword argument: directional (boolean: if True, path searching operates normally, in a leafward only direction. If False, search operates in both directions)
+
 **is_descendant_of(self, ending_node, \*\*kwargs)**
 
 Provided an ending_node Node instance, returns True if the current Node instance and is a descendant of the provided Node instance
 
+Optional keyword argument: directional (boolean: if True, path searching operates normally, in a leafward only direction. If False, search operates in both directions)
+
 **is_sibling_of(self, ending_node)**
 
 Provided an ending_node Node instance, returns True if the provided Node instance and the current Node instance share a parent Node
@@ -232,3 +240,54 @@ Given a list or set of Edge instances, verify that they result in a contiguous r
 Given a list or set of Edge instances, sort them from root-side to leaf-side
 
 *Not yet implemented.*
+
+**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)