Doc/lib/xmldomminidom.tex

   1 \section{\module{xml.dom.minidom} ---
   2          Lightweight DOM implementation}
   3
   4 \declaremodule{standard}{xml.dom.minidom}
   5 \modulesynopsis{Lightweight Document Object Model (DOM) implementation.}
   6 \moduleauthor{Paul Prescod}{paul@prescod.net}
   7 \sectionauthor{Paul Prescod}{paul@prescod.net}
   8 \sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de}
   9
  10 \versionadded{2.0}
  11
  12 \module{xml.dom.minidom} is a light-weight implementation of the
  13 Document Object Model interface.  It is intended to be
  14 simpler than the full DOM and also significantly smaller.
  15
  16 DOM applications typically start by parsing some XML into a DOM.  With
  17 \module{xml.dom.minidom}, this is done through the parse functions:
  18
  19 \begin{verbatim}
  20 from xml.dom.minidom import parse, parseString
  21
  22 dom1 = parse('c:\\temp\\mydata.xml') # parse an XML file by name
  23
  24 datasource = open('c:\\temp\\mydata.xml')
  25 dom2 = parse(datasource)   # parse an open file
  26
  27 dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')
  28 \end{verbatim}
  29
  30 The parse function can take either a filename or an open file object.
  31
  32 \begin{funcdesc}{parse}{filename_or_file{, parser}}
  33   Return a \class{Document} from the given input. \var{filename_or_file}
  34   may be either a file name, or a file-like object. \var{parser}, if
  35   given, must be a SAX2 parser object. This function will change the
  36   document handler of the parser and activate namespace support; other
  37   parser configuration (like setting an entity resolver) must have been
  38   done in advance.
  39 \end{funcdesc}
  40
  41 If you have XML in a string, you can use the
  42 \function{parseString()} function instead:
  43
  44 \begin{funcdesc}{parseString}{string\optional{, parser}}
  45   Return a \class{Document} that represents the \var{string}. This
  46   method creates a \class{StringIO} object for the string and passes
  47   that on to \function{parse}.
  48 \end{funcdesc}
  49
  50 Both functions return a \class{Document} object representing the
  51 content of the document.
  52
  53 You can also create a \class{Document} node merely by instantiating a
  54 document object.  Then you could add child nodes to it to populate
  55 the DOM:
  56
  57 \begin{verbatim}
  58 from xml.dom.minidom import Document
  59
  60 newdoc = Document()
  61 newel = newdoc.createElement("some_tag")
  62 newdoc.appendChild(newel)
  63 \end{verbatim}
  64
  65 Once you have a DOM document object, you can access the parts of your
  66 XML document through its properties and methods.  These properties are
  67 defined in the DOM specification.  The main property of the document
  68 object is the \member{documentElement} property.  It gives you the
  69 main element in the XML document: the one that holds all others.  Here
  70 is an example program:
  71
  72 \begin{verbatim}
  73 dom3 = parseString("<myxml>Some data</myxml>")
  74 assert dom3.documentElement.tagName == "myxml"
  75 \end{verbatim}
  76
  77 When you are finished with a DOM, you should clean it up.  This is
  78 necessary because some versions of Python do not support garbage
  79 collection of objects that refer to each other in a cycle.  Until this
  80 restriction is removed from all versions of Python, it is safest to
  81 write your code as if cycles would not be cleaned up.
  82
  83 The way to clean up a DOM is to call its \method{unlink()} method:
  84
  85 \begin{verbatim}
  86 dom1.unlink()
  87 dom2.unlink()
  88 dom3.unlink()
  89 \end{verbatim}
  90
  91 \method{unlink()} is a \module{xml.dom.minidom}-specific extension to
  92 the DOM API.  After calling \method{unlink()} on a node, the node and
  93 its descendents are essentially useless.
  94
  95 \begin{seealso}
  96   \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object
  97             Model (DOM) Level 1 Specification}
  98            {The W3C recommendation for the
  99             DOM supported by \module{xml.dom.minidom}.}
 100 \end{seealso}
 101
 102
 103 \subsection{DOM objects \label{dom-objects}}
 104
 105 The definition of the DOM API for Python is given as part of the
 106 \refmodule{xml.dom} module documentation.  This section lists the
 107 differences between the API and \refmodule{xml.dom.minidom}.
 108
 109
 110 \begin{methoddesc}{unlink}{}
 111 Break internal references within the DOM so that it will be garbage
 112 collected on versions of Python without cyclic GC.  Even when cyclic
 113 GC is available, using this can make large amounts of memory available
 114 sooner, so calling this on DOM objects as soon as they are no longer
 115 needed is good practice.  This only needs to be called on the
 116 \class{Document} object, but may be called on child nodes to discard
 117 children of that node.
 118 \end{methoddesc}
 119
 120 \begin{methoddesc}{writexml}{writer}
 121 Write XML to the writer object.  The writer should have a
 122 \method{write()} method which matches that of the file object
 123 interface.
 124
 125 \versionadded[To support pretty output, new keyword parameters indent,
 126 addindent, and newl have been added]{2.1}
 127
 128 \versionadded[For the \class{Document} node, an additional keyword
 129 argument encoding can be used to specify the encoding field of the XML
 130 header]{2.3}
 131
 132 \end{methoddesc}
 133
 134 \begin{methoddesc}{toxml}{\optional{encoding}}
 135 Return the XML that the DOM represents as a string.
 136
 137 \versionadded[the \var{encoding} argument]{2.3}
 138
 139 With no argument, the XML header does not specify an encoding, and the
 140 result is Unicode string if the default encoding cannot represent all
 141 characters in the document. Encoding this string in an encoding other
 142 than UTF-8 is likely incorrect, since UTF-8 is the default encoding of
 143 XML.
 144
 145 With an explicit \var{encoding} argument, the result is a byte string
 146 in the specified encoding. It is recommended that this argument is
 147 always specified. To avoid UnicodeError exceptions in case of
 148 unrepresentable text data, the encoding argument should be specified
 149 as "utf-8".
 150
 151 \end{methoddesc}
 152
 153 \begin{methoddesc}{toprettyxml}{\optional{indent\optional{, newl}}}
 154
 155 Return a pretty-printed version of the document. \var{indent} specifies
 156 the indentation string and defaults to a tabulator; \var{newl} specifies
 157 the string emitted at the end of each line and defaults to \\n.
 158
 159 \versionadded{2.1}
 160
 161 \versionadded[the encoding argument; see \method{toxml}]{2.3}
 162
 163 \end{methoddesc}
 164
 165 The following standard DOM methods have special considerations with
 166 \refmodule{xml.dom.minidom}:
 167
 168 \begin{methoddesc}{cloneNode}{deep}
 169 Although this method was present in the version of
 170 \refmodule{xml.dom.minidom} packaged with Python 2.0, it was seriously
 171 broken.  This has been corrected for subsequent releases.
 172 \end{methoddesc}
 173
 174
 175 \subsection{DOM Example \label{dom-example}}
 176
 177 This example program is a fairly realistic example of a simple
 178 program. In this particular case, we do not take much advantage
 179 of the flexibility of the DOM.
 180
 181 \verbatiminput{minidom-example.py}
 182
 183
 184 \subsection{minidom and the DOM standard \label{minidom-and-dom}}
 185
 186 The \refmodule{xml.dom.minidom} module is essentially a DOM
 187 1.0-compatible DOM with some DOM 2 features (primarily namespace
 188 features).
 189
 190 Usage of the DOM interface in Python is straight-forward.  The
 191 following mapping rules apply:
 192
 193 \begin{itemize}
 194 \item Interfaces are accessed through instance objects. Applications
 195       should not instantiate the classes themselves; they should use
 196       the creator functions available on the \class{Document} object.
 197       Derived interfaces support all operations (and attributes) from
 198       the base interfaces, plus any new operations.
 199
 200 \item Operations are used as methods. Since the DOM uses only
 201       \keyword{in} parameters, the arguments are passed in normal
 202       order (from left to right).   There are no optional
 203       arguments. \keyword{void} operations return \code{None}.
 204
 205 \item IDL attributes map to instance attributes. For compatibility
 206       with the OMG IDL language mapping for Python, an attribute
 207       \code{foo} can also be accessed through accessor methods
 208       \method{_get_foo()} and \method{_set_foo()}.  \keyword{readonly}
 209       attributes must not be changed; this is not enforced at
 210       runtime.
 211
 212 \item The types \code{short int}, \code{unsigned int}, \code{unsigned
 213       long long}, and \code{boolean} all map to Python integer
 214       objects.
 215
 216 \item The type \code{DOMString} maps to Python strings.
 217       \refmodule{xml.dom.minidom} supports either byte or Unicode
 218       strings, but will normally produce Unicode strings.  Values
 219       of type \code{DOMString} may also be \code{None} where allowed
 220       to have the IDL \code{null} value by the DOM specification from
 221       the W3C.
 222
 223 \item \keyword{const} declarations map to variables in their
 224       respective scope
 225       (e.g. \code{xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE});
 226       they must not be changed.
 227
 228 \item \code{DOMException} is currently not supported in
 229       \refmodule{xml.dom.minidom}.  Instead,
 230       \refmodule{xml.dom.minidom} uses standard Python exceptions such
 231       as \exception{TypeError} and \exception{AttributeError}.
 232
 233 \item \class{NodeList} objects are implemented using Python's built-in
 234       list type.  Starting with Python 2.2, these objects provide the
 235       interface defined in the DOM specification, but with earlier
 236       versions of Python they do not support the official API.  They
 237       are, however, much more ``Pythonic'' than the interface defined
 238       in the W3C recommendations.
 239 \end{itemize}
 240
 241
 242 The following interfaces have no implementation in
 243 \refmodule{xml.dom.minidom}:
 244
 245 \begin{itemize}
 246 \item \class{DOMTimeStamp}
 247
 248 \item \class{DocumentType} (added in Python 2.1)
 249
 250 \item \class{DOMImplementation} (added in Python 2.1)
 251
 252 \item \class{CharacterData}
 253
 254 \item \class{CDATASection}
 255
 256 \item \class{Notation}
 257
 258 \item \class{Entity}
 259
 260 \item \class{EntityReference}
 261
 262 \item \class{DocumentFragment}
 263 \end{itemize}
 264
 265 Most of these reflect information in the XML document that is not of
 266 general utility to most DOM users.