From dcbb0fbc7fd892b70a4bdc9d67dc7af398bad3ed Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 12 Aug 2026 18:29:30 +0300 Subject: [PATCH 01/11] gh-155631: Document the CharacterData interface and other DOM members CharacterData was not mentioned at all, although Text, Comment and CDATASection inherit from it. Also document members which are implemented, but were omitted: Node.ownerDocument, Node.isSupported(), Node.getUserData(), Node.setUserData(), Document.doctype, Document.implementation, Document.documentURI, Document.strictErrorChecking, Document.createDocumentFragment(), Document.createCDATASection(), Document.importNode(), Document.renameNode(), Element.setIdAttribute(), Element.setIdAttributeNS(), Element.setIdAttributeNode(), Attr.isId, Attr.ownerElement, Text.wholeText, Text.splitText() and Text.replaceWholeText(). --- Doc/library/xml.dom.rst | 192 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 188 insertions(+), 4 deletions(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index 34e58dcad93012..3760b6ac99fc4f 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -314,6 +314,34 @@ All of the components of an XML document are subclasses of :class:`Node`. ``None``. This is a read-only attribute. +.. attribute:: Node.ownerDocument + + The :class:`Document` object to which this node belongs, or ``None`` + for a document itself. + This is a read-only attribute. + + +.. method:: Node.isSupported(feature, version) + + Return whether the DOM implementation supports a particular *feature*, + as :meth:`DOMImplementation.hasFeature` does. + + +.. method:: Node.setUserData(key, data, handler) + + Associate *data* with *key* on this node and return the data previously + associated with *key*, or ``None``. + If *data* is ``None``, the association is removed. + *handler* is called when the node is cloned, imported, renamed or deleted; + pass ``None`` if no notification is needed. + + +.. method:: Node.getUserData(key) + + Return the data associated with *key* on this node + by :meth:`~Node.setUserData`, or ``None``. + + .. attribute:: Node.nodeName This has a different meaning for each node type; see the DOM specification for @@ -509,6 +537,46 @@ inherits properties from :class:`Node`. The one and only root element of the document. +.. attribute:: Document.doctype + + The :class:`DocumentType` node of the document, or ``None``. + This is a read-only attribute. + + +.. attribute:: Document.implementation + + The :class:`DOMImplementation` object which created this document. + This is a read-only attribute. + + +.. attribute:: Document.strictErrorChecking + + Whether error checking is enforced. + Always ``False`` in :mod:`xml.dom.minidom`. + + +.. attribute:: Document.documentURI + + The location of the document, or ``None`` if it is unknown. + + +.. method:: Document.createDocumentFragment() + + Create and return an empty :class:`DocumentFragment` node. + + +.. method:: Document.createCDATASection(data) + + Create and return a :class:`CDATASection` node containing *data*. + + +.. method:: Document.importNode(importedNode, deep) + + Return a copy of *importedNode* which belongs to this document. + The original node is not removed from its document. + If *deep* is true, the descendants of the node are copied too. + + .. method:: Document.createElement(tagName) Create and return a new element node. The element is not inserted into the @@ -574,6 +642,18 @@ inherits properties from :class:`Node`. namespace after the prefix. +.. method:: Document.renameNode(n, namespaceURI, name) + + Rename the element or attribute node *n* + and return it. + *namespaceURI* is the new namespace URI, or + :data:`~xml.dom.EMPTY_NAMESPACE` if the node does not belong to a namespace. + *name* is the new qualified name. + + Raise :exc:`WrongDocumentErr` if *n* was created by other document, + and :exc:`NotSupportedErr` if it is neither an element nor an attribute. + + .. _dom-element-objects: Element Objects @@ -589,6 +669,25 @@ of that class. The value is a string. +.. method:: Element.setIdAttribute(name) + + Declare that the attribute *name* is of type ID, + so that the element is found by :meth:`Document.getElementById`. + Raise :exc:`NotFoundErr` if the element has no such attribute. + + +.. method:: Element.setIdAttributeNS(namespaceURI, localName) + + The same as :meth:`~Element.setIdAttribute`, + but for an attribute specified by its namespace URI and local name. + + +.. method:: Element.setIdAttributeNode(idAttr) + + The same as :meth:`~Element.setIdAttribute`, + but for an already retrieved attribute node. + + .. method:: Element.getElementsByTagName(tagName) Same as equivalent method in the :class:`Document` class. @@ -705,6 +804,21 @@ Attr Objects empty string. +.. attribute:: Attr.isId + + Whether this attribute is of type ID, + either because it is declared as such in the DTD + or because :meth:`Element.setIdAttribute` was used. + This is a read-only attribute. + + +.. attribute:: Attr.ownerElement + + The :class:`Element` node to which this attribute belongs, + or ``None`` if it is not used. + This is a read-only attribute. + + .. attribute:: Attr.value The text value of the attribute. This is a synonym for the @@ -735,13 +849,63 @@ You can use them or you can use the standardized :meth:`!getAttribute\*` family of methods on the :class:`Element` objects. +.. _dom-characterdata-objects: + +CharacterData Objects +^^^^^^^^^^^^^^^^^^^^^ + +:class:`CharacterData` represents text-like data in the XML document. +It is a subclass of :class:`Node`, and the base class +of :class:`Text`, :class:`CDATASection` and :class:`Comment`. +Such nodes cannot have child nodes. + + +.. attribute:: CharacterData.data + + The content of the node as a string. + + +.. attribute:: CharacterData.length + + The number of characters in :attr:`~CharacterData.data`. + This is a read-only attribute. + + +.. method:: CharacterData.substringData(offset, count) + + Return the substring of :attr:`~CharacterData.data` + of *count* characters starting at *offset*. + + +.. method:: CharacterData.appendData(arg) + + Append the string *arg* to :attr:`~CharacterData.data`. + + +.. method:: CharacterData.insertData(offset, arg) + + Insert the string *arg* into :attr:`~CharacterData.data` at *offset*. + + +.. method:: CharacterData.deleteData(offset, count) + + Remove *count* characters from :attr:`~CharacterData.data` + starting at *offset*. + + +.. method:: CharacterData.replaceData(offset, count, arg) + + Replace *count* characters of :attr:`~CharacterData.data` + starting at *offset* with the string *arg*. + + .. _dom-comment-objects: Comment Objects ^^^^^^^^^^^^^^^ -:class:`Comment` represents a comment in the XML document. It is a subclass of -:class:`Node`, but cannot have child nodes. +:class:`Comment` represents a comment in the XML document. +It is a subclass of :class:`CharacterData`. .. attribute:: Comment.data @@ -762,14 +926,34 @@ enclosed in CDATA marked sections are stored in :class:`CDATASection` objects. These two interfaces are identical, but provide different values for the :attr:`nodeType` attribute. -These interfaces extend the :class:`Node` interface. They cannot have child -nodes. +These interfaces extend the :class:`CharacterData` interface. .. attribute:: Text.data The content of the text node as a string. + +.. attribute:: Text.wholeText + + The text of all :class:`Text` nodes logically adjacent to this node, + concatenated in document order. + This is a read-only attribute. + + +.. method:: Text.replaceWholeText(content) + + Replace the text of all :class:`Text` nodes logically adjacent + to this node with *content*, removing the other nodes. + Return this node, or ``None`` if *content* is empty. + + +.. method:: Text.splitText(offset) + + Split this node into two nodes at *offset*, + keeping the first part in this node + and returning a new sibling node with the rest. + .. note:: The use of a :class:`CDATASection` node does not indicate that the node From 363e3ccee1fe255633de0fc354dd7886aac7ba3a Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 12 Aug 2026 19:59:15 +0300 Subject: [PATCH 02/11] gh-155631: Document the classes, DocumentFragment and NamedNodeMap methods Add class directives for all documented DOM classes, so that references to them resolve. They use :no-typesetting:, because the classes are not instantiated directly and the sections already introduce them. Add a section for DocumentFragment, which was referenced, but had no section of its own, and document Document.getElementById() and the getNamedItem(), setNamedItem() and removeNamedItem() families of NamedNodeMap, which are implemented, but were omitted. Silence references to the illustrative names in the IDL mapping example and to the PYTHON_DOM environment variable. --- Doc/library/xml.dom.rst | 106 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 102 insertions(+), 4 deletions(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index 3760b6ac99fc4f..6ecb635e40c2b9 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -95,7 +95,7 @@ The :mod:`!xml.dom` contains the following functions: module name of a DOM implementation, or ``None``. If it is not ``None``, imports the corresponding module and returns a :class:`DOMImplementation` object if the import succeeds. If no name is given, and if the environment variable - :envvar:`PYTHON_DOM` is set, this variable is used to find the implementation. + :envvar:`!PYTHON_DOM` is set, this variable is used to find the implementation. If name is not given, this examines the available implementations to find one with the required feature set. If no implementation can be found, raise an @@ -199,6 +199,9 @@ in Python. DOMImplementation Objects ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. class:: DOMImplementation + :no-typesetting: + The :class:`DOMImplementation` interface provides a way for applications to determine the availability of particular features in the DOM they are using. DOM Level 2 added the ability to create new :class:`Document` and @@ -233,6 +236,9 @@ DOM Level 2 added the ability to create new :class:`Document` and Node Objects ^^^^^^^^^^^^ +.. class:: Node + :no-typesetting: + All of the components of an XML document are subclasses of :class:`Node`. @@ -428,6 +434,9 @@ All of the components of an XML document are subclasses of :class:`Node`. NodeList Objects ^^^^^^^^^^^^^^^^ +.. class:: NodeList + :no-typesetting: + A :class:`NodeList` represents a sequence of nodes. These objects are used in two ways in the DOM Core recommendation: an :class:`Element` object provides one as its list of child nodes, and the :meth:`getElementsByTagName` and @@ -467,6 +476,9 @@ If a DOM implementation supports modification of the document, the DocumentType Objects ^^^^^^^^^^^^^^^^^^^^ +.. class:: DocumentType + :no-typesetting: + Information about the notations and entities declared by a document (including the external subset if the parser uses it and can provide the information) is available from a :class:`DocumentType` object. The :class:`DocumentType` for a @@ -527,6 +539,9 @@ following attributes: Document Objects ^^^^^^^^^^^^^^^^ +.. class:: Document + :no-typesetting: + A :class:`Document` represents an entire XML document, including its constituent elements, attributes, processing instructions, comments etc. Remember that it inherits properties from :class:`Node`. @@ -629,6 +644,13 @@ inherits properties from :class:`Node`. :class:`Element` object to use the newly created attribute instance. +.. method:: Document.getElementById(id) + + Return the element with the given ID, or ``None``. + Only attributes declared as being of type ID in the DTD + or by :meth:`Element.setIdAttribute` are searched. + + .. method:: Document.getElementsByTagName(tagName) Search for all descendants (direct children, children's children, etc.) with a @@ -659,6 +681,9 @@ inherits properties from :class:`Node`. Element Objects ^^^^^^^^^^^^^^^ +.. class:: Element + :no-typesetting: + :class:`Element` is a subclass of :class:`Node`, so inherits all the attributes of that class. @@ -782,6 +807,9 @@ of that class. Attr Objects ^^^^^^^^^^^^ +.. class:: Attr + :no-typesetting: + :class:`Attr` inherits from :class:`Node`, so inherits all its attributes. @@ -830,6 +858,9 @@ Attr Objects NamedNodeMap Objects ^^^^^^^^^^^^^^^^^^^^ +.. class:: NamedNodeMap + :no-typesetting: + :class:`NamedNodeMap` does *not* inherit from :class:`Node`. @@ -844,16 +875,71 @@ NamedNodeMap Objects in is arbitrary but will be consistent for the life of a DOM. Each item is an attribute node. Get its value with the :attr:`value` attribute. + +.. method:: NamedNodeMap.getNamedItem(name) + + Return the node with the given :attr:`~Attr.name`, + or ``None`` if there is no such node. + + +.. method:: NamedNodeMap.getNamedItemNS(namespaceURI, localName) + + Return the node with the given namespace URI and local name, + or ``None`` if there is no such node. + + +.. method:: NamedNodeMap.setNamedItem(node) + + Add *node* to the map, using its :attr:`~Attr.name` as the key. + Return the node which it replaces, or ``None`` if it replaces no node. + + +.. method:: NamedNodeMap.setNamedItemNS(node) + + Add *node* to the map, + using its namespace URI and local name as the key. + Return the node which it replaces, or ``None`` if it replaces no node. + + +.. method:: NamedNodeMap.removeNamedItem(name) + + Remove and return the node with the given :attr:`~Attr.name`. + Raise :exc:`NotFoundErr` if there is no such node. + + +.. method:: NamedNodeMap.removeNamedItemNS(namespaceURI, localName) + + Remove and return the node with the given namespace URI and local name. + Raise :exc:`NotFoundErr` if there is no such node. + There are also experimental methods that give this class more mapping behavior. You can use them or you can use the standardized :meth:`!getAttribute\*` family of methods on the :class:`Element` objects. +.. _dom-documentfragment-objects: + +DocumentFragment Objects +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. class:: DocumentFragment + :no-typesetting: + +:class:`DocumentFragment` is a lightweight container of nodes. +It is a subclass of :class:`Node`. +When it is inserted into the document tree, +its children are inserted instead of it, +and it becomes empty. + + .. _dom-characterdata-objects: CharacterData Objects ^^^^^^^^^^^^^^^^^^^^^ +.. class:: CharacterData + :no-typesetting: + :class:`CharacterData` represents text-like data in the XML document. It is a subclass of :class:`Node`, and the base class of :class:`Text`, :class:`CDATASection` and :class:`Comment`. @@ -904,6 +990,9 @@ Such nodes cannot have child nodes. Comment Objects ^^^^^^^^^^^^^^^ +.. class:: Comment + :no-typesetting: + :class:`Comment` represents a comment in the XML document. It is a subclass of :class:`CharacterData`. @@ -920,6 +1009,12 @@ It is a subclass of :class:`CharacterData`. Text and CDATASection Objects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. class:: Text + :no-typesetting: + +.. class:: CDATASection + :no-typesetting: + The :class:`Text` interface represents text in the XML document. If the parser and DOM implementation support the DOM's XML extension, portions of the text enclosed in CDATA marked sections are stored in :class:`CDATASection` objects. @@ -968,6 +1063,9 @@ These interfaces extend the :class:`CharacterData` interface. ProcessingInstruction Objects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. class:: ProcessingInstruction + :no-typesetting: + Represents a processing instruction in the XML document; this inherits from the :class:`Node` interface and cannot have child nodes. @@ -1186,9 +1284,9 @@ Mapping the IDL declarations :: readonly attribute string someValue; attribute string anotherValue; -yields three accessor functions: a "get" method for :attr:`someValue` -(:meth:`_get_someValue`), and "get" and "set" methods for :attr:`anotherValue` -(:meth:`_get_anotherValue` and :meth:`_set_anotherValue`). The mapping, in +yields three accessor functions: a "get" method for :attr:`!someValue` +(:meth:`!_get_someValue`), and "get" and "set" methods for :attr:`!anotherValue` +(:meth:`!_get_anotherValue` and :meth:`!_set_anotherValue`). The mapping, in particular, does not require that the IDL attributes are accessible as normal Python attributes: ``object.someValue`` is *not* required to work, and may raise an :exc:`AttributeError`. From 22cf80164cbf36d6e21794b5af8bacfe26a0eac6 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 12 Aug 2026 20:25:46 +0300 Subject: [PATCH 03/11] gh-155631: Document the DOM constants and fix references to members The node type constants and the exception code constants were referenced, but never documented. Document them, including ENTITY_REFERENCE_NODE, DOCUMENT_FRAGMENT_NODE and VALIDATION_ERR, which were not even mentioned, and the ValidationErr exception. Qualify references to attributes and methods with the class which defines them, so that they resolve, and refer to xml.dom.minidom for unlink(), which is not part of the DOM. --- Doc/library/xml.dom.rst | 168 +++++++++++++++++++++++----------------- 1 file changed, 98 insertions(+), 70 deletions(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index 6ecb635e40c2b9..068978d6b7449e 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -100,8 +100,8 @@ The :mod:`!xml.dom` contains the following functions: If name is not given, this examines the available implementations to find one with the required feature set. If no implementation can be found, raise an :exc:`ImportError`. The features list must be a sequence of ``(feature, - version)`` pairs which are passed to the :meth:`hasFeature` method on available - :class:`DOMImplementation` objects. + version)`` pairs which are passed to the :meth:`~DOMImplementation.hasFeature` + method on available :class:`DOMImplementation` objects. Some convenience constants are also provided: @@ -109,8 +109,8 @@ Some convenience constants are also provided: .. data:: EMPTY_NAMESPACE The value used to indicate that no namespace is associated with a node in the - DOM. This is typically found as the :attr:`namespaceURI` of a node, or used as - the *namespaceURI* parameter to a namespaces-specific method. + DOM. This is typically found as the :attr:`~Node.namespaceURI` of a node, or + used as the *namespaceURI* parameter to a namespaces-specific method. .. data:: XML_NAMESPACE @@ -137,7 +137,7 @@ exception classes. The :class:`Node` class provided by this module does not implement any of the methods or attributes defined by the DOM specification; concrete DOM implementations must provide those. The :class:`Node` class provided as part of this module does provide the constants used for the -:attr:`nodeType` attribute on concrete :class:`Node` objects; they are located +:attr:`~Node.nodeType` attribute on concrete :class:`Node` objects; they are located within the class rather than at the module level to conform with the DOM specifications. @@ -245,13 +245,27 @@ All of the components of an XML document are subclasses of :class:`Node`. .. attribute:: Node.nodeType An integer representing the node type. Symbolic constants for the types are on - the :class:`Node` object: :const:`ELEMENT_NODE`, :const:`ATTRIBUTE_NODE`, - :const:`TEXT_NODE`, :const:`CDATA_SECTION_NODE`, :const:`ENTITY_NODE`, - :const:`PROCESSING_INSTRUCTION_NODE`, :const:`COMMENT_NODE`, - :const:`DOCUMENT_NODE`, :const:`DOCUMENT_TYPE_NODE`, :const:`NOTATION_NODE`. + the :class:`Node` object. This is a read-only attribute. +.. data:: Node.ELEMENT_NODE + Node.ATTRIBUTE_NODE + Node.TEXT_NODE + Node.CDATA_SECTION_NODE + Node.ENTITY_REFERENCE_NODE + Node.ENTITY_NODE + Node.PROCESSING_INSTRUCTION_NODE + Node.COMMENT_NODE + Node.DOCUMENT_NODE + Node.DOCUMENT_TYPE_NODE + Node.DOCUMENT_FRAGMENT_NODE + Node.NOTATION_NODE + + Integer constants for the possible values + of the :attr:`~Node.nodeType` attribute. + + .. attribute:: Node.parentNode The parent of the current node, or ``None`` for the document node. The value is @@ -304,14 +318,14 @@ All of the components of an XML document are subclasses of :class:`Node`. .. attribute:: Node.localName - The part of the :attr:`tagName` following the colon if there is one, else the - entire :attr:`tagName`. The value is a string. + The part of the :attr:`~Element.tagName` following the colon if there is one, + else the entire :attr:`~Element.tagName`. The value is a string. .. attribute:: Node.prefix - The part of the :attr:`tagName` preceding the colon if there is one, else the - empty string. The value is a string, or ``None``. + The part of the :attr:`~Element.tagName` preceding the colon if there is one, + else the empty string. The value is a string, or ``None``. .. attribute:: Node.namespaceURI @@ -352,9 +366,10 @@ All of the components of an XML document are subclasses of :class:`Node`. This has a different meaning for each node type; see the DOM specification for details. You can always get the information you would get here from another - property such as the :attr:`tagName` property for elements or the :attr:`name` - property for attributes. For all node types, the value of this attribute will be - either a string or ``None``. This is a read-only attribute. + property such as the :attr:`~Element.tagName` property for elements or the + :attr:`~Attr.name` property for attributes. For all node types, the value of + this attribute will be either a string or ``None``. + This is a read-only attribute. .. attribute:: Node.nodeValue @@ -407,7 +422,8 @@ All of the components of an XML document are subclasses of :class:`Node`. Remove a child node. *oldChild* must be a child of this node; if not, :exc:`ValueError` is raised. *oldChild* is returned on success. If *oldChild* - will not be used further, its :meth:`unlink` method should be called. + will not be used further, its :meth:`~xml.dom.minidom.Node.unlink` method + should be called. .. method:: Node.replaceChild(newChild, oldChild) @@ -439,9 +455,9 @@ NodeList Objects A :class:`NodeList` represents a sequence of nodes. These objects are used in two ways in the DOM Core recommendation: an :class:`Element` object provides -one as its list of child nodes, and the :meth:`getElementsByTagName` and -:meth:`getElementsByTagNameNS` methods of :class:`Node` return objects with this -interface to represent query results. +one as its list of child nodes, and the :meth:`~Element.getElementsByTagName` +and :meth:`~Element.getElementsByTagNameNS` methods of :class:`Node` return +objects with this interface to represent query results. The DOM Level 2 recommendation defines one method and one attribute for these objects: @@ -482,9 +498,9 @@ DocumentType Objects Information about the notations and entities declared by a document (including the external subset if the parser uses it and can provide the information) is available from a :class:`DocumentType` object. The :class:`DocumentType` for a -document is available from the :class:`Document` object's :attr:`doctype` +document is available from the :class:`Document` object's :attr:`~Document.doctype` attribute; if there is no ``DOCTYPE`` declaration for the document, the -document's :attr:`doctype` attribute will be set to ``None`` instead of an +document's :attr:`~Document.doctype` attribute will be set to ``None`` instead of an instance of this interface. :class:`DocumentType` is a specialization of :class:`Node`, and adds the @@ -596,7 +612,7 @@ inherits properties from :class:`Node`. Create and return a new element node. The element is not inserted into the document when it is created. You need to explicitly insert it with one of the - other methods such as :meth:`insertBefore` or :meth:`appendChild`. + other methods such as :meth:`~Node.insertBefore` or :meth:`~Node.appendChild`. .. method:: Document.createElementNS(namespaceURI, tagName) @@ -604,7 +620,7 @@ inherits properties from :class:`Node`. Create and return a new element with a namespace. The *tagName* may have a prefix. The element is not inserted into the document when it is created. You need to explicitly insert it with one of the other methods such as - :meth:`insertBefore` or :meth:`appendChild`. + :meth:`~Node.insertBefore` or :meth:`~Node.appendChild`. .. method:: Document.createTextNode(data) @@ -632,15 +648,15 @@ inherits properties from :class:`Node`. Create and return an attribute node. This method does not associate the attribute node with any particular element. You must use - :meth:`setAttributeNode` on the appropriate :class:`Element` object to use the - newly created attribute instance. + :meth:`~Element.setAttributeNode` on the appropriate :class:`Element` object + to use the newly created attribute instance. .. method:: Document.createAttributeNS(namespaceURI, qualifiedName) Create and return an attribute node with a namespace. The *tagName* may have a prefix. This method does not associate the attribute node with any particular - element. You must use :meth:`setAttributeNode` on the appropriate + element. You must use :meth:`~Element.setAttributeNode` on the appropriate :class:`Element` object to use the newly created attribute instance. @@ -783,17 +799,18 @@ of that class. .. method:: Element.setAttributeNode(newAttr) Add a new attribute node to the element, replacing an existing attribute if - necessary if the :attr:`name` attribute matches. If a replacement occurs, the - old attribute node will be returned. If *newAttr* is already in use, + necessary if the :attr:`~Attr.name` attribute matches. If a replacement + occurs, the old attribute node will be returned. If *newAttr* is already in use, :exc:`InuseAttributeErr` will be raised. .. method:: Element.setAttributeNodeNS(newAttr) Add a new attribute node to the element, replacing an existing attribute if - necessary if the :attr:`namespaceURI` and :attr:`localName` attributes match. - If a replacement occurs, the old attribute node will be returned. If *newAttr* - is already in use, :exc:`InuseAttributeErr` will be raised. + necessary if the :attr:`~Node.namespaceURI` and :attr:`~Attr.localName` + attributes match. If a replacement occurs, the old attribute node will be + returned. If *newAttr* is already in use, :exc:`InuseAttributeErr` will be + raised. .. method:: Element.setAttributeNS(namespaceURI, qname, value) @@ -850,7 +867,7 @@ Attr Objects .. attribute:: Attr.value The text value of the attribute. This is a synonym for the - :attr:`nodeValue` attribute. + :attr:`~Node.nodeValue` attribute. .. _dom-attributelist-objects: @@ -873,7 +890,7 @@ NamedNodeMap Objects Return an attribute with a particular index. The order you get the attributes in is arbitrary but will be consistent for the life of a DOM. Each item is an - attribute node. Get its value with the :attr:`value` attribute. + attribute node. Get its value with the :attr:`~Attr.value` attribute. .. method:: NamedNodeMap.getNamedItem(name) @@ -1019,7 +1036,7 @@ The :class:`Text` interface represents text in the XML document. If the parser and DOM implementation support the DOM's XML extension, portions of the text enclosed in CDATA marked sections are stored in :class:`CDATASection` objects. These two interfaces are identical, but provide different values for the -:attr:`nodeType` attribute. +:attr:`~Node.nodeType` attribute. These interfaces extend the :class:`CharacterData` interface. @@ -1194,48 +1211,59 @@ attribute. .. XXX how is this different from InvalidCharacterErr? +.. exception:: ValidationErr + + Raised when an operation would make the document invalid + with respect to partial validity. + This is not known to be used in the Python DOM implementations, + but may be received from DOM implementations not written in Python. + + .. exception:: WrongDocumentErr Raised when a node is inserted in a different document than it currently belongs to, and the implementation does not support migrating the node from one document to the other. + The exception codes defined in the DOM recommendation map to the exceptions described above according to this table: -+--------------------------------------+---------------------------------+ -| Constant | Exception | -+======================================+=================================+ -| :const:`DOMSTRING_SIZE_ERR` | :exc:`DomstringSizeErr` | -+--------------------------------------+---------------------------------+ -| :const:`HIERARCHY_REQUEST_ERR` | :exc:`HierarchyRequestErr` | -+--------------------------------------+---------------------------------+ -| :const:`INDEX_SIZE_ERR` | :exc:`IndexSizeErr` | -+--------------------------------------+---------------------------------+ -| :const:`INUSE_ATTRIBUTE_ERR` | :exc:`InuseAttributeErr` | -+--------------------------------------+---------------------------------+ -| :const:`INVALID_ACCESS_ERR` | :exc:`InvalidAccessErr` | -+--------------------------------------+---------------------------------+ -| :const:`INVALID_CHARACTER_ERR` | :exc:`InvalidCharacterErr` | -+--------------------------------------+---------------------------------+ -| :const:`INVALID_MODIFICATION_ERR` | :exc:`InvalidModificationErr` | -+--------------------------------------+---------------------------------+ -| :const:`INVALID_STATE_ERR` | :exc:`InvalidStateErr` | -+--------------------------------------+---------------------------------+ -| :const:`NAMESPACE_ERR` | :exc:`NamespaceErr` | -+--------------------------------------+---------------------------------+ -| :const:`NOT_FOUND_ERR` | :exc:`NotFoundErr` | -+--------------------------------------+---------------------------------+ -| :const:`NOT_SUPPORTED_ERR` | :exc:`NotSupportedErr` | -+--------------------------------------+---------------------------------+ -| :const:`NO_DATA_ALLOWED_ERR` | :exc:`NoDataAllowedErr` | -+--------------------------------------+---------------------------------+ -| :const:`NO_MODIFICATION_ALLOWED_ERR` | :exc:`NoModificationAllowedErr` | -+--------------------------------------+---------------------------------+ -| :const:`SYNTAX_ERR` | :exc:`SyntaxErr` | -+--------------------------------------+---------------------------------+ -| :const:`WRONG_DOCUMENT_ERR` | :exc:`WrongDocumentErr` | -+--------------------------------------+---------------------------------+ ++---------------------------------------+---------------------------------+ +| Constant | Exception | ++=======================================+=================================+ +| .. data:: DOMSTRING_SIZE_ERR | :exc:`DomstringSizeErr` | ++---------------------------------------+---------------------------------+ +| .. data:: HIERARCHY_REQUEST_ERR | :exc:`HierarchyRequestErr` | ++---------------------------------------+---------------------------------+ +| .. data:: INDEX_SIZE_ERR | :exc:`IndexSizeErr` | ++---------------------------------------+---------------------------------+ +| .. data:: INUSE_ATTRIBUTE_ERR | :exc:`InuseAttributeErr` | ++---------------------------------------+---------------------------------+ +| .. data:: INVALID_ACCESS_ERR | :exc:`InvalidAccessErr` | ++---------------------------------------+---------------------------------+ +| .. data:: INVALID_CHARACTER_ERR | :exc:`InvalidCharacterErr` | ++---------------------------------------+---------------------------------+ +| .. data:: INVALID_MODIFICATION_ERR | :exc:`InvalidModificationErr` | ++---------------------------------------+---------------------------------+ +| .. data:: INVALID_STATE_ERR | :exc:`InvalidStateErr` | ++---------------------------------------+---------------------------------+ +| .. data:: NAMESPACE_ERR | :exc:`NamespaceErr` | ++---------------------------------------+---------------------------------+ +| .. data:: NOT_FOUND_ERR | :exc:`NotFoundErr` | ++---------------------------------------+---------------------------------+ +| .. data:: NOT_SUPPORTED_ERR | :exc:`NotSupportedErr` | ++---------------------------------------+---------------------------------+ +| .. data:: NO_DATA_ALLOWED_ERR | :exc:`NoDataAllowedErr` | ++---------------------------------------+---------------------------------+ +| .. data:: NO_MODIFICATION_ALLOWED_ERR | :exc:`NoModificationAllowedErr` | ++---------------------------------------+---------------------------------+ +| .. data:: SYNTAX_ERR | :exc:`SyntaxErr` | ++---------------------------------------+---------------------------------+ +| .. data:: VALIDATION_ERR | :exc:`ValidationErr` | ++---------------------------------------+---------------------------------+ +| .. data:: WRONG_DOCUMENT_ERR | :exc:`WrongDocumentErr` | ++---------------------------------------+---------------------------------+ .. _dom-conformance: @@ -1307,6 +1335,6 @@ considered unnecessary since the attributes are accessible directly from Python. The IDL definitions do not fully embody the requirements of the W3C DOM API, such as the notion of certain objects, such as the return value of -:meth:`getElementsByTagName`, being "live". The Python DOM API does not require -implementations to enforce such requirements. +:meth:`~Element.getElementsByTagName`, being "live". The Python DOM API does +not require implementations to enforce such requirements. From cef4943d6150da017d7bf73f76f1aa67b0e3cdba Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 12 Aug 2026 20:37:32 +0300 Subject: [PATCH 04/11] gh-155631: Remove xml.dom.rst from the nit-picky mode exceptions It no longer produces warnings in the Sphinx nit-picky mode. --- Doc/tools/.nitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 976cc3b2a5282d..4e7ec83723b344 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -24,7 +24,6 @@ Doc/library/urllib.request.rst Doc/library/wsgiref.rst Doc/library/xml.dom.minidom.rst Doc/library/xml.dom.pulldom.rst -Doc/library/xml.dom.rst Doc/library/xml.sax.reader.rst Doc/library/xml.sax.rst Doc/library/xmlrpc.client.rst From 9e9461450aa9c5af0ef583bc37c8a4e3c616892c Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 12 Aug 2026 20:51:42 +0300 Subject: [PATCH 05/11] gh-155631: Document the Entity and Notation interfaces and Attr.specified Entity and Notation were not mentioned at all, although they are implemented and DocumentType.entities and DocumentType.notations contain such nodes. --- Doc/library/xml.dom.rst | 78 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 76 insertions(+), 2 deletions(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index 068978d6b7449e..71b4527210b4b8 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -534,7 +534,8 @@ following attributes: .. attribute:: DocumentType.entities - This is a :class:`NamedNodeMap` giving the definitions of external entities. + This is a :class:`NamedNodeMap` of :class:`Entity` nodes + giving the definitions of external entities. For entity names defined more than once, only the first definition is provided (others are ignored as required by the XML recommendation). This may be ``None`` if the information is not provided by the parser, or if no entities are @@ -543,7 +544,8 @@ following attributes: .. attribute:: DocumentType.notations - This is a :class:`NamedNodeMap` giving the definitions of notations. For + This is a :class:`NamedNodeMap` of :class:`Notation` nodes + giving the definitions of notations. For notation names defined more than once, only the first definition is provided (others are ignored as required by the XML recommendation). This may be ``None`` if the information is not provided by the parser, or if no notations @@ -864,6 +866,14 @@ Attr Objects This is a read-only attribute. +.. attribute:: Attr.specified + + Whether the value of the attribute was explicitly set in the document, + as opposed to being defaulted from the DTD. + Always ``False`` in :mod:`xml.dom.minidom`. + This is a read-only attribute. + + .. attribute:: Attr.value The text value of the attribute. This is a synonym for the @@ -1099,6 +1109,70 @@ Represents a processing instruction in the XML document; this inherits from the character. +.. _dom-entity-objects: + +Entity Objects +^^^^^^^^^^^^^^ + +.. class:: Entity + :no-typesetting: + +:class:`Entity` represents a parsed or unparsed entity declared in the DTD. +It is a subclass of :class:`Node`. +Entity nodes are contained in :attr:`DocumentType.entities` +and cannot be inserted into the document tree. +The name of the entity is its :attr:`~Node.nodeName`. + + +.. attribute:: Entity.publicId + + The public identifier of the entity, + or ``None`` if it is not specified. + This is a read-only attribute. + + +.. attribute:: Entity.systemId + + The system identifier of the entity. + This is a read-only attribute. + + +.. attribute:: Entity.notationName + + The name of the notation for an unparsed entity, + or ``None`` for a parsed entity. + This is a read-only attribute. + + +.. _dom-notation-objects: + +Notation Objects +^^^^^^^^^^^^^^^^ + +.. class:: Notation + :no-typesetting: + +:class:`Notation` represents a notation declared in the DTD. +It is a subclass of :class:`Node` and cannot have child nodes. +Notation nodes are contained in :attr:`DocumentType.notations` +and cannot be inserted into the document tree. +The name of the notation is its :attr:`~Node.nodeName`. + + +.. attribute:: Notation.publicId + + The public identifier of the notation, + or ``None`` if it is not specified. + This is a read-only attribute. + + +.. attribute:: Notation.systemId + + The system identifier of the notation, + or ``None`` if it is not specified. + This is a read-only attribute. + + .. _dom-exceptions: Exceptions From af7e732604e5decc7ea8757ec67ba60fd748860b Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 28 Aug 2026 09:27:34 +0300 Subject: [PATCH 06/11] Apply batched suggestions from code review Co-authored-by: dgelessus --- Doc/library/xml.dom.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index 71b4527210b4b8..17ee2380e0cf99 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -690,7 +690,7 @@ inherits properties from :class:`Node`. :data:`~xml.dom.EMPTY_NAMESPACE` if the node does not belong to a namespace. *name* is the new qualified name. - Raise :exc:`WrongDocumentErr` if *n* was created by other document, + Raise :exc:`WrongDocumentErr` if *n* was created by another document, and :exc:`NotSupportedErr` if it is neither an element nor an attribute. @@ -1133,7 +1133,8 @@ The name of the entity is its :attr:`~Node.nodeName`. .. attribute:: Entity.systemId - The system identifier of the entity. + The system identifier of the entity, + or ``None`` if it is not specified. This is a read-only attribute. From 28dcdeee41d03de81ef65c50afd2d452373877f9 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 28 Aug 2026 09:31:29 +0300 Subject: [PATCH 07/11] gh-151943: Fix the documentation of CDATASection, NodeList and Attr CDATASection extends Text, as in the DOM Level 1 and Level 2 IDL. NodeList.item() returns None for an index out of range, it does not forbid such index. Attribute nodes are not part of the document tree. --- Doc/library/xml.dom.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index 17ee2380e0cf99..d25e3f7403f1ec 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -465,9 +465,9 @@ objects: .. method:: NodeList.item(i) - Return the *i*'th item from the sequence, if there is one, or ``None``. The - index *i* is not allowed to be less than zero or greater than or equal to the - length of the sequence. + Return the *i*'th item from the sequence, + or ``None`` if *i* is out of range. + Negative indices are not supported. .. attribute:: NodeList.length @@ -831,6 +831,12 @@ Attr Objects :class:`Attr` inherits from :class:`Node`, so inherits all its attributes. +Attribute nodes are not part of the document tree. +They are contained in the :attr:`~Node.attributes` map of an element, +not in its children, +and their :attr:`~Node.parentNode`, :attr:`~Node.previousSibling` +and :attr:`~Node.nextSibling` are always ``None``. + .. attribute:: Attr.name @@ -1048,7 +1054,8 @@ enclosed in CDATA marked sections are stored in :class:`CDATASection` objects. These two interfaces are identical, but provide different values for the :attr:`~Node.nodeType` attribute. -These interfaces extend the :class:`CharacterData` interface. +:class:`Text` extends the :class:`CharacterData` interface, +and :class:`CDATASection` extends :class:`Text`. .. attribute:: Text.data From e48c25e2becb7637f8e5d05adbcf7c9d814a4fc3 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 28 Aug 2026 09:55:00 +0300 Subject: [PATCH 08/11] gh-151943: Document more details of the DOM interfaces Reported in gh-156388: * which node types can have children, and of which types; * the values of nodeName and nodeValue for every node type; * childNodes is a NodeList; * NodeList does not inherit from Node; * when DocumentType.publicId and systemId are None; * "minidom" is the only well-known implementation name; * which mapping methods minidom adds to a NamedNodeMap, and where they are not available. --- Doc/library/xml.dom.rst | 87 +++++++++++++++++++++++++++++++++-------- 1 file changed, 71 insertions(+), 16 deletions(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index d25e3f7403f1ec..d27eac943ae2ab 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -96,6 +96,8 @@ The :mod:`!xml.dom` contains the following functions: the corresponding module and returns a :class:`DOMImplementation` object if the import succeeds. If no name is given, and if the environment variable :envvar:`!PYTHON_DOM` is set, this variable is used to find the implementation. + The only well-known name in the standard library is ``'minidom'``, + for :mod:`xml.dom.minidom`. If name is not given, this examines the available implementations to find one with the required feature set. If no implementation can be found, raise an @@ -241,6 +243,23 @@ Node Objects All of the components of an XML document are subclasses of :class:`Node`. +Only nodes of the following types can have children, +and only children of the listed types: + +:class:`Document` + at most one :class:`Element`, at most one :class:`DocumentType`, + :class:`ProcessingInstruction` and :class:`Comment` + +:class:`DocumentFragment` and :class:`Element` + :class:`Element`, :class:`Text`, :class:`CDATASection`, + :class:`ProcessingInstruction` and :class:`Comment` + +:class:`Attr` + :class:`Text` + +Nodes of other types cannot have children. +Inserting a child of a not allowed type raises :exc:`HierarchyRequestErr`. + .. attribute:: Node.nodeType @@ -301,7 +320,9 @@ All of the components of an XML document are subclasses of :class:`Node`. .. attribute:: Node.childNodes - A list of nodes contained within this node. This is a read-only attribute. + A :class:`NodeList` of the children of this node. + If the node has no children, the list is empty. + This is a read-only attribute. .. attribute:: Node.firstChild @@ -364,20 +385,48 @@ All of the components of an XML document are subclasses of :class:`Node`. .. attribute:: Node.nodeName - This has a different meaning for each node type; see the DOM specification for - details. You can always get the information you would get here from another + The name of this node, depending on its type; see the table below. + You can always get the information you would get here from another property such as the :attr:`~Element.tagName` property for elements or the - :attr:`~Attr.name` property for attributes. For all node types, the value of - this attribute will be either a string or ``None``. + :attr:`~Attr.name` property for attributes. + For all node types, the value of this attribute is a string or ``None``. This is a read-only attribute. .. attribute:: Node.nodeValue - This has a different meaning for each node type; see the DOM specification for - details. The situation is similar to that with :attr:`nodeName`. The value is - a string or ``None``. - + The value of this node, depending on its type; see the table below. + The value is a string or ``None``. + + +The values of :attr:`~Node.nodeName` and :attr:`~Node.nodeValue` +for each node type are: + ++--------------------------------+---------------------------------------+-------------------------------------+ +| Node type | nodeName | nodeValue | ++================================+=======================================+=====================================+ +| :class:`Attr` | :attr:`~Attr.name` | :attr:`~Attr.value` | ++--------------------------------+---------------------------------------+-------------------------------------+ +| :class:`CDATASection` | ``'#cdata-section'`` | the content | ++--------------------------------+---------------------------------------+-------------------------------------+ +| :class:`Comment` | ``'#comment'`` | the content | ++--------------------------------+---------------------------------------+-------------------------------------+ +| :class:`Document` | ``'#document'`` | ``None`` | ++--------------------------------+---------------------------------------+-------------------------------------+ +| :class:`DocumentFragment` | ``'#document-fragment'`` | ``None`` | ++--------------------------------+---------------------------------------+-------------------------------------+ +| :class:`DocumentType` | :attr:`~DocumentType.name` | ``None`` | ++--------------------------------+---------------------------------------+-------------------------------------+ +| :class:`Element` | :attr:`~Element.tagName` | ``None`` | ++--------------------------------+---------------------------------------+-------------------------------------+ +| :class:`Entity` | the name of the entity | ``None`` | ++--------------------------------+---------------------------------------+-------------------------------------+ +| :class:`Notation` | the name of the notation | ``None`` | ++--------------------------------+---------------------------------------+-------------------------------------+ +| :class:`ProcessingInstruction` | :attr:`~ProcessingInstruction.target` | :attr:`~ProcessingInstruction.data` | ++--------------------------------+---------------------------------------+-------------------------------------+ +| :class:`Text` | ``'#text'`` | the content | ++--------------------------------+---------------------------------------+-------------------------------------+ .. method:: Node.hasAttributes() @@ -459,6 +508,8 @@ one as its list of child nodes, and the :meth:`~Element.getElementsByTagName` and :meth:`~Element.getElementsByTagNameNS` methods of :class:`Node` return objects with this interface to represent query results. +:class:`NodeList` does *not* inherit from :class:`Node`. + The DOM Level 2 recommendation defines one method and one attribute for these objects: @@ -509,14 +560,14 @@ following attributes: .. attribute:: DocumentType.publicId - The public identifier for the external subset of the document type definition. - This will be a string or ``None``. + The public identifier for the external subset of the document type definition, + or ``None`` if the ``DOCTYPE`` declaration does not specify it. .. attribute:: DocumentType.systemId - The system identifier for the external subset of the document type definition. - This will be a URI as a string, or ``None``. + The system identifier, a URI, for the external subset of the document type + definition, or ``None`` if the ``DOCTYPE`` declaration does not specify it. .. attribute:: DocumentType.internalSubset @@ -945,9 +996,13 @@ NamedNodeMap Objects Remove and return the node with the given namespace URI and local name. Raise :exc:`NotFoundErr` if there is no such node. -There are also experimental methods that give this class more mapping behavior. -You can use them or you can use the standardized :meth:`!getAttribute\*` family -of methods on the :class:`Element` objects. +:mod:`xml.dom.minidom` provides additional methods which make the attribute +map of an element behave more like a mapping: :meth:`!get`, :meth:`!keys`, +:meth:`!keysNS`, :meth:`!values`, :meth:`!items` and :meth:`!itemsNS`, as well +as ``len()``, ``in``, subscription and deletion. They are not available for +:attr:`DocumentType.entities` and :attr:`DocumentType.notations`, which are +read-only. You can also use the standardized :meth:`!getAttribute\*` family of +methods on the :class:`Element` objects. .. _dom-documentfragment-objects: From d67e631851a0502ee097584ace31358533a5794d Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 28 Aug 2026 10:36:21 +0300 Subject: [PATCH 09/11] gh-151943: Clarify how minidom implements NodeList It is a list subclass, not a replacement for NodeList, and nodes which cannot have children use a tuple subclass. Remove the note about earlier versions of Python which did not support the official API. --- Doc/library/xml.dom.minidom.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst index 1a5291d018ac70..8134aa3c8dd155 100644 --- a/Doc/library/xml.dom.minidom.rst +++ b/Doc/library/xml.dom.minidom.rst @@ -245,11 +245,12 @@ rules apply: Instead, :mod:`!xml.dom.minidom` uses standard Python exceptions such as :exc:`TypeError` and :exc:`AttributeError`. -* :class:`NodeList` objects are implemented using Python's built-in list type. - These objects provide the interface defined in the DOM specification, but with - earlier versions of Python they do not support the official API. They are, - however, much more "Pythonic" than the interface defined in the W3C - recommendations. +* The :mod:`!xml.dom.minidom` implementation of :class:`~xml.dom.NodeList` + is a subclass of :class:`list`. + In addition to the interface defined in the DOM specification, + it supports all list operations, which are much more "Pythonic". + Nodes which cannot have children use another implementation, + which is a subclass of :class:`tuple`. The following interfaces have no implementation in :mod:`!xml.dom.minidom`: From 7fa7f46b9f56b94554371a0df4ef44cf3af0c427 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 28 Aug 2026 10:45:35 +0300 Subject: [PATCH 10/11] gh-151943: Do not claim that nodeName can be None The table above gives the value for every node type, and none of them is None. --- Doc/library/xml.dom.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index d27eac943ae2ab..72389e26de6d3f 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -389,7 +389,6 @@ Inserting a child of a not allowed type raises :exc:`HierarchyRequestErr`. You can always get the information you would get here from another property such as the :attr:`~Element.tagName` property for elements or the :attr:`~Attr.name` property for attributes. - For all node types, the value of this attribute is a string or ``None``. This is a read-only attribute. From b92b565c66bdd0d981d6f5e952ed38662b4830ed Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 28 Aug 2026 11:38:39 +0300 Subject: [PATCH 11/11] gh-151943: Document minidom specific differences in the minidom docs Each of the NodeList and NamedNodeMap interfaces has two implementations in minidom, which support additional operations. Move this and the notes about strictErrorChecking and Attr.specified out of the documentation of the generic DOM interface. --- Doc/library/xml.dom.minidom.rst | 24 ++++++++++++++++++------ Doc/library/xml.dom.rst | 11 ++--------- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst index 8134aa3c8dd155..dcde403ee27dea 100644 --- a/Doc/library/xml.dom.minidom.rst +++ b/Doc/library/xml.dom.minidom.rst @@ -245,12 +245,24 @@ rules apply: Instead, :mod:`!xml.dom.minidom` uses standard Python exceptions such as :exc:`TypeError` and :exc:`AttributeError`. -* The :mod:`!xml.dom.minidom` implementation of :class:`~xml.dom.NodeList` - is a subclass of :class:`list`. - In addition to the interface defined in the DOM specification, - it supports all list operations, which are much more "Pythonic". - Nodes which cannot have children use another implementation, - which is a subclass of :class:`tuple`. +* Each of the :class:`~xml.dom.NodeList` and :class:`~xml.dom.NamedNodeMap` + interfaces has two implementations, which provide additional methods and + operations. + + :attr:`~xml.dom.Node.childNodes` is a subclass of :class:`list`, or, for + nodes which cannot have children, a subclass of :class:`tuple`. + It supports iteration, concatenation, indexing and slicing. + + :attr:`~xml.dom.Node.attributes` supports ``len()``, the :keyword:`in` + operator, subscription by a name or by a ``(namespaceURI, localName)`` + tuple, assignment and deletion, and the methods :meth:`!get`, :meth:`!keys`, + :meth:`!keysNS`, :meth:`!values`, :meth:`!items` and :meth:`!itemsNS`. + :attr:`~xml.dom.DocumentType.entities` and + :attr:`~xml.dom.DocumentType.notations` are read-only and support only + ``len()`` and subscription by a name. + +* :attr:`~xml.dom.Document.strictErrorChecking` and + :attr:`~xml.dom.Attr.specified` are always ``False``. The following interfaces have no implementation in :mod:`!xml.dom.minidom`: diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index 72389e26de6d3f..81e58cff321a47 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -635,7 +635,6 @@ inherits properties from :class:`Node`. .. attribute:: Document.strictErrorChecking Whether error checking is enforced. - Always ``False`` in :mod:`xml.dom.minidom`. .. attribute:: Document.documentURI @@ -926,7 +925,6 @@ and :attr:`~Node.nextSibling` are always ``None``. Whether the value of the attribute was explicitly set in the document, as opposed to being defaulted from the DTD. - Always ``False`` in :mod:`xml.dom.minidom`. This is a read-only attribute. @@ -995,13 +993,8 @@ NamedNodeMap Objects Remove and return the node with the given namespace URI and local name. Raise :exc:`NotFoundErr` if there is no such node. -:mod:`xml.dom.minidom` provides additional methods which make the attribute -map of an element behave more like a mapping: :meth:`!get`, :meth:`!keys`, -:meth:`!keysNS`, :meth:`!values`, :meth:`!items` and :meth:`!itemsNS`, as well -as ``len()``, ``in``, subscription and deletion. They are not available for -:attr:`DocumentType.entities` and :attr:`DocumentType.notations`, which are -read-only. You can also use the standardized :meth:`!getAttribute\*` family of -methods on the :class:`Element` objects. +You can also use the standardized :meth:`!getAttribute\*` family of methods +on the :class:`Element` objects. .. _dom-documentfragment-objects: