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