Doc/lib/xmldom.tex

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