From dcbb0fbc7fd892b70a4bdc9d67dc7af398bad3ed Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 12 Aug 2026 18:29:30 +0300 Subject: [PATCH 1/5] 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 2/5] 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 3/5] 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 4/5] 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 5/5] 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