diff --git a/Lib/xml/dom/minidom.py b/Lib/xml/dom/minidom.py index db51f350ea0153..f7e3c9f326480f 100644 --- a/Lib/xml/dom/minidom.py +++ b/Lib/xml/dom/minidom.py @@ -32,6 +32,9 @@ class Node(xml.dom.Node): + """Base class representing a node in the DOM tree. + Provides core properties and methods that all DOM nodes must implement. + """ namespaceURI = None # this is non-null only for elements and attributes parentNode = None ownerDocument = None @@ -44,6 +47,7 @@ def __bool__(self): return True def toxml(self, encoding=None, standalone=None): + """Generate a string representation of a DOM.""" return self.toprettyxml("", "", encoding, standalone) def toprettyxml(self, indent="\t", newl="\n", encoding=None, @@ -80,6 +84,14 @@ def _get_lastChild(self): return self.childNodes[-1] def insertBefore(self, newChild, refChild): + """Insert a new DOM Node before an existing Node. + + newChild + The new node to insert + refChild + The existing node that will be the next sibling of newChild. + If None, newChild is appended to the end. + """ if newChild.nodeType == self.DOCUMENT_FRAGMENT_NODE: for c in tuple(newChild.childNodes): self.insertBefore(c, refChild) @@ -112,6 +124,7 @@ def insertBefore(self, newChild, refChild): return newChild def appendChild(self, node): + """Append a child node to an existing node.""" if node.nodeType == self.DOCUMENT_FRAGMENT_NODE: for c in tuple(node.childNodes): self.appendChild(c) @@ -129,6 +142,7 @@ def appendChild(self, node): return node def replaceChild(self, newChild, oldChild): + """Replace child node *oldChild* with *newChild*.""" if newChild.nodeType == self.DOCUMENT_FRAGMENT_NODE: refChild = oldChild.nextSibling self.removeChild(oldChild) @@ -161,6 +175,7 @@ def replaceChild(self, newChild, oldChild): return oldChild def removeChild(self, oldChild): + """Remove an existing child.""" try: self.childNodes.remove(oldChild) except ValueError: @@ -177,6 +192,12 @@ def removeChild(self, oldChild): return oldChild def normalize(self): + """Transform this node into its normalized form. + + Remove empty exclusive Text nodes and concatenate data of + remaining contiguous exclusive Text nodes into the first of + their nodes. + """ L = [] for child in self.childNodes: if child.nodeType == Node.TEXT_NODE: @@ -204,6 +225,12 @@ def normalize(self): self.childNodes[:] = L def cloneNode(self, deep): + """Create and return a duplicate of this node. + + deep + If True, recursively clone this node's descendants. + If False, clone only this node. + """ return _clone_node(self, deep, self.ownerDocument or self) def isSupported(self, feature, version): @@ -1341,6 +1368,12 @@ def _get_internalSubset(self): return self.internalSubset def cloneNode(self, deep): + """Create and return a duplicate of this node. + + deep + If True, recursively clone this node's descendants. + If False, clone only this node. + """ if self.ownerDocument is None: # it's ok clone = DocumentType(None) @@ -1903,9 +1936,15 @@ def renameNode(self, n, namespaceURI, name): def _clone_node(node, deep, newOwnerDocument): - """ - Clone a node and give it the new owner document. - Called by Node.cloneNode and Document.importNode + """Create and return a clone of a DOM node. + + node + The DOM node to clone. + deep + If True, recursively clone the node's descendants. + If False, only clone the node itself. + newOwnerDocument + The document that will own the cloned node. """ if node.ownerDocument.isSameNode(newOwnerDocument): operation = xml.dom.UserDataHandler.NODE_CLONED