gh-151943: Document the CharacterData interface and other DOM members (GH-155632)
CharacterData was not mentioned at all, although Text, Comment and
CDATASection inherit from it. Document also DocumentFragment, Entity
and Notation, many implemented members which were omitted, the node type
constants and the exception code constants.
Add class directives for all documented interfaces, so that references
to them resolve, and remove xml.dom.rst from the nit-picky mode
exceptions.
Fix incorrect statements about nodeName, NodeList.item(), CDATASection
and attribute nodes, and describe minidom specific differences in the
minidom documentation.
diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst
index 1a5291d..dcde403 100644
--- a/Doc/library/xml.dom.minidom.rst
+++ b/Doc/library/xml.dom.minidom.rst
@@ -245,11 +245,24 @@
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.
+* 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 34e58dc..81e58cf 100644
--- a/Doc/library/xml.dom.rst
+++ b/Doc/library/xml.dom.rst
@@ -95,13 +95,15 @@
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.
+ 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
: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 +111,8 @@
.. 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 +139,7 @@
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.
@@ -199,6 +201,9 @@
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,19 +238,53 @@
Node Objects
^^^^^^^^^^^^
+.. class:: Node
+ :no-typesetting:
+
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
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
@@ -281,7 +320,9 @@
.. 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
@@ -298,14 +339,14 @@
.. 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
@@ -314,22 +355,78 @@
``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
- 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.
+ 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.
+ 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()
Return ``True`` if the node has any attributes.
@@ -373,7 +470,8 @@
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)
@@ -400,11 +498,16 @@
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
-: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.
+
+:class:`NodeList` does *not* inherit from :class:`Node`.
The DOM Level 2 recommendation defines one method and one attribute for these
objects:
@@ -412,9 +515,9 @@
.. 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
@@ -439,12 +542,15 @@
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
-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
@@ -453,14 +559,14 @@
.. 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
@@ -478,7 +584,8 @@
.. 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
@@ -487,7 +594,8 @@
.. 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
@@ -499,6 +607,9 @@
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`.
@@ -509,11 +620,50 @@
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.
+
+
+.. 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
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)
@@ -521,7 +671,7 @@
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)
@@ -549,18 +699,25 @@
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.
+.. 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
@@ -574,11 +731,26 @@
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 another document,
+ and :exc:`NotSupportedErr` if it is neither an element nor an attribute.
+
+
.. _dom-element-objects:
Element Objects
^^^^^^^^^^^^^^^
+.. class:: Element
+ :no-typesetting:
+
:class:`Element` is a subclass of :class:`Node`, so inherits all the attributes
of that class.
@@ -589,6 +761,25 @@
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.
@@ -659,17 +850,18 @@
.. 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)
@@ -683,8 +875,17 @@
Attr Objects
^^^^^^^^^^^^
+.. class:: Attr
+ :no-typesetting:
+
: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
@@ -705,10 +906,32 @@
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.specified
+
+ Whether the value of the attribute was explicitly set in the document,
+ as opposed to being defaulted from the DTD.
+ This is a read-only attribute.
+
+
.. 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:
@@ -716,6 +939,9 @@
NamedNodeMap Objects
^^^^^^^^^^^^^^^^^^^^
+.. class:: NamedNodeMap
+ :no-typesetting:
+
:class:`NamedNodeMap` does *not* inherit from :class:`Node`.
@@ -728,11 +954,115 @@
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.
-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.
+
+.. 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.
+
+You can also 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`.
+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:
@@ -740,8 +1070,11 @@
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
+ :no-typesetting:
+
+:class:`Comment` represents a comment in the XML document.
+It is a subclass of :class:`CharacterData`.
.. attribute:: Comment.data
@@ -756,20 +1089,47 @@
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.
These two interfaces are identical, but provide different values for the
-:attr:`nodeType` attribute.
+:attr:`~Node.nodeType` attribute.
-These interfaces extend the :class:`Node` interface. They cannot have child
-nodes.
+:class:`Text` extends the :class:`CharacterData` interface,
+and :class:`CDATASection` extends :class:`Text`.
.. 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
@@ -784,6 +1144,9 @@
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.
@@ -800,6 +1163,71 @@
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,
+ or ``None`` if it is not specified.
+ 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
@@ -912,48 +1340,59 @@
.. 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:
@@ -1002,9 +1441,9 @@
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`.
@@ -1025,6 +1464,6 @@
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.
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index 976cc3b..4e7ec83 100644
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -24,7 +24,6 @@
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
