blob: b89769d5568cf0aaf105abace4b300f77fba7523 [file] [log] [blame]
Fred Drakeeaf57aa2000-11-29 06:10:22 +00001\section{\module{xml.dom} ---
2 The Document Object Model API}
Fred Drake669d36f2000-10-24 02:34:45 +00003
Fred Drakeeaf57aa2000-11-29 06:10:22 +00004\declaremodule{standard}{xml.dom}
5\modulesynopsis{Document Object Model API for Python.}
Fred Drake669d36f2000-10-24 02:34:45 +00006\sectionauthor{Paul Prescod}{paul@prescod.net}
7\sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de}
8
9\versionadded{2.0}
10
Fred Drakeeaf57aa2000-11-29 06:10:22 +000011The Document Object Model, or ``DOM,'' is a cross-language API from
12the World Wide Web Consortium (W3C) for accessing and modifying XML
13documents. A DOM implementation presents an XML document as a tree
14structure, or allows client code to build such a structure from
15scratch. It then gives access to the structure through a set of
16objects which provided well-known interfaces.
Fred Drake669d36f2000-10-24 02:34:45 +000017
Fred Drakeeaf57aa2000-11-29 06:10:22 +000018The DOM is extremely useful for random-access applications. SAX only
19allows you a view of one bit of the document at a time. If you are
20looking at one SAX element, you have no access to another. If you are
21looking at a text node, you have no access to a containing element.
22When you write a SAX application, you need to keep track of your
23program's position in the document somewhere in your own code. SAX
24does not do it for you. Also, if you need to look ahead in the XML
25document, you are just out of luck.
Fred Drake669d36f2000-10-24 02:34:45 +000026
27Some applications are simply impossible in an event driven model with
Fred Drakeeaf57aa2000-11-29 06:10:22 +000028no access to a tree. Of course you could build some sort of tree
Fred Drake669d36f2000-10-24 02:34:45 +000029yourself in SAX events, but the DOM allows you to avoid writing that
Fred Drakeeaf57aa2000-11-29 06:10:22 +000030code. The DOM is a standard tree representation for XML data.
Fred Drake669d36f2000-10-24 02:34:45 +000031
Fred Drakeeaf57aa2000-11-29 06:10:22 +000032%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.
Fred Drake669d36f2000-10-24 02:34:45 +000038% See http://www.prescod.net/python/pulldom
39
Fred Drakeeaf57aa2000-11-29 06:10:22 +000040The Document Object Model is being defined by the W3C in stages, or
41``levels'' in their terminology. The Python mapping of the API is
42substantially based on the DOM Level 2 recommendation. Some aspects
Fred Drake66f98b42001-01-26 20:51:32 +000043of the API will only become available in Python 2.1, or may only be
Fred Drakeeaf57aa2000-11-29 06:10:22 +000044available in particular DOM implementations.
Fred Drake669d36f2000-10-24 02:34:45 +000045
Fred Drakeeaf57aa2000-11-29 06:10:22 +000046DOM applications typically start by parsing some XML into a DOM. How
47this is accomplished is not covered at all by DOM Level 1, and Level 2
48provides only limited improvements. There is a
49\class{DOMImplementation} object class which provides access to
50\class{Document} creation methods, but these methods were only added
51in DOM Level 2 and were not implemented in time for Python 2.0. There
Fred Drake66f98b42001-01-26 20:51:32 +000052is also no well-defined way to access these methods without an
Fred Drakeeaf57aa2000-11-29 06:10:22 +000053existing \class{Document} object. For Python 2.0, consult the
54documentation for each particular DOM implementation to determine the
55bootstrap procedure needed to create and initialize \class{Document}
Fred Drake66f98b42001-01-26 20:51:32 +000056and \class{DocumentType} instances.
Fred Drake669d36f2000-10-24 02:34:45 +000057
58Once you have a DOM document object, you can access the parts of your
59XML document through its properties and methods. These properties are
Fred Drakeeaf57aa2000-11-29 06:10:22 +000060defined in the DOM specification; this portion of the reference manual
61describes the interpretation of the specification in Python.
Fred Drake669d36f2000-10-24 02:34:45 +000062
Fred Drakeeaf57aa2000-11-29 06:10:22 +000063The specification provided by the W3C defines the DOM API for Java,
64ECMAScript, and OMG IDL. The Python mapping defined here is based in
65large part on the IDL version of the specification, but strict
66compliance is not required (though implementations are free to support
67the strict mapping from IDL). See section \ref{dom-conformance},
68``Conformance,'' for a detailed discussion of mapping requirements.
Fred Drake669d36f2000-10-24 02:34:45 +000069
Fred Drake669d36f2000-10-24 02:34:45 +000070
71\begin{seealso}
Fred Drakeeaf57aa2000-11-29 06:10:22 +000072 \seetitle[http://www.w3.org/TR/DOM-Level-2-Core/]{Document Object
73 Model (DOM) Level 2 Specification}
74 {The W3C recommendation upon which the Python DOM API is
75 based.}
76 \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object
77 Model (DOM) Level 1 Specification}
78 {The W3C recommendation for the
Fred Drake669d36f2000-10-24 02:34:45 +000079 DOM supported by \module{xml.dom.minidom}.}
80 \seetitle[http://pyxml.sourceforge.net]{PyXML}{Users that require a
81 full-featured implementation of DOM should use the PyXML
82 package.}
Fred Drakeeaf57aa2000-11-29 06:10:22 +000083 \seetitle[http://cgi.omg.org/cgi-bin/doc?orbos/99-08-02.pdf]{CORBA
84 Scripting with Python}
85 {This specifies the mapping from OMG IDL to Python.}
Fred Drake669d36f2000-10-24 02:34:45 +000086\end{seealso}
87
Martin v. Löwis7edbd4f2001-02-22 14:05:50 +000088\subsection{Module Contents}
89
90The \module{xml.dom} contains the following functions:
91
92\begin{funcdesc}{registerDOMImplementation}{name, factory}
Fred Drake07e6c502001-02-23 19:15:56 +000093Register the \var{factory} function with the name \var{name}. The
94factory function should return an object which implements the
95\class{DOMImplementation} interface. The factory function can return
96the same object every time, or a new one for each call, as appropriate
97for the specific implementation (e.g. if that implementation supports
Martin v. Löwis7edbd4f2001-02-22 14:05:50 +000098some customization).
99\end{funcdesc}
100
Fred Drake89d63cc2001-11-30 16:58:15 +0000101\begin{funcdesc}{getDOMImplementation}{\optional{name\optional{, features}}}
Martin v. Löwis7edbd4f2001-02-22 14:05:50 +0000102Return a suitable DOM implementation. The \var{name} is either
103well-known, the module name of a DOM implementation, or
Fred Drake89d63cc2001-11-30 16:58:15 +0000104\code{None}. If it is not \code{None}, imports the corresponding
105module and returns a \class{DOMImplementation} object if the import
106succeeds. If no name is given, and if the environment variable
107\envvar{PYTHON_DOM} is set, this variable is used to find the
108implementation.
Martin v. Löwis7edbd4f2001-02-22 14:05:50 +0000109
Fred Drake89d63cc2001-11-30 16:58:15 +0000110If name is not given, this examines the available implementations to
111find one with the required feature set. If no implementation can be
112found, raise an \exception{ImportError}. The features list must be a
113sequence of \code{(\var{feature}, \var{version})} pairs which are
114passed to the \method{hasFeature()} method on available
115\class{DOMImplementation} objects.
Martin v. Löwis7edbd4f2001-02-22 14:05:50 +0000116\end{funcdesc}
117
Fred Drakebd34b6b2001-11-30 15:37:33 +0000118
119Some convenience constants are also provided:
120
121\begin{datadesc}{EMPTY_NAMESPACE}
122 The value used to indicate that no namespace is associated with a
123 node in the DOM. This is typically found as the
124 \member{namespaceURI} of a node, or used as the \var{namespaceURI}
125 parameter to a namespaces-specific method.
126 \versionadded{2.2}
127\end{datadesc}
128
129\begin{datadesc}{XML_NAMESPACE}
130 The namespace URI associated with the reserved prefix \code{xml}, as
131 defined by
132 \citetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML}
133 (section~4).
134 \versionadded{2.2}
135\end{datadesc}
136
137\begin{datadesc}{XMLNS_NAMESPACE}
138 The namespace URI for namespace declarations, as defined by
139 \citetitle[http://www.w3.org/TR/DOM-Level-2-Core/core.html]{Document
140 Object Model (DOM) Level 2 Core Specification} (section~1.1.8).
141 \versionadded{2.2}
142\end{datadesc}
143
144\begin{datadesc}{XHTML_NAMESPACE}
145 The URI of the XHTML namespace as defined by
146 \citetitle[http://www.w3.org/TR/xhtml1/]{XHTML 1.0: The Extensible
147 HyperText Markup Language} (section~3.1.1).
148 \versionadded{2.2}
149\end{datadesc}
150
151
Martin v. Löwis7edbd4f2001-02-22 14:05:50 +0000152% Should the Node documentation go here?
153
Fred Drakee21e2bb2001-10-26 20:09:49 +0000154In addition, \module{xml.dom} contains a base \class{Node} class and
155the DOM exception classes. The \class{Node} class provided by this
156module does not implement any of the methods or attributes defined by
157the DOM specification; concrete DOM implementations must provide
158those. The \class{Node} class provided as part of this module does
159provide the constants used for the \member{nodeType} attribute on
160concrete \class{Node} objects; they are located within the class
161rather than at the module level to conform with the DOM
162specifications.
Fred Drake669d36f2000-10-24 02:34:45 +0000163
Fred Drakebd34b6b2001-11-30 15:37:33 +0000164
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000165\subsection{Objects in the DOM \label{dom-objects}}
Fred Drake669d36f2000-10-24 02:34:45 +0000166
167The definitive documentation for the DOM is the DOM specification from
Fred Drake16942f22000-12-07 04:47:51 +0000168the W3C.
Fred Drake669d36f2000-10-24 02:34:45 +0000169
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000170Note that DOM attributes may also be manipulated as nodes instead of
171as simple strings. It is fairly rare that you must do this, however,
172so this usage is not yet documented.
173
174
175\begin{tableiii}{l|l|l}{class}{Interface}{Section}{Purpose}
Fred Drake16942f22000-12-07 04:47:51 +0000176 \lineiii{DOMImplementation}{\ref{dom-implementation-objects}}
177 {Interface to the underlying implementation.}
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000178 \lineiii{Node}{\ref{dom-node-objects}}
179 {Base interface for most objects in a document.}
Fred Drake16942f22000-12-07 04:47:51 +0000180 \lineiii{NodeList}{\ref{dom-nodelist-objects}}
181 {Interface for a sequence of nodes.}
182 \lineiii{DocumentType}{\ref{dom-documenttype-objects}}
183 {Information about the declarations needed to process a document.}
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000184 \lineiii{Document}{\ref{dom-document-objects}}
185 {Object which represents an entire document.}
186 \lineiii{Element}{\ref{dom-element-objects}}
187 {Element nodes in the document hierarchy.}
188 \lineiii{Attr}{\ref{dom-attr-objects}}
189 {Attribute value nodes on element nodes.}
190 \lineiii{Comment}{\ref{dom-comment-objects}}
191 {Representation of comments in the source document.}
192 \lineiii{Text}{\ref{dom-text-objects}}
193 {Nodes containing textual content from the document.}
194 \lineiii{ProcessingInstruction}{\ref{dom-pi-objects}}
195 {Processing instruction representation.}
196\end{tableiii}
197
Fred Drakebc9c1b12000-12-13 17:38:02 +0000198An additional section describes the exceptions defined for working
199with the DOM in Python.
200
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000201
Fred Drake16942f22000-12-07 04:47:51 +0000202\subsubsection{DOMImplementation Objects
203 \label{dom-implementation-objects}}
204
205The \class{DOMImplementation} interface provides a way for
206applications to determine the availability of particular features in
207the DOM they are using. DOM Level 2 added the ability to create new
208\class{Document} and \class{DocumentType} objects using the
209\class{DOMImplementation} as well.
210
211\begin{methoddesc}[DOMImplementation]{hasFeature}{feature, version}
212\end{methoddesc}
213
214
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000215\subsubsection{Node Objects \label{dom-node-objects}}
216
Fred Drake669d36f2000-10-24 02:34:45 +0000217All of the components of an XML document are subclasses of
218\class{Node}.
219
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000220\begin{memberdesc}[Node]{nodeType}
Fred Drake669d36f2000-10-24 02:34:45 +0000221An integer representing the node type. Symbolic constants for the
Fred Drake66f98b42001-01-26 20:51:32 +0000222types are on the \class{Node} object:
Fred Drake669d36f2000-10-24 02:34:45 +0000223\constant{ELEMENT_NODE}, \constant{ATTRIBUTE_NODE},
224\constant{TEXT_NODE}, \constant{CDATA_SECTION_NODE},
225\constant{ENTITY_NODE}, \constant{PROCESSING_INSTRUCTION_NODE},
226\constant{COMMENT_NODE}, \constant{DOCUMENT_NODE},
227\constant{DOCUMENT_TYPE_NODE}, \constant{NOTATION_NODE}.
Fred Drake9a29dd62000-12-08 06:54:51 +0000228This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000229\end{memberdesc}
230
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000231\begin{memberdesc}[Node]{parentNode}
Fred Drake16942f22000-12-07 04:47:51 +0000232The parent of the current node, or \code{None} for the document node.
233The value is always a \class{Node} object or \code{None}. For
234\class{Element} nodes, this will be the parent element, except for the
235root element, in which case it will be the \class{Document} object.
236For \class{Attr} nodes, this is always \code{None}.
Fred Drake9a29dd62000-12-08 06:54:51 +0000237This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000238\end{memberdesc}
239
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000240\begin{memberdesc}[Node]{attributes}
Fred Drake61f79492001-10-25 20:42:57 +0000241A \class{NamedNodeMap} of attribute objects. Only elements have
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000242actual values for this; others provide \code{None} for this attribute.
Fred Drake9a29dd62000-12-08 06:54:51 +0000243This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000244\end{memberdesc}
245
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000246\begin{memberdesc}[Node]{previousSibling}
Fred Drake669d36f2000-10-24 02:34:45 +0000247The node that immediately precedes this one with the same parent. For
248instance the element with an end-tag that comes just before the
249\var{self} element's start-tag. Of course, XML documents are made
250up of more than just elements so the previous sibling could be text, a
Fred Drake16942f22000-12-07 04:47:51 +0000251comment, or something else. If this node is the first child of the
252parent, this attribute will be \code{None}.
Fred Drake9a29dd62000-12-08 06:54:51 +0000253This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000254\end{memberdesc}
255
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000256\begin{memberdesc}[Node]{nextSibling}
Fred Drake669d36f2000-10-24 02:34:45 +0000257The node that immediately follows this one with the same parent. See
Fred Drake16942f22000-12-07 04:47:51 +0000258also \member{previousSibling}. If this is the last child of the
259parent, this attribute will be \code{None}.
Fred Drake9a29dd62000-12-08 06:54:51 +0000260This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000261\end{memberdesc}
262
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000263\begin{memberdesc}[Node]{childNodes}
Fred Drake669d36f2000-10-24 02:34:45 +0000264A list of nodes contained within this node.
Fred Drake9a29dd62000-12-08 06:54:51 +0000265This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000266\end{memberdesc}
267
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000268\begin{memberdesc}[Node]{firstChild}
269The first child of the node, if there are any, or \code{None}.
Fred Drake9a29dd62000-12-08 06:54:51 +0000270This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000271\end{memberdesc}
272
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000273\begin{memberdesc}[Node]{lastChild}
274The last child of the node, if there are any, or \code{None}.
Fred Drake9a29dd62000-12-08 06:54:51 +0000275This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000276\end{memberdesc}
277
Fred Drake9a29dd62000-12-08 06:54:51 +0000278\begin{memberdesc}[Node]{localName}
279The part of the \member{tagName} following the colon if there is one,
280else the entire \member{tagName}. The value is a string.
281\end{memberdesc}
282
283\begin{memberdesc}[Node]{prefix}
284The part of the \member{tagName} preceding the colon if there is one,
285else the empty string. The value is a string, or \code{None}
286\end{memberdesc}
287
288\begin{memberdesc}[Node]{namespaceURI}
Fred Drake16942f22000-12-07 04:47:51 +0000289The namespace associated with the element name. This will be a
Fred Drake9a29dd62000-12-08 06:54:51 +0000290string or \code{None}. This is a read-only attribute.
Fred Drake16942f22000-12-07 04:47:51 +0000291\end{memberdesc}
292
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000293\begin{memberdesc}[Node]{nodeName}
Fred Drake9a29dd62000-12-08 06:54:51 +0000294This has a different meaning for each node type; see the DOM
295specification for details. You can always get the information you
296would get here from another property such as the \member{tagName}
297property for elements or the \member{name} property for attributes.
298For all node types, the value of this attribute will be either a
299string or \code{None}. This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000300\end{memberdesc}
301
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000302\begin{memberdesc}[Node]{nodeValue}
Fred Drake9a29dd62000-12-08 06:54:51 +0000303This has a different meaning for each node type; see the DOM
304specification for details. The situation is similar to that with
305\member{nodeName}. The value is a string or \code{None}.
Fred Drake669d36f2000-10-24 02:34:45 +0000306\end{memberdesc}
307
Fred Drake9a29dd62000-12-08 06:54:51 +0000308\begin{methoddesc}[Node]{hasAttributes}{}
309Returns true if the node has any attributes.
310\end{methoddesc}
311
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000312\begin{methoddesc}[Node]{hasChildNodes}{}
313Returns true if the node has any child nodes.
Fred Drake669d36f2000-10-24 02:34:45 +0000314\end{methoddesc}
315
Fred Drake40e43bf2001-02-03 01:20:01 +0000316\begin{methoddesc}[Node]{isSameNode}{other}
317Returns true if \var{other} refers to the same node as this node.
318This is especially useful for DOM implementations which use any sort
319of proxy architecture (because more than one object can refer to the
320same node).
Fred Drake15862f52001-02-14 20:39:15 +0000321
Fred Drake0aa811c2001-10-20 04:24:09 +0000322\note{This is based on a proposed DOM Level 3 API which is
Fred Drake15862f52001-02-14 20:39:15 +0000323still in the ``working draft'' stage, but this particular interface
324appears uncontroversial. Changes from the W3C will not necessarily
325affect this method in the Python DOM interface (though any new W3C
Fred Drake0aa811c2001-10-20 04:24:09 +0000326API for this would also be supported).}
Fred Drake40e43bf2001-02-03 01:20:01 +0000327\end{methoddesc}
328
Fred Drake9a29dd62000-12-08 06:54:51 +0000329\begin{methoddesc}[Node]{appendChild}{newChild}
330Add a new child node to this node at the end of the list of children,
331returning \var{newChild}.
332\end{methoddesc}
333
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000334\begin{methoddesc}[Node]{insertBefore}{newChild, refChild}
Fred Drake669d36f2000-10-24 02:34:45 +0000335Insert a new child node before an existing child. It must be the case
336that \var{refChild} is a child of this node; if not,
Fred Drake9a29dd62000-12-08 06:54:51 +0000337\exception{ValueError} is raised. \var{newChild} is returned.
Fred Drake669d36f2000-10-24 02:34:45 +0000338\end{methoddesc}
339
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000340\begin{methoddesc}[Node]{removeChild}{oldChild}
Fred Drake669d36f2000-10-24 02:34:45 +0000341Remove a child node. \var{oldChild} must be a child of this node; if
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000342not, \exception{ValueError} is raised. \var{oldChild} is returned on
343success. If \var{oldChild} will not be used further, its
344\method{unlink()} method should be called.
Fred Drake669d36f2000-10-24 02:34:45 +0000345\end{methoddesc}
346
Fred Drake9a29dd62000-12-08 06:54:51 +0000347\begin{methoddesc}[Node]{replaceChild}{newChild, oldChild}
348Replace an existing node with a new node. It must be the case that
349\var{oldChild} is a child of this node; if not,
350\exception{ValueError} is raised.
Fred Drake669d36f2000-10-24 02:34:45 +0000351\end{methoddesc}
352
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000353\begin{methoddesc}[Node]{normalize}{}
354Join adjacent text nodes so that all stretches of text are stored as
355single \class{Text} instances. This simplifies processing text from a
356DOM tree for many applications.
357\versionadded{2.1}
Fred Drake669d36f2000-10-24 02:34:45 +0000358\end{methoddesc}
359
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000360\begin{methoddesc}[Node]{cloneNode}{deep}
361Clone this node. Setting \var{deep} means to clone all child nodes as
Fred Drake16942f22000-12-07 04:47:51 +0000362well. This returns the clone.
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000363\end{methoddesc}
Fred Drake669d36f2000-10-24 02:34:45 +0000364
365
Fred Drake16942f22000-12-07 04:47:51 +0000366\subsubsection{NodeList Objects \label{dom-nodelist-objects}}
367
368A \class{NodeList} represents a sequence of nodes. These objects are
369used in two ways in the DOM Core recommendation: the
370\class{Element} objects provides one as it's list of child nodes, and
371the \method{getElementsByTagName()} and
372\method{getElementsByTagNameNS()} methods of \class{Node} return
373objects with this interface to represent query results.
374
375The DOM Level 2 recommendation defines one method and one attribute
376for these objects:
377
378\begin{methoddesc}[NodeList]{item}{i}
379 Return the \var{i}'th item from the sequence, if there is one, or
380 \code{None}. The index \var{i} is not allowed to be less then zero
381 or greater than or equal to the length of the sequence.
382\end{methoddesc}
383
384\begin{memberdesc}[NodeList]{length}
385 The number of nodes in the sequence.
386\end{memberdesc}
387
388In addition, the Python DOM interface requires that some additional
389support is provided to allow \class{NodeList} objects to be used as
390Python sequences. All \class{NodeList} implementations must include
391support for \method{__len__()} and \method{__getitem__()}; this allows
392iteration over the \class{NodeList} in \keyword{for} statements and
393proper support for the \function{len()} built-in function.
394
395If a DOM implementation supports modification of the document, the
396\class{NodeList} implementation must also support the
397\method{__setitem__()} and \method{__delitem__()} methods.
398
399
400\subsubsection{DocumentType Objects \label{dom-documenttype-objects}}
401
402Information about the notations and entities declared by a document
403(including the external subset if the parser uses it and can provide
404the information) is available from a \class{DocumentType} object. The
405\class{DocumentType} for a document is available from the
Fred Drakee21e2bb2001-10-26 20:09:49 +0000406\class{Document} object's \member{doctype} attribute; if there is no
407\code{DOCTYPE} declaration for the document, the document's
408\member{doctype} attribute will be set to \code{None} instead of an
409instance of this interface.
Fred Drake16942f22000-12-07 04:47:51 +0000410
411\class{DocumentType} is a specialization of \class{Node}, and adds the
412following attributes:
413
414\begin{memberdesc}[DocumentType]{publicId}
415 The public identifier for the external subset of the document type
416 definition. This will be a string or \code{None}.
417\end{memberdesc}
418
419\begin{memberdesc}[DocumentType]{systemId}
420 The system identifier for the external subset of the document type
421 definition. This will be a URI as a string, or \code{None}.
422\end{memberdesc}
423
424\begin{memberdesc}[DocumentType]{internalSubset}
425 A string giving the complete internal subset from the document.
Fred Drakef459d852001-04-05 18:30:04 +0000426 This does not include the brackets which enclose the subset. If the
427 document has no internal subset, this should be \code{None}.
Fred Drake16942f22000-12-07 04:47:51 +0000428\end{memberdesc}
429
430\begin{memberdesc}[DocumentType]{name}
431 The name of the root element as given in the \code{DOCTYPE}
Fred Drakee21e2bb2001-10-26 20:09:49 +0000432 declaration, if present.
Fred Drake16942f22000-12-07 04:47:51 +0000433\end{memberdesc}
434
435\begin{memberdesc}[DocumentType]{entities}
436 This is a \class{NamedNodeMap} giving the definitions of external
437 entities. For entity names defined more than once, only the first
438 definition is provided (others are ignored as required by the XML
439 recommendation). This may be \code{None} if the information is not
440 provided by the parser, or if no entities are defined.
441\end{memberdesc}
442
443\begin{memberdesc}[DocumentType]{notations}
444 This is a \class{NamedNodeMap} giving the definitions of notations.
445 For notation names defined more than once, only the first definition
446 is provided (others are ignored as required by the XML
447 recommendation). This may be \code{None} if the information is not
448 provided by the parser, or if no notations are defined.
449\end{memberdesc}
450
451
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000452\subsubsection{Document Objects \label{dom-document-objects}}
Fred Drake669d36f2000-10-24 02:34:45 +0000453
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000454A \class{Document} represents an entire XML document, including its
455constituent elements, attributes, processing instructions, comments
456etc. Remeber that it inherits properties from \class{Node}.
457
458\begin{memberdesc}[Document]{documentElement}
Fred Drake669d36f2000-10-24 02:34:45 +0000459The one and only root element of the document.
460\end{memberdesc}
461
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000462\begin{methoddesc}[Document]{createElement}{tagName}
Fred Drake16942f22000-12-07 04:47:51 +0000463Create and return a new element node. The element is not inserted
464into the document when it is created. You need to explicitly insert
465it with one of the other methods such as \method{insertBefore()} or
Fred Drake669d36f2000-10-24 02:34:45 +0000466\method{appendChild()}.
467\end{methoddesc}
468
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000469\begin{methoddesc}[Document]{createElementNS}{namespaceURI, tagName}
Fred Drake16942f22000-12-07 04:47:51 +0000470Create and return a new element with a namespace. The
471\var{tagName} may have a prefix. The element is not inserted into the
472document when it is created. You need to explicitly insert it with
473one of the other methods such as \method{insertBefore()} or
474\method{appendChild()}.
Fred Drake669d36f2000-10-24 02:34:45 +0000475\end{methoddesc}
476
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000477\begin{methoddesc}[Document]{createTextNode}{data}
Fred Drake16942f22000-12-07 04:47:51 +0000478Create and return a text node containing the data passed as a
479parameter. As with the other creation methods, this one does not
480insert the node into the tree.
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000481\end{methoddesc}
Fred Drake669d36f2000-10-24 02:34:45 +0000482
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000483\begin{methoddesc}[Document]{createComment}{data}
Fred Drake16942f22000-12-07 04:47:51 +0000484Create and return a comment node containing the data passed as a
485parameter. As with the other creation methods, this one does not
486insert the node into the tree.
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000487\end{methoddesc}
488
489\begin{methoddesc}[Document]{createProcessingInstruction}{target, data}
Fred Drake16942f22000-12-07 04:47:51 +0000490Create and return a processing instruction node containing the
491\var{target} and \var{data} passed as parameters. As with the other
492creation methods, this one does not insert the node into the tree.
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000493\end{methoddesc}
494
495\begin{methoddesc}[Document]{createAttribute}{name}
Fred Drake16942f22000-12-07 04:47:51 +0000496Create and return an attribute node. This method does not associate
497the attribute node with any particular element. You must use
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000498\method{setAttributeNode()} on the appropriate \class{Element} object
499to use the newly created attribute instance.
500\end{methoddesc}
501
502\begin{methoddesc}[Document]{createAttributeNS}{namespaceURI, qualifiedName}
Fred Drake16942f22000-12-07 04:47:51 +0000503Create and return an attribute node with a namespace. The
504\var{tagName} may have a prefix. This method does not associate the
505attribute node with any particular element. You must use
506\method{setAttributeNode()} on the appropriate \class{Element} object
507to use the newly created attribute instance.
Fred Drake669d36f2000-10-24 02:34:45 +0000508\end{methoddesc}
509
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000510\begin{methoddesc}[Document]{getElementsByTagName}{tagName}
Fred Drake669d36f2000-10-24 02:34:45 +0000511Search for all descendants (direct children, children's children,
512etc.) with a particular element type name.
513\end{methoddesc}
514
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000515\begin{methoddesc}[Document]{getElementsByTagNameNS}{namespaceURI, localName}
Fred Drake669d36f2000-10-24 02:34:45 +0000516Search for all descendants (direct children, children's children,
517etc.) with a particular namespace URI and localname. The localname is
518the part of the namespace after the prefix.
519\end{methoddesc}
520
Fred Drake669d36f2000-10-24 02:34:45 +0000521
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000522\subsubsection{Element Objects \label{dom-element-objects}}
Fred Drake669d36f2000-10-24 02:34:45 +0000523
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000524\class{Element} is a subclass of \class{Node}, so inherits all the
525attributes of that class.
526
527\begin{memberdesc}[Element]{tagName}
Fred Drake669d36f2000-10-24 02:34:45 +0000528The element type name. In a namespace-using document it may have
Fred Drake16942f22000-12-07 04:47:51 +0000529colons in it. The value is a string.
Fred Drake669d36f2000-10-24 02:34:45 +0000530\end{memberdesc}
531
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000532\begin{methoddesc}[Element]{getElementsByTagName}{tagName}
Fred Drake669d36f2000-10-24 02:34:45 +0000533Same as equivalent method in the \class{Document} class.
534\end{methoddesc}
535
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000536\begin{methoddesc}[Element]{getElementsByTagNameNS}{tagName}
Fred Drake669d36f2000-10-24 02:34:45 +0000537Same as equivalent method in the \class{Document} class.
538\end{methoddesc}
539
Fred Drake9a29dd62000-12-08 06:54:51 +0000540\begin{methoddesc}[Element]{getAttribute}{attname}
541Return an attribute value as a string.
542\end{methoddesc}
543
544\begin{methoddesc}[Element]{getAttributeNode}{attrname}
545Return the \class{Attr} node for the attribute named by
546\var{attrname}.
547\end{methoddesc}
548
549\begin{methoddesc}[Element]{getAttributeNS}{namespaceURI, localName}
550Return an attribute value as a string, given a \var{namespaceURI} and
551\var{localName}.
552\end{methoddesc}
553
554\begin{methoddesc}[Element]{getAttributeNodeNS}{namespaceURI, localName}
555Return an attribute value as a node, given a \var{namespaceURI} and
556\var{localName}.
557\end{methoddesc}
558
559\begin{methoddesc}[Element]{removeAttribute}{attname}
560Remove an attribute by name. No exception is raised if there is no
561matching attribute.
562\end{methoddesc}
563
564\begin{methoddesc}[Element]{removeAttributeNode}{oldAttr}
565Remove and return \var{oldAttr} from the attribute list, if present.
566If \var{oldAttr} is not present, \exception{NotFoundErr} is raised.
567\end{methoddesc}
568
569\begin{methoddesc}[Element]{removeAttributeNS}{namespaceURI, localName}
570Remove an attribute by name. Note that it uses a localName, not a
571qname. No exception is raised if there is no matching attribute.
572\end{methoddesc}
573
574\begin{methoddesc}[Element]{setAttribute}{attname, value}
575Set an attribute value from a string.
576\end{methoddesc}
577
578\begin{methoddesc}[Element]{setAttributeNode}{newAttr}
579Add a new attibute node to the element, replacing an existing
580attribute if necessary if the \member{name} attribute matches. If a
581replacement occurs, the old attribute node will be returned. If
582\var{newAttr} is already in use, \exception{InuseAttributeErr} will be
583raised.
584\end{methoddesc}
585
586\begin{methoddesc}[Element]{setAttributeNodeNS}{newAttr}
587Add a new attibute node to the element, replacing an existing
588attribute if necessary if the \member{namespaceURI} and
589\member{localName} attributes match. If a replacement occurs, the old
590attribute node will be returned. If \var{newAttr} is already in use,
591\exception{InuseAttributeErr} will be raised.
592\end{methoddesc}
593
594\begin{methoddesc}[Element]{setAttributeNS}{namespaceURI, qname, value}
595Set an attribute value from a string, given a \var{namespaceURI} and a
596\var{qname}. Note that a qname is the whole attribute name. This is
597different than above.
598\end{methoddesc}
599
Fred Drake669d36f2000-10-24 02:34:45 +0000600
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000601\subsubsection{Attr Objects \label{dom-attr-objects}}
Fred Drake669d36f2000-10-24 02:34:45 +0000602
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000603\class{Attr} inherits from \class{Node}, so inherits all its
604attributes.
Fred Drake669d36f2000-10-24 02:34:45 +0000605
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000606\begin{memberdesc}[Attr]{name}
Fred Drake669d36f2000-10-24 02:34:45 +0000607The attribute name. In a namespace-using document it may have colons
608in it.
609\end{memberdesc}
610
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000611\begin{memberdesc}[Attr]{localName}
Fred Drake669d36f2000-10-24 02:34:45 +0000612The part of the name following the colon if there is one, else the
Fred Drake9a29dd62000-12-08 06:54:51 +0000613entire name. This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000614\end{memberdesc}
615
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000616\begin{memberdesc}[Attr]{prefix}
Fred Drake669d36f2000-10-24 02:34:45 +0000617The part of the name preceding the colon if there is one, else the
618empty string.
619\end{memberdesc}
620
Fred Drake669d36f2000-10-24 02:34:45 +0000621
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000622\subsubsection{NamedNodeMap Objects \label{dom-attributelist-objects}}
Fred Drake669d36f2000-10-24 02:34:45 +0000623
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000624\class{NamedNodeMap} does \emph{not} inherit from \class{Node}.
Fred Drake669d36f2000-10-24 02:34:45 +0000625
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000626\begin{memberdesc}[NamedNodeMap]{length}
Fred Drake669d36f2000-10-24 02:34:45 +0000627The length of the attribute list.
628\end{memberdesc}
629
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000630\begin{methoddesc}[NamedNodeMap]{item}{index}
Fred Drake669d36f2000-10-24 02:34:45 +0000631Return an attribute with a particular index. The order you get the
632attributes in is arbitrary but will be consistent for the life of a
633DOM. Each item is an attribute node. Get its value with the
634\member{value} attribbute.
635\end{methoddesc}
636
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000637There are also experimental methods that give this class more mapping
638behavior. You can use them or you can use the standardized
Fred Drakee21e2bb2001-10-26 20:09:49 +0000639\method{getAttribute*()} family of methods on the \class{Element}
640objects.
Fred Drake669d36f2000-10-24 02:34:45 +0000641
642
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000643\subsubsection{Comment Objects \label{dom-comment-objects}}
Fred Drake669d36f2000-10-24 02:34:45 +0000644
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000645\class{Comment} represents a comment in the XML document. It is a
Fred Drake9a29dd62000-12-08 06:54:51 +0000646subclass of \class{Node}, but cannot have child nodes.
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000647
648\begin{memberdesc}[Comment]{data}
Fred Drake9a29dd62000-12-08 06:54:51 +0000649The content of the comment as a string. The attribute contains all
650characters between the leading \code{<!-}\code{-} and trailing
651\code{-}\code{->}, but does not include them.
Fred Drake669d36f2000-10-24 02:34:45 +0000652\end{memberdesc}
Fred Drake669d36f2000-10-24 02:34:45 +0000653
654
Fred Drake9a29dd62000-12-08 06:54:51 +0000655\subsubsection{Text and CDATASection Objects \label{dom-text-objects}}
Fred Drake669d36f2000-10-24 02:34:45 +0000656
Fred Drake9a29dd62000-12-08 06:54:51 +0000657The \class{Text} interface represents text in the XML document. If
658the parser and DOM implementation support the DOM's XML extension,
659portions of the text enclosed in CDATA marked sections are stored in
660\class{CDATASection} objects. These two interfaces are identical, but
661provide different values for the \member{nodeType} attribute.
662
663These interfaces extend the \class{Node} interface. They cannot have
664child nodes.
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000665
666\begin{memberdesc}[Text]{data}
Fred Drake9a29dd62000-12-08 06:54:51 +0000667The content of the text node as a string.
Fred Drake669d36f2000-10-24 02:34:45 +0000668\end{memberdesc}
Fred Drake669d36f2000-10-24 02:34:45 +0000669
Fred Drake0aa811c2001-10-20 04:24:09 +0000670\note{The use of a \class{CDATASection} node does not
Fred Drake9a29dd62000-12-08 06:54:51 +0000671indicate that the node represents a complete CDATA marked section,
672only that the content of the node was part of a CDATA section. A
673single CDATA section may be represented by more than one node in the
674document tree. There is no way to determine whether two adjacent
Fred Drake0aa811c2001-10-20 04:24:09 +0000675\class{CDATASection} nodes represent different CDATA marked sections.}
Fred Drake9a29dd62000-12-08 06:54:51 +0000676
Fred Drake669d36f2000-10-24 02:34:45 +0000677
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000678\subsubsection{ProcessingInstruction Objects \label{dom-pi-objects}}
Fred Drake669d36f2000-10-24 02:34:45 +0000679
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000680Represents a processing instruction in the XML document; this inherits
Fred Drake9a29dd62000-12-08 06:54:51 +0000681from the \class{Node} interface and cannot have child nodes.
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000682
683\begin{memberdesc}[ProcessingInstruction]{target}
Fred Drake669d36f2000-10-24 02:34:45 +0000684The content of the processing instruction up to the first whitespace
Fred Drake9a29dd62000-12-08 06:54:51 +0000685character. This is a read-only attribute.
Fred Drake669d36f2000-10-24 02:34:45 +0000686\end{memberdesc}
687
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000688\begin{memberdesc}[ProcessingInstruction]{data}
Fred Drake669d36f2000-10-24 02:34:45 +0000689The content of the processing instruction following the first
690whitespace character.
691\end{memberdesc}
Fred Drake669d36f2000-10-24 02:34:45 +0000692
693
Fred Drakebc9c1b12000-12-13 17:38:02 +0000694\subsubsection{Exceptions \label{dom-exceptions}}
695
696\versionadded{2.1}
697
698The DOM Level 2 recommendation defines a single exception,
699\exception{DOMException}, and a number of constants that allow
700applications to determine what sort of error occurred.
701\exception{DOMException} instances carry a \member{code} attribute
702that provides the appropriate value for the specific exception.
703
704The Python DOM interface provides the constants, but also expands the
705set of exceptions so that a specific exception exists for each of the
706exception codes defined by the DOM. The implementations must raise
707the appropriate specific exception, each of which carries the
708appropriate value for the \member{code} attribute.
709
710\begin{excdesc}{DOMException}
711 Base exception class used for all specific DOM exceptions. This
712 exception class cannot be directly instantiated.
713\end{excdesc}
714
715\begin{excdesc}{DomstringSizeErr}
716 Raised when a specified range of text does not fit into a string.
717 This is not known to be used in the Python DOM implementations, but
718 may be received from DOM implementations not written in Python.
719\end{excdesc}
720
721\begin{excdesc}{HierarchyRequestErr}
722 Raised when an attempt is made to insert a node where the node type
723 is not allowed.
724\end{excdesc}
725
726\begin{excdesc}{IndexSizeErr}
727 Raised when an index or size parameter to a method is negative or
728 exceeds the allowed values.
729\end{excdesc}
730
731\begin{excdesc}{InuseAttributeErr}
732 Raised when an attempt is made to insert an \class{Attr} node that
733 is already present elsewhere in the document.
734\end{excdesc}
735
736\begin{excdesc}{InvalidAccessErr}
737 Raised if a parameter or an operation is not supported on the
738 underlying object.
739\end{excdesc}
740
741\begin{excdesc}{InvalidCharacterErr}
742 This exception is raised when a string parameter contains a
743 character that is not permitted in the context it's being used in by
744 the XML 1.0 recommendation. For example, attempting to create an
745 \class{Element} node with a space in the element type name will
746 cause this error to be raised.
747\end{excdesc}
748
749\begin{excdesc}{InvalidModificationErr}
750 Raised when an attempt is made to modify the type of a node.
751\end{excdesc}
752
753\begin{excdesc}{InvalidStateErr}
754 Raised when an attempt is made to use an object that is not or is no
755 longer usable.
756\end{excdesc}
757
758\begin{excdesc}{NamespaceErr}
759 If an attempt is made to change any object in a way that is not
760 permitted with regard to the
761 \citetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML}
762 recommendation, this exception is raised.
763\end{excdesc}
764
765\begin{excdesc}{NotFoundErr}
766 Exception when a node does not exist in the referenced context. For
767 example, \method{NamedNodeMap.removeNamedItem()} will raise this if
768 the node passed in does not exist in the map.
769\end{excdesc}
770
771\begin{excdesc}{NotSupportedErr}
772 Raised when the implementation does not support the requested type
773 of object or operation.
774\end{excdesc}
775
776\begin{excdesc}{NoDataAllowedErr}
777 This is raised if data is specified for a node which does not
778 support data.
779 % XXX a better explanation is needed!
780\end{excdesc}
781
782\begin{excdesc}{NoModificationAllowedErr}
783 Raised on attempts to modify an object where modifications are not
784 allowed (such as for read-only nodes).
785\end{excdesc}
786
787\begin{excdesc}{SyntaxErr}
788 Raised when an invalid or illegal string is specified.
789 % XXX how is this different from InvalidCharacterErr ???
790\end{excdesc}
791
792\begin{excdesc}{WrongDocumentErr}
793 Raised when a node is inserted in a different document than it
794 currently belongs to, and the implementation does not support
795 migrating the node from one document to the other.
796\end{excdesc}
797
798The exception codes defined in the DOM recommendation map to the
799exceptions described above according to this table:
800
801\begin{tableii}{l|l}{constant}{Constant}{Exception}
802 \lineii{DOMSTRING_SIZE_ERR}{\exception{DomstringSizeErr}}
803 \lineii{HIERARCHY_REQUEST_ERR}{\exception{HierarchyRequestErr}}
804 \lineii{INDEX_SIZE_ERR}{\exception{IndexSizeErr}}
805 \lineii{INUSE_ATTRIBUTE_ERR}{\exception{InuseAttributeErr}}
806 \lineii{INVALID_ACCESS_ERR}{\exception{InvalidAccessErr}}
807 \lineii{INVALID_CHARACTER_ERR}{\exception{InvalidCharacterErr}}
808 \lineii{INVALID_MODIFICATION_ERR}{\exception{InvalidModificationErr}}
809 \lineii{INVALID_STATE_ERR}{\exception{InvalidStateErr}}
810 \lineii{NAMESPACE_ERR}{\exception{NamespaceErr}}
811 \lineii{NOT_FOUND_ERR}{\exception{NotFoundErr}}
812 \lineii{NOT_SUPPORTED_ERR}{\exception{NotSupportedErr}}
813 \lineii{NO_DATA_ALLOWED_ERR}{\exception{NoDataAllowedErr}}
814 \lineii{NO_MODIFICATION_ALLOWED_ERR}{\exception{NoModificationAllowedErr}}
815 \lineii{SYNTAX_ERR}{\exception{SyntaxErr}}
816 \lineii{WRONG_DOCUMENT_ERR}{\exception{WrongDocumentErr}}
817\end{tableii}
818
819
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000820\subsection{Conformance \label{dom-conformance}}
Fred Drake669d36f2000-10-24 02:34:45 +0000821
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000822This section describes the conformance requirements and relationships
823between the Python DOM API, the W3C DOM recommendations, and the OMG
824IDL mapping for Python.
Fred Drake669d36f2000-10-24 02:34:45 +0000825
Fred Drake16942f22000-12-07 04:47:51 +0000826
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000827\subsubsection{Type Mapping \label{dom-type-mapping}}
Fred Drake669d36f2000-10-24 02:34:45 +0000828
Fred Drake16942f22000-12-07 04:47:51 +0000829The primitive IDL types used in the DOM specification are mapped to
830Python types according to the following table.
831
832\begin{tableii}{l|l}{code}{IDL Type}{Python Type}
833 \lineii{boolean}{\code{IntegerType} (with a value of \code{0} or \code{1})}
834 \lineii{int}{\code{IntegerType}}
835 \lineii{long int}{\code{IntegerType}}
836 \lineii{unsigned int}{\code{IntegerType}}
837\end{tableii}
838
839Additionally, the \class{DOMString} defined in the recommendation is
840mapped to a Python string or Unicode string. Applications should
841be able to handle Unicode whenever a string is returned from the DOM.
842
843The IDL \keyword{null} value is mapped to \code{None}, which may be
844accepted or provided by the implementation whenever \keyword{null} is
845allowed by the API.
846
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000847
848\subsubsection{Accessor Methods \label{dom-accessor-methods}}
849
850The mapping from OMG IDL to Python defines accessor functions for IDL
851\keyword{attribute} declarations in much the way the Java mapping
852does. Mapping the IDL declarations
Fred Drake669d36f2000-10-24 02:34:45 +0000853
854\begin{verbatim}
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000855readonly attribute string someValue;
856 attribute string anotherValue;
Fred Drake669d36f2000-10-24 02:34:45 +0000857\end{verbatim}
858
Andrew M. Kuchlinge7e03cd2001-06-23 16:26:44 +0000859yields three accessor functions: a ``get'' method for
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000860\member{someValue} (\method{_get_someValue()}), and ``get'' and
861``set'' methods for
862\member{anotherValue} (\method{_get_anotherValue()} and
863\method{_set_anotherValue()}). The mapping, in particular, does not
864require that the IDL attributes are accessible as normal Python
865attributes: \code{\var{object}.someValue} is \emph{not} required to
866work, and may raise an \exception{AttributeError}.
Fred Drake669d36f2000-10-24 02:34:45 +0000867
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000868The Python DOM API, however, \emph{does} require that normal attribute
869access work. This means that the typical surrogates generated by
870Python IDL compilers are not likely to work, and wrapper objects may
871be needed on the client if the DOM objects are accessed via CORBA.
872While this does require some additional consideration for CORBA DOM
873clients, the implementers with experience using DOM over CORBA from
874Python do not consider this a problem. Attributes that are declared
875\keyword{readonly} may not restrict write access in all DOM
876implementations.
Fred Drake669d36f2000-10-24 02:34:45 +0000877
Fred Drakeeaf57aa2000-11-29 06:10:22 +0000878Additionally, the accessor functions are not required. If provided,
879they should take the form defined by the Python IDL mapping, but
880these methods are considered unnecessary since the attributes are
Fred Drake16942f22000-12-07 04:47:51 +0000881accessible directly from Python. ``Set'' accessors should never be
882provided for \keyword{readonly} attributes.