/Doc/library/xml.dom.rst

   1
   2:mod:`xml.dom` --- The Document Object Model API
   3================================================
   4
   5.. module:: xml.dom
   6   :synopsis: Document Object Model API for Python.
   7.. sectionauthor:: Paul Prescod <paul@prescod.net>
   8.. sectionauthor:: Martin v. Lรถwis <martin@v.loewis.de>
   9
  10
  11.. versionadded:: 2.0
  12
  13The Document Object Model, or "DOM," is a cross-language API from the World Wide
  14Web Consortium (W3C) for accessing and modifying XML documents.  A DOM
  15implementation presents an XML document as a tree structure, or allows client
  16code to build such a structure from scratch.  It then gives access to the
  17structure through a set of objects which provided well-known interfaces.
  18
  19The DOM is extremely useful for random-access applications.  SAX only allows you
  20a view of one bit of the document at a time.  If you are looking at one SAX
  21element, you have no access to another.  If you are looking at a text node, you
  22have no access to a containing element. When you write a SAX application, you
  23need to keep track of your program's position in the document somewhere in your
  24own code.  SAX does not do it for you.  Also, if you need to look ahead in the
  25XML document, you are just out of luck.
  26
  27Some applications are simply impossible in an event driven model with no access
  28to a tree.  Of course you could build some sort of tree yourself in SAX events,
  29but the DOM allows you to avoid writing that code.  The DOM is a standard tree
  30representation for XML data.
  31
  32The Document Object Model is being defined by the W3C in stages, or "levels" in
  33their terminology.  The Python mapping of the API is substantially based on the
  34DOM Level 2 recommendation.
  35
  36.. XXX PyXML is dead...
  37.. The mapping of the Level 3 specification, currently
  38   only available in draft form, is being developed by the `Python XML Special
  39   Interest Group <http://www.python.org/sigs/xml-sig/>`_ as part of the `PyXML
  40   package <http://pyxml.sourceforge.net/>`_.  Refer to the documentation bundled
  41   with that package for information on the current state of DOM Level 3 support.
  42
  43.. What if your needs are somewhere between SAX and the DOM?  Perhaps
  44   you cannot afford to load the entire tree in memory but you find the
  45   SAX model somewhat cumbersome and low-level.  There is also a module
  46   called xml.dom.pulldom that allows you to build trees of only the
  47   parts of a document that you need structured access to.  It also has
  48   features that allow you to find your way around the DOM.
  49   See http://www.prescod.net/python/pulldom
  50
  51DOM applications typically start by parsing some XML into a DOM.  How this is
  52accomplished is not covered at all by DOM Level 1, and Level 2 provides only
  53limited improvements: There is a :class:`DOMImplementation` object class which
  54provides access to :class:`Document` creation methods, but no way to access an
  55XML reader/parser/Document builder in an implementation-independent way. There
  56is also no well-defined way to access these methods without an existing
  57:class:`Document` object.  In Python, each DOM implementation will provide a
  58function :func:`getDOMImplementation`. DOM Level 3 adds a Load/Store
  59specification, which defines an interface to the reader, but this is not yet
  60available in the Python standard library.
  61
  62Once you have a DOM document object, you can access the parts of your XML
  63document through its properties and methods.  These properties are defined in
  64the DOM specification; this portion of the reference manual describes the
  65interpretation of the specification in Python.
  66
  67The specification provided by the W3C defines the DOM API for Java, ECMAScript,
  68and OMG IDL.  The Python mapping defined here is based in large part on the IDL
  69version of the specification, but strict compliance is not required (though
  70implementations are free to support the strict mapping from IDL).  See section
  71:ref:`dom-conformance` for a detailed discussion of mapping requirements.
  72
  73
  74.. seealso::
  75
  76   `Document Object Model (DOM) Level 2 Specification <http://www.w3.org/TR/DOM-Level-2-Core/>`_
  77      The W3C recommendation upon which the Python DOM API is based.
  78
  79   `Document Object Model (DOM) Level 1 Specification <http://www.w3.org/TR/REC-DOM-Level-1/>`_
  80      The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`.
  81
  82   `Python Language Mapping Specification <http://www.omg.org/docs/formal/02-11-05.pdf>`_
  83      This specifies the mapping from OMG IDL to Python.
  84
  85
  86Module Contents
  87---------------
  88
  89The :mod:`xml.dom` contains the following functions:
  90
  91
  92.. function:: registerDOMImplementation(name, factory)
  93
  94   Register the *factory* function with the name *name*.  The factory function
  95   should return an object which implements the :class:`DOMImplementation`
  96   interface.  The factory function can return the same object every time, or a new
  97   one for each call, as appropriate for the specific implementation (e.g. if that
  98   implementation supports some customization).
  99
 100
 101.. function:: getDOMImplementation([name[, features]])
 102
 103   Return a suitable DOM implementation. The *name* is either well-known, the
 104   module name of a DOM implementation, or ``None``. If it is not ``None``, imports
 105   the corresponding module and returns a :class:`DOMImplementation` object if the
 106   import succeeds.  If no name is given, and if the environment variable
 107   :envvar:`PYTHON_DOM` is set, this variable is used to find the implementation.
 108
 109   If name is not given, this examines the available implementations to find one
 110   with the required feature set.  If no implementation can be found, raise an
 111   :exc:`ImportError`.  The features list must be a sequence of ``(feature,
 112   version)`` pairs which are passed to the :meth:`hasFeature` method on available
 113   :class:`DOMImplementation` objects.
 114
 115Some convenience constants are also provided:
 116
 117
 118.. data:: EMPTY_NAMESPACE
 119
 120   The value used to indicate that no namespace is associated with a node in the
 121   DOM.  This is typically found as the :attr:`namespaceURI` of a node, or used as
 122   the *namespaceURI* parameter to a namespaces-specific method.
 123
 124   .. versionadded:: 2.2
 125
 126
 127.. data:: XML_NAMESPACE
 128
 129   The namespace URI associated with the reserved prefix ``xml``, as defined by
 130   `Namespaces in XML <http://www.w3.org/TR/REC-xml-names/>`_ (section 4).
 131
 132   .. versionadded:: 2.2
 133
 134
 135.. data:: XMLNS_NAMESPACE
 136
 137   The namespace URI for namespace declarations, as defined by `Document Object
 138   Model (DOM) Level 2 Core Specification
 139   <http://www.w3.org/TR/DOM-Level-2-Core/core.html>`_ (section 1.1.8).
 140
 141   .. versionadded:: 2.2
 142
 143
 144.. data:: XHTML_NAMESPACE
 145
 146   The URI of the XHTML namespace as defined by `XHTML 1.0: The Extensible
 147   HyperText Markup Language <http://www.w3.org/TR/xhtml1/>`_ (section 3.1.1).
 148
 149   .. versionadded:: 2.2
 150
 151In addition, :mod:`xml.dom` contains a base :class:`Node` class and the DOM
 152exception classes.  The :class:`Node` class provided by this module does not
 153implement any of the methods or attributes defined by the DOM specification;
 154concrete DOM implementations must provide those.  The :class:`Node` class
 155provided as part of this module does provide the constants used for the
 156:attr:`nodeType` attribute on concrete :class:`Node` objects; they are located
 157within the class rather than at the module level to conform with the DOM
 158specifications.
 159
 160.. Should the Node documentation go here?
 161
 162
 163.. _dom-objects:
 164
 165Objects in the DOM
 166------------------
 167
 168The definitive documentation for the DOM is the DOM specification from the W3C.
 169
 170Note that DOM attributes may also be manipulated as nodes instead of as simple
 171strings.  It is fairly rare that you must do this, however, so this usage is not
 172yet documented.
 173
 174+--------------------------------+-----------------------------------+---------------------------------+
 175| Interface                      | Section                           | Purpose                         |
 176+================================+===================================+=================================+
 177| :class:`DOMImplementation`     | :ref:`dom-implementation-objects` | Interface to the underlying     |
 178|                                |                                   | implementation.                 |
 179+--------------------------------+-----------------------------------+---------------------------------+
 180| :class:`Node`                  | :ref:`dom-node-objects`           | Base interface for most objects |
 181|                                |                                   | in a document.                  |
 182+--------------------------------+-----------------------------------+---------------------------------+
 183| :class:`NodeList`              | :ref:`dom-nodelist-objects`       | Interface for a sequence of     |
 184|                                |                                   | nodes.                          |
 185+--------------------------------+-----------------------------------+---------------------------------+
 186| :class:`DocumentType`          | :ref:`dom-documenttype-objects`   | Information about the           |
 187|                                |                                   | declarations needed to process  |
 188|                                |                                   | a document.                     |
 189+--------------------------------+-----------------------------------+---------------------------------+
 190| :class:`Document`              | :ref:`dom-document-objects`       | Object which represents an      |
 191|                                |                                   | entire document.                |
 192+--------------------------------+-----------------------------------+---------------------------------+
 193| :class:`Element`               | :ref:`dom-element-objects`        | Element nodes in the document   |
 194|                                |                                   | hierarchy.                      |
 195+--------------------------------+-----------------------------------+---------------------------------+
 196| :class:`Attr`                  | :ref:`dom-attr-objects`           | Attribute value nodes on        |
 197|                                |                                   | element nodes.                  |
 198+--------------------------------+-----------------------------------+---------------------------------+
 199| :class:`Comment`               | :ref:`dom-comment-objects`        | Representation of comments in   |
 200|                                |                                   | the source document.            |
 201+--------------------------------+-----------------------------------+---------------------------------+
 202| :class:`Text`                  | :ref:`dom-text-objects`           | Nodes containing textual        |
 203|                                |                                   | content from the document.      |
 204+--------------------------------+-----------------------------------+---------------------------------+
 205| :class:`ProcessingInstruction` | :ref:`dom-pi-objects`             | Processing instruction          |
 206|                                |                                   | representation.                 |
 207+--------------------------------+-----------------------------------+---------------------------------+
 208
 209An additional section describes the exceptions defined for working with the DOM
 210in Python.
 211
 212
 213.. _dom-implementation-objects:
 214
 215DOMImplementation Objects
 216^^^^^^^^^^^^^^^^^^^^^^^^^
 217
 218The :class:`DOMImplementation` interface provides a way for applications to
 219determine the availability of particular features in the DOM they are using.
 220DOM Level 2 added the ability to create new :class:`Document` and
 221:class:`DocumentType` objects using the :class:`DOMImplementation` as well.
 222
 223
 224.. method:: DOMImplementation.hasFeature(feature, version)
 225
 226   Return true if the feature identified by the pair of strings *feature* and
 227   *version* is implemented.
 228
 229
 230.. method:: DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)
 231
 232   Return a new :class:`Document` object (the root of the DOM), with a child
 233   :class:`Element` object having the given *namespaceUri* and *qualifiedName*. The
 234   *doctype* must be a :class:`DocumentType` object created by
 235   :meth:`createDocumentType`, or ``None``. In the Python DOM API, the first two
 236   arguments can also be ``None`` in order to indicate that no :class:`Element`
 237   child is to be created.
 238
 239
 240.. method:: DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)
 241
 242   Return a new :class:`DocumentType` object that encapsulates the given
 243   *qualifiedName*, *publicId*, and *systemId* strings, representing the
 244   information contained in an XML document type declaration.
 245
 246
 247.. _dom-node-objects:
 248
 249Node Objects
 250^^^^^^^^^^^^
 251
 252All of the components of an XML document are subclasses of :class:`Node`.
 253
 254
 255.. attribute:: Node.nodeType
 256
 257   An integer representing the node type.  Symbolic constants for the types are on
 258   the :class:`Node` object: :const:`ELEMENT_NODE`, :const:`ATTRIBUTE_NODE`,
 259   :const:`TEXT_NODE`, :const:`CDATA_SECTION_NODE`, :const:`ENTITY_NODE`,
 260   :const:`PROCESSING_INSTRUCTION_NODE`, :const:`COMMENT_NODE`,
 261   :const:`DOCUMENT_NODE`, :const:`DOCUMENT_TYPE_NODE`, :const:`NOTATION_NODE`.
 262   This is a read-only attribute.
 263
 264
 265.. attribute:: Node.parentNode
 266
 267   The parent of the current node, or ``None`` for the document node. The value is
 268   always a :class:`Node` object or ``None``.  For :class:`Element` nodes, this
 269   will be the parent element, except for the root element, in which case it will
 270   be the :class:`Document` object. For :class:`Attr` nodes, this is always
 271   ``None``. This is a read-only attribute.
 272
 273
 274.. attribute:: Node.attributes
 275
 276   A :class:`NamedNodeMap` of attribute objects.  Only elements have actual values
 277   for this; others provide ``None`` for this attribute. This is a read-only
 278   attribute.
 279
 280
 281.. attribute:: Node.previousSibling
 282
 283   The node that immediately precedes this one with the same parent.  For
 284   instance the element with an end-tag that comes just before the *self*
 285   element's start-tag.  Of course, XML documents are made up of more than just
 286   elements so the previous sibling could be text, a comment, or something else.
 287   If this node is the first child of the parent, this attribute will be
 288   ``None``. This is a read-only attribute.
 289
 290
 291.. attribute:: Node.nextSibling
 292
 293   The node that immediately follows this one with the same parent.  See also
 294   :attr:`previousSibling`.  If this is the last child of the parent, this
 295   attribute will be ``None``. This is a read-only attribute.
 296
 297
 298.. attribute:: Node.childNodes
 299
 300   A list of nodes contained within this node. This is a read-only attribute.
 301
 302
 303.. attribute:: Node.firstChild
 304
 305   The first child of the node, if there are any, or ``None``. This is a read-only
 306   attribute.
 307
 308
 309.. attribute:: Node.lastChild
 310
 311   The last child of the node, if there are any, or ``None``. This is a read-only
 312   attribute.
 313
 314
 315.. attribute:: Node.localName
 316
 317   The part of the :attr:`tagName` following the colon if there is one, else the
 318   entire :attr:`tagName`.  The value is a string.
 319
 320
 321.. attribute:: Node.prefix
 322
 323   The part of the :attr:`tagName` preceding the colon if there is one, else the
 324   empty string.  The value is a string, or ``None``
 325
 326
 327.. attribute:: Node.namespaceURI
 328
 329   The namespace associated with the element name.  This will be a string or
 330   ``None``.  This is a read-only attribute.
 331
 332
 333.. attribute:: Node.nodeName
 334
 335   This has a different meaning for each node type; see the DOM specification for
 336   details.  You can always get the information you would get here from another
 337   property such as the :attr:`tagName` property for elements or the :attr:`name`
 338   property for attributes. For all node types, the value of this attribute will be
 339   either a string or ``None``.  This is a read-only attribute.
 340
 341
 342.. attribute:: Node.nodeValue
 343
 344   This has a different meaning for each node type; see the DOM specification for
 345   details.  The situation is similar to that with :attr:`nodeName`.  The value is
 346   a string or ``None``.
 347
 348
 349.. method:: Node.hasAttributes()
 350
 351   Returns true if the node has any attributes.
 352
 353
 354.. method:: Node.hasChildNodes()
 355
 356   Returns true if the node has any child nodes.
 357
 358
 359.. method:: Node.isSameNode(other)
 360
 361   Returns true if *other* refers to the same node as this node. This is especially
 362   useful for DOM implementations which use any sort of proxy architecture (because
 363   more than one object can refer to the same node).
 364
 365   .. note::
 366
 367      This is based on a proposed DOM Level 3 API which is still in the "working
 368      draft" stage, but this particular interface appears uncontroversial.  Changes
 369      from the W3C will not necessarily affect this method in the Python DOM interface
 370      (though any new W3C API for this would also be supported).
 371
 372
 373.. method:: Node.appendChild(newChild)
 374
 375   Add a new child node to this node at the end of the list of
 376   children, returning *newChild*. If the node was already in
 377   in the tree, it is removed first.
 378
 379
 380.. method:: Node.insertBefore(newChild, refChild)
 381
 382   Insert a new child node before an existing child.  It must be the case that
 383   *refChild* is a child of this node; if not, :exc:`ValueError` is raised.
 384   *newChild* is returned. If *refChild* is ``None``, it inserts *newChild* at the
 385   end of the children's list.
 386
 387
 388.. method:: Node.removeChild(oldChild)
 389
 390   Remove a child node.  *oldChild* must be a child of this node; if not,
 391   :exc:`ValueError` is raised.  *oldChild* is returned on success.  If *oldChild*
 392   will not be used further, its :meth:`unlink` method should be called.
 393
 394
 395.. method:: Node.replaceChild(newChild, oldChild)
 396
 397   Replace an existing node with a new node. It must be the case that  *oldChild*
 398   is a child of this node; if not, :exc:`ValueError` is raised.
 399
 400
 401.. method:: Node.normalize()
 402
 403   Join adjacent text nodes so that all stretches of text are stored as single
 404   :class:`Text` instances.  This simplifies processing text from a DOM tree for
 405   many applications.
 406
 407   .. versionadded:: 2.1
 408
 409
 410.. method:: Node.cloneNode(deep)
 411
 412   Clone this node.  Setting *deep* means to clone all child nodes as well.  This
 413   returns the clone.
 414
 415
 416.. _dom-nodelist-objects:
 417
 418NodeList Objects
 419^^^^^^^^^^^^^^^^
 420
 421A :class:`NodeList` represents a sequence of nodes.  These objects are used in
 422two ways in the DOM Core recommendation:  the :class:`Element` objects provides
 423one as its list of child nodes, and the :meth:`getElementsByTagName` and
 424:meth:`getElementsByTagNameNS` methods of :class:`Node` return objects with this
 425interface to represent query results.
 426
 427The DOM Level 2 recommendation defines one method and one attribute for these
 428objects:
 429
 430
 431.. method:: NodeList.item(i)
 432
 433   Return the *i*'th item from the sequence, if there is one, or ``None``.  The
 434   index *i* is not allowed to be less then zero or greater than or equal to the
 435   length of the sequence.
 436
 437
 438.. attribute:: NodeList.length
 439
 440   The number of nodes in the sequence.
 441
 442In addition, the Python DOM interface requires that some additional support is
 443provided to allow :class:`NodeList` objects to be used as Python sequences.  All
 444:class:`NodeList` implementations must include support for :meth:`__len__` and
 445:meth:`__getitem__`; this allows iteration over the :class:`NodeList` in
 446:keyword:`for` statements and proper support for the :func:`len` built-in
 447function.
 448
 449If a DOM implementation supports modification of the document, the
 450:class:`NodeList` implementation must also support the :meth:`__setitem__` and
 451:meth:`__delitem__` methods.
 452
 453
 454.. _dom-documenttype-objects:
 455
 456DocumentType Objects
 457^^^^^^^^^^^^^^^^^^^^
 458
 459Information about the notations and entities declared by a document (including
 460the external subset if the parser uses it and can provide the information) is
 461available from a :class:`DocumentType` object.  The :class:`DocumentType` for a
 462document is available from the :class:`Document` object's :attr:`doctype`
 463attribute; if there is no ``DOCTYPE`` declaration for the document, the
 464document's :attr:`doctype` attribute will be set to ``None`` instead of an
 465instance of this interface.
 466
 467:class:`DocumentType` is a specialization of :class:`Node`, and adds the
 468following attributes:
 469
 470
 471.. attribute:: DocumentType.publicId
 472
 473   The public identifier for the external subset of the document type definition.
 474   This will be a string or ``None``.
 475
 476
 477.. attribute:: DocumentType.systemId
 478
 479   The system identifier for the external subset of the document type definition.
 480   This will be a URI as a string, or ``None``.
 481
 482
 483.. attribute:: DocumentType.internalSubset
 484
 485   A string giving the complete internal subset from the document. This does not
 486   include the brackets which enclose the subset.  If the document has no internal
 487   subset, this should be ``None``.
 488
 489
 490.. attribute:: DocumentType.name
 491
 492   The name of the root element as given in the ``DOCTYPE`` declaration, if
 493   present.
 494
 495
 496.. attribute:: DocumentType.entities
 497
 498   This is a :class:`NamedNodeMap` giving the definitions of external entities.
 499   For entity names defined more than once, only the first definition is provided
 500   (others are ignored as required by the XML recommendation).  This may be
 501   ``None`` if the information is not provided by the parser, or if no entities are
 502   defined.
 503
 504
 505.. attribute:: DocumentType.notations
 506
 507   This is a :class:`NamedNodeMap` giving the definitions of notations. For
 508   notation names defined more than once, only the first definition is provided
 509   (others are ignored as required by the XML recommendation).  This may be
 510   ``None`` if the information is not provided by the parser, or if no notations
 511   are defined.
 512
 513
 514.. _dom-document-objects:
 515
 516Document Objects
 517^^^^^^^^^^^^^^^^
 518
 519A :class:`Document` represents an entire XML document, including its constituent
 520elements, attributes, processing instructions, comments etc.  Remember that it
 521inherits properties from :class:`Node`.
 522
 523
 524.. attribute:: Document.documentElement
 525
 526   The one and only root element of the document.
 527
 528
 529.. method:: Document.createElement(tagName)
 530
 531   Create and return a new element node.  The element is not inserted into the
 532   document when it is created.  You need to explicitly insert it with one of the
 533   other methods such as :meth:`insertBefore` or :meth:`appendChild`.
 534
 535
 536.. method:: Document.createElementNS(namespaceURI, tagName)
 537
 538   Create and return a new element with a namespace.  The *tagName* may have a
 539   prefix.  The element is not inserted into the document when it is created.  You
 540   need to explicitly insert it with one of the other methods such as
 541   :meth:`insertBefore` or :meth:`appendChild`.
 542
 543
 544.. method:: Document.createTextNode(data)
 545
 546   Create and return a text node containing the data passed as a parameter.  As
 547   with the other creation methods, this one does not insert the node into the
 548   tree.
 549
 550
 551.. method:: Document.createComment(data)
 552
 553   Create and return a comment node containing the data passed as a parameter.  As
 554   with the other creation methods, this one does not insert the node into the
 555   tree.
 556
 557
 558.. method:: Document.createProcessingInstruction(target, data)
 559
 560   Create and return a processing instruction node containing the *target* and
 561   *data* passed as parameters.  As with the other creation methods, this one does
 562   not insert the node into the tree.
 563
 564
 565.. method:: Document.createAttribute(name)
 566
 567   Create and return an attribute node.  This method does not associate the
 568   attribute node with any particular element.  You must use
 569   :meth:`setAttributeNode` on the appropriate :class:`Element` object to use the
 570   newly created attribute instance.
 571
 572
 573.. method:: Document.createAttributeNS(namespaceURI, qualifiedName)
 574
 575   Create and return an attribute node with a namespace.  The *tagName* may have a
 576   prefix.  This method does not associate the attribute node with any particular
 577   element.  You must use :meth:`setAttributeNode` on the appropriate
 578   :class:`Element` object to use the newly created attribute instance.
 579
 580
 581.. method:: Document.getElementsByTagName(tagName)
 582
 583   Search for all descendants (direct children, children's children, etc.) with a
 584   particular element type name.
 585
 586
 587.. method:: Document.getElementsByTagNameNS(namespaceURI, localName)
 588
 589   Search for all descendants (direct children, children's children, etc.) with a
 590   particular namespace URI and localname.  The localname is the part of the
 591   namespace after the prefix.
 592
 593
 594.. _dom-element-objects:
 595
 596Element Objects
 597^^^^^^^^^^^^^^^
 598
 599:class:`Element` is a subclass of :class:`Node`, so inherits all the attributes
 600of that class.
 601
 602
 603.. attribute:: Element.tagName
 604
 605   The element type name.  In a namespace-using document it may have colons in it.
 606   The value is a string.
 607
 608
 609.. method:: Element.getElementsByTagName(tagName)
 610
 611   Same as equivalent method in the :class:`Document` class.
 612
 613
 614.. method:: Element.getElementsByTagNameNS(namespaceURI, localName)
 615
 616   Same as equivalent method in the :class:`Document` class.
 617
 618
 619.. method:: Element.hasAttribute(name)
 620
 621   Returns true if the element has an attribute named by *name*.
 622
 623
 624.. method:: Element.hasAttributeNS(namespaceURI, localName)
 625
 626   Returns true if the element has an attribute named by *namespaceURI* and
 627   *localName*.
 628
 629
 630.. method:: Element.getAttribute(name)
 631
 632   Return the value of the attribute named by *name* as a string. If no such
 633   attribute exists, an empty string is returned, as if the attribute had no value.
 634
 635
 636.. method:: Element.getAttributeNode(attrname)
 637
 638   Return the :class:`Attr` node for the attribute named by *attrname*.
 639
 640
 641.. method:: Element.getAttributeNS(namespaceURI, localName)
 642
 643   Return the value of the attribute named by *namespaceURI* and *localName* as a
 644   string. If no such attribute exists, an empty string is returned, as if the
 645   attribute had no value.
 646
 647
 648.. method:: Element.getAttributeNodeNS(namespaceURI, localName)
 649
 650   Return an attribute value as a node, given a *namespaceURI* and *localName*.
 651
 652
 653.. method:: Element.removeAttribute(name)
 654
 655   Remove an attribute by name.  If there is no matching attribute, a
 656   :exc:`NotFoundErr` is raised.
 657
 658
 659.. method:: Element.removeAttributeNode(oldAttr)
 660
 661   Remove and return *oldAttr* from the attribute list, if present. If *oldAttr* is
 662   not present, :exc:`NotFoundErr` is raised.
 663
 664
 665.. method:: Element.removeAttributeNS(namespaceURI, localName)
 666
 667   Remove an attribute by name.  Note that it uses a localName, not a qname.  No
 668   exception is raised if there is no matching attribute.
 669
 670
 671.. method:: Element.setAttribute(name, value)
 672
 673   Set an attribute value from a string.
 674
 675
 676.. method:: Element.setAttributeNode(newAttr)
 677
 678   Add a new attribute node to the element, replacing an existing attribute if
 679   necessary if the :attr:`name` attribute matches.  If a replacement occurs, the
 680   old attribute node will be returned.  If *newAttr* is already in use,
 681   :exc:`InuseAttributeErr` will be raised.
 682
 683
 684.. method:: Element.setAttributeNodeNS(newAttr)
 685
 686   Add a new attribute node to the element, replacing an existing attribute if
 687   necessary if the :attr:`namespaceURI` and :attr:`localName` attributes match.
 688   If a replacement occurs, the old attribute node will be returned.  If *newAttr*
 689   is already in use, :exc:`InuseAttributeErr` will be raised.
 690
 691
 692.. method:: Element.setAttributeNS(namespaceURI, qname, value)
 693
 694   Set an attribute value from a string, given a *namespaceURI* and a *qname*.
 695   Note that a qname is the whole attribute name.  This is different than above.
 696
 697
 698.. _dom-attr-objects:
 699
 700Attr Objects
 701^^^^^^^^^^^^
 702
 703:class:`Attr` inherits from :class:`Node`, so inherits all its attributes.
 704
 705
 706.. attribute:: Attr.name
 707
 708   The attribute name.  In a namespace-using document it may have colons in it.
 709
 710
 711.. attribute:: Attr.localName
 712
 713   The part of the name following the colon if there is one, else the entire name.
 714   This is a read-only attribute.
 715
 716
 717.. attribute:: Attr.prefix
 718
 719   The part of the name preceding the colon if there is one, else the empty string.
 720
 721
 722.. _dom-attributelist-objects:
 723
 724NamedNodeMap Objects
 725^^^^^^^^^^^^^^^^^^^^
 726
 727:class:`NamedNodeMap` does *not* inherit from :class:`Node`.
 728
 729
 730.. attribute:: NamedNodeMap.length
 731
 732   The length of the attribute list.
 733
 734
 735.. method:: NamedNodeMap.item(index)
 736
 737   Return an attribute with a particular index.  The order you get the attributes
 738   in is arbitrary but will be consistent for the life of a DOM.  Each item is an
 739   attribute node.  Get its value with the :attr:`value` attribute.
 740
 741There are also experimental methods that give this class more mapping behavior.
 742You can use them or you can use the standardized :meth:`getAttribute\*` family
 743of methods on the :class:`Element` objects.
 744
 745
 746.. _dom-comment-objects:
 747
 748Comment Objects
 749^^^^^^^^^^^^^^^
 750
 751:class:`Comment` represents a comment in the XML document.  It is a subclass of
 752:class:`Node`, but cannot have child nodes.
 753
 754
 755.. attribute:: Comment.data
 756
 757   The content of the comment as a string.  The attribute contains all characters
 758   between the leading ``<!-``\ ``-`` and trailing ``-``\ ``->``, but does not
 759   include them.
 760
 761
 762.. _dom-text-objects:
 763
 764Text and CDATASection Objects
 765^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 766
 767The :class:`Text` interface represents text in the XML document.  If the parser
 768and DOM implementation support the DOM's XML extension, portions of the text
 769enclosed in CDATA marked sections are stored in :class:`CDATASection` objects.
 770These two interfaces are identical, but provide different values for the
 771:attr:`nodeType` attribute.
 772
 773These interfaces extend the :class:`Node` interface.  They cannot have child
 774nodes.
 775
 776
 777.. attribute:: Text.data
 778
 779   The content of the text node as a string.
 780
 781.. note::
 782
 783   The use of a :class:`CDATASection` node does not indicate that the node
 784   represents a complete CDATA marked section, only that the content of the node
 785   was part of a CDATA section.  A single CDATA section may be represented by more
 786   than one node in the document tree.  There is no way to determine whether two
 787   adjacent :class:`CDATASection` nodes represent different CDATA marked sections.
 788
 789
 790.. _dom-pi-objects:
 791
 792ProcessingInstruction Objects
 793^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 794
 795Represents a processing instruction in the XML document; this inherits from the
 796:class:`Node` interface and cannot have child nodes.
 797
 798
 799.. attribute:: ProcessingInstruction.target
 800
 801   The content of the processing instruction up to the first whitespace character.
 802   This is a read-only attribute.
 803
 804
 805.. attribute:: ProcessingInstruction.data
 806
 807   The content of the processing instruction following the first whitespace
 808   character.
 809
 810
 811.. _dom-exceptions:
 812
 813Exceptions
 814^^^^^^^^^^
 815
 816.. versionadded:: 2.1
 817
 818The DOM Level 2 recommendation defines a single exception, :exc:`DOMException`,
 819and a number of constants that allow applications to determine what sort of
 820error occurred. :exc:`DOMException` instances carry a :attr:`code` attribute
 821that provides the appropriate value for the specific exception.
 822
 823The Python DOM interface provides the constants, but also expands the set of
 824exceptions so that a specific exception exists for each of the exception codes
 825defined by the DOM.  The implementations must raise the appropriate specific
 826exception, each of which carries the appropriate value for the :attr:`code`
 827attribute.
 828
 829
 830.. exception:: DOMException
 831
 832   Base exception class used for all specific DOM exceptions.  This exception class
 833   cannot be directly instantiated.
 834
 835
 836.. exception:: DomstringSizeErr
 837
 838   Raised when a specified range of text does not fit into a string. This is not
 839   known to be used in the Python DOM implementations, but may be received from DOM
 840   implementations not written in Python.
 841
 842
 843.. exception:: HierarchyRequestErr
 844
 845   Raised when an attempt is made to insert a node where the node type is not
 846   allowed.
 847
 848
 849.. exception:: IndexSizeErr
 850
 851   Raised when an index or size parameter to a method is negative or exceeds the
 852   allowed values.
 853
 854
 855.. exception:: InuseAttributeErr
 856
 857   Raised when an attempt is made to insert an :class:`Attr` node that is already
 858   present elsewhere in the document.
 859
 860
 861.. exception:: InvalidAccessErr
 862
 863   Raised if a parameter or an operation is not supported on the underlying object.
 864
 865
 866.. exception:: InvalidCharacterErr
 867
 868   This exception is raised when a string parameter contains a character that is
 869   not permitted in the context it's being used in by the XML 1.0 recommendation.
 870   For example, attempting to create an :class:`Element` node with a space in the
 871   element type name will cause this error to be raised.
 872
 873
 874.. exception:: InvalidModificationErr
 875
 876   Raised when an attempt is made to modify the type of a node.
 877
 878
 879.. exception:: InvalidStateErr
 880
 881   Raised when an attempt is made to use an object that is not defined or is no
 882   longer usable.
 883
 884
 885.. exception:: NamespaceErr
 886
 887   If an attempt is made to change any object in a way that is not permitted with
 888   regard to the `Namespaces in XML <http://www.w3.org/TR/REC-xml-names/>`_
 889   recommendation, this exception is raised.
 890
 891
 892.. exception:: NotFoundErr
 893
 894   Exception when a node does not exist in the referenced context.  For example,
 895   :meth:`NamedNodeMap.removeNamedItem` will raise this if the node passed in does
 896   not exist in the map.
 897
 898
 899.. exception:: NotSupportedErr
 900
 901   Raised when the implementation does not support the requested type of object or
 902   operation.
 903
 904
 905.. exception:: NoDataAllowedErr
 906
 907   This is raised if data is specified for a node which does not support data.
 908
 909   .. XXX  a better explanation is needed!
 910
 911
 912.. exception:: NoModificationAllowedErr
 913
 914   Raised on attempts to modify an object where modifications are not allowed (such
 915   as for read-only nodes).
 916
 917
 918.. exception:: SyntaxErr
 919
 920   Raised when an invalid or illegal string is specified.
 921
 922   .. XXX  how is this different from InvalidCharacterErr?
 923
 924
 925.. exception:: WrongDocumentErr
 926
 927   Raised when a node is inserted in a different document than it currently belongs
 928   to, and the implementation does not support migrating the node from one document
 929   to the other.
 930
 931The exception codes defined in the DOM recommendation map to the exceptions
 932described above according to this table:
 933
 934+--------------------------------------+---------------------------------+
 935| Constant                             | Exception                       |
 936+======================================+=================================+
 937| :const:`DOMSTRING_SIZE_ERR`          | :exc:`DomstringSizeErr`         |
 938+--------------------------------------+---------------------------------+
 939| :const:`HIERARCHY_REQUEST_ERR`       | :exc:`HierarchyRequestErr`      |
 940+--------------------------------------+---------------------------------+
 941| :const:`INDEX_SIZE_ERR`              | :exc:`IndexSizeErr`             |
 942+--------------------------------------+---------------------------------+
 943| :const:`INUSE_ATTRIBUTE_ERR`         | :exc:`InuseAttributeErr`        |
 944+--------------------------------------+---------------------------------+
 945| :const:`INVALID_ACCESS_ERR`          | :exc:`InvalidAccessErr`         |
 946+--------------------------------------+---------------------------------+
 947| :const:`INVALID_CHARACTER_ERR`       | :exc:`InvalidCharacterErr`      |
 948+--------------------------------------+---------------------------------+
 949| :const:`INVALID_MODIFICATION_ERR`    | :exc:`InvalidModificationErr`   |
 950+--------------------------------------+---------------------------------+
 951| :const:`INVALID_STATE_ERR`           | :exc:`InvalidStateErr`          |
 952+--------------------------------------+---------------------------------+
 953| :const:`NAMESPACE_ERR`               | :exc:`NamespaceErr`             |
 954+--------------------------------------+---------------------------------+
 955| :const:`NOT_FOUND_ERR`               | :exc:`NotFoundErr`              |
 956+--------------------------------------+---------------------------------+
 957| :const:`NOT_SUPPORTED_ERR`           | :exc:`NotSupportedErr`          |
 958+--------------------------------------+---------------------------------+
 959| :const:`NO_DATA_ALLOWED_ERR`         | :exc:`NoDataAllowedErr`         |
 960+--------------------------------------+---------------------------------+
 961| :const:`NO_MODIFICATION_ALLOWED_ERR` | :exc:`NoModificationAllowedErr` |
 962+--------------------------------------+---------------------------------+
 963| :const:`SYNTAX_ERR`                  | :exc:`SyntaxErr`                |
 964+--------------------------------------+---------------------------------+
 965| :const:`WRONG_DOCUMENT_ERR`          | :exc:`WrongDocumentErr`         |
 966+--------------------------------------+---------------------------------+
 967
 968
 969.. _dom-conformance:
 970
 971Conformance
 972-----------
 973
 974This section describes the conformance requirements and relationships between
 975the Python DOM API, the W3C DOM recommendations, and the OMG IDL mapping for
 976Python.
 977
 978
 979.. _dom-type-mapping:
 980
 981Type Mapping
 982^^^^^^^^^^^^
 983
 984The primitive IDL types used in the DOM specification are mapped to Python types
 985according to the following table.
 986
 987+------------------+-------------------------------------------+
 988| IDL Type         | Python Type                               |
 989+==================+===========================================+
 990| ``boolean``      | ``IntegerType`` (with a value of ``0`` or |
 991|                  | ``1``)                                    |
 992+------------------+-------------------------------------------+
 993| ``int``          | ``IntegerType``                           |
 994+------------------+-------------------------------------------+
 995| ``long int``     | ``IntegerType``                           |
 996+------------------+-------------------------------------------+
 997| ``unsigned int`` | ``IntegerType``                           |
 998+------------------+-------------------------------------------+
 999
1000Additionally, the :class:`DOMString` defined in the recommendation is mapped to
1001a Python string or Unicode string.  Applications should be able to handle
1002Unicode whenever a string is returned from the DOM.
1003
1004The IDL ``null`` value is mapped to ``None``, which may be accepted or
1005provided by the implementation whenever ``null`` is allowed by the API.
1006
1007
1008.. _dom-accessor-methods:
1009
1010Accessor Methods
1011^^^^^^^^^^^^^^^^
1012
1013The mapping from OMG IDL to Python defines accessor functions for IDL
1014``attribute`` declarations in much the way the Java mapping does.
1015Mapping the IDL declarations ::
1016
1017   readonly attribute string someValue;
1018            attribute string anotherValue;
1019
1020yields three accessor functions:  a "get" method for :attr:`someValue`
1021(:meth:`_get_someValue`), and "get" and "set" methods for :attr:`anotherValue`
1022(:meth:`_get_anotherValue` and :meth:`_set_anotherValue`).  The mapping, in
1023particular, does not require that the IDL attributes are accessible as normal
1024Python attributes:  ``object.someValue`` is *not* required to work, and may
1025raise an :exc:`AttributeError`.
1026
1027The Python DOM API, however, *does* require that normal attribute access work.
1028This means that the typical surrogates generated by Python IDL compilers are not
1029likely to work, and wrapper objects may be needed on the client if the DOM
1030objects are accessed via CORBA. While this does require some additional
1031consideration for CORBA DOM clients, the implementers with experience using DOM
1032over CORBA from Python do not consider this a problem.  Attributes that are
1033declared ``readonly`` may not restrict write access in all DOM
1034implementations.
1035
1036In the Python DOM API, accessor functions are not required.  If provided, they
1037should take the form defined by the Python IDL mapping, but these methods are
1038considered unnecessary since the attributes are accessible directly from Python.
1039"Set" accessors should never be provided for ``readonly`` attributes.
1040
1041The IDL definitions do not fully embody the requirements of the W3C DOM API,
1042such as the notion of certain objects, such as the return value of
1043:meth:`getElementsByTagName`, being "live".  The Python DOM API does not require
1044implementations to enforce such requirements.
1045