Create method insert_before() (#16)

Author: hepheir

w3/python/core/fundamental_interface/Node.py

@@ -266,6 +266,48 @@ def _set_owner_document(self,
         """Indirect accessor to set the 'owner_document' property."""
         self._owner_document = owner_document
 
+    def insert_before(self,
+                      new_child: _AnyNode,
+                      ref_child: Optional[_AnyNode] = None) -> _AnyNode:
+        """Inserts the node `new_child` before the existing child node `ref_child`. If `ref_child` is `None`, insert `new_child` at the end of the list of children.
+
+        If `new_child` is a `DocumentFragment` object, all of its children are inserted, in the same order, before `ref_child`. If the `new_child` is already in the tree, it is first removed.
+
+        Args:
+            new_child: The node to insert.
+            ref_child: The reference node, i.e., the node before which the new node must be inserted.
+
+        Returns:
+            The node being inserted.
+
+        Raises:
+            DOMException:
+              - `HIERARCHY_REQUEST_ERR`: Raised if this node is of a type that does not allow children of the type of the `new_child` node, or if the node to insert is one of this node's ancestors.
+              - `WRONG_DOCUMENT_ERR`: Raised if `new_child` was created from a different document than the one that created this node.
+              - `NO_MODIFICATION_ALLOWED_ERR`: Raised if this node is readonly.
+              - `NOT_FOUND_ERR`: Raised if `ref_child` is not a child of this node.
+        """
+        if self._read_only:
+            raise DOMException(DOMException.NO_MODIFICATION_ALLOWED_ERR)
+        if self.owner_document is not new_child.owner_document:
+            raise DOMException(DOMException.WRONG_DOCUMENT_ERR)
+        # `HIERARCHY_REQUEST_ERR` should be checked on subclasses by overriding.
+        if new_child in self.child_nodes:
+            self.child_nodes.remove(new_child)
+        if new_child.node_type == NodeType.DOCUMENT_FRAGMENT_NODE:
+            grand_child_node: _AnyNode
+            for grand_child_node in new_child.child_nodes:
+                self.insert_before(grand_child_node, ref_child)
+        elif ref_child is None:
+            self.child_nodes.append(new_child)
+        elif ref_child not in self.child_nodes:
+            raise DOMException(DOMException.NOT_FOUND_ERR)
+        else:
+            self.child_nodes.insert(self.child_nodes.index(ref_child),
+                                    new_child)
+        new_child._set_parent_node(self)
+        return new_child
+
     def has_child_nodes(self) -> bool:
         """This is a convenience method to allow easy determination of whether a node has any children.