GeezerVisonThe World Wide Web, restored to 800 pixels of glory. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Home|About|Gaming cabinet|Archives|How it works|Starter sites | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
GeezerVison is showing docs.python.org — xml.dom — The Document Object Model API
|
Interface |
Section |
Purpose |
|---|---|---|
Interface to the underlying implementation. |
||
Base interface for most objects in a document. |
||
Interface for a sequence of nodes. |
||
Information about the declarations needed to process a document. |
||
Object which represents an entire document. |
||
Element nodes in the document hierarchy. |
||
Attribute value nodes on element nodes. |
||
Representation of comments in the source document. |
||
Nodes containing textual content from the document. |
||
Processing instruction representation. |
An additional section describes the exceptions defined for working with the DOM in Python.
The 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 Document and
DocumentType objects using the DOMImplementation as well.
Return True if the feature identified by the pair of strings feature and
version is implemented.
Return a new Document object (the root of the DOM), with a child
Element object having the given namespaceUri and qualifiedName. The
doctype must be a DocumentType object created by
createDocumentType(), or None. In the Python DOM API, the first two
arguments can also be None in order to indicate that no Element
child is to be created.
Return a new DocumentType object that encapsulates the given
qualifiedName, publicId, and systemId strings, representing the
information contained in an XML document type declaration.
Raise InvalidCharacterErr if the name is not a valid XML name.
All of the components of an XML document are subclasses of Node.
Only nodes of the following types can have children, and only children of the listed types:
Documentat most one Element, at most one DocumentType,
ProcessingInstruction and Comment
DocumentFragment and ElementElement, Text, CDATASection,
ProcessingInstruction and Comment
AttrNodes of other types cannot have children.
Inserting a child of a not allowed type raises HierarchyRequestErr.
An integer representing the node type. Symbolic constants for the types are on
the Node object.
This is a read-only attribute.
Integer constants for the possible values
of the nodeType attribute.
The parent of the current node, or None for the document node. The value is
always a Node object or None. For Element nodes, this
will be the parent element, except for the root element, in which case it will
be the Document object. For Attr nodes, this is always
None. This is a read-only attribute.
A NamedNodeMap of attribute objects. Only elements have actual values
for this; others provide None for this attribute. This is a read-only
attribute.
The node that immediately precedes this one with the same parent. For
instance the element with an end-tag that comes just before the self
element’s start-tag. Of course, XML documents are made up of more than just
elements so the previous sibling could be text, a comment, or something else.
If this node is the first child of the parent, this attribute will be
None. This is a read-only attribute.
The node that immediately follows this one with the same parent. See also
previousSibling. If this is the last child of the parent, this
attribute will be None. This is a read-only attribute.
A NodeList of the children of this node.
If the node has no children, the list is empty.
This is a read-only attribute.
The first child of the node, if there are any, or None. This is a read-only
attribute.
The last child of the node, if there are any, or None. This is a read-only
attribute.
The part of the tagName following the colon if there is one,
else the entire tagName. The value is a string.
The part of the tagName preceding the colon if there is one,
else the empty string. The value is a string, or None.
The namespace associated with the element name. This will be a string or
None. This is a read-only attribute.
The Document object to which this node belongs, or None
for a document itself.
This is a read-only attribute.
Return whether the DOM implementation supports a particular feature,
as DOMImplementation.hasFeature() does.
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.
Return the data associated with key on this node
by setUserData(), or None.
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 tagName property for elements or the
name property for attributes.
This is a read-only attribute.
The value of this node, depending on its type; see the table below.
The value is a string or None.
The values of nodeName and nodeValue
for each node type are:
Node type |
nodeName |
nodeValue |
|---|---|---|
|
the content |
|
|
the content |
|
|
|
|
|
|
|
|
||
|
||
the name of the entity |
|
|
the name of the notation |
|
|
|
the content |
Return True if the node has any attributes.
Return True if the node has any child nodes.
Return True if other refers to the same node as this node. This is especially
useful for DOM implementations which use any sort of proxy architecture (because
more than one object can refer to the same node).
Note
This is based on a proposed DOM Level 3 API which is still in the “working draft” stage, but this particular interface appears uncontroversial. Changes from the W3C will not necessarily affect this method in the Python DOM interface (though any new W3C API for this would also be supported).
Add a new child node to this node at the end of the list of children, returning newChild. If the node was already in the tree, it is removed first.
Raise WrongDocumentErr if newChild was created by another
document, and HierarchyRequestErr if it is this node itself or
its ancestor.
Insert a new child node before an existing child. It must be the case that
refChild is a child of this node; if not, NotFoundErr is raised.
newChild is returned. If refChild is None, it inserts newChild at the
end of the children’s list.
Raise WrongDocumentErr if newChild was created by another
document, and HierarchyRequestErr if it is this node itself or
its ancestor.
Remove a child node. oldChild must be a child of this node; if not,
NotFoundErr is raised. oldChild is returned on success. If oldChild
will not be used further, its unlink() method
should be called.
Replace an existing node with a new node. It must be the case that oldChild
is a child of this node; if not, NotFoundErr is raised.
Raise WrongDocumentErr if newChild was created by another
document, and HierarchyRequestErr if it is this node itself or
its ancestor.
Join adjacent text nodes so that all stretches of text are stored as single
Text instances. This simplifies processing text from a DOM tree for
many applications.
Clone this node. Setting deep means to clone all child nodes as well. This returns the clone.
A NodeList represents a sequence of nodes. These objects are used in
two ways in the DOM Core recommendation: an Element object provides
one as its list of child nodes, and the getElementsByTagName()
and getElementsByTagNameNS() methods of Element return
objects with this interface to represent query results.
NodeList does not inherit from Node.
The DOM Level 2 recommendation defines one method and one attribute for these objects:
Return the i’th item from the sequence,
or None if i is out of range.
Negative indices are not supported.
The number of nodes in the sequence.
In addition, the Python DOM interface requires that some additional support is
provided to allow NodeList objects to be used as Python sequences. All
NodeList implementations must include support for
__len__() and
__getitem__(); this allows iteration over the NodeList in
for statements and proper support for the len() built-in
function.
If a DOM implementation supports modification of the document, the
NodeList implementation must also support the
__setitem__() and __delitem__() methods.
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 DocumentType object. The DocumentType for a
document is available from the Document object’s doctype
attribute; if there is no DOCTYPE declaration for the document, the
document’s doctype attribute will be set to None instead of an
instance of this interface.
DocumentType is a specialization of Node, and adds the
following attributes:
The public identifier for the external subset of the document type definition,
or None if the DOCTYPE declaration does not specify it.
The system identifier, a URI, for the external subset of the document type
definition, or None if the DOCTYPE declaration does not specify it.
A string giving the complete internal subset from the document. This does not
include the brackets which enclose the subset. If the document has no internal
subset, this should be None.
The name of the root element as given in the DOCTYPE declaration, if
present.
This is a NamedNodeMap of 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
defined.
This is a NamedNodeMap of 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
are defined.
A Document represents an entire XML document, including its constituent
elements, attributes, processing instructions, comments etc. Remember that it
inherits properties from Node.
The one and only root element of the document.
The DocumentType node of the document, or None.
This is a read-only attribute.
The DOMImplementation object which created this document.
This is a read-only attribute.
Whether error checking is enforced.
The location of the document, or None if it is unknown.
Create and return an empty DocumentFragment node.
Create and return a CDATASection node containing data.
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.
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 insertBefore() or appendChild().
Raise InvalidCharacterErr if the name is not a valid XML name.
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
insertBefore() or appendChild().
Raise InvalidCharacterErr if the name is not a valid XML name.
Raise NamespaceErr if the qualified name is malformed,
if it has a prefix and the namespace URI is empty,
or if the prefix is 'xml'
and the namespace URI is not the XML namespace.
Create and return a text node containing the data passed as a parameter. As with the other creation methods, this one does not insert the node into the tree.
Create and return a new entity reference node. The node is not inserted into the document when it is created.
Raise InvalidCharacterErr if the name is not a valid XML name.
Added in version 3.16.
Create and return a comment node containing the data passed as a parameter. As with the other creation methods, this one does not insert the node into the tree.
Create and return a processing instruction node containing the target and data passed as parameters. As with the other creation methods, this one does not insert the node into the tree.
Raise InvalidCharacterErr if the name is not a valid XML name.
Create and return an attribute node. This method does not associate the
attribute node with any particular element. You must use
setAttributeNode() on the appropriate Element object
to use the newly created attribute instance.
Raise InvalidCharacterErr if the name is not a valid XML name.
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 setAttributeNode() on the appropriate
Element object to use the newly created attribute instance.
Raise InvalidCharacterErr if the name is not a valid XML name.
Raise NamespaceErr if the qualified name is malformed,
if it has a prefix and the namespace URI is empty,
if the prefix is 'xml' and the namespace URI is not the XML namespace,
or if the name or the prefix is 'xmlns'
and the namespace URI is not the XMLNS namespace, or vice versa.
Return the element with the given ID, or None.
Only attributes declared as being of type ID in the DTD
or by Element.setIdAttribute() are searched.
If several elements have the same ID, the first one
in document order is returned.
Changed in version 3.16: Previously, which of the elements with the same ID was returned was unspecified and could change between calls.
Search for all descendants (direct children, children’s children, etc.) with a particular element type name.
Search for all descendants (direct children, children’s children, etc.) with a particular namespace URI and localname. The localname is the part of the namespace after the prefix.
Rename the element or attribute node n
and return it.
namespaceURI is the new namespace URI, or
EMPTY_NAMESPACE if the node does not belong to a namespace.
name is the new qualified name.
Raise WrongDocumentErr if n was created by another document,
and NotSupportedErr if it is neither an element nor an attribute.
Element is a subclass of Node, so inherits all the attributes
of that class.
The element type name. In a namespace-using document it may have colons in it. The value is a string.
Declare that the attribute name is of type ID,
so that the element is found by Document.getElementById().
Raise NotFoundErr if the element has no such attribute.
The same as setIdAttribute(),
but for an attribute specified by its namespace URI and local name.
The same as setIdAttribute(),
but for an already retrieved attribute node.
Same as equivalent method in the Document class.
Return True if the element has an attribute named by name.
Return True if the element has an attribute named by namespaceURI and
localName.
Return the value of the attribute named by name as a string. If no such attribute exists, an empty string is returned, as if the attribute had no value.
Return the value of the attribute named by namespaceURI and localName as a string. If no such attribute exists, an empty string is returned, as if the attribute had no value.
Return an attribute value as a node, given a namespaceURI and localName.
Remove an attribute by name.
Remove and return oldAttr from the attribute list, if present. If oldAttr is
not present, NotFoundErr is raised.
Remove an attribute by name. Note that it uses a localName, not a qname.
Set an attribute value from a string.
Raise InvalidCharacterErr if the name is not a valid XML name.
Add a new attribute node to the element, replacing an existing attribute if
necessary if the name attribute matches. If a replacement
occurs, the old attribute node will be returned. If newAttr is already in use,
InuseAttributeErr will be raised.
Raise WrongDocumentErr if newAttr was created by another document.
Add a new attribute node to the element, replacing an existing attribute if
necessary if the namespaceURI and localName
attributes match. If a replacement occurs, the old attribute node will be
returned. If newAttr is already in use, InuseAttributeErr will be
raised.
Raise WrongDocumentErr if newAttr was created by another document.
Set an attribute value from a string, given a namespaceURI and a qname. Note that a qname is the whole attribute name. This is different than above.
Raise InvalidCharacterErr if the name is not a valid XML name.
Raise NamespaceErr if the qualified name is malformed,
if it has a prefix and the namespace URI is empty,
if the prefix is 'xml' and the namespace URI is not the XML namespace,
or if the name or the prefix is 'xmlns'
and the namespace URI is not the XMLNS namespace, or vice versa.
Attr inherits from Node, so inherits all its attributes.
Attribute nodes are not part of the document tree.
They are contained in the attributes map of an element,
not in its children,
and their parentNode, previousSibling
and nextSibling are always None.
The attribute name. In a namespace-using document it may include a colon.
The part of the name following the colon if there is one, else the entire name. This is a read-only attribute.
The part of the name preceding the colon if there is one, else the empty string.
Whether this attribute is of type ID,
either because it is declared as such in the DTD
or because Element.setIdAttribute() was used.
This is a read-only attribute.
The Element node to which this attribute belongs,
or None if it is not used.
This is a read-only attribute.
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.
NamedNodeMap does not inherit from Node.
The length of the attribute list.
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 value attribute.
Return the node with the given name,
or None if there is no such node.
Return the node with the given namespace URI and local name,
or None if there is no such node.
Add node to the map, using its name as the key.
Return the node which it replaces, or None if it replaces no node.
Raise WrongDocumentErr if node was created by another document,
and InuseAttributeErr if it belongs to another element.
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.
Raise WrongDocumentErr if node was created by another document,
and InuseAttributeErr if it belongs to another element.
Remove and return the node with the given name.
Raise NotFoundErr if there is no such node.
Remove and return the node with the given namespace URI and local name.
Raise NotFoundErr if there is no such node.
You can also use the standardized getAttribute*() family of methods
on the Element objects.
DocumentFragment is a lightweight container of nodes.
It is a subclass of Node.
When it is inserted into the document tree,
its children are inserted instead of it,
and it becomes empty.
CharacterData represents text-like data in the XML document.
It is a subclass of Node, and the base class
of Text, CDATASection and Comment.
Such nodes cannot have child nodes.
The content of the node as a string.
Comment represents a comment in the XML document.
It is a subclass of CharacterData.
The content of the comment as a string. The attribute contains all characters
between the leading <!-- and trailing -->, but does not
include them.
The 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 CDATASection objects.
These two interfaces are identical, but provide different values for the
nodeType attribute.
Text extends the CharacterData interface,
and CDATASection extends Text.
The content of the text node as a string.
The text of all Text nodes logically adjacent to this node,
concatenated in document order.
This is a read-only attribute.
Replace the text of all Text nodes logically adjacent
to this node with content, removing the other nodes.
Return this node, or None if content is empty.
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 CDATASection node does not indicate that the node
represents a complete CDATA marked section, only that the content of the node
was part of a CDATA section. A single CDATA section may be represented by more
than one node in the document tree. There is no way to determine whether two
adjacent CDATASection nodes represent different CDATA marked sections.
Represents a processing instruction in the XML document; this inherits from the
Node interface and cannot have child nodes.
The content of the processing instruction up to the first whitespace character. This is a read-only attribute.
The content of the processing instruction following the first whitespace character.
Entity represents a parsed or unparsed entity declared in the DTD.
It is a subclass of Node.
Entity nodes are contained in DocumentType.entities
and cannot be inserted into the document tree.
The name of the entity is its nodeName.
The public identifier of the entity,
or None if it is not specified.
This is a read-only attribute.
The system identifier of the entity,
or None if it is not specified.
This is a read-only attribute.
The name of the notation for an unparsed entity,
or None for a parsed entity.
This is a read-only attribute.
Notation represents a notation declared in the DTD.
It is a subclass of Node and cannot have child nodes.
Notation nodes are contained in DocumentType.notations
and cannot be inserted into the document tree.
The name of the notation is its nodeName.
The public identifier of the notation,
or None if it is not specified.
This is a read-only attribute.
The system identifier of the notation,
or None if it is not specified.
This is a read-only attribute.
EntityReference represents an entity reference in the XML document.
It is a subclass of Node.
The name of the referenced entity is its nodeName.
Its children are the replacement text of the entity, and are read-only.
Parsers may expand entity references, so such a node only occurs in a document if it was created explicitly.
Added in version 3.16.
The DOM Level 2 recommendation defines a single exception, DOMException,
and a number of constants that allow applications to determine what sort of
error occurred. DOMException instances carry a code attribute
that provides the appropriate value for the specific exception.
The Python DOM interface provides the constants, but also expands the set of
exceptions so that a specific exception exists for each of the exception codes
defined by the DOM. The implementations must raise the appropriate specific
exception, each of which carries the appropriate value for the code
attribute.
Base exception class used for all specific DOM exceptions. This exception class cannot be directly instantiated.
Raised when a specified range of text does not fit into a string. This is not known to be used in the Python DOM implementations, but may be received from DOM implementations not written in Python.
Raised when an attempt is made to insert a node where the node type is not allowed.
Raised when an index or size parameter to a method is negative or exceeds the allowed values.
Raised when an attempt is made to insert an Attr node that is already
present elsewhere in the document.
Raised if a parameter or an operation is not supported on the underlying object.
This exception is raised when a string parameter contains a character that is
not permitted in the context it’s being used in by the XML 1.0 recommendation.
For example, attempting to create an Element node with a space in the
element type name will cause this error to be raised.
Raised when an attempt is made to modify the type of a node.
Raised when an attempt is made to use an object that is not defined or is no longer usable.
If an attempt is made to change any object in a way that is not permitted with regard to the Namespaces in XML recommendation, this exception is raised.
Exception when a node does not exist in the referenced context. For example,
NamedNodeMap.removeNamedItem() will raise this if the node passed in does
not exist in the map.
Raised when the implementation does not support the requested type of object or operation.
This is raised if data is specified for a node which does not support data.
Raised on attempts to modify an object where modifications are not allowed (such as for read-only nodes).
Raised when an invalid or illegal string is specified.
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.
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This section describes the conformance requirements and relationships between the Python DOM API, the W3C DOM recommendations, and the OMG IDL mapping for Python.
The IDL types used in the DOM specification are mapped to Python types according to the following table.
IDL Type |
Python Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
The mapping from OMG IDL to Python defines accessor functions for IDL
attribute declarations in much the way the Java mapping does.
Mapping the IDL declarations
readonly attribute string someValue; attribute string anotherValue;
yields three accessor functions: a “get” method for someValue
(_get_someValue()), and “get” and “set” methods for anotherValue
(_get_anotherValue() and _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 AttributeError.
The Python DOM API, however, does require that normal attribute access work.
This means that the typical surrogates generated by Python IDL compilers are not
likely to work, and wrapper objects may be needed on the client if the DOM
objects are accessed via CORBA. While this does require some additional
consideration for CORBA DOM clients, the implementers with experience using DOM
over CORBA from Python do not consider this a problem. Attributes that are
declared readonly may not restrict write access in all DOM
implementations.
In the Python DOM API, accessor functions are not required. If provided, they
should take the form defined by the Python IDL mapping, but these methods are
considered unnecessary since the attributes are accessible directly from Python.
“Set” accessors should never be provided for readonly attributes.
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
getElementsByTagName(), being “live”. The Python DOM API does
not require implementations to enforce such requirements.