rest25/library/xml.dom.rst => rest262/library/xml.dom.rst
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
n34+DOM Level 2 recommendation.
35+ 
36+.. XXX PyXML is dead...
34-DOM Level 2 recommendation.  The mapping of the Level 3 specification, currently
37+.. The mapping of the Level 3 specification, currently
35-only available in draft form, is being developed by the `Python XML Special
38+   only available in draft form, is being developed by the `Python XML Special
36-Interest Group <http://www.python.org/sigs/xml-sig/>`_ as part of the `PyXML
39+   Interest Group <http://www.python.org/sigs/xml-sig/>`_ as part of the `PyXML
37-package <http://pyxml.sourceforge.net/>`_.  Refer to the documentation bundled
40+   package <http://pyxml.sourceforge.net/>`_.  Refer to the documentation bundled
38-with that package for information on the current state of DOM Level 3 support.
41+   with that package for information on the current state of DOM Level 3 support.
39
n40-.. % What if your needs are somewhere between SAX and the DOM?  Perhaps
n43+.. What if your needs are somewhere between SAX and the DOM?  Perhaps
41-.. % you cannot afford to load the entire tree in memory but you find the
44+   you cannot afford to load the entire tree in memory but you find the
42-.. % SAX model somewhat cumbersome and low-level.  There is also a module
45+   SAX model somewhat cumbersome and low-level.  There is also a module
43-.. % called xml.dom.pulldom that allows you to build trees of only the
46+   called xml.dom.pulldom that allows you to build trees of only the
44-.. % parts of a document that you need structured access to.  It also has
47+   parts of a document that you need structured access to.  It also has
45-.. % features that allow you to find your way around the DOM.
48+   features that allow you to find your way around the DOM.
46-.. % See http://www.prescod.net/python/pulldom
49+   See http://www.prescod.net/python/pulldom
47
48DOM applications typically start by parsing some XML into a DOM.  How this is
49accomplished is not covered at all by DOM Level 1, and Level 2 provides only
50limited improvements: There is a :class:`DOMImplementation` object class which
51provides access to :class:`Document` creation methods, but no way to access an
52XML reader/parser/Document builder in an implementation-independent way. There
53is also no well-defined way to access these methods without an existing
54:class:`Document` object.  In Python, each DOM implementation will provide a
60document through its properties and methods.  These properties are defined in
61the DOM specification; this portion of the reference manual describes the
62interpretation of the specification in Python.
63
64The specification provided by the W3C defines the DOM API for Java, ECMAScript,
65and OMG IDL.  The Python mapping defined here is based in large part on the IDL
66version of the specification, but strict compliance is not required (though
67implementations are free to support the strict mapping from IDL).  See section
n68-:ref:`dom-conformance`, "Conformance," for a detailed discussion of mapping
n71+:ref:`dom-conformance` for a detailed discussion of mapping requirements.
69-requirements.
70
71
72.. seealso::
73
74   `Document Object Model (DOM) Level 2 Specification <http://www.w3.org/TR/DOM-Level-2-Core/>`_
75      The W3C recommendation upon which the Python DOM API is based.
76
77   `Document Object Model (DOM) Level 1 Specification <http://www.w3.org/TR/REC-DOM-Level-1/>`_
78      The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`.
n79- 
80-   `PyXML <http://pyxml.sourceforge.net>`_
81-      Users that require a full-featured implementation of DOM should use the PyXML
82-      package.
83
84   `Python Language Mapping Specification <http://www.omg.org/docs/formal/02-11-05.pdf>`_
85      This specifies the mapping from OMG IDL to Python.
86
87
88Module Contents
89---------------
90
132   `Namespaces in XML <http://www.w3.org/TR/REC-xml-names/>`_ (section 4).
133
134   .. versionadded:: 2.2
135
136
137.. data:: XMLNS_NAMESPACE
138
139   The namespace URI for namespace declarations, as defined by `Document Object
n140-   Model (DOM) Level 2 Core Specification <http://www.w3.org/TR/DOM-
n138+   Model (DOM) Level 2 Core Specification
141-   Level-2-Core/core.html>`_ (section 1.1.8).
139+   <http://www.w3.org/TR/DOM-Level-2-Core/core.html>`_ (section 1.1.8).
142
143   .. versionadded:: 2.2
144
145
146.. data:: XHTML_NAMESPACE
147
148   The URI of the XHTML namespace as defined by `XHTML 1.0: The Extensible
149   HyperText Markup Language <http://www.w3.org/TR/xhtml1/>`_ (section 3.1.1).
154exception classes.  The :class:`Node` class provided by this module does not
155implement any of the methods or attributes defined by the DOM specification;
156concrete DOM implementations must provide those.  The :class:`Node` class
157provided as part of this module does provide the constants used for the
158:attr:`nodeType` attribute on concrete :class:`Node` objects; they are located
159within the class rather than at the module level to conform with the DOM
160specifications.
161
n162-.. % Should the Node documentation go here?
n160+.. Should the Node documentation go here?
163
164
165.. _dom-objects:
166
167Objects in the DOM
168------------------
169
170The definitive documentation for the DOM is the DOM specification from the W3C.
171
172Note that DOM attributes may also be manipulated as nodes instead of as simple
173strings.  It is fairly rare that you must do this, however, so this usage is not
174yet documented.
175
n176-+--------------------------------+---------------------------------+---------------------------------+
n174++--------------------------------+-----------------------------------+---------------------------------+
177-| Interface                      | Section                         | Purpose                         |
175+| Interface                      | Section                           | Purpose                         |
178-+================================+=================================+=================================+
176++================================+===================================+=================================+
179-| :class:`DOMImplementation`     | :ref:`dom-implementation-       | Interface to the underlying     |
177+| :class:`DOMImplementation`     | :ref:`dom-implementation-objects` | Interface to the underlying     |
180-|                                | objects`                        | implementation.                 |
178+|                                |                                   | implementation.                 |
181-+--------------------------------+---------------------------------+---------------------------------+
179++--------------------------------+-----------------------------------+---------------------------------+
182-| :class:`Node`                  | :ref:`dom-node-objects`         | Base interface for most objects |
180+| :class:`Node`                  | :ref:`dom-node-objects`           | Base interface for most objects |
183-|                                |                                 | in a document.                  |
181+|                                |                                   | in a document.                  |
184-+--------------------------------+---------------------------------+---------------------------------+
182++--------------------------------+-----------------------------------+---------------------------------+
185-| :class:`NodeList`              | :ref:`dom-nodelist-objects`     | Interface for a sequence of     |
183+| :class:`NodeList`              | :ref:`dom-nodelist-objects`       | Interface for a sequence of     |
186-|                                |                                 | nodes.                          |
184+|                                |                                   | nodes.                          |
187-+--------------------------------+---------------------------------+---------------------------------+
185++--------------------------------+-----------------------------------+---------------------------------+
188-| :class:`DocumentType`          | :ref:`dom-documenttype-objects` | Information about the           |
186+| :class:`DocumentType`          | :ref:`dom-documenttype-objects`   | Information about the           |
189-|                                |                                 | declarations needed to process  |
187+|                                |                                   | declarations needed to process  |
190-|                                |                                 | a document.                     |
188+|                                |                                   | a document.                     |
191-+--------------------------------+---------------------------------+---------------------------------+
189++--------------------------------+-----------------------------------+---------------------------------+
192-| :class:`Document`              | :ref:`dom-document-objects`     | Object which represents an      |
190+| :class:`Document`              | :ref:`dom-document-objects`       | Object which represents an      |
193-|                                |                                 | entire document.                |
191+|                                |                                   | entire document.                |
194-+--------------------------------+---------------------------------+---------------------------------+
192++--------------------------------+-----------------------------------+---------------------------------+
195-| :class:`Element`               | :ref:`dom-element-objects`      | Element nodes in the document   |
193+| :class:`Element`               | :ref:`dom-element-objects`        | Element nodes in the document   |
196-|                                |                                 | hierarchy.                      |
194+|                                |                                   | hierarchy.                      |
197-+--------------------------------+---------------------------------+---------------------------------+
195++--------------------------------+-----------------------------------+---------------------------------+
198-| :class:`Attr`                  | :ref:`dom-attr-objects`         | Attribute value nodes on        |
196+| :class:`Attr`                  | :ref:`dom-attr-objects`           | Attribute value nodes on        |
199-|                                |                                 | element nodes.                  |
197+|                                |                                   | element nodes.                  |
200-+--------------------------------+---------------------------------+---------------------------------+
198++--------------------------------+-----------------------------------+---------------------------------+
201-| :class:`Comment`               | :ref:`dom-comment-objects`      | Representation of comments in   |
199+| :class:`Comment`               | :ref:`dom-comment-objects`        | Representation of comments in   |
202-|                                |                                 | the source document.            |
200+|                                |                                   | the source document.            |
203-+--------------------------------+---------------------------------+---------------------------------+
201++--------------------------------+-----------------------------------+---------------------------------+
204-| :class:`Text`                  | :ref:`dom-text-objects`         | Nodes containing textual        |
202+| :class:`Text`                  | :ref:`dom-text-objects`           | Nodes containing textual        |
205-|                                |                                 | content from the document.      |
203+|                                |                                   | content from the document.      |
206-+--------------------------------+---------------------------------+---------------------------------+
204++--------------------------------+-----------------------------------+---------------------------------+
207-| :class:`ProcessingInstruction` | :ref:`dom-pi-objects`           | Processing instruction          |
205+| :class:`ProcessingInstruction` | :ref:`dom-pi-objects`             | Processing instruction          |
208-|                                |                                 | representation.                 |
206+|                                |                                   | representation.                 |
209-+--------------------------------+---------------------------------+---------------------------------+
207++--------------------------------+-----------------------------------+---------------------------------+
210
211An additional section describes the exceptions defined for working with the DOM
212in Python.
213
214
215.. _dom-implementation-objects:
216
217DOMImplementation Objects
277
278   A :class:`NamedNodeMap` of attribute objects.  Only elements have actual values
279   for this; others provide ``None`` for this attribute. This is a read-only
280   attribute.
281
282
283.. attribute:: Node.previousSibling
284
n285-   The node that immediately precedes this one with the same parent.  For instance
n283+   The node that immediately precedes this one with the same parent.  For
286-   the element with an end-tag that comes just before the *self* element's start-
284+   instance the element with an end-tag that comes just before the *self*
287-   tag.  Of course, XML documents are made up of more than just elements so the
285+   element's start-tag.  Of course, XML documents are made up of more than just
288-   previous sibling could be text, a comment, or something else.  If this node is
286+   elements so the previous sibling could be text, a comment, or something else.
289-   the first child of the parent, this attribute will be ``None``. This is a read-
287+   If this node is the first child of the parent, this attribute will be
290-   only attribute.
288+   ``None``. This is a read-only attribute.
291
292
293.. attribute:: Node.nextSibling
294
295   The node that immediately follows this one with the same parent.  See also
296   :attr:`previousSibling`.  If this is the last child of the parent, this
297   attribute will be ``None``. This is a read-only attribute.
298
369      This is based on a proposed DOM Level 3 API which is still in the "working
370      draft" stage, but this particular interface appears uncontroversial.  Changes
371      from the W3C will not necessarily affect this method in the Python DOM interface
372      (though any new W3C API for this would also be supported).
373
374
375.. method:: Node.appendChild(newChild)
376
n377-   Add a new child node to this node at the end of the list of children, returning
n375+   Add a new child node to this node at the end of the list of
378-   *newChild*.
376+   children, returning *newChild*. If the node was already in
377+   in the tree, it is removed first.
379
380
381.. method:: Node.insertBefore(newChild, refChild)
382
383   Insert a new child node before an existing child.  It must be the case that
384   *refChild* is a child of this node; if not, :exc:`ValueError` is raised.
385   *newChild* is returned. If *refChild* is ``None``, it inserts *newChild* at the
386   end of the children's list.
513
514
515.. _dom-document-objects:
516
517Document Objects
518^^^^^^^^^^^^^^^^
519
520A :class:`Document` represents an entire XML document, including its constituent
n521-elements, attributes, processing instructions, comments etc.  Remeber that it
n520+elements, attributes, processing instructions, comments etc.  Remember that it
522inherits properties from :class:`Node`.
523
524
525.. attribute:: Document.documentElement
526
527   The one and only root element of the document.
528
529
607   The value is a string.
608
609
610.. method:: Element.getElementsByTagName(tagName)
611
612   Same as equivalent method in the :class:`Document` class.
613
614
n615-.. method:: Element.getElementsByTagNameNS(tagName)
n614+.. method:: Element.getElementsByTagNameNS(namespaceURI, localName)
616
617   Same as equivalent method in the :class:`Document` class.
618
619
620.. method:: Element.hasAttribute(name)
621
622   Returns true if the element has an attribute named by *name*.
623
648
649.. method:: Element.getAttributeNodeNS(namespaceURI, localName)
650
651   Return an attribute value as a node, given a *namespaceURI* and *localName*.
652
653
654.. method:: Element.removeAttribute(name)
655
n656-   Remove an attribute by name.  No exception is raised if there is no matching
n655+   Remove an attribute by name.  If there is no matching attribute, a
657-   attribute.
656+   :exc:`NotFoundErr` is raised.
658
659
660.. method:: Element.removeAttributeNode(oldAttr)
661
662   Remove and return *oldAttr* from the attribute list, if present. If *oldAttr* is
663   not present, :exc:`NotFoundErr` is raised.
664
665
902   Raised when the implementation does not support the requested type of object or
903   operation.
904
905
906.. exception:: NoDataAllowedErr
907
908   This is raised if data is specified for a node which does not support data.
909
n910-   .. % XXX  a better explanation is needed!
n909+   .. XXX  a better explanation is needed!
911
912
913.. exception:: NoModificationAllowedErr
914
915   Raised on attempts to modify an object where modifications are not allowed (such
916   as for read-only nodes).
917
918
919.. exception:: SyntaxErr
920
921   Raised when an invalid or illegal string is specified.
922
n923-   .. % XXX  how is this different from InvalidCharacterErr ???
n922+   .. XXX  how is this different from InvalidCharacterErr?
924
925
926.. exception:: WrongDocumentErr
927
928   Raised when a node is inserted in a different document than it currently belongs
929   to, and the implementation does not support migrating the node from one document
930   to the other.
931
997+------------------+-------------------------------------------+
998| ``unsigned int`` | ``IntegerType``                           |
999+------------------+-------------------------------------------+
1000
1001Additionally, the :class:`DOMString` defined in the recommendation is mapped to
1002a Python string or Unicode string.  Applications should be able to handle
1003Unicode whenever a string is returned from the DOM.
1004
n1005-The IDL :keyword:`null` value is mapped to ``None``, which may be accepted or
n1004+The IDL ``null`` value is mapped to ``None``, which may be accepted or
1006-provided by the implementation whenever :keyword:`null` is allowed by the API.
1005+provided by the implementation whenever ``null`` is allowed by the API.
1007
1008
1009.. _dom-accessor-methods:
1010
1011Accessor Methods
1012^^^^^^^^^^^^^^^^
1013
1014The mapping from OMG IDL to Python defines accessor functions for IDL
n1015-:keyword:`attribute` declarations in much the way the Java mapping does.
n1014+``attribute`` declarations in much the way the Java mapping does.
1016Mapping the IDL declarations ::
1017
1018   readonly attribute string someValue;
1019            attribute string anotherValue;
1020
1021yields three accessor functions:  a "get" method for :attr:`someValue`
1022(:meth:`_get_someValue`), and "get" and "set" methods for :attr:`anotherValue`
1023(:meth:`_get_anotherValue` and :meth:`_set_anotherValue`).  The mapping, in
1026raise an :exc:`AttributeError`.
1027
1028The Python DOM API, however, *does* require that normal attribute access work.
1029This means that the typical surrogates generated by Python IDL compilers are not
1030likely to work, and wrapper objects may be needed on the client if the DOM
1031objects are accessed via CORBA. While this does require some additional
1032consideration for CORBA DOM clients, the implementers with experience using DOM
1033over CORBA from Python do not consider this a problem.  Attributes that are
n1034-declared :keyword:`readonly` may not restrict write access in all DOM
n1033+declared ``readonly`` may not restrict write access in all DOM
1035implementations.
1036
1037In the Python DOM API, accessor functions are not required.  If provided, they
1038should take the form defined by the Python IDL mapping, but these methods are
1039considered unnecessary since the attributes are accessible directly from Python.
t1040-"Set" accessors should never be provided for :keyword:`readonly` attributes.
t1039+"Set" accessors should never be provided for ``readonly`` attributes.
1041
1042The IDL definitions do not fully embody the requirements of the W3C DOM API,
1043such as the notion of certain objects, such as the return value of
1044:meth:`getElementsByTagName`, being "live".  The Python DOM API does not require
1045implementations to enforce such requirements.
1046
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op