Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`xml.dom` --- The Document Object Model API |
| 2 | ================================================ |
| 3 | |
| 4 | .. module:: xml.dom |
| 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> |
| 8 | |
| 9 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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. |
| 15 | |
| 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. |
| 23 | |
| 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. |
| 28 | |
| 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 |
Guido van Rossum | 0d3fb8a | 2007-11-26 23:23:18 +0000 | [diff] [blame] | 31 | DOM Level 2 recommendation. |
| 32 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 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 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
| 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. |
| 51 | |
| 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. |
| 56 | |
| 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. |
| 62 | |
| 63 | |
| 64 | .. seealso:: |
| 65 | |
| 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. |
| 68 | |
| 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`. |
| 71 | |
Benjamin Peterson | 2021100 | 2009-11-25 18:34:42 +0000 | [diff] [blame] | 72 | `Python Language Mapping Specification <http://www.omg.org/spec/PYTH/1.2/PDF>`_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | This specifies the mapping from OMG IDL to Python. |
| 74 | |
| 75 | |
| 76 | Module Contents |
| 77 | --------------- |
| 78 | |
| 79 | The :mod:`xml.dom` contains the following functions: |
| 80 | |
| 81 | |
| 82 | .. function:: registerDOMImplementation(name, factory) |
| 83 | |
| 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). |
| 89 | |
| 90 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 91 | .. function:: getDOMImplementation(name=None, features=()) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
| 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. |
| 98 | |
| 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. |
| 104 | |
| 105 | Some convenience constants are also provided: |
| 106 | |
| 107 | |
| 108 | .. data:: EMPTY_NAMESPACE |
| 109 | |
| 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. |
| 113 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
| 115 | .. data:: XML_NAMESPACE |
| 116 | |
| 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). |
| 119 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | |
| 121 | .. data:: XMLNS_NAMESPACE |
| 122 | |
| 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). |
| 126 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 127 | |
| 128 | .. data:: XHTML_NAMESPACE |
| 129 | |
| 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). |
| 132 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 133 | |
| 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 |
| 141 | specifications. |
| 142 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 143 | .. Should the Node documentation go here? |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | |
| 145 | |
| 146 | .. _dom-objects: |
| 147 | |
| 148 | Objects in the DOM |
| 149 | ------------------ |
| 150 | |
| 151 | The definitive documentation for the DOM is the DOM specification from the W3C. |
| 152 | |
| 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 |
| 155 | yet documented. |
| 156 | |
| 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 | |
| 167 | | | | nodes. | |
| 168 | +--------------------------------+-----------------------------------+---------------------------------+ |
| 169 | | :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the | |
| 170 | | | | declarations needed to process | |
| 171 | | | | a document. | |
| 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 | |
| 177 | | | | hierarchy. | |
| 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 | +--------------------------------+-----------------------------------+---------------------------------+ |
| 191 | |
| 192 | An additional section describes the exceptions defined for working with the DOM |
| 193 | in Python. |
| 194 | |
| 195 | |
| 196 | .. _dom-implementation-objects: |
| 197 | |
| 198 | DOMImplementation Objects |
| 199 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 200 | |
| 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. |
| 205 | |
| 206 | |
| 207 | .. method:: DOMImplementation.hasFeature(feature, version) |
| 208 | |
| 209 | Return true if the feature identified by the pair of strings *feature* and |
| 210 | *version* is implemented. |
| 211 | |
| 212 | |
| 213 | .. method:: DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype) |
| 214 | |
| 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. |
| 221 | |
| 222 | |
| 223 | .. method:: DOMImplementation.createDocumentType(qualifiedName, publicId, systemId) |
| 224 | |
| 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. |
| 228 | |
| 229 | |
| 230 | .. _dom-node-objects: |
| 231 | |
| 232 | Node Objects |
| 233 | ^^^^^^^^^^^^ |
| 234 | |
| 235 | All of the components of an XML document are subclasses of :class:`Node`. |
| 236 | |
| 237 | |
| 238 | .. attribute:: Node.nodeType |
| 239 | |
| 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. |
| 246 | |
| 247 | |
| 248 | .. attribute:: Node.parentNode |
| 249 | |
| 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. |
| 255 | |
| 256 | |
| 257 | .. attribute:: Node.attributes |
| 258 | |
| 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 |
| 261 | attribute. |
| 262 | |
| 263 | |
| 264 | .. attribute:: Node.previousSibling |
| 265 | |
| 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. |
| 272 | |
| 273 | |
| 274 | .. attribute:: Node.nextSibling |
| 275 | |
| 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. |
| 279 | |
| 280 | |
| 281 | .. attribute:: Node.childNodes |
| 282 | |
| 283 | A list of nodes contained within this node. This is a read-only attribute. |
| 284 | |
| 285 | |
| 286 | .. attribute:: Node.firstChild |
| 287 | |
| 288 | The first child of the node, if there are any, or ``None``. This is a read-only |
| 289 | attribute. |
| 290 | |
| 291 | |
| 292 | .. attribute:: Node.lastChild |
| 293 | |
| 294 | The last child of the node, if there are any, or ``None``. This is a read-only |
| 295 | attribute. |
| 296 | |
| 297 | |
| 298 | .. attribute:: Node.localName |
| 299 | |
| 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. |
| 302 | |
| 303 | |
| 304 | .. attribute:: Node.prefix |
| 305 | |
| 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`` |
| 308 | |
| 309 | |
| 310 | .. attribute:: Node.namespaceURI |
| 311 | |
| 312 | The namespace associated with the element name. This will be a string or |
| 313 | ``None``. This is a read-only attribute. |
| 314 | |
| 315 | |
| 316 | .. attribute:: Node.nodeName |
| 317 | |
| 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. |
| 323 | |
| 324 | |
| 325 | .. attribute:: Node.nodeValue |
| 326 | |
| 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``. |
| 330 | |
| 331 | |
| 332 | .. method:: Node.hasAttributes() |
| 333 | |
| 334 | Returns true if the node has any attributes. |
| 335 | |
| 336 | |
| 337 | .. method:: Node.hasChildNodes() |
| 338 | |
| 339 | Returns true if the node has any child nodes. |
| 340 | |
| 341 | |
| 342 | .. method:: Node.isSameNode(other) |
| 343 | |
| 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). |
| 347 | |
| 348 | .. note:: |
| 349 | |
| 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). |
| 354 | |
| 355 | |
| 356 | .. method:: Node.appendChild(newChild) |
| 357 | |
Guido van Rossum | 0d3fb8a | 2007-11-26 23:23:18 +0000 | [diff] [blame] | 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 | in the tree, it is removed first. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 361 | |
| 362 | |
| 363 | .. method:: Node.insertBefore(newChild, refChild) |
| 364 | |
| 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. |
| 369 | |
| 370 | |
| 371 | .. method:: Node.removeChild(oldChild) |
| 372 | |
| 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. |
| 376 | |
| 377 | |
| 378 | .. method:: Node.replaceChild(newChild, oldChild) |
| 379 | |
| 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. |
| 382 | |
| 383 | |
| 384 | .. method:: Node.normalize() |
| 385 | |
| 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 |
| 388 | many applications. |
| 389 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 390 | |
| 391 | .. method:: Node.cloneNode(deep) |
| 392 | |
| 393 | Clone this node. Setting *deep* means to clone all child nodes as well. This |
| 394 | returns the clone. |
| 395 | |
| 396 | |
| 397 | .. _dom-nodelist-objects: |
| 398 | |
| 399 | NodeList Objects |
| 400 | ^^^^^^^^^^^^^^^^ |
| 401 | |
| 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. |
| 407 | |
| 408 | The DOM Level 2 recommendation defines one method and one attribute for these |
| 409 | objects: |
| 410 | |
| 411 | |
| 412 | .. method:: NodeList.item(i) |
| 413 | |
| 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. |
| 417 | |
| 418 | |
| 419 | .. attribute:: NodeList.length |
| 420 | |
| 421 | The number of nodes in the sequence. |
| 422 | |
| 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 :meth:`__len__` and |
| 426 | :meth:`__getitem__`; this allows iteration over the :class:`NodeList` in |
| 427 | :keyword:`for` statements and proper support for the :func:`len` built-in |
| 428 | function. |
| 429 | |
| 430 | If a DOM implementation supports modification of the document, the |
| 431 | :class:`NodeList` implementation must also support the :meth:`__setitem__` and |
| 432 | :meth:`__delitem__` methods. |
| 433 | |
| 434 | |
| 435 | .. _dom-documenttype-objects: |
| 436 | |
| 437 | DocumentType Objects |
| 438 | ^^^^^^^^^^^^^^^^^^^^ |
| 439 | |
| 440 | Information about the notations and entities declared by a document (including |
| 441 | the external subset if the parser uses it and can provide the information) is |
| 442 | available from a :class:`DocumentType` object. The :class:`DocumentType` for a |
| 443 | document is available from the :class:`Document` object's :attr:`doctype` |
| 444 | attribute; if there is no ``DOCTYPE`` declaration for the document, the |
| 445 | document's :attr:`doctype` attribute will be set to ``None`` instead of an |
| 446 | instance of this interface. |
| 447 | |
| 448 | :class:`DocumentType` is a specialization of :class:`Node`, and adds the |
| 449 | following attributes: |
| 450 | |
| 451 | |
| 452 | .. attribute:: DocumentType.publicId |
| 453 | |
| 454 | The public identifier for the external subset of the document type definition. |
| 455 | This will be a string or ``None``. |
| 456 | |
| 457 | |
| 458 | .. attribute:: DocumentType.systemId |
| 459 | |
| 460 | The system identifier for the external subset of the document type definition. |
| 461 | This will be a URI as a string, or ``None``. |
| 462 | |
| 463 | |
| 464 | .. attribute:: DocumentType.internalSubset |
| 465 | |
| 466 | A string giving the complete internal subset from the document. This does not |
| 467 | include the brackets which enclose the subset. If the document has no internal |
| 468 | subset, this should be ``None``. |
| 469 | |
| 470 | |
| 471 | .. attribute:: DocumentType.name |
| 472 | |
| 473 | The name of the root element as given in the ``DOCTYPE`` declaration, if |
| 474 | present. |
| 475 | |
| 476 | |
| 477 | .. attribute:: DocumentType.entities |
| 478 | |
| 479 | This is a :class:`NamedNodeMap` giving the definitions of external entities. |
| 480 | For entity names defined more than once, only the first definition is provided |
| 481 | (others are ignored as required by the XML recommendation). This may be |
| 482 | ``None`` if the information is not provided by the parser, or if no entities are |
| 483 | defined. |
| 484 | |
| 485 | |
| 486 | .. attribute:: DocumentType.notations |
| 487 | |
| 488 | This is a :class:`NamedNodeMap` giving the definitions of notations. For |
| 489 | notation names defined more than once, only the first definition is provided |
| 490 | (others are ignored as required by the XML recommendation). This may be |
| 491 | ``None`` if the information is not provided by the parser, or if no notations |
| 492 | are defined. |
| 493 | |
| 494 | |
| 495 | .. _dom-document-objects: |
| 496 | |
| 497 | Document Objects |
| 498 | ^^^^^^^^^^^^^^^^ |
| 499 | |
| 500 | A :class:`Document` represents an entire XML document, including its constituent |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 501 | elements, attributes, processing instructions, comments etc. Remember that it |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 502 | inherits properties from :class:`Node`. |
| 503 | |
| 504 | |
| 505 | .. attribute:: Document.documentElement |
| 506 | |
| 507 | The one and only root element of the document. |
| 508 | |
| 509 | |
| 510 | .. method:: Document.createElement(tagName) |
| 511 | |
| 512 | Create and return a new element node. The element is not inserted into the |
| 513 | document when it is created. You need to explicitly insert it with one of the |
| 514 | other methods such as :meth:`insertBefore` or :meth:`appendChild`. |
| 515 | |
| 516 | |
| 517 | .. method:: Document.createElementNS(namespaceURI, tagName) |
| 518 | |
| 519 | Create and return a new element with a namespace. The *tagName* may have a |
| 520 | prefix. The element is not inserted into the document when it is created. You |
| 521 | need to explicitly insert it with one of the other methods such as |
| 522 | :meth:`insertBefore` or :meth:`appendChild`. |
| 523 | |
| 524 | |
| 525 | .. method:: Document.createTextNode(data) |
| 526 | |
| 527 | Create and return a text node containing the data passed as a parameter. As |
| 528 | with the other creation methods, this one does not insert the node into the |
| 529 | tree. |
| 530 | |
| 531 | |
| 532 | .. method:: Document.createComment(data) |
| 533 | |
| 534 | Create and return a comment node containing the data passed as a parameter. As |
| 535 | with the other creation methods, this one does not insert the node into the |
| 536 | tree. |
| 537 | |
| 538 | |
| 539 | .. method:: Document.createProcessingInstruction(target, data) |
| 540 | |
| 541 | Create and return a processing instruction node containing the *target* and |
| 542 | *data* passed as parameters. As with the other creation methods, this one does |
| 543 | not insert the node into the tree. |
| 544 | |
| 545 | |
| 546 | .. method:: Document.createAttribute(name) |
| 547 | |
| 548 | Create and return an attribute node. This method does not associate the |
| 549 | attribute node with any particular element. You must use |
| 550 | :meth:`setAttributeNode` on the appropriate :class:`Element` object to use the |
| 551 | newly created attribute instance. |
| 552 | |
| 553 | |
| 554 | .. method:: Document.createAttributeNS(namespaceURI, qualifiedName) |
| 555 | |
| 556 | Create and return an attribute node with a namespace. The *tagName* may have a |
| 557 | prefix. This method does not associate the attribute node with any particular |
| 558 | element. You must use :meth:`setAttributeNode` on the appropriate |
| 559 | :class:`Element` object to use the newly created attribute instance. |
| 560 | |
| 561 | |
| 562 | .. method:: Document.getElementsByTagName(tagName) |
| 563 | |
| 564 | Search for all descendants (direct children, children's children, etc.) with a |
| 565 | particular element type name. |
| 566 | |
| 567 | |
| 568 | .. method:: Document.getElementsByTagNameNS(namespaceURI, localName) |
| 569 | |
| 570 | Search for all descendants (direct children, children's children, etc.) with a |
| 571 | particular namespace URI and localname. The localname is the part of the |
| 572 | namespace after the prefix. |
| 573 | |
| 574 | |
| 575 | .. _dom-element-objects: |
| 576 | |
| 577 | Element Objects |
| 578 | ^^^^^^^^^^^^^^^ |
| 579 | |
| 580 | :class:`Element` is a subclass of :class:`Node`, so inherits all the attributes |
| 581 | of that class. |
| 582 | |
| 583 | |
| 584 | .. attribute:: Element.tagName |
| 585 | |
| 586 | The element type name. In a namespace-using document it may have colons in it. |
| 587 | The value is a string. |
| 588 | |
| 589 | |
| 590 | .. method:: Element.getElementsByTagName(tagName) |
| 591 | |
| 592 | Same as equivalent method in the :class:`Document` class. |
| 593 | |
| 594 | |
Benjamin Peterson | f07d002 | 2009-03-21 17:31:58 +0000 | [diff] [blame] | 595 | .. method:: Element.getElementsByTagNameNS(namespaceURI, localName) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 596 | |
| 597 | Same as equivalent method in the :class:`Document` class. |
| 598 | |
| 599 | |
| 600 | .. method:: Element.hasAttribute(name) |
| 601 | |
| 602 | Returns true if the element has an attribute named by *name*. |
| 603 | |
| 604 | |
| 605 | .. method:: Element.hasAttributeNS(namespaceURI, localName) |
| 606 | |
| 607 | Returns true if the element has an attribute named by *namespaceURI* and |
| 608 | *localName*. |
| 609 | |
| 610 | |
| 611 | .. method:: Element.getAttribute(name) |
| 612 | |
| 613 | Return the value of the attribute named by *name* as a string. If no such |
| 614 | attribute exists, an empty string is returned, as if the attribute had no value. |
| 615 | |
| 616 | |
| 617 | .. method:: Element.getAttributeNode(attrname) |
| 618 | |
| 619 | Return the :class:`Attr` node for the attribute named by *attrname*. |
| 620 | |
| 621 | |
| 622 | .. method:: Element.getAttributeNS(namespaceURI, localName) |
| 623 | |
| 624 | Return the value of the attribute named by *namespaceURI* and *localName* as a |
| 625 | string. If no such attribute exists, an empty string is returned, as if the |
| 626 | attribute had no value. |
| 627 | |
| 628 | |
| 629 | .. method:: Element.getAttributeNodeNS(namespaceURI, localName) |
| 630 | |
| 631 | Return an attribute value as a node, given a *namespaceURI* and *localName*. |
| 632 | |
| 633 | |
| 634 | .. method:: Element.removeAttribute(name) |
| 635 | |
Christian Heimes | d3eb5a15 | 2008-02-24 00:38:49 +0000 | [diff] [blame] | 636 | Remove an attribute by name. If there is no matching attribute, a |
| 637 | :exc:`NotFoundErr` is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 638 | |
| 639 | |
| 640 | .. method:: Element.removeAttributeNode(oldAttr) |
| 641 | |
| 642 | Remove and return *oldAttr* from the attribute list, if present. If *oldAttr* is |
| 643 | not present, :exc:`NotFoundErr` is raised. |
| 644 | |
| 645 | |
| 646 | .. method:: Element.removeAttributeNS(namespaceURI, localName) |
| 647 | |
| 648 | Remove an attribute by name. Note that it uses a localName, not a qname. No |
| 649 | exception is raised if there is no matching attribute. |
| 650 | |
| 651 | |
| 652 | .. method:: Element.setAttribute(name, value) |
| 653 | |
| 654 | Set an attribute value from a string. |
| 655 | |
| 656 | |
| 657 | .. method:: Element.setAttributeNode(newAttr) |
| 658 | |
| 659 | Add a new attribute node to the element, replacing an existing attribute if |
| 660 | necessary if the :attr:`name` attribute matches. If a replacement occurs, the |
| 661 | old attribute node will be returned. If *newAttr* is already in use, |
| 662 | :exc:`InuseAttributeErr` will be raised. |
| 663 | |
| 664 | |
| 665 | .. method:: Element.setAttributeNodeNS(newAttr) |
| 666 | |
| 667 | Add a new attribute node to the element, replacing an existing attribute if |
| 668 | necessary if the :attr:`namespaceURI` and :attr:`localName` attributes match. |
| 669 | If a replacement occurs, the old attribute node will be returned. If *newAttr* |
| 670 | is already in use, :exc:`InuseAttributeErr` will be raised. |
| 671 | |
| 672 | |
| 673 | .. method:: Element.setAttributeNS(namespaceURI, qname, value) |
| 674 | |
| 675 | Set an attribute value from a string, given a *namespaceURI* and a *qname*. |
| 676 | Note that a qname is the whole attribute name. This is different than above. |
| 677 | |
| 678 | |
| 679 | .. _dom-attr-objects: |
| 680 | |
| 681 | Attr Objects |
| 682 | ^^^^^^^^^^^^ |
| 683 | |
| 684 | :class:`Attr` inherits from :class:`Node`, so inherits all its attributes. |
| 685 | |
| 686 | |
| 687 | .. attribute:: Attr.name |
| 688 | |
Fred Drake | ade1917 | 2010-05-12 02:34:50 +0000 | [diff] [blame] | 689 | The attribute name. |
| 690 | In a namespace-using document it may include a colon. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 691 | |
| 692 | |
| 693 | .. attribute:: Attr.localName |
| 694 | |
Fred Drake | ade1917 | 2010-05-12 02:34:50 +0000 | [diff] [blame] | 695 | The part of the name following the colon if there is one, else the |
| 696 | entire name. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 697 | This is a read-only attribute. |
| 698 | |
| 699 | |
| 700 | .. attribute:: Attr.prefix |
| 701 | |
Fred Drake | ade1917 | 2010-05-12 02:34:50 +0000 | [diff] [blame] | 702 | The part of the name preceding the colon if there is one, else the |
| 703 | empty string. |
| 704 | |
| 705 | |
| 706 | .. attribute:: Attr.value |
| 707 | |
| 708 | The text value of the attribute. This is a synonym for the |
| 709 | :attr:`nodeValue` attribute. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 710 | |
| 711 | |
| 712 | .. _dom-attributelist-objects: |
| 713 | |
| 714 | NamedNodeMap Objects |
| 715 | ^^^^^^^^^^^^^^^^^^^^ |
| 716 | |
| 717 | :class:`NamedNodeMap` does *not* inherit from :class:`Node`. |
| 718 | |
| 719 | |
| 720 | .. attribute:: NamedNodeMap.length |
| 721 | |
| 722 | The length of the attribute list. |
| 723 | |
| 724 | |
| 725 | .. method:: NamedNodeMap.item(index) |
| 726 | |
| 727 | Return an attribute with a particular index. The order you get the attributes |
| 728 | in is arbitrary but will be consistent for the life of a DOM. Each item is an |
| 729 | attribute node. Get its value with the :attr:`value` attribute. |
| 730 | |
| 731 | There are also experimental methods that give this class more mapping behavior. |
| 732 | You can use them or you can use the standardized :meth:`getAttribute\*` family |
| 733 | of methods on the :class:`Element` objects. |
| 734 | |
| 735 | |
| 736 | .. _dom-comment-objects: |
| 737 | |
| 738 | Comment Objects |
| 739 | ^^^^^^^^^^^^^^^ |
| 740 | |
| 741 | :class:`Comment` represents a comment in the XML document. It is a subclass of |
| 742 | :class:`Node`, but cannot have child nodes. |
| 743 | |
| 744 | |
| 745 | .. attribute:: Comment.data |
| 746 | |
| 747 | The content of the comment as a string. The attribute contains all characters |
| 748 | between the leading ``<!-``\ ``-`` and trailing ``-``\ ``->``, but does not |
| 749 | include them. |
| 750 | |
| 751 | |
| 752 | .. _dom-text-objects: |
| 753 | |
| 754 | Text and CDATASection Objects |
| 755 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 756 | |
| 757 | The :class:`Text` interface represents text in the XML document. If the parser |
| 758 | and DOM implementation support the DOM's XML extension, portions of the text |
| 759 | enclosed in CDATA marked sections are stored in :class:`CDATASection` objects. |
| 760 | These two interfaces are identical, but provide different values for the |
| 761 | :attr:`nodeType` attribute. |
| 762 | |
| 763 | These interfaces extend the :class:`Node` interface. They cannot have child |
| 764 | nodes. |
| 765 | |
| 766 | |
| 767 | .. attribute:: Text.data |
| 768 | |
| 769 | The content of the text node as a string. |
| 770 | |
| 771 | .. note:: |
| 772 | |
| 773 | The use of a :class:`CDATASection` node does not indicate that the node |
| 774 | represents a complete CDATA marked section, only that the content of the node |
| 775 | was part of a CDATA section. A single CDATA section may be represented by more |
| 776 | than one node in the document tree. There is no way to determine whether two |
| 777 | adjacent :class:`CDATASection` nodes represent different CDATA marked sections. |
| 778 | |
| 779 | |
| 780 | .. _dom-pi-objects: |
| 781 | |
| 782 | ProcessingInstruction Objects |
| 783 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 784 | |
| 785 | Represents a processing instruction in the XML document; this inherits from the |
| 786 | :class:`Node` interface and cannot have child nodes. |
| 787 | |
| 788 | |
| 789 | .. attribute:: ProcessingInstruction.target |
| 790 | |
| 791 | The content of the processing instruction up to the first whitespace character. |
| 792 | This is a read-only attribute. |
| 793 | |
| 794 | |
| 795 | .. attribute:: ProcessingInstruction.data |
| 796 | |
| 797 | The content of the processing instruction following the first whitespace |
| 798 | character. |
| 799 | |
| 800 | |
| 801 | .. _dom-exceptions: |
| 802 | |
| 803 | Exceptions |
| 804 | ^^^^^^^^^^ |
| 805 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 806 | The DOM Level 2 recommendation defines a single exception, :exc:`DOMException`, |
| 807 | and a number of constants that allow applications to determine what sort of |
| 808 | error occurred. :exc:`DOMException` instances carry a :attr:`code` attribute |
| 809 | that provides the appropriate value for the specific exception. |
| 810 | |
| 811 | The Python DOM interface provides the constants, but also expands the set of |
| 812 | exceptions so that a specific exception exists for each of the exception codes |
| 813 | defined by the DOM. The implementations must raise the appropriate specific |
| 814 | exception, each of which carries the appropriate value for the :attr:`code` |
| 815 | attribute. |
| 816 | |
| 817 | |
| 818 | .. exception:: DOMException |
| 819 | |
| 820 | Base exception class used for all specific DOM exceptions. This exception class |
| 821 | cannot be directly instantiated. |
| 822 | |
| 823 | |
| 824 | .. exception:: DomstringSizeErr |
| 825 | |
| 826 | Raised when a specified range of text does not fit into a string. This is not |
| 827 | known to be used in the Python DOM implementations, but may be received from DOM |
| 828 | implementations not written in Python. |
| 829 | |
| 830 | |
| 831 | .. exception:: HierarchyRequestErr |
| 832 | |
| 833 | Raised when an attempt is made to insert a node where the node type is not |
| 834 | allowed. |
| 835 | |
| 836 | |
| 837 | .. exception:: IndexSizeErr |
| 838 | |
| 839 | Raised when an index or size parameter to a method is negative or exceeds the |
| 840 | allowed values. |
| 841 | |
| 842 | |
| 843 | .. exception:: InuseAttributeErr |
| 844 | |
| 845 | Raised when an attempt is made to insert an :class:`Attr` node that is already |
| 846 | present elsewhere in the document. |
| 847 | |
| 848 | |
| 849 | .. exception:: InvalidAccessErr |
| 850 | |
| 851 | Raised if a parameter or an operation is not supported on the underlying object. |
| 852 | |
| 853 | |
| 854 | .. exception:: InvalidCharacterErr |
| 855 | |
| 856 | This exception is raised when a string parameter contains a character that is |
| 857 | not permitted in the context it's being used in by the XML 1.0 recommendation. |
| 858 | For example, attempting to create an :class:`Element` node with a space in the |
| 859 | element type name will cause this error to be raised. |
| 860 | |
| 861 | |
| 862 | .. exception:: InvalidModificationErr |
| 863 | |
| 864 | Raised when an attempt is made to modify the type of a node. |
| 865 | |
| 866 | |
| 867 | .. exception:: InvalidStateErr |
| 868 | |
| 869 | Raised when an attempt is made to use an object that is not defined or is no |
| 870 | longer usable. |
| 871 | |
| 872 | |
| 873 | .. exception:: NamespaceErr |
| 874 | |
| 875 | If an attempt is made to change any object in a way that is not permitted with |
| 876 | regard to the `Namespaces in XML <http://www.w3.org/TR/REC-xml-names/>`_ |
| 877 | recommendation, this exception is raised. |
| 878 | |
| 879 | |
| 880 | .. exception:: NotFoundErr |
| 881 | |
| 882 | Exception when a node does not exist in the referenced context. For example, |
| 883 | :meth:`NamedNodeMap.removeNamedItem` will raise this if the node passed in does |
| 884 | not exist in the map. |
| 885 | |
| 886 | |
| 887 | .. exception:: NotSupportedErr |
| 888 | |
| 889 | Raised when the implementation does not support the requested type of object or |
| 890 | operation. |
| 891 | |
| 892 | |
| 893 | .. exception:: NoDataAllowedErr |
| 894 | |
| 895 | This is raised if data is specified for a node which does not support data. |
| 896 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 897 | .. XXX a better explanation is needed! |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 898 | |
| 899 | |
| 900 | .. exception:: NoModificationAllowedErr |
| 901 | |
| 902 | Raised on attempts to modify an object where modifications are not allowed (such |
| 903 | as for read-only nodes). |
| 904 | |
| 905 | |
| 906 | .. exception:: SyntaxErr |
| 907 | |
| 908 | Raised when an invalid or illegal string is specified. |
| 909 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 910 | .. XXX how is this different from InvalidCharacterErr? |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 911 | |
| 912 | |
| 913 | .. exception:: WrongDocumentErr |
| 914 | |
| 915 | Raised when a node is inserted in a different document than it currently belongs |
| 916 | to, and the implementation does not support migrating the node from one document |
| 917 | to the other. |
| 918 | |
| 919 | The exception codes defined in the DOM recommendation map to the exceptions |
| 920 | described above according to this table: |
| 921 | |
| 922 | +--------------------------------------+---------------------------------+ |
| 923 | | Constant | Exception | |
| 924 | +======================================+=================================+ |
| 925 | | :const:`DOMSTRING_SIZE_ERR` | :exc:`DomstringSizeErr` | |
| 926 | +--------------------------------------+---------------------------------+ |
| 927 | | :const:`HIERARCHY_REQUEST_ERR` | :exc:`HierarchyRequestErr` | |
| 928 | +--------------------------------------+---------------------------------+ |
| 929 | | :const:`INDEX_SIZE_ERR` | :exc:`IndexSizeErr` | |
| 930 | +--------------------------------------+---------------------------------+ |
| 931 | | :const:`INUSE_ATTRIBUTE_ERR` | :exc:`InuseAttributeErr` | |
| 932 | +--------------------------------------+---------------------------------+ |
| 933 | | :const:`INVALID_ACCESS_ERR` | :exc:`InvalidAccessErr` | |
| 934 | +--------------------------------------+---------------------------------+ |
| 935 | | :const:`INVALID_CHARACTER_ERR` | :exc:`InvalidCharacterErr` | |
| 936 | +--------------------------------------+---------------------------------+ |
| 937 | | :const:`INVALID_MODIFICATION_ERR` | :exc:`InvalidModificationErr` | |
| 938 | +--------------------------------------+---------------------------------+ |
| 939 | | :const:`INVALID_STATE_ERR` | :exc:`InvalidStateErr` | |
| 940 | +--------------------------------------+---------------------------------+ |
| 941 | | :const:`NAMESPACE_ERR` | :exc:`NamespaceErr` | |
| 942 | +--------------------------------------+---------------------------------+ |
| 943 | | :const:`NOT_FOUND_ERR` | :exc:`NotFoundErr` | |
| 944 | +--------------------------------------+---------------------------------+ |
| 945 | | :const:`NOT_SUPPORTED_ERR` | :exc:`NotSupportedErr` | |
| 946 | +--------------------------------------+---------------------------------+ |
| 947 | | :const:`NO_DATA_ALLOWED_ERR` | :exc:`NoDataAllowedErr` | |
| 948 | +--------------------------------------+---------------------------------+ |
| 949 | | :const:`NO_MODIFICATION_ALLOWED_ERR` | :exc:`NoModificationAllowedErr` | |
| 950 | +--------------------------------------+---------------------------------+ |
| 951 | | :const:`SYNTAX_ERR` | :exc:`SyntaxErr` | |
| 952 | +--------------------------------------+---------------------------------+ |
| 953 | | :const:`WRONG_DOCUMENT_ERR` | :exc:`WrongDocumentErr` | |
| 954 | +--------------------------------------+---------------------------------+ |
| 955 | |
| 956 | |
| 957 | .. _dom-conformance: |
| 958 | |
| 959 | Conformance |
| 960 | ----------- |
| 961 | |
| 962 | This section describes the conformance requirements and relationships between |
| 963 | the Python DOM API, the W3C DOM recommendations, and the OMG IDL mapping for |
| 964 | Python. |
| 965 | |
| 966 | |
| 967 | .. _dom-type-mapping: |
| 968 | |
| 969 | Type Mapping |
| 970 | ^^^^^^^^^^^^ |
| 971 | |
Andrew M. Kuchling | 4d4d1ce | 2010-07-25 22:57:12 +0000 | [diff] [blame] | 972 | The IDL types used in the DOM specification are mapped to Python types |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 973 | according to the following table. |
| 974 | |
| 975 | +------------------+-------------------------------------------+ |
| 976 | | IDL Type | Python Type | |
| 977 | +==================+===========================================+ |
Andrew M. Kuchling | 4d4d1ce | 2010-07-25 22:57:12 +0000 | [diff] [blame] | 978 | | ``boolean`` | ``bool`` or ``int`` | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 979 | +------------------+-------------------------------------------+ |
Andrew M. Kuchling | 4d4d1ce | 2010-07-25 22:57:12 +0000 | [diff] [blame] | 980 | | ``int`` | ``int`` | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 981 | +------------------+-------------------------------------------+ |
Andrew M. Kuchling | 4d4d1ce | 2010-07-25 22:57:12 +0000 | [diff] [blame] | 982 | | ``long int`` | ``int`` | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 983 | +------------------+-------------------------------------------+ |
Andrew M. Kuchling | 4d4d1ce | 2010-07-25 22:57:12 +0000 | [diff] [blame] | 984 | | ``unsigned int`` | ``int`` | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 985 | +------------------+-------------------------------------------+ |
Andrew M. Kuchling | 4d4d1ce | 2010-07-25 22:57:12 +0000 | [diff] [blame] | 986 | | ``DOMString`` | ``str`` or ``bytes`` | |
| 987 | +------------------+-------------------------------------------+ |
| 988 | | ``null`` | ``None`` | |
| 989 | +------------------+-------------------------------------------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 990 | |
| 991 | .. _dom-accessor-methods: |
| 992 | |
| 993 | Accessor Methods |
| 994 | ^^^^^^^^^^^^^^^^ |
| 995 | |
| 996 | The mapping from OMG IDL to Python defines accessor functions for IDL |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 997 | ``attribute`` declarations in much the way the Java mapping does. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 998 | Mapping the IDL declarations :: |
| 999 | |
| 1000 | readonly attribute string someValue; |
| 1001 | attribute string anotherValue; |
| 1002 | |
| 1003 | yields three accessor functions: a "get" method for :attr:`someValue` |
| 1004 | (:meth:`_get_someValue`), and "get" and "set" methods for :attr:`anotherValue` |
| 1005 | (:meth:`_get_anotherValue` and :meth:`_set_anotherValue`). The mapping, in |
| 1006 | particular, does not require that the IDL attributes are accessible as normal |
| 1007 | Python attributes: ``object.someValue`` is *not* required to work, and may |
| 1008 | raise an :exc:`AttributeError`. |
| 1009 | |
| 1010 | The Python DOM API, however, *does* require that normal attribute access work. |
| 1011 | This means that the typical surrogates generated by Python IDL compilers are not |
| 1012 | likely to work, and wrapper objects may be needed on the client if the DOM |
| 1013 | objects are accessed via CORBA. While this does require some additional |
| 1014 | consideration for CORBA DOM clients, the implementers with experience using DOM |
| 1015 | over CORBA from Python do not consider this a problem. Attributes that are |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 1016 | declared ``readonly`` may not restrict write access in all DOM |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1017 | implementations. |
| 1018 | |
| 1019 | In the Python DOM API, accessor functions are not required. If provided, they |
| 1020 | should take the form defined by the Python IDL mapping, but these methods are |
| 1021 | considered unnecessary since the attributes are accessible directly from Python. |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 1022 | "Set" accessors should never be provided for ``readonly`` attributes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1023 | |
| 1024 | The IDL definitions do not fully embody the requirements of the W3C DOM API, |
| 1025 | such as the notion of certain objects, such as the return value of |
| 1026 | :meth:`getElementsByTagName`, being "live". The Python DOM API does not require |
| 1027 | implementations to enforce such requirements. |
| 1028 | |