These are utility classes and functions that provide capabilities not yet specified in the DOM spec. Some of these facilities, such as factories and readers are expected to be specified in later levels of the DOM, so we try to keep our proprietary interfaces simple for now so that you can more painlessly migrate when relevant standards emerge.
See the demo directory for examples exercising many of these extensions.
The Reader package allows you to parse source strings in XML and HTML into DOM trees. You select a reader module according to the nature of your input. If you are using Python's htmllib library to read in HTML, use reader.HtmlLib. If you are reading the xml-sig's SAX package to read in XML, you would use reader.Sax2. In some cases, you might want to use reader.Sax instead.
xml.dom.ext.reader.Sax2.FromXml(str, ownerDocument, validate, keepAllWs, catName, saxHandlerClass)
ParametersReturn Value
str
of type well-formed XML string
The XML source
ownerDocument
of type xml.dom.Document
An optional document to hold the generated nodes. If None, a new document node will be created as the root node. Default is None.
validate
of type boolean
Whether or not to validate the document. Default is 0.
keepAllWs
of type boolean
Whether or not to maintain ignorable whitespace in the DOM tree as text nodes. Note that even if you set this flag, you can always get rid of the white space using xml.dom.ext.StripXml(). Default is 0.
catName
of type string representing a file path
An XCatalog file to use for looking up XML public identifiers. A catalog is only useful if you choose to validate. Default is None.
saxHandlerClass
of type xml.sax.Handler
SAX event consumer that builds a DOM tree accordingly . Default is xml.dom.ext.reader.Sax2.XmlDomGenerator.
- xml.dom.Document
The DOM tree resulting from the given text
There are also similar functions for reading from stream, file name and URL.
xml.dom.ext.reader.HtmlLib.FromHtml(str, ownerDocument)
ParametersReturn Value
str
of type HTML string
The HTML source
ownerDocument
of type xml.dom.Document
An optional document to hold the generated nodes. If None, a new document node will be created as the root node. Default is None.
- xml.dom.html.HTMLDocument
The DOM tree resulting from the given text
There are also similar functions for reading from stream, file name and URL.
The Printer module allows you to write a text representation of DOM nodes to an output stream, including stdout. Note that limitations in the SAX interface used to parse in XML files, and in the DOM spec itself make it impossible at this point to handle an unchanged "round trip". That is, if you use the builder to build a DOM node from text and then use the Printer to turn it back to text, there may be differences; some may be significant.
The easiest way to use the Printer module is through the front-end functions in the Ft.Dom.Ext package.
xml.dom.ext.Print(root, stream, encoding)
Render the DOM tree to text with no special formatting.
ParametersReturn Value
root
of type xml.dom.Node.Node
The node to be printed, with all its children recursively.
stream
of type output stream
An optional document to hold the generated nodes. The output stream. Note: can be a StringIO object if you want to generate a string instead. Default is sys.stdout.
encoding
of type string
The character encoding to use for output. Default is 'UTF-8'.
None
xml.dom.ext.PrettyPrint(root, stream, encoding, indent, width, preserveElements)
Render the DOM tree to text, with added indentation and new-lines for enhanced readability.
ParametersReturn Value
root
of type xml.dom.Node.Node
The node to be pretty-printed, with all its children recursively.
stream
of type output stream
An optional document to hold the generated nodes. The output stream. Note: can be a StringIO object if you want to generate a string instead. Default is sys.stdout.
encoding
of type string
The character encoding to use for output. Default is 'UTF-8'.
indent
of type string
The amount by which nested constructs are indented when printed on a fresh line. Default is '\t'.
width
of type positive integer
The width of the output console. Used to make line-break decisions. Default is 80.
preserveElements
of type list of strings, each of which is an SGML generic identifier.
Specifes elements in which white-space shouldn't be added. Note that white-space is never added to in-line elements in an HTMLDocument. Default is None.
None
xml.dom.ext.NodeTypeToInterface(nodeType)
Look up a node type (as returned from getNodeType()) and returns a corresponding interface name.
ParametersReturn Value
nodeType
of type One of the integers defined as node types in xml.dom.Node.Node
The node type to look up.
- string
Name of corresponding DOM interface from spec.
xml.dom.ext.ReleaseNode(node)
Reclaims a Node from the DOM tree by cutting all links from parent to child and thus eliminating circular references.
ParametersReturn Value
node
of type xml.dom.Node.Node
Node to reclaim
None
xml.dom.ext.StripHtml(startNode, preserveElements)
Strips extraneous white-space from an HTML DOM tree.
ParametersReturn Value
startNode
of type xml.dom.Node.Node
The node to be stripped, with all its children recursively.
preserveElements
of type list of strings, each of which is an SGML generic identifier, or None to indicate an empty list.
Specifes elements from which white-space shouldn't be stripped. Note that white-space is never stripped from in-line elements in an HTMLDocument. Default is None.
- xml.dom.Node
The startNode with descendant ignorable white-space stripped.
xml.dom.ext.StripXml(startNode, preserveElements)
Strips extraneous white-space from an XML DOM tree. Takes xml:space attributes into account.
ParametersReturn Value
startNode
of type xml.dom.Node.Node
The node to be stripped, with all its children recursively.
preserveElements
of type list of strings, each of which is an SGML generic identifier, or None to indicate an empty list.
Specifes elements from which white-space shouldn't be stripped. Default is None.
- xml.dom.Node
The startNode with descendant ignorable white-space stripped.
xml.dom.ext.GetElementById(startNode, targetId)
Returns the element node whose "ID" attribute is as given.
ParametersReturn Value
startNode
of type xml.dom.Node.Node
The node whose descendants are to be searched.
targetId
of type string conforming to XML ID type
The XML ID to find.
- xml.dom.Element
The elemtn with the given ID, or None to indicate no match.
xml.dom.ext.GetAllNs(node)
Returns all the namespaces in effect on the given node, including the default namespace and the xml namespace.
ParametersReturn Value
node
of type xml.dom.Node.Node
The node for which all in-scope namespaces are returned.
- doctionary
Dictionary mapping all in-scope namespaces to URIs, with '' as prefix for the default namespace.
xml.dom.ext.XmlSpaceState(node)
Determines whether the xml:space state at a given node is "preserve" or "default" (See the XML 1.0 spec).
ParametersReturn Value
node
of type xml.dom.Node.Node
The node whose space state is to be found.
- string
"preserve" or "default".
xml.dom.ext.SplitQName(qname)
Splits a valid QName from the XML Namespaces 1.0 spec into prefix and suffix (the local name in the case of element and attribute names, and the declared prefix in the case of namespace declarations.
ParametersReturn Value
qname
of type string matching QName production in XML Namespaces 1.0 spec
The name to be split.
- tuple with 2 items.
a tuple of the form (prefix, suffix). If there is exactly one colon in the qname, prefix is the part before and suffix the part after the colon. Otherwise prefix is '' and suffix is the entire input string.