10000 Update and Add docstrings for functions and methods in minidom.py module · python/cpython@21bb374 · GitHub
[go: up one dir, main page]

Skip to content

Commit 21bb374

Browse files
committed
Update and Add docstrings for functions and methods in minidom.py module
1 parent 513a4ef commit 21bb374

File tree

1 file changed

+22
-4
lines changed

1 file changed

+22
-4
lines changed

Lib/xml/dom/minidom.py

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232

3333

3434
class Node(xml.dom.Node):
35+
"""Define properties accessible on a DOM node."""
3536
namespaceURI = None # this is non-null only for elements and attributes
3637
parentNode = None
3738
ownerDocument = None
@@ -44,6 +45,7 @@ def __bool__(self):
4445
return True
4546

4647
def toxml(self, encoding=None, standalone=None):
48+
"""Generate a string representation of a DOM."""
4749
return self.toprettyxml("", "", encoding, standalone)
4850

4951
def toprettyxml(self, indent="\t", newl="\n", encoding=None,
@@ -80,10 +82,16 @@ def _get_lastChild(self):
8082
return self.childNodes[-1]
8183

8284
def insertBefore(self, newChild, refChild):
85+
"""Insert a new DOM Node before an existing Node.
86+
https://dom.spec.whatwg.org/#dom-node-insertbefore
87+
The insertBefore(node, child) method, when invoked,
88+
must return the result of pre-inserting node into
89+
this before child.
90+
See also https://dom.spec.whatwg.org/#concept-node-pre-insert
91+
"""
8392
if newChild.nodeType == self.DOCUMENT_FRAGMENT_NODE:
8493
for c in tuple(newChild.childNodes):
8594
self.insertBefore(c, refChild)
86-
### The DOM does not clearly specify what to return in this case
8795
return newChild
8896
if newChild.nodeType not in self._child_node_types:
8997
raise xml.dom.HierarchyRequestErr(
@@ -112,6 +120,7 @@ def insertBefore(self, newChild, refChild):
112120
return newChild
113121

114122
def appendChild(self, node):
123+
"""Append a child node to an existing node."""
115124
if node.nodeType == self.DOCUMENT_FRAGMENT_NODE:
116125
for c in tuple(node.childNodes):
117126
self.appendChild(c)
@@ -129,6 +138,7 @@ def appendChild(self, node):
129138
return node
130139

131140
def replaceChild(self, newChild, oldChild):
141+
"""Replace an existing node with a new node."""
132142
if newChild.nodeType == self.DOCUMENT_FRAGMENT_NODE:
133143
refChild = oldChild.nextSibling
134144
self.removeChild(oldChild)
@@ -161,6 +171,7 @@ def replaceChild(self, newChild, oldChild):
161171
return oldChild
162172

163173
def removeChild(self, oldChild):
174+
"""Remove an existing child."""
164175
try:
165176
self.childNodes.remove(oldChild)
166177
except ValueError:
@@ -172,11 +183,15 @@ def removeChild(self, oldChild):
172183
oldChild.nextSibling = oldChild.previousSibling = None
173184
if oldChild.nodeType in _nodeTypes_with_children:
174185
_clear_id_cache(self)
175-
176186
oldChild.parentNode = None
177187
return oldChild
178188

179189
def normalize(self):
190+
"""Transform a node into its normalized form.
191+
Removes empty exclusive Text nodes and concatenates the data of
192+
remaining contiguous exclusive Text nodes into the first of
193+
their nodes.
194+
"""
180195< 10000 div class="diff-text-inner"> L = []
181196
for child in self.childNodes:
182197
if child.nodeType == Node.TEXT_NODE:
@@ -204,6 +219,7 @@ def normalize(self):
204219
self.childNodes[:] = L
205220

206221
def cloneNode(self, deep):
222+
"""The Node.cloneNode() method returns a duplicate of the node."""
207223
return _clone_node(self, deep, self.ownerDocument or self)
208224

209225
def isSupported(self, feature, version):
@@ -882,7 +898,7 @@ def getElementsByTagNameNS(self, namespaceURI, localName):
882898
self, namespaceURI, localName, NodeList())
883899

884900
def __repr__(self):
885-
return "<DOM Element: %s at %#x>" % (self.tagName, id(self))
901+
return f"<DOM Element: {self.tagName}>"
886902

887903
def writexml(self, writer, indent="", addindent="", newl=""):
888904
"""Write an XML element to a file-like object
@@ -1341,6 +1357,7 @@ def _get_internalSubset(self):
13411357
return self.internalSubset
13421358

13431359
def cloneNode(self, deep):
1360+
"""The Node.cloneNode() method returns a duplicate of the node."""
13441361
if self.ownerDocument is None:
13451362
# it's ok
13461363
clone = DocumentType(None)
@@ -1904,7 +1921,8 @@ def renameNode(self, n, namespaceURI, name):
19041921

19051922
def _clone_node(node, deep, newOwnerDocument):
19061923
"""
1907-
Clone a node and give it the new owner document.
1924+
Returns a copy of node.
1925+
If deep is true, the copy also includes the node’s descendants.
19081926
Called by Node.cloneNode and Document.importNode
19091927
"""
19101928
if node.ownerDocument.isSameNode(newOwnerDocument):

0 commit comments

Comments
 (0)
0