From 21bb3743d92e2c70f54bdce107cba20ae21688b3 Mon Sep 17 00:00:00 2001 From: Srinivas Reddy Thatiparthy <thatiparthysreenivas@gmail.com> Date: Sat, 4 Jan 2025 15:59:32 +0530 Subject: [PATCH] Update and Add docstrings for functions and methods in minidom.py module --- Lib/xml/dom/minidom.py | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/Lib/xml/dom/minidom.py b/Lib/xml/dom/minidom.py index db51f350ea0153..3f3944e7a935c8 100644 --- a/Lib/xml/dom/minidom.py +++ b/Lib/xml/dom/minidom.py @@ -32,6 +32,7 @@ class Node(xml.dom.Node): + """Define properties accessible on a DOM node.""" namespaceURI = None # this is non-null only for elements and attributes parentNode = None ownerDocument = None @@ -44,6 +45,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,10 +82,16 @@ def _get_lastChild(self): return self.childNodes[-1] def insertBefore(self, newChild, refChild): + """Insert a new DOM Node before an existing Node. + https://dom.spec.whatwg.org/#dom-node-insertbefore + The insertBefore(node, child) method, when invoked, + must return the result of pre-inserting node into + this before child. + See also https://dom.spec.whatwg.org/#concept-node-pre-insert + """ if newChild.nodeType == self.DOCUMENT_FRAGMENT_NODE: for c in tuple(newChild.childNodes): self.insertBefore(c, refChild) - ### The DOM does not clearly specify what to return in this case return newChild if newChild.nodeType not in self._child_node_types: raise xml.dom.HierarchyRequestErr( @@ -112,6 +120,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 +138,7 @@ def appendChild(self, node): return node def replaceChild(self, newChild, oldChild): + """Replace an existing node with a new node.""" if newChild.nodeType == self.DOCUMENT_FRAGMENT_NODE: refChild = oldChild.nextSibling self.removeChild(oldChild) @@ -161,6 +171,7 @@ def replaceChild(self, newChild, oldChild): return oldChild def removeChild(self, oldChild): + """Remove an existing child.""" try: self.childNodes.remove(oldChild) except ValueError: @@ -172,11 +183,15 @@ def removeChild(self, oldChild): oldChild.nextSibling = oldChild.previousSibling = None if oldChild.nodeType in _nodeTypes_with_children: _clear_id_cache(self) - oldChild.parentNode = None return oldChild def normalize(self): + """Transform a node into its normalized form. + Removes empty exclusive Text nodes and concatenates the 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 +219,7 @@ def normalize(self): self.childNodes[:] = L def cloneNode(self, deep): + """The Node.cloneNode() method returns a duplicate of the node.""" return _clone_node(self, deep, self.ownerDocument or self) def isSupported(self, feature, version): @@ -882,7 +898,7 @@ def getElementsByTagNameNS(self, namespaceURI, localName): self, namespaceURI, localName, NodeList()) def __repr__(self): - return "<DOM Element: %s at %#x>" % (self.tagName, id(self)) + return f"<DOM Element: {self.tagName}>" def writexml(self, writer, indent="", addindent="", newl=""): """Write an XML element to a file-like object @@ -1341,6 +1357,7 @@ def _get_internalSubset(self): return self.internalSubset def cloneNode(self, deep): + """The Node.cloneNode() method returns a duplicate of the node.""" if self.ownerDocument is None: # it's ok clone = DocumentType(None) @@ -1904,7 +1921,8 @@ def renameNode(self, n, namespaceURI, name): def _clone_node(node, deep, newOwnerDocument): """ - Clone a node and give it the new owner document. + Returns a copy of node. + If deep is true, the copy also includes the node’s descendants. Called by Node.cloneNode and Document.importNode """ if node.ownerDocument.isSameNode(newOwnerDocument):