1
:mod:`xml.dom` --- The Document Object Model API
2
================================================
5
:synopsis: Document Object Model API for Python.
6
.. sectionauthor:: Paul Prescod <paul@prescod.net>
7
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
10
The Document Object Model, or "DOM," is a cross-language API from the World Wide
11
Web Consortium (W3C) for accessing and modifying XML documents. A DOM
12
implementation presents an XML document as a tree structure, or allows client
13
code to build such a structure from scratch. It then gives access to the
14
structure through a set of objects which provided well-known interfaces.
16
The DOM is extremely useful for random-access applications. SAX only allows you
17
a view of one bit of the document at a time. If you are looking at one SAX
18
element, you have no access to another. If you are looking at a text node, you
19
have no access to a containing element. When you write a SAX application, you
20
need to keep track of your program's position in the document somewhere in your
21
own code. SAX does not do it for you. Also, if you need to look ahead in the
22
XML document, you are just out of luck.
24
Some applications are simply impossible in an event driven model with no access
25
to a tree. Of course you could build some sort of tree yourself in SAX events,
26
but the DOM allows you to avoid writing that code. The DOM is a standard tree
27
representation for XML data.
29
The Document Object Model is being defined by the W3C in stages, or "levels" in
30
their terminology. The Python mapping of the API is substantially based on the
31
DOM Level 2 recommendation.
33
.. What if your needs are somewhere between SAX and the DOM? Perhaps
34
you cannot afford to load the entire tree in memory but you find the
35
SAX model somewhat cumbersome and low-level. There is also a module
36
called xml.dom.pulldom that allows you to build trees of only the
37
parts of a document that you need structured access to. It also has
38
features that allow you to find your way around the DOM.
39
See http://www.prescod.net/python/pulldom
41
DOM applications typically start by parsing some XML into a DOM. How this is
42
accomplished is not covered at all by DOM Level 1, and Level 2 provides only
43
limited improvements: There is a :class:`DOMImplementation` object class which
44
provides access to :class:`Document` creation methods, but no way to access an
45
XML reader/parser/Document builder in an implementation-independent way. There
46
is also no well-defined way to access these methods without an existing
47
:class:`Document` object. In Python, each DOM implementation will provide a
48
function :func:`getDOMImplementation`. DOM Level 3 adds a Load/Store
49
specification, which defines an interface to the reader, but this is not yet
50
available in the Python standard library.
52
Once you have a DOM document object, you can access the parts of your XML
53
document through its properties and methods. These properties are defined in
54
the DOM specification; this portion of the reference manual describes the
55
interpretation of the specification in Python.
57
The specification provided by the W3C defines the DOM API for Java, ECMAScript,
58
and OMG IDL. The Python mapping defined here is based in large part on the IDL
59
version of the specification, but strict compliance is not required (though
60
implementations are free to support the strict mapping from IDL). See section
61
:ref:`dom-conformance` for a detailed discussion of mapping requirements.
66
`Document Object Model (DOM) Level 2 Specification <http://www.w3.org/TR/DOM-Level-2-Core/>`_
67
The W3C recommendation upon which the Python DOM API is based.
69
`Document Object Model (DOM) Level 1 Specification <http://www.w3.org/TR/REC-DOM-Level-1/>`_
70
The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`.
72
`Python Language Mapping Specification <http://www.omg.org/spec/PYTH/1.2/PDF>`_
73
This specifies the mapping from OMG IDL to Python.
79
The :mod:`xml.dom` contains the following functions:
82
.. function:: registerDOMImplementation(name, factory)
84
Register the *factory* function with the name *name*. The factory function
85
should return an object which implements the :class:`DOMImplementation`
86
interface. The factory function can return the same object every time, or a new
87
one for each call, as appropriate for the specific implementation (e.g. if that
88
implementation supports some customization).
91
.. function:: getDOMImplementation(name=None, features=())
93
Return a suitable DOM implementation. The *name* is either well-known, the
94
module name of a DOM implementation, or ``None``. If it is not ``None``, imports
95
the corresponding module and returns a :class:`DOMImplementation` object if the
96
import succeeds. If no name is given, and if the environment variable
97
:envvar:`PYTHON_DOM` is set, this variable is used to find the implementation.
99
If name is not given, this examines the available implementations to find one
100
with the required feature set. If no implementation can be found, raise an
101
:exc:`ImportError`. The features list must be a sequence of ``(feature,
102
version)`` pairs which are passed to the :meth:`hasFeature` method on available
103
:class:`DOMImplementation` objects.
105
Some convenience constants are also provided:
108
.. data:: EMPTY_NAMESPACE
110
The value used to indicate that no namespace is associated with a node in the
111
DOM. This is typically found as the :attr:`namespaceURI` of a node, or used as
112
the *namespaceURI* parameter to a namespaces-specific method.
115
.. data:: XML_NAMESPACE
117
The namespace URI associated with the reserved prefix ``xml``, as defined by
118
`Namespaces in XML <http://www.w3.org/TR/REC-xml-names/>`_ (section 4).
121
.. data:: XMLNS_NAMESPACE
123
The namespace URI for namespace declarations, as defined by `Document Object
124
Model (DOM) Level 2 Core Specification
125
<http://www.w3.org/TR/DOM-Level-2-Core/core.html>`_ (section 1.1.8).
128
.. data:: XHTML_NAMESPACE
130
The URI of the XHTML namespace as defined by `XHTML 1.0: The Extensible
131
HyperText Markup Language <http://www.w3.org/TR/xhtml1/>`_ (section 3.1.1).
134
In addition, :mod:`xml.dom` contains a base :class:`Node` class and the DOM
135
exception classes. The :class:`Node` class provided by this module does not
136
implement any of the methods or attributes defined by the DOM specification;
137
concrete DOM implementations must provide those. The :class:`Node` class
138
provided as part of this module does provide the constants used for the
139
:attr:`nodeType` attribute on concrete :class:`Node` objects; they are located
140
within the class rather than at the module level to conform with the DOM
143
.. Should the Node documentation go here?
151
The definitive documentation for the DOM is the DOM specification from the W3C.
153
Note that DOM attributes may also be manipulated as nodes instead of as simple
154
strings. It is fairly rare that you must do this, however, so this usage is not
157
+--------------------------------+-----------------------------------+---------------------------------+
158
| Interface | Section | Purpose |
159
+================================+===================================+=================================+
160
| :class:`DOMImplementation` | :ref:`dom-implementation-objects` | Interface to the underlying |
161
| | | implementation. |
162
+--------------------------------+-----------------------------------+---------------------------------+
163
| :class:`Node` | :ref:`dom-node-objects` | Base interface for most objects |
164
| | | in a document. |
165
+--------------------------------+-----------------------------------+---------------------------------+
166
| :class:`NodeList` | :ref:`dom-nodelist-objects` | Interface for a sequence of |
168
+--------------------------------+-----------------------------------+---------------------------------+
169
| :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the |
170
| | | declarations needed to process |
172
+--------------------------------+-----------------------------------+---------------------------------+
173
| :class:`Document` | :ref:`dom-document-objects` | Object which represents an |
174
| | | entire document. |
175
+--------------------------------+-----------------------------------+---------------------------------+
176
| :class:`Element` | :ref:`dom-element-objects` | Element nodes in the document |
178
+--------------------------------+-----------------------------------+---------------------------------+
179
| :class:`Attr` | :ref:`dom-attr-objects` | Attribute value nodes on |
180
| | | element nodes. |
181
+--------------------------------+-----------------------------------+---------------------------------+
182
| :class:`Comment` | :ref:`dom-comment-objects` | Representation of comments in |
183
| | | the source document. |
184
+--------------------------------+-----------------------------------+---------------------------------+
185
| :class:`Text` | :ref:`dom-text-objects` | Nodes containing textual |
186
| | | content from the document. |
187
+--------------------------------+-----------------------------------+---------------------------------+
188
| :class:`ProcessingInstruction` | :ref:`dom-pi-objects` | Processing instruction |
189
| | | representation. |
190
+--------------------------------+-----------------------------------+---------------------------------+
192
An additional section describes the exceptions defined for working with the DOM
196
.. _dom-implementation-objects:
198
DOMImplementation Objects
199
^^^^^^^^^^^^^^^^^^^^^^^^^
201
The :class:`DOMImplementation` interface provides a way for applications to
202
determine the availability of particular features in the DOM they are using.
203
DOM Level 2 added the ability to create new :class:`Document` and
204
:class:`DocumentType` objects using the :class:`DOMImplementation` as well.
207
.. method:: DOMImplementation.hasFeature(feature, version)
209
Return true if the feature identified by the pair of strings *feature* and
210
*version* is implemented.
213
.. method:: DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)
215
Return a new :class:`Document` object (the root of the DOM), with a child
216
:class:`Element` object having the given *namespaceUri* and *qualifiedName*. The
217
*doctype* must be a :class:`DocumentType` object created by
218
:meth:`createDocumentType`, or ``None``. In the Python DOM API, the first two
219
arguments can also be ``None`` in order to indicate that no :class:`Element`
220
child is to be created.
223
.. method:: DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)
225
Return a new :class:`DocumentType` object that encapsulates the given
226
*qualifiedName*, *publicId*, and *systemId* strings, representing the
227
information contained in an XML document type declaration.
230
.. _dom-node-objects:
235
All of the components of an XML document are subclasses of :class:`Node`.
238
.. attribute:: Node.nodeType
240
An integer representing the node type. Symbolic constants for the types are on
241
the :class:`Node` object: :const:`ELEMENT_NODE`, :const:`ATTRIBUTE_NODE`,
242
:const:`TEXT_NODE`, :const:`CDATA_SECTION_NODE`, :const:`ENTITY_NODE`,
243
:const:`PROCESSING_INSTRUCTION_NODE`, :const:`COMMENT_NODE`,
244
:const:`DOCUMENT_NODE`, :const:`DOCUMENT_TYPE_NODE`, :const:`NOTATION_NODE`.
245
This is a read-only attribute.
248
.. attribute:: Node.parentNode
250
The parent of the current node, or ``None`` for the document node. The value is
251
always a :class:`Node` object or ``None``. For :class:`Element` nodes, this
252
will be the parent element, except for the root element, in which case it will
253
be the :class:`Document` object. For :class:`Attr` nodes, this is always
254
``None``. This is a read-only attribute.
257
.. attribute:: Node.attributes
259
A :class:`NamedNodeMap` of attribute objects. Only elements have actual values
260
for this; others provide ``None`` for this attribute. This is a read-only
264
.. attribute:: Node.previousSibling
266
The node that immediately precedes this one with the same parent. For
267
instance the element with an end-tag that comes just before the *self*
268
element's start-tag. Of course, XML documents are made up of more than just
269
elements so the previous sibling could be text, a comment, or something else.
270
If this node is the first child of the parent, this attribute will be
271
``None``. This is a read-only attribute.
274
.. attribute:: Node.nextSibling
276
The node that immediately follows this one with the same parent. See also
277
:attr:`previousSibling`. If this is the last child of the parent, this
278
attribute will be ``None``. This is a read-only attribute.
281
.. attribute:: Node.childNodes
283
A list of nodes contained within this node. This is a read-only attribute.
286
.. attribute:: Node.firstChild
288
The first child of the node, if there are any, or ``None``. This is a read-only
292
.. attribute:: Node.lastChild
294
The last child of the node, if there are any, or ``None``. This is a read-only
298
.. attribute:: Node.localName
300
The part of the :attr:`tagName` following the colon if there is one, else the
301
entire :attr:`tagName`. The value is a string.
304
.. attribute:: Node.prefix
306
The part of the :attr:`tagName` preceding the colon if there is one, else the
307
empty string. The value is a string, or ``None``
310
.. attribute:: Node.namespaceURI
312
The namespace associated with the element name. This will be a string or
313
``None``. This is a read-only attribute.
316
.. attribute:: Node.nodeName
318
This has a different meaning for each node type; see the DOM specification for
319
details. You can always get the information you would get here from another
320
property such as the :attr:`tagName` property for elements or the :attr:`name`
321
property for attributes. For all node types, the value of this attribute will be
322
either a string or ``None``. This is a read-only attribute.
325
.. attribute:: Node.nodeValue
327
This has a different meaning for each node type; see the DOM specification for
328
details. The situation is similar to that with :attr:`nodeName`. The value is
329
a string or ``None``.
332
.. method:: Node.hasAttributes()
334
Returns true if the node has any attributes.
337
.. method:: Node.hasChildNodes()
339
Returns true if the node has any child nodes.
342
.. method:: Node.isSameNode(other)
344
Returns true if *other* refers to the same node as this node. This is especially
345
useful for DOM implementations which use any sort of proxy architecture (because
346
more than one object can refer to the same node).
350
This is based on a proposed DOM Level 3 API which is still in the "working
351
draft" stage, but this particular interface appears uncontroversial. Changes
352
from the W3C will not necessarily affect this method in the Python DOM interface
353
(though any new W3C API for this would also be supported).
356
.. method:: Node.appendChild(newChild)
358
Add a new child node to this node at the end of the list of
359
children, returning *newChild*. If the node was already in
360
the tree, it is removed first.
363
.. method:: Node.insertBefore(newChild, refChild)
365
Insert a new child node before an existing child. It must be the case that
366
*refChild* is a child of this node; if not, :exc:`ValueError` is raised.
367
*newChild* is returned. If *refChild* is ``None``, it inserts *newChild* at the
368
end of the children's list.
371
.. method:: Node.removeChild(oldChild)
373
Remove a child node. *oldChild* must be a child of this node; if not,
374
:exc:`ValueError` is raised. *oldChild* is returned on success. If *oldChild*
375
will not be used further, its :meth:`unlink` method should be called.
378
.. method:: Node.replaceChild(newChild, oldChild)
380
Replace an existing node with a new node. It must be the case that *oldChild*
381
is a child of this node; if not, :exc:`ValueError` is raised.
384
.. method:: Node.normalize()
386
Join adjacent text nodes so that all stretches of text are stored as single
387
:class:`Text` instances. This simplifies processing text from a DOM tree for
391
.. method:: Node.cloneNode(deep)
393
Clone this node. Setting *deep* means to clone all child nodes as well. This
397
.. _dom-nodelist-objects:
402
A :class:`NodeList` represents a sequence of nodes. These objects are used in
403
two ways in the DOM Core recommendation: the :class:`Element` objects provides
404
one as its list of child nodes, and the :meth:`getElementsByTagName` and
405
:meth:`getElementsByTagNameNS` methods of :class:`Node` return objects with this
406
interface to represent query results.
408
The DOM Level 2 recommendation defines one method and one attribute for these
412
.. method:: NodeList.item(i)
414
Return the *i*'th item from the sequence, if there is one, or ``None``. The
415
index *i* is not allowed to be less then zero or greater than or equal to the
416
length of the sequence.
419
.. attribute:: NodeList.length
421
The number of nodes in the sequence.
423
In addition, the Python DOM interface requires that some additional support is
424
provided to allow :class:`NodeList` objects to be used as Python sequences. All
425
:class:`NodeList` implementations must include support for
426
:meth:`~object.__len__` and
427
:meth:`~object.__getitem__`; this allows iteration over the :class:`NodeList` in
428
:keyword:`for` statements and proper support for the :func:`len` built-in
431
If a DOM implementation supports modification of the document, the
432
:class:`NodeList` implementation must also support the
433
:meth:`~object.__setitem__` and :meth:`~object.__delitem__` methods.
436
.. _dom-documenttype-objects:
441
Information about the notations and entities declared by a document (including
442
the external subset if the parser uses it and can provide the information) is
443
available from a :class:`DocumentType` object. The :class:`DocumentType` for a
444
document is available from the :class:`Document` object's :attr:`doctype`
445
attribute; if there is no ``DOCTYPE`` declaration for the document, the
446
document's :attr:`doctype` attribute will be set to ``None`` instead of an
447
instance of this interface.
449
:class:`DocumentType` is a specialization of :class:`Node`, and adds the
450
following attributes:
453
.. attribute:: DocumentType.publicId
455
The public identifier for the external subset of the document type definition.
456
This will be a string or ``None``.
459
.. attribute:: DocumentType.systemId
461
The system identifier for the external subset of the document type definition.
462
This will be a URI as a string, or ``None``.
465
.. attribute:: DocumentType.internalSubset
467
A string giving the complete internal subset from the document. This does not
468
include the brackets which enclose the subset. If the document has no internal
469
subset, this should be ``None``.
472
.. attribute:: DocumentType.name
474
The name of the root element as given in the ``DOCTYPE`` declaration, if
478
.. attribute:: DocumentType.entities
480
This is a :class:`NamedNodeMap` giving the definitions of external entities.
481
For entity names defined more than once, only the first definition is provided
482
(others are ignored as required by the XML recommendation). This may be
483
``None`` if the information is not provided by the parser, or if no entities are
487
.. attribute:: DocumentType.notations
489
This is a :class:`NamedNodeMap` giving the definitions of notations. For
490
notation names defined more than once, only the first definition is provided
491
(others are ignored as required by the XML recommendation). This may be
492
``None`` if the information is not provided by the parser, or if no notations
496
.. _dom-document-objects:
501
A :class:`Document` represents an entire XML document, including its constituent
502
elements, attributes, processing instructions, comments etc. Remember that it
503
inherits properties from :class:`Node`.
506
.. attribute:: Document.documentElement
508
The one and only root element of the document.
511
.. method:: Document.createElement(tagName)
513
Create and return a new element node. The element is not inserted into the
514
document when it is created. You need to explicitly insert it with one of the
515
other methods such as :meth:`insertBefore` or :meth:`appendChild`.
518
.. method:: Document.createElementNS(namespaceURI, tagName)
520
Create and return a new element with a namespace. The *tagName* may have a
521
prefix. The element is not inserted into the document when it is created. You
522
need to explicitly insert it with one of the other methods such as
523
:meth:`insertBefore` or :meth:`appendChild`.
526
.. method:: Document.createTextNode(data)
528
Create and return a text node containing the data passed as a parameter. As
529
with the other creation methods, this one does not insert the node into the
533
.. method:: Document.createComment(data)
535
Create and return a comment node containing the data passed as a parameter. As
536
with the other creation methods, this one does not insert the node into the
540
.. method:: Document.createProcessingInstruction(target, data)
542
Create and return a processing instruction node containing the *target* and
543
*data* passed as parameters. As with the other creation methods, this one does
544
not insert the node into the tree.
547
.. method:: Document.createAttribute(name)
549
Create and return an attribute node. This method does not associate the
550
attribute node with any particular element. You must use
551
:meth:`setAttributeNode` on the appropriate :class:`Element` object to use the
552
newly created attribute instance.
555
.. method:: Document.createAttributeNS(namespaceURI, qualifiedName)
557
Create and return an attribute node with a namespace. The *tagName* may have a
558
prefix. This method does not associate the attribute node with any particular
559
element. You must use :meth:`setAttributeNode` on the appropriate
560
:class:`Element` object to use the newly created attribute instance.
563
.. method:: Document.getElementsByTagName(tagName)
565
Search for all descendants (direct children, children's children, etc.) with a
566
particular element type name.
569
.. method:: Document.getElementsByTagNameNS(namespaceURI, localName)
571
Search for all descendants (direct children, children's children, etc.) with a
572
particular namespace URI and localname. The localname is the part of the
573
namespace after the prefix.
576
.. _dom-element-objects:
581
:class:`Element` is a subclass of :class:`Node`, so inherits all the attributes
585
.. attribute:: Element.tagName
587
The element type name. In a namespace-using document it may have colons in it.
588
The value is a string.
591
.. method:: Element.getElementsByTagName(tagName)
593
Same as equivalent method in the :class:`Document` class.
596
.. method:: Element.getElementsByTagNameNS(namespaceURI, localName)
598
Same as equivalent method in the :class:`Document` class.
601
.. method:: Element.hasAttribute(name)
603
Returns true if the element has an attribute named by *name*.
606
.. method:: Element.hasAttributeNS(namespaceURI, localName)
608
Returns true if the element has an attribute named by *namespaceURI* and
612
.. method:: Element.getAttribute(name)
614
Return the value of the attribute named by *name* as a string. If no such
615
attribute exists, an empty string is returned, as if the attribute had no value.
618
.. method:: Element.getAttributeNode(attrname)
620
Return the :class:`Attr` node for the attribute named by *attrname*.
623
.. method:: Element.getAttributeNS(namespaceURI, localName)
625
Return the value of the attribute named by *namespaceURI* and *localName* as a
626
string. If no such attribute exists, an empty string is returned, as if the
627
attribute had no value.
630
.. method:: Element.getAttributeNodeNS(namespaceURI, localName)
632
Return an attribute value as a node, given a *namespaceURI* and *localName*.
635
.. method:: Element.removeAttribute(name)
637
Remove an attribute by name. If there is no matching attribute, a
638
:exc:`NotFoundErr` is raised.
641
.. method:: Element.removeAttributeNode(oldAttr)
643
Remove and return *oldAttr* from the attribute list, if present. If *oldAttr* is
644
not present, :exc:`NotFoundErr` is raised.
647
.. method:: Element.removeAttributeNS(namespaceURI, localName)
649
Remove an attribute by name. Note that it uses a localName, not a qname. No
650
exception is raised if there is no matching attribute.
653
.. method:: Element.setAttribute(name, value)
655
Set an attribute value from a string.
658
.. method:: Element.setAttributeNode(newAttr)
660
Add a new attribute node to the element, replacing an existing attribute if
661
necessary if the :attr:`name` attribute matches. If a replacement occurs, the
662
old attribute node will be returned. If *newAttr* is already in use,
663
:exc:`InuseAttributeErr` will be raised.
666
.. method:: Element.setAttributeNodeNS(newAttr)
668
Add a new attribute node to the element, replacing an existing attribute if
669
necessary if the :attr:`namespaceURI` and :attr:`localName` attributes match.
670
If a replacement occurs, the old attribute node will be returned. If *newAttr*
671
is already in use, :exc:`InuseAttributeErr` will be raised.
674
.. method:: Element.setAttributeNS(namespaceURI, qname, value)
676
Set an attribute value from a string, given a *namespaceURI* and a *qname*.
677
Note that a qname is the whole attribute name. This is different than above.
680
.. _dom-attr-objects:
685
:class:`Attr` inherits from :class:`Node`, so inherits all its attributes.
688
.. attribute:: Attr.name
691
In a namespace-using document it may include a colon.
694
.. attribute:: Attr.localName
696
The part of the name following the colon if there is one, else the
698
This is a read-only attribute.
701
.. attribute:: Attr.prefix
703
The part of the name preceding the colon if there is one, else the
707
.. attribute:: Attr.value
709
The text value of the attribute. This is a synonym for the
710
:attr:`nodeValue` attribute.
713
.. _dom-attributelist-objects:
718
:class:`NamedNodeMap` does *not* inherit from :class:`Node`.
721
.. attribute:: NamedNodeMap.length
723
The length of the attribute list.
726
.. method:: NamedNodeMap.item(index)
728
Return an attribute with a particular index. The order you get the attributes
729
in is arbitrary but will be consistent for the life of a DOM. Each item is an
730
attribute node. Get its value with the :attr:`value` attribute.
732
There are also experimental methods that give this class more mapping behavior.
733
You can use them or you can use the standardized :meth:`getAttribute\*` family
734
of methods on the :class:`Element` objects.
737
.. _dom-comment-objects:
742
:class:`Comment` represents a comment in the XML document. It is a subclass of
743
:class:`Node`, but cannot have child nodes.
746
.. attribute:: Comment.data
748
The content of the comment as a string. The attribute contains all characters
749
between the leading ``<!-``\ ``-`` and trailing ``-``\ ``->``, but does not
753
.. _dom-text-objects:
755
Text and CDATASection Objects
756
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
758
The :class:`Text` interface represents text in the XML document. If the parser
759
and DOM implementation support the DOM's XML extension, portions of the text
760
enclosed in CDATA marked sections are stored in :class:`CDATASection` objects.
761
These two interfaces are identical, but provide different values for the
762
:attr:`nodeType` attribute.
764
These interfaces extend the :class:`Node` interface. They cannot have child
768
.. attribute:: Text.data
770
The content of the text node as a string.
774
The use of a :class:`CDATASection` node does not indicate that the node
775
represents a complete CDATA marked section, only that the content of the node
776
was part of a CDATA section. A single CDATA section may be represented by more
777
than one node in the document tree. There is no way to determine whether two
778
adjacent :class:`CDATASection` nodes represent different CDATA marked sections.
783
ProcessingInstruction Objects
784
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
786
Represents a processing instruction in the XML document; this inherits from the
787
:class:`Node` interface and cannot have child nodes.
790
.. attribute:: ProcessingInstruction.target
792
The content of the processing instruction up to the first whitespace character.
793
This is a read-only attribute.
796
.. attribute:: ProcessingInstruction.data
798
The content of the processing instruction following the first whitespace
807
The DOM Level 2 recommendation defines a single exception, :exc:`DOMException`,
808
and a number of constants that allow applications to determine what sort of
809
error occurred. :exc:`DOMException` instances carry a :attr:`code` attribute
810
that provides the appropriate value for the specific exception.
812
The Python DOM interface provides the constants, but also expands the set of
813
exceptions so that a specific exception exists for each of the exception codes
814
defined by the DOM. The implementations must raise the appropriate specific
815
exception, each of which carries the appropriate value for the :attr:`code`
819
.. exception:: DOMException
821
Base exception class used for all specific DOM exceptions. This exception class
822
cannot be directly instantiated.
825
.. exception:: DomstringSizeErr
827
Raised when a specified range of text does not fit into a string. This is not
828
known to be used in the Python DOM implementations, but may be received from DOM
829
implementations not written in Python.
832
.. exception:: HierarchyRequestErr
834
Raised when an attempt is made to insert a node where the node type is not
838
.. exception:: IndexSizeErr
840
Raised when an index or size parameter to a method is negative or exceeds the
844
.. exception:: InuseAttributeErr
846
Raised when an attempt is made to insert an :class:`Attr` node that is already
847
present elsewhere in the document.
850
.. exception:: InvalidAccessErr
852
Raised if a parameter or an operation is not supported on the underlying object.
855
.. exception:: InvalidCharacterErr
857
This exception is raised when a string parameter contains a character that is
858
not permitted in the context it's being used in by the XML 1.0 recommendation.
859
For example, attempting to create an :class:`Element` node with a space in the
860
element type name will cause this error to be raised.
863
.. exception:: InvalidModificationErr
865
Raised when an attempt is made to modify the type of a node.
868
.. exception:: InvalidStateErr
870
Raised when an attempt is made to use an object that is not defined or is no
874
.. exception:: NamespaceErr
876
If an attempt is made to change any object in a way that is not permitted with
877
regard to the `Namespaces in XML <http://www.w3.org/TR/REC-xml-names/>`_
878
recommendation, this exception is raised.
881
.. exception:: NotFoundErr
883
Exception when a node does not exist in the referenced context. For example,
884
:meth:`NamedNodeMap.removeNamedItem` will raise this if the node passed in does
885
not exist in the map.
888
.. exception:: NotSupportedErr
890
Raised when the implementation does not support the requested type of object or
894
.. exception:: NoDataAllowedErr
896
This is raised if data is specified for a node which does not support data.
898
.. XXX a better explanation is needed!
901
.. exception:: NoModificationAllowedErr
903
Raised on attempts to modify an object where modifications are not allowed (such
904
as for read-only nodes).
907
.. exception:: SyntaxErr
909
Raised when an invalid or illegal string is specified.
911
.. XXX how is this different from InvalidCharacterErr?
914
.. exception:: WrongDocumentErr
916
Raised when a node is inserted in a different document than it currently belongs
917
to, and the implementation does not support migrating the node from one document
920
The exception codes defined in the DOM recommendation map to the exceptions
921
described above according to this table:
923
+--------------------------------------+---------------------------------+
924
| Constant | Exception |
925
+======================================+=================================+
926
| :const:`DOMSTRING_SIZE_ERR` | :exc:`DomstringSizeErr` |
927
+--------------------------------------+---------------------------------+
928
| :const:`HIERARCHY_REQUEST_ERR` | :exc:`HierarchyRequestErr` |
929
+--------------------------------------+---------------------------------+
930
| :const:`INDEX_SIZE_ERR` | :exc:`IndexSizeErr` |
931
+--------------------------------------+---------------------------------+
932
| :const:`INUSE_ATTRIBUTE_ERR` | :exc:`InuseAttributeErr` |
933
+--------------------------------------+---------------------------------+
934
| :const:`INVALID_ACCESS_ERR` | :exc:`InvalidAccessErr` |
935
+--------------------------------------+---------------------------------+
936
| :const:`INVALID_CHARACTER_ERR` | :exc:`InvalidCharacterErr` |
937
+--------------------------------------+---------------------------------+
938
| :const:`INVALID_MODIFICATION_ERR` | :exc:`InvalidModificationErr` |
939
+--------------------------------------+---------------------------------+
940
| :const:`INVALID_STATE_ERR` | :exc:`InvalidStateErr` |
941
+--------------------------------------+---------------------------------+
942
| :const:`NAMESPACE_ERR` | :exc:`NamespaceErr` |
943
+--------------------------------------+---------------------------------+
944
| :const:`NOT_FOUND_ERR` | :exc:`NotFoundErr` |
945
+--------------------------------------+---------------------------------+
946
| :const:`NOT_SUPPORTED_ERR` | :exc:`NotSupportedErr` |
947
+--------------------------------------+---------------------------------+
948
| :const:`NO_DATA_ALLOWED_ERR` | :exc:`NoDataAllowedErr` |
949
+--------------------------------------+---------------------------------+
950
| :const:`NO_MODIFICATION_ALLOWED_ERR` | :exc:`NoModificationAllowedErr` |
951
+--------------------------------------+---------------------------------+
952
| :const:`SYNTAX_ERR` | :exc:`SyntaxErr` |
953
+--------------------------------------+---------------------------------+
954
| :const:`WRONG_DOCUMENT_ERR` | :exc:`WrongDocumentErr` |
955
+--------------------------------------+---------------------------------+
963
This section describes the conformance requirements and relationships between
964
the Python DOM API, the W3C DOM recommendations, and the OMG IDL mapping for
968
.. _dom-type-mapping:
973
The IDL types used in the DOM specification are mapped to Python types
974
according to the following table.
976
+------------------+-------------------------------------------+
977
| IDL Type | Python Type |
978
+==================+===========================================+
979
| ``boolean`` | ``bool`` or ``int`` |
980
+------------------+-------------------------------------------+
981
| ``int`` | ``int`` |
982
+------------------+-------------------------------------------+
983
| ``long int`` | ``int`` |
984
+------------------+-------------------------------------------+
985
| ``unsigned int`` | ``int`` |
986
+------------------+-------------------------------------------+
987
| ``DOMString`` | ``str`` or ``bytes`` |
988
+------------------+-------------------------------------------+
989
| ``null`` | ``None`` |
990
+------------------+-------------------------------------------+
992
.. _dom-accessor-methods:
997
The mapping from OMG IDL to Python defines accessor functions for IDL
998
``attribute`` declarations in much the way the Java mapping does.
999
Mapping the IDL declarations ::
1001
readonly attribute string someValue;
1002
attribute string anotherValue;
1004
yields three accessor functions: a "get" method for :attr:`someValue`
1005
(:meth:`_get_someValue`), and "get" and "set" methods for :attr:`anotherValue`
1006
(:meth:`_get_anotherValue` and :meth:`_set_anotherValue`). The mapping, in
1007
particular, does not require that the IDL attributes are accessible as normal
1008
Python attributes: ``object.someValue`` is *not* required to work, and may
1009
raise an :exc:`AttributeError`.
1011
The Python DOM API, however, *does* require that normal attribute access work.
1012
This means that the typical surrogates generated by Python IDL compilers are not
1013
likely to work, and wrapper objects may be needed on the client if the DOM
1014
objects are accessed via CORBA. While this does require some additional
1015
consideration for CORBA DOM clients, the implementers with experience using DOM
1016
over CORBA from Python do not consider this a problem. Attributes that are
1017
declared ``readonly`` may not restrict write access in all DOM
1020
In the Python DOM API, accessor functions are not required. If provided, they
1021
should take the form defined by the Python IDL mapping, but these methods are
1022
considered unnecessary since the attributes are accessible directly from Python.
1023
"Set" accessors should never be provided for ``readonly`` attributes.
1025
The IDL definitions do not fully embody the requirements of the W3C DOM API,
1026
such as the notion of certain objects, such as the return value of
1027
:meth:`getElementsByTagName`, being "live". The Python DOM API does not require
1028
implementations to enforce such requirements.
added
removed
Doc/library/xml.dom.rst
