-\section{\module{xml.dom.minidom} ---
- The Document Object Model}
+\section{\module{xml.dom} ---
+ The Document Object Model API}
-\declaremodule{standard}{xml.dom.minidom}
-\modulesynopsis{Lightweight Document Object Model (DOM) implementation.}
-\moduleauthor{Paul Prescod}{paul@prescod.net}
+\declaremodule{standard}{xml.dom}
+\modulesynopsis{Document Object Model API for Python.}
\sectionauthor{Paul Prescod}{paul@prescod.net}
\sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de}
\versionadded{2.0}
-The \module{xml.dom.minidom} provides a light-weight implementation of
-the W3C Document Object Model. The DOM is a cross-language API from
-the Web Consortium (W3C) for accessing and modifying XML documents. A
-DOM implementation allows to convert an XML document into a tree-like
-structure, or to build such a structure from scratch. It then gives
-access to the structure through a set of objects which provided
-well-known interfaces. Minidom is intended to be simpler than the full
-DOM and also significantly smaller.
-
-The DOM is extremely useful for random-access applications. SAX only
-allows you a view of one bit of the document at a time. If you are
-looking at one SAX element, you have no access to another. If you are
-looking at a text node, you have no access to a containing
-element. When you write a SAX application, you need to keep track of
-your program's position in the document somewhere in your own
-code. Sax does not do it for you. Also, if you need to look ahead in
-the XML document, you are just out of luck.
+The Document Object Model, or ``DOM,'' is a cross-language API from
+the World Wide Web Consortium (W3C) for accessing and modifying XML
+documents. A DOM implementation presents an XML document as a tree
+structure, or allows client code to build such a structure from
+scratch. It then gives access to the structure through a set of
+objects which provided well-known interfaces.
+
+The DOM is extremely useful for random-access applications. SAX only
+allows you a view of one bit of the document at a time. If you are
+looking at one SAX element, you have no access to another. If you are
+looking at a text node, you have no access to a containing element.
+When you write a SAX application, you need to keep track of your
+program's position in the document somewhere in your own code. SAX
+does not do it for you. Also, if you need to look ahead in the XML
+document, you are just out of luck.
Some applications are simply impossible in an event driven model with
-no access to a tree. Of course you could build some sort of tree
+no access to a tree. Of course you could build some sort of tree
yourself in SAX events, but the DOM allows you to avoid writing that
-code. The DOM is a standard tree representation for XML data.
-
-%What if your needs are somewhere between SAX and the DOM? Perhaps you cannot
-%afford to load the entire tree in memory but you find the SAX model
-%somewhat cumbersome and low-level. There is also an experimental module
-%called pulldom that allows you to build trees of only the parts of a
-%document that you need structured access to. It also has features that allow
-%you to find your way around the DOM.
+code. The DOM is a standard tree representation for XML data.
+
+%What if your needs are somewhere between SAX and the DOM? Perhaps
+%you cannot afford to load the entire tree in memory but you find the
+%SAX model somewhat cumbersome and low-level. There is also a module
+%called xml.dom.pulldom that allows you to build trees of only the
+%parts of a document that you need structured access to. It also has
+%features that allow you to find your way around the DOM.
% See http://www.prescod.net/python/pulldom
-DOM applications typically start by parsing some XML into a DOM. This
-is done through the parse functions:
-
-\begin{verbatim}
-from xml.dom.minidom import parse, parseString
-
-dom1 = parse('c:\\temp\\mydata.xml') # parse an XML file by name
-
-datasource = open('c:\\temp\\mydata.xml')
-dom2 = parse(datasource) # parse an open file
-
-dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')
-\end{verbatim}
-
-The parse function can take either a filename or an open file object.
-
-\begin{funcdesc}{parse}{filename_or_file{, parser}}
- Return a \class{Document} from the given input. \var{filename_or_file}
- may be either a file name, or a file-like object. \var{parser}, if
- given, must be a SAX2 parser object. This function will change the
- document handler of the parser and activate namespace support; other
- parser configuration (like setting an entity resolver) must have been
- done in advance.
-\end{funcdesc}
-
-If you have XML in a string, you can use the parseString function
-instead:
-
-\begin{funcdesc}{parseString}{string\optional{, parser}}
- Return a \class{Document} that represents the \var{string}. This
- method creates a \class{StringIO} object for the string and passes
- that on to \function{parse}.
-\end{funcdesc}
-
-Both functions return a document object representing the content of
-the document.
-
-You can also create a document node merely by instantiating a
-document object. Then you could add child nodes to it to populate
-the DOM.
-
-\begin{verbatim}
-from xml.dom.minidom import Document
-
-newdoc = Document()
-newel = newdoc.createElement("some_tag")
-newdoc.appendChild(newel)
-\end{verbatim}
+The Document Object Model is being defined by the W3C in stages, or
+``levels'' in their terminology. The Python mapping of the API is
+substantially based on the DOM Level 2 recommendation. Some aspects
+of the API will only became available in Python 2.1, or may only be
+available in particular DOM implementations.
+
+DOM applications typically start by parsing some XML into a DOM. How
+this is accomplished is not covered at all by DOM Level 1, and Level 2
+provides only limited improvements. There is a
+\class{DOMImplementation} object class which provides access to
+\class{Document} creation methods, but these methods were only added
+in DOM Level 2 and were not implemented in time for Python 2.0. There
+is also no well-defined way to access this functions without an
+existing \class{Document} object. For Python 2.0, consult the
+documentation for each particular DOM implementation to determine the
+bootstrap procedure needed to create and initialize \class{Document}
+instances.
Once you have a DOM document object, you can access the parts of your
XML document through its properties and methods. These properties are
-defined in the DOM specification. The main property of the document
-object is the documentElement property. It gives you the main element
-in the XML document: the one that holds all others. Here is an
-example program:
+defined in the DOM specification; this portion of the reference manual
+describes the interpretation of the specification in Python.
-\begin{verbatim}
-dom3 = parseString("<myxml>Some data</myxml>")
-assert dom3.documentElement.tagName == "myxml"
-\end{verbatim}
-
-When you are finished with a DOM, you should clean it up. This is
-necessary because some versions of Python do not support garbage
-collection of objects that refer to each other in a cycle. Until this
-restriction is removed from all versions of Python, it is safest to
-write your code as if cycles would not be cleaned up.
+The specification provided by the W3C defines the DOM API for Java,
+ECMAScript, and OMG IDL. The Python mapping defined here is based in
+large part on the IDL version of the specification, but strict
+compliance is not required (though implementations are free to support
+the strict mapping from IDL). See section \ref{dom-conformance},
+``Conformance,'' for a detailed discussion of mapping requirements.
-The way to clean up a DOM is to call its \method{unlink()} method:
-
-\begin{verbatim}
-dom1.unlink()
-dom2.unlink()
-dom3.unlink()
-\end{verbatim}
-
-\method{unlink()} is a \module{minidom}-specific extension to the DOM
-API. After calling \method{unlink()}, a DOM is basically useless.
\begin{seealso}
- \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{DOM Specification}
- {This is the canonical specification for the level of the
+ \seetitle[http://www.w3.org/TR/DOM-Level-2-Core/]{Document Object
+ Model (DOM) Level 2 Specification}
+ {The W3C recommendation upon which the Python DOM API is
+ based.}
+ \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object
+ Model (DOM) Level 1 Specification}
+ {The W3C recommendation for the
DOM supported by \module{xml.dom.minidom}.}
\seetitle[http://pyxml.sourceforge.net]{PyXML}{Users that require a
full-featured implementation of DOM should use the PyXML
package.}
+ \seetitle[http://cgi.omg.org/cgi-bin/doc?orbos/99-08-02.pdf]{CORBA
+ Scripting with Python}
+ {This specifies the mapping from OMG IDL to Python.}
\end{seealso}
-\subsection{DOM objects \label{dom-objects}}
+\subsection{Objects in the DOM \label{dom-objects}}
The definitive documentation for the DOM is the DOM specification from
the W3C. This section lists the properties and methods supported by
\refmodule{xml.dom.minidom}.
-\begin{classdesc}{Node}{}
+Note that DOM attributes may also be manipulated as nodes instead of
+as simple strings. It is fairly rare that you must do this, however,
+so this usage is not yet documented.
+
+
+\begin{tableiii}{l|l|l}{class}{Interface}{Section}{Purpose}
+ \lineiii{Node}{\ref{dom-node-objects}}
+ {Base interface for most objects in a document.}
+ \lineiii{Document}{\ref{dom-document-objects}}
+ {Object which represents an entire document.}
+ \lineiii{Element}{\ref{dom-element-objects}}
+ {Element nodes in the document hierarchy.}
+ \lineiii{Attr}{\ref{dom-attr-objects}}
+ {Attribute value nodes on element nodes.}
+ \lineiii{Comment}{\ref{dom-comment-objects}}
+ {Representation of comments in the source document.}
+ \lineiii{Text}{\ref{dom-text-objects}}
+ {Nodes containing textual content from the document.}
+ \lineiii{ProcessingInstruction}{\ref{dom-pi-objects}}
+ {Processing instruction representation.}
+\end{tableiii}
+
+
+\subsubsection{Node Objects \label{dom-node-objects}}
+
All of the components of an XML document are subclasses of
\class{Node}.
-\begin{memberdesc}{nodeType}
+\begin{memberdesc}[Node]{nodeType}
An integer representing the node type. Symbolic constants for the
types are on the \class{Node} object: \constant{DOCUMENT_NODE},
\constant{ELEMENT_NODE}, \constant{ATTRIBUTE_NODE},
\constant{DOCUMENT_TYPE_NODE}, \constant{NOTATION_NODE}.
\end{memberdesc}
-\begin{memberdesc}{parentNode}
+\begin{memberdesc}[Node]{parentNode}
The parent of the current node. \code{None} for the document node.
\end{memberdesc}
-\begin{memberdesc}{attributes}
-An \class{AttributeList} of attribute objects. Only
-elements have this attribute. Others return \code{None}.
+\begin{memberdesc}[Node]{attributes}
+An \class{AttributeList} of attribute objects. Only elements have
+actual values for this; others provide \code{None} for this attribute.
\end{memberdesc}
-\begin{memberdesc}{previousSibling}
+\begin{memberdesc}[Node]{previousSibling}
The node that immediately precedes this one with the same parent. For
instance the element with an end-tag that comes just before the
\var{self} element's start-tag. Of course, XML documents are made
comment, or something else.
\end{memberdesc}
-\begin{memberdesc}{nextSibling}
+\begin{memberdesc}[Node]{nextSibling}
The node that immediately follows this one with the same parent. See
also \member{previousSibling}.
\end{memberdesc}
-\begin{memberdesc}{childNodes}
+\begin{memberdesc}[Node]{childNodes}
A list of nodes contained within this node.
\end{memberdesc}
-\begin{memberdesc}{firstChild}
-Equivalent to \code{childNodes[0]}.
+\begin{memberdesc}[Node]{firstChild}
+The first child of the node, if there are any, or \code{None}.
\end{memberdesc}
-\begin{memberdesc}{lastChild}
-Equivalent to \code{childNodes[-1]}.
+\begin{memberdesc}[Node]{lastChild}
+The last child of the node, if there are any, or \code{None}.
\end{memberdesc}
-\begin{memberdesc}{nodeName}
+\begin{memberdesc}[Node]{nodeName}
Has a different meaning for each node type. See the DOM specification
for details. You can always get the information you would get here
from another property such as the \member{tagName} property for
elements or the \member{name} property for attributes.
\end{memberdesc}
-\begin{memberdesc}{nodeValue}
+\begin{memberdesc}[Node]{nodeValue}
Has a different meaning for each node type. See the DOM specification
for details. The situation is similar to that with \member{nodeName}.
\end{memberdesc}
-\begin{methoddesc}{unlink}{}
-Break internal references within the DOM so that it will be garbage
-collected on versions of Python without cyclic GC.
-\end{methoddesc}
-
-\begin{methoddesc}{writexml}{writer}
-Write XML to the writer object. The writer should have a
-\method{write()} method which matches that of the file object
-interface.
-\end{methoddesc}
-
-\begin{methoddesc}{toxml}{}
-Return the XML string that the DOM represents.
-\end{methoddesc}
-
-\begin{methoddesc}{hasChildNodes}{}
-Returns true the node has any child nodes.
+\begin{methoddesc}[Node]{hasChildNodes}{}
+Returns true if the node has any child nodes.
\end{methoddesc}
-\begin{methoddesc}{insertBefore}{newChild, refChild}
+\begin{methoddesc}[Node]{insertBefore}{newChild, refChild}
Insert a new child node before an existing child. It must be the case
that \var{refChild} is a child of this node; if not,
\exception{ValueError} is raised.
\end{methoddesc}
-\begin{methoddesc}{replaceChild}{newChild, oldChild}
+\begin{methoddesc}[Node]{replaceChild}{newChild, oldChild}
Replace an existing node with a new node. It must be the case that
\var{oldChild} is a child of this node; if not,
\exception{ValueError} is raised.
\end{methoddesc}
-\begin{methoddesc}{removeChild}{oldChild}
+\begin{methoddesc}[Node]{removeChild}{oldChild}
Remove a child node. \var{oldChild} must be a child of this node; if
-not, \exception{ValueError} is raised.
+not, \exception{ValueError} is raised. \var{oldChild} is returned on
+success. If \var{oldChild} will not be used further, its
+\method{unlink()} method should be called.
+\end{methoddesc}
+
+\begin{methoddesc}[Node]{appendChild}{newChild}
+Add a new child node to this node at the end of the list of children,
+returning \var{newChild}.
\end{methoddesc}
-\begin{methoddesc}{appendChild}{newChild}
-Add a new child node to this node list.
+\begin{methoddesc}[Node]{normalize}{}
+Join adjacent text nodes so that all stretches of text are stored as
+single \class{Text} instances. This simplifies processing text from a
+DOM tree for many applications.
+\versionadded{2.1}
\end{methoddesc}
-\begin{methoddesc}{cloneNode}{deep}
-Clone this node. Deep means to clone all children also. Deep cloning
-is not implemented in Python 2 so the deep parameter should always be
-0 for now.
+\begin{methoddesc}[Node]{cloneNode}{deep}
+Clone this node. Setting \var{deep} means to clone all child nodes as
+well.
+
+\strong{Warning:} Although this method was present in the version of
+\refmodule{xml.dom.minidom} packaged with Python 2.0, it was seriously
+broken. This has been corrected for subsequent releases.
\end{methoddesc}
-\end{classdesc}
+\subsubsection{Document Objects \label{dom-document-objects}}
-\begin{classdesc}{Document}{}
-Represents an entire XML document, including its constituent elements,
-attributes, processing instructions, comments etc. Remeber that it
-inherits properties from \class{Node}.
+A \class{Document} represents an entire XML document, including its
+constituent elements, attributes, processing instructions, comments
+etc. Remeber that it inherits properties from \class{Node}.
-\begin{memberdesc}{documentElement}
+\begin{memberdesc}[Document]{documentElement}
The one and only root element of the document.
\end{memberdesc}
-\begin{methoddesc}{createElement}{tagName}
+\begin{methoddesc}[Document]{createElement}{tagName}
Create a new element. The element is not inserted into the document
when it is created. You need to explicitly insert it with one of the
other methods such as \method{insertBefore()} or
\method{appendChild()}.
\end{methoddesc}
-\begin{methoddesc}{createTextNode}{data}
+\begin{methoddesc}[Document]{createElementNS}{namespaceURI, tagName}
+Create a new element with a namespace. The \var{tagName} may have a
+prefix. The element is not inserted into the document when it is
+created. You need to explicitly insert it with one of the other
+methods such as \method{insertBefore()} or \method{appendChild()}.
+\end{methoddesc}
+
+\begin{methoddesc}[Document]{createTextNode}{data}
Create a text node containing the data passed as a parameter. As with
the other creation methods, this one does not insert the node into the
tree.
\end{methoddesc}
-\begin{methoddesc}{createComment}{data}
+\begin{methoddesc}[Document]{createComment}{data}
Create a comment node containing the data passed as a parameter. As
with the other creation methods, this one does not insert the node
into the tree.
\end{methoddesc}
-\begin{methoddesc}{createProcessingInstruction}{target, data}
+\begin{methoddesc}[Document]{createProcessingInstruction}{target, data}
Create a processing instruction node containing the \var{target} and
\var{data} passed as parameters. As with the other creation methods,
this one does not insert the node into the tree.
\end{methoddesc}
-\begin{methoddesc}{createAttribute}{name}
+\begin{methoddesc}[Document]{createAttribute}{name}
Create an attribute node. This method does not associate the
attribute node with any particular element. You must use
\method{setAttributeNode()} on the appropriate \class{Element} object
to use the newly created attribute instance.
\end{methoddesc}
-\begin{methoddesc}{createElementNS}{namespaceURI, tagName}
-Create a new element with a namespace. The \var{tagName} may have a
-prefix. The element is not inserted into the document when it is
-created. You need to explicitly insert it with one of the other
-methods such as \method{insertBefore()} or \method{appendChild()}.
-\end{methoddesc}
-
-
-\begin{methoddesc}{createAttributeNS}{namespaceURI, qualifiedName}
+\begin{methoddesc}[Document]{createAttributeNS}{namespaceURI, qualifiedName}
Create an attribute node with a namespace. The \var{tagName} may have
a prefix. This method does not associate the attribute node with any
particular element. You must use \method{setAttributeNode()} on the
instance.
\end{methoddesc}
-\begin{methoddesc}{getElementsByTagName}{tagName}
+\begin{methoddesc}[Document]{getElementsByTagName}{tagName}
Search for all descendants (direct children, children's children,
etc.) with a particular element type name.
\end{methoddesc}
-\begin{methoddesc}{getElementsByTagNameNS}{namespaceURI, localName}
+\begin{methoddesc}[Document]{getElementsByTagNameNS}{namespaceURI, localName}
Search for all descendants (direct children, children's children,
etc.) with a particular namespace URI and localname. The localname is
the part of the namespace after the prefix.
\end{methoddesc}
-\end{classdesc}
+\subsubsection{Element Objects \label{dom-element-objects}}
+
+\class{Element} is a subclass of \class{Node}, so inherits all the
+attributes of that class.
-\begin{classdesc}{Element}{}
-\begin{memberdesc}{tagName}
+\begin{memberdesc}[Element]{tagName}
The element type name. In a namespace-using document it may have
colons in it.
\end{memberdesc}
-\begin{memberdesc}{localName}
+\begin{memberdesc}[Element]{localName}
The part of the \member{tagName} following the colon if there is one,
else the entire \member{tagName}.
\end{memberdesc}
-\begin{memberdesc}{prefix}
+\begin{memberdesc}[Element]{prefix}
The part of the \member{tagName} preceding the colon if there is one,
else the empty string.
\end{memberdesc}
-\begin{memberdesc}{namespaceURI}
+\begin{memberdesc}[Element]{namespaceURI}
The namespace associated with the tagName.
\end{memberdesc}
-\begin{methoddesc}{getAttribute}{attname}
+\begin{methoddesc}[Element]{getAttribute}{attname}
Return an attribute value as a string.
\end{methoddesc}
-\begin{methoddesc}{setAttribute}{attname, value}
+\begin{methoddesc}[Element]{setAttribute}{attname, value}
Set an attribute value from a string.
\end{methoddesc}
-\begin{methoddesc}{removeAttribute}{attname}
+\begin{methoddesc}[Element]{removeAttribute}{attname}
Remove an attribute by name.
\end{methoddesc}
-\begin{methoddesc}{getAttributeNS}{namespaceURI, localName}
+\begin{methoddesc}[Element]{getAttributeNS}{namespaceURI, localName}
Return an attribute value as a string, given a \var{namespaceURI} and
\var{localName}. Note that a localname is the part of a prefixed
attribute name after the colon (if there is one).
\end{methoddesc}
-\begin{methoddesc}{setAttributeNS}{namespaceURI, qname, value}
+\begin{methoddesc}[Element]{setAttributeNS}{namespaceURI, qname, value}
Set an attribute value from a string, given a \var{namespaceURI} and a
\var{qname}. Note that a qname is the whole attribute name. This is
different than above.
\end{methoddesc}
-\begin{methoddesc}{removeAttributeNS}{namespaceURI, localName}
+\begin{methoddesc}[Element]{removeAttributeNS}{namespaceURI, localName}
Remove an attribute by name. Note that it uses a localName, not a
qname.
\end{methoddesc}
-\begin{methoddesc}{getElementsByTagName}{tagName}
+\begin{methoddesc}[Element]{getElementsByTagName}{tagName}
Same as equivalent method in the \class{Document} class.
\end{methoddesc}
-\begin{methoddesc}{getElementsByTagNameNS}{tagName}
+\begin{methoddesc}[Element]{getElementsByTagNameNS}{tagName}
Same as equivalent method in the \class{Document} class.
\end{methoddesc}
-\end{classdesc}
+\subsubsection{Attr Objects \label{dom-attr-objects}}
-\begin{classdesc}{Attribute}{}
+\class{Attr} inherits from \class{Node}, so inherits all its
+attributes.
-\begin{memberdesc}{name}
+\begin{memberdesc}[Attr]{name}
The attribute name. In a namespace-using document it may have colons
in it.
\end{memberdesc}
-\begin{memberdesc}{localName}
+\begin{memberdesc}[Attr]{localName}
The part of the name following the colon if there is one, else the
entire name.
\end{memberdesc}
-\begin{memberdesc}{prefix}
+\begin{memberdesc}[Attr]{prefix}
The part of the name preceding the colon if there is one, else the
empty string.
\end{memberdesc}
-\begin{memberdesc}{namespaceURI}
+\begin{memberdesc}[Attr]{namespaceURI}
The namespace associated with the attribute name.
\end{memberdesc}
-\end{classdesc}
+\subsubsection{NamedNodeMap Objects \label{dom-attributelist-objects}}
-\begin{classdesc}{AttributeList}{}
+\class{NamedNodeMap} does \emph{not} inherit from \class{Node}.
-\begin{memberdesc}{length}
+\begin{memberdesc}[NamedNodeMap]{length}
The length of the attribute list.
\end{memberdesc}
-\begin{methoddesc}{item}{index}
+\begin{methoddesc}[NamedNodeMap]{item}{index}
Return an attribute with a particular index. The order you get the
attributes in is arbitrary but will be consistent for the life of a
DOM. Each item is an attribute node. Get its value with the
\member{value} attribbute.
\end{methoddesc}
-There are also experimental methods that give this class more
-dictionary-like behavior. You can use them or you can use the
-standardized \method{getAttribute*()}-family methods.
+There are also experimental methods that give this class more mapping
+behavior. You can use them or you can use the standardized
+\method{getAttribute*()}-family methods on the \class{Element} objects.
-\end{classdesc}
+\subsubsection{Comment Objects \label{dom-comment-objects}}
-\begin{classdesc}{Comment}{}
-Represents a comment in the XML document.
+\class{Comment} represents a comment in the XML document. It is a
+subclass of \class{Node}.
-\begin{memberdesc}{data}
+\begin{memberdesc}[Comment]{data}
The content of the comment.
\end{memberdesc}
-\end{classdesc}
-\begin{classdesc}{Text}{}
-Represents text in the XML document.
+\subsubsection{Text Objects \label{dom-text-objects}}
-\begin{memberdesc}{data}
+The \class{Text} interface represents text in the XML document. It
+inherits from \class{Node}.
+
+\begin{memberdesc}[Text]{data}
The content of the text node.
\end{memberdesc}
-\end{classdesc}
-\begin{classdesc}{ProcessingInstruction}{}
-Represents a processing instruction in the XML document.
+\subsubsection{ProcessingInstruction Objects \label{dom-pi-objects}}
+
+Represents a processing instruction in the XML document; this inherits
+from the \class{Node} interface.
-\begin{memberdesc}{target}
+\begin{memberdesc}[ProcessingInstruction]{target}
The content of the processing instruction up to the first whitespace
character.
\end{memberdesc}
-\begin{memberdesc}{data}
+\begin{memberdesc}[ProcessingInstruction]{data}
The content of the processing instruction following the first
whitespace character.
\end{memberdesc}
-\end{classdesc}
-Note that DOM attributes may also be manipulated as nodes instead of as
-simple strings. It is fairly rare that you must do this, however, so this
-usage is not yet documented here.
+\subsection{Conformance \label{dom-conformance}}
-\begin{seealso}
- \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{DOM Specification}
- {This is the canonical specification for the level of the
- DOM supported by \module{xml.dom.minidom}.}
-\end{seealso}
+This section describes the conformance requirements and relationships
+between the Python DOM API, the W3C DOM recommendations, and the OMG
+IDL mapping for Python.
+\subsubsection{Type Mapping \label{dom-type-mapping}}
-\subsection{DOM Example \label{dom-example}}
+XXX Explain what a \class{DOMString} maps to...
-This example program is a fairly realistic example of a simple
-program. In this particular case, we do not take much advantage
-of the flexibility of the DOM.
+\subsubsection{Accessor Methods \label{dom-accessor-methods}}
+
+The mapping from OMG IDL to Python defines accessor functions for IDL
+\keyword{attribute} declarations in much the way the Java mapping
+does. Mapping the IDL declarations
\begin{verbatim}
-from xml.dom.minidom import parse, parseString
-
-document="""
-<slideshow>
-<title>Demo slideshow</title>
-<slide><title>Slide title</title>
-<point>This is a demo</point>
-<point>Of a program for processing slides</point>
-</slide>
-
-<slide><title>Another demo slide</title>
-<point>It is important</point>
-<point>To have more than</point>
-<point>one slide</point>
-</slide>
-</slideshow>
-"""
-
-dom = parseString(document)
-
-space=" "
-def getText(nodelist):
- rc=""
- for node in nodelist:
- if node.nodeType==node.TEXT_NODE:
- rc=rc+node.data
- return rc
-
-def handleSlideshow(slideshow):
- print "<html>"
- handleSlideshowTitle(slideshow.getElementsByTagName("title")[0])
- slides = slideshow.getElementsByTagName("slide")
- handleToc(slides)
- handleSlides(slides)
- print "</html>"
-
-def handleSlides(slides):
- for slide in slides:
- handleSlide(slide)
-
-def handleSlide(slide):
- handleSlideTitle(slide.getElementsByTagName("title")[0])
- handlePoints(slide.getElementsByTagName("point"))
-
-def handleSlideshowTitle(title):
- print "<title>%s</title>"%getText(title.childNodes)
-
-def handleSlideTitle(title):
- print "<h2>%s</h2>"%getText(title.childNodes)
-
-def handlePoints(points):
- print "<ul>"
- for point in points:
- handlePoint(point)
- print "</ul>"
-
-def handlePoint(point):
- print "<li>%s</li>"%getText(point.childNodes)
-
-def handleToc(slides):
- for slide in slides:
- title = slide.getElementsByTagName("title")[0]
- print "<p>%s</p>"%getText(title.childNodes)
-
-handleSlideshow(dom)
+readonly attribute string someValue;
+ attribute string anotherValue;
\end{verbatim}
-\subsection{minidom and the DOM standard \label{minidom-and-dom}}
-
-Minidom is basically a DOM 1.0-compatible DOM with some DOM 2 features
-(primarily namespace features).
-
-Usage of the other DOM interfaces in Python is straight-forward. The
-following mapping rules apply:
-
-\begin{itemize}
-
-\item Interfaces are accessed through instance objects. Applications
-should
-not instantiate the classes themselves; they should use the creator
-functions. Derived interfaces support all operations (and attributes)
-from the base interfaces, plus any new operations.
-
-\item Operations are used as methods. Since the DOM uses only
-\code{in}
-parameters, the arguments are passed in normal order (from left to
-right).
-There are no optional arguments. \code{void} operations return
-\code{None}.
-
-\item IDL attributes map to instance attributes. For compatibility
-with
-the OMG IDL language mapping for Python, an attribute \code{foo} can
-also be accessed through accessor functions \code{_get_foo} and
-\code{_set_foo}. \code{readonly} attributes must not be changed.
-
-\item The types \code{short int},\code{unsigned int},\code{unsigned
-long long},
-and \code{boolean} all map to Python integer objects.
-
-\item The type \code{DOMString} maps to Python strings. \code{minidom}
-supports either byte or Unicode strings, but will normally produce
-Unicode
-strings. Attributes of type \code{DOMString} may also be \code{None}.
-
-\item \code{const} declarations map to variables in their respective
-scope
-(e.g. \code{xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE}); they
-must
-not be changed.
-
-\item \code{DOMException} is currently not supported in
-\module{minidom}. Instead, minidom returns standard Python exceptions
-such as TypeError and AttributeError.
-
-\end{itemize}
-
-The following interfaces have no equivalent in minidom:
-
-\begin{itemize}
-
-\item DOMTimeStamp
-
-\item DocumentType
-
-\item DOMImplementation
-
-\item CharacterData
-
-\item CDATASection
-
-\item Notation
-
-\item Entity
-
-\item EntityReference
-
-\item DocumentFragment
-
-\end{itemize}
-
-Most of these reflect information in the XML document that is not of
-general utility to most DOM users.
+yeilds three accessor functions: a ``get'' method for
+\member{someValue} (\method{_get_someValue()}), and ``get'' and
+``set'' methods for
+\member{anotherValue} (\method{_get_anotherValue()} and
+\method{_set_anotherValue()}). The mapping, in particular, does not
+require that the IDL attributes are accessible as normal Python
+attributes: \code{\var{object}.someValue} is \emph{not} required to
+work, and may raise an \exception{AttributeError}.
+
+The Python DOM API, however, \emph{does} require that normal attribute
+access work. This means that the typical surrogates generated by
+Python IDL compilers are not likely to work, and wrapper objects may
+be needed on the client if the DOM objects are accessed via CORBA.
+While this does require some additional consideration for CORBA DOM
+clients, the implementers with experience using DOM over CORBA from
+Python do not consider this a problem. Attributes that are declared
+\keyword{readonly} may not restrict write access in all DOM
+implementations.
+
+Additionally, the accessor functions are not required. If provided,
+they should take the form defined by the Python IDL mapping, but
+these methods are considered unnecessary since the attributes are
+accessible directly from Python.
--- /dev/null
+\section{\module{xml.dom.minidom} ---
+ Lightweight DOM implementation}
+
+\declaremodule{standard}{xml.dom.minidom}
+\modulesynopsis{Lightweight Document Object Model (DOM) implementation.}
+\moduleauthor{Paul Prescod}{paul@prescod.net}
+\sectionauthor{Paul Prescod}{paul@prescod.net}
+\sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de}
+
+\versionadded{2.0}
+
+\module{xml.dom.minidom} is a light-weight implementation of the
+Document Object Model interface. It is intended to be
+simpler than the full DOM and also significantly smaller.
+
+DOM applications typically start by parsing some XML into a DOM. With
+\module{xml.dom.minidom}, this is done through the parse functions:
+
+\begin{verbatim}
+from xml.dom.minidom import parse, parseString
+
+dom1 = parse('c:\\temp\\mydata.xml') # parse an XML file by name
+
+datasource = open('c:\\temp\\mydata.xml')
+dom2 = parse(datasource) # parse an open file
+
+dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')
+\end{verbatim}
+
+The parse function can take either a filename or an open file object.
+
+\begin{funcdesc}{parse}{filename_or_file{, parser}}
+ Return a \class{Document} from the given input. \var{filename_or_file}
+ may be either a file name, or a file-like object. \var{parser}, if
+ given, must be a SAX2 parser object. This function will change the
+ document handler of the parser and activate namespace support; other
+ parser configuration (like setting an entity resolver) must have been
+ done in advance.
+\end{funcdesc}
+
+If you have XML in a string, you can use the
+\function{parseString()} function instead:
+
+\begin{funcdesc}{parseString}{string\optional{, parser}}
+ Return a \class{Document} that represents the \var{string}. This
+ method creates a \class{StringIO} object for the string and passes
+ that on to \function{parse}.
+\end{funcdesc}
+
+Both functions return a \class{Document} object representing the
+content of the document.
+
+You can also create a \class{Document} node merely by instantiating a
+document object. Then you could add child nodes to it to populate
+the DOM:
+
+\begin{verbatim}
+from xml.dom.minidom import Document
+
+newdoc = Document()
+newel = newdoc.createElement("some_tag")
+newdoc.appendChild(newel)
+\end{verbatim}
+
+Once you have a DOM document object, you can access the parts of your
+XML document through its properties and methods. These properties are
+defined in the DOM specification. The main property of the document
+object is the \member{documentElement} property. It gives you the
+main element in the XML document: the one that holds all others. Here
+is an example program:
+
+\begin{verbatim}
+dom3 = parseString("<myxml>Some data</myxml>")
+assert dom3.documentElement.tagName == "myxml"
+\end{verbatim}
+
+When you are finished with a DOM, you should clean it up. This is
+necessary because some versions of Python do not support garbage
+collection of objects that refer to each other in a cycle. Until this
+restriction is removed from all versions of Python, it is safest to
+write your code as if cycles would not be cleaned up.
+
+The way to clean up a DOM is to call its \method{unlink()} method:
+
+\begin{verbatim}
+dom1.unlink()
+dom2.unlink()
+dom3.unlink()
+\end{verbatim}
+
+\method{unlink()} is a \module{xml.dom.minidom}-specific extension to
+the DOM API. After calling \method{unlink()} on a node, the node and
+its descendents are essentially useless.
+
+\begin{seealso}
+ \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object
+ Model (DOM) Level 1 Specification}
+ {The W3C recommendation for the
+ DOM supported by \module{xml.dom.minidom}.}
+\end{seealso}
+
+
+\subsection{DOM objects \label{dom-objects}}
+
+The definition of the DOM API for Python is given as part of the
+\refmodule{xml.dom} module documentation. This section lists the
+differences between the API and \refmodule{xml.dom.minidom}.
+
+
+\begin{methoddesc}{unlink}{}
+Break internal references within the DOM so that it will be garbage
+collected on versions of Python without cyclic GC. Even when cyclic
+GC is available, using this can make large amounts of memory available
+sooner, so calling this on DOM objects as soon as they are no longer
+needed is good practice. This only needs to be called on the
+\class{Document} object, but may be called on child nodes to discard
+children of that node.
+\end{methoddesc}
+
+\begin{methoddesc}{writexml}{writer}
+Write XML to the writer object. The writer should have a
+\method{write()} method which matches that of the file object
+interface.
+\end{methoddesc}
+
+\begin{methoddesc}{toxml}{}
+Return the XML that the DOM represents as a string.
+\end{methoddesc}
+
+The following standard DOM methods have special considerations with
+\refmodule{xml.dom.minidom}:
+
+\begin{methoddesc}{cloneNode}{deep}
+Although this method was present in the version of
+\refmodule{xml.dom.minidom} packaged with Python 2.0, it was seriously
+broken. This has been corrected for subsequent releases.
+\end{methoddesc}
+
+
+\subsection{DOM Example \label{dom-example}}
+
+This example program is a fairly realistic example of a simple
+program. In this particular case, we do not take much advantage
+of the flexibility of the DOM.
+
+\begin{verbatim}
+import xml.dom.minidom
+
+document = """\
+<slideshow>
+<title>Demo slideshow</title>
+<slide><title>Slide title</title>
+<point>This is a demo</point>
+<point>Of a program for processing slides</point>
+</slide>
+
+<slide><title>Another demo slide</title>
+<point>It is important</point>
+<point>To have more than</point>
+<point>one slide</point>
+</slide>
+</slideshow>
+"""
+
+dom = xml.dom.minidom.parseString(document)
+
+space = " "
+def getText(nodelist):
+ rc = ""
+ for node in nodelist:
+ if node.nodeType == node.TEXT_NODE:
+ rc = rc + node.data
+ return rc
+
+def handleSlideshow(slideshow):
+ print "<html>"
+ handleSlideshowTitle(slideshow.getElementsByTagName("title")[0])
+ slides = slideshow.getElementsByTagName("slide")
+ handleToc(slides)
+ handleSlides(slides)
+ print "</html>"
+
+def handleSlides(slides):
+ for slide in slides:
+ handleSlide(slide)
+
+def handleSlide(slide):
+ handleSlideTitle(slide.getElementsByTagName("title")[0])
+ handlePoints(slide.getElementsByTagName("point"))
+
+def handleSlideshowTitle(title):
+ print "<title>%s</title>" % getText(title.childNodes)
+
+def handleSlideTitle(title):
+ print "<h2>%s</h2>" % getText(title.childNodes)
+
+def handlePoints(points):
+ print "<ul>"
+ for point in points:
+ handlePoint(point)
+ print "</ul>"
+
+def handlePoint(point):
+ print "<li>%s</li>" % getText(point.childNodes)
+
+def handleToc(slides):
+ for slide in slides:
+ title = slide.getElementsByTagName("title")[0]
+ print "<p>%s</p>" % getText(title.childNodes)
+
+handleSlideshow(dom)
+\end{verbatim}
+
+
+\subsection{minidom and the DOM standard \label{minidom-and-dom}}
+
+\refmodule{xml.dom.minidom} is basically a DOM 1.0-compatible DOM with
+some DOM 2 features (primarily namespace features).
+
+Usage of the DOM interface in Python is straight-forward. The
+following mapping rules apply:
+
+\begin{itemize}
+\item Interfaces are accessed through instance objects. Applications
+ should not instantiate the classes themselves; they should use
+ the creator functions available on the \class{Document} object.
+ Derived interfaces support all operations (and attributes) from
+ the base interfaces, plus any new operations.
+
+\item Operations are used as methods. Since the DOM uses only
+ \keyword{in} parameters, the arguments are passed in normal
+ order (from left to right). There are no optional
+ arguments. \keyword{void} operations return \code{None}.
+
+\item IDL attributes map to instance attributes. For compatibility
+ with the OMG IDL language mapping for Python, an attribute
+ \code{foo} can also be accessed through accessor methods
+ \method{_get_foo()} and \method{_set_foo()}. \keyword{readonly}
+ attributes must not be changed; this is not enforced at
+ runtime.
+
+\item The types \code{short int}, \code{unsigned int}, \code{unsigned
+ long long}, and \code{boolean} all map to Python integer
+ objects.
+
+\item The type \code{DOMString} maps to Python strings.
+ \refmodule{xml.dom.minidom} supports either byte or Unicode
+ strings, but will normally produce Unicode strings. Attributes
+ of type \code{DOMString} may also be \code{None}.
+
+\item \keyword{const} declarations map to variables in their
+ respective scope
+ (e.g. \code{xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE});
+ they must not be changed.
+
+\item \code{DOMException} is currently not supported in
+ \refmodule{xml.dom.minidom}. Instead,
+ \refmodule{xml.dom.minidom} uses standard Python exceptions such
+ as \exception{TypeError} and \exception{AttributeError}.
+
+\item \class{NodeList} objects are implemented as Python's built-in
+ list type, so don't support the official API, but are much more
+ ``Pythonic.''
+
+\item \class{NamedNodeMap} is implemented by the class
+ \class{AttributeList}. This should not impact user code.
+\end{itemize}
+
+
+The following interfaces have no implementation in
+\refmodule{xml.dom.minidom}:
+
+\begin{itemize}
+\item DOMTimeStamp
+
+\item DocumentType (added for Python 2.1)
+
+\item DOMImplementation (added for Python 2.1)
+
+\item CharacterData
+
+\item CDATASection
+
+\item Notation
+
+\item Entity
+
+\item EntityReference
+
+\item DocumentFragment
+\end{itemize}
+
+Most of these reflect information in the XML document that is not of
+general utility to most DOM users.
projects / python / commitdiff