357 lines
11 KiB
TeX
357 lines
11 KiB
TeX
\section{\module{xml.etree.ElementTree} --- The ElementTree XML API}
|
|
\declaremodule{standard}{xml.etree.ElementTree}
|
|
\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
|
|
\modulesynopsis{Implementation of the ElementTree API.}
|
|
|
|
\versionadded{2.5}
|
|
|
|
The Element type is a flexible container object, designed to store
|
|
hierarchical data structures in memory. The type can be described as a
|
|
cross between a list and a dictionary.
|
|
|
|
Each element has a number of properties associated with it:
|
|
|
|
\begin{itemize}
|
|
\item a tag which is a string identifying what kind of data
|
|
this element represents (the element type, in other words).
|
|
\item a number of attributes, stored in a Python dictionary.
|
|
\item a text string.
|
|
\item an optional tail string.
|
|
\item a number of child elements, stored in a Python sequence
|
|
\end{itemize}
|
|
|
|
To create an element instance, use the Element or SubElement factory
|
|
functions.
|
|
|
|
The \class{ElementTree} class can be used to wrap an element
|
|
structure, and convert it from and to XML.
|
|
|
|
A C implementation of this API is available as
|
|
\module{xml.etree.cElementTree}.
|
|
|
|
|
|
\subsection{Functions\label{elementtree-functions}}
|
|
|
|
\begin{funcdesc}{Comment}{\optional{text}}
|
|
Comment element factory. This factory function creates a special
|
|
element that will be serialized as an XML comment.
|
|
The comment string can be either an 8-bit ASCII string or a Unicode
|
|
string.
|
|
\var{text} is a string containing the comment string.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An element instance, representing a comment.
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{dump}{elem}
|
|
Writes an element tree or element structure to sys.stdout. This
|
|
function should be used for debugging only.
|
|
|
|
The exact output format is implementation dependent. In this
|
|
version, it's written as an ordinary XML file.
|
|
|
|
\var{elem} is an element tree or an individual element.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{Element}{tag\optional{, attrib}\optional{, **extra}}
|
|
Element factory. This function returns an object implementing the
|
|
standard Element interface. The exact class or type of that object
|
|
is implementation dependent, but it will always be compatible with
|
|
the {\_}ElementInterface class in this module.
|
|
|
|
The element name, attribute names, and attribute values can be
|
|
either 8-bit ASCII strings or Unicode strings.
|
|
\var{tag} is the element name.
|
|
\var{attrib} is an optional dictionary, containing element attributes.
|
|
\var{extra} contains additional attributes, given as keyword arguments.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An element instance.
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fromstring}{text}
|
|
Parses an XML section from a string constant. Same as XML.
|
|
\var{text} is a string containing XML data.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An Element instance.
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{iselement}{element}
|
|
Checks if an object appears to be a valid element object.
|
|
\var{element} is an element instance.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
A true value if this is an element object.
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{iterparse}{source\optional{, events}}
|
|
Parses an XML section into an element tree incrementally, and reports
|
|
what's going on to the user.
|
|
\var{source} is a filename or file object containing XML data.
|
|
\var{events} is a list of events to report back. If omitted, only ``end''
|
|
events are reported.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
A (event, elem) iterator.
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{parse}{source\optional{, parser}}
|
|
Parses an XML section into an element tree.
|
|
\var{source} is a filename or file object containing XML data.
|
|
\var{parser} is an optional parser instance. If not given, the
|
|
standard XMLTreeBuilder parser is used.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An ElementTree instance
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{ProcessingInstruction}{target\optional{, text}}
|
|
PI element factory. This factory function creates a special element
|
|
that will be serialized as an XML processing instruction.
|
|
\var{target} is a string containing the PI target.
|
|
\var{text} is a string containing the PI contents, if given.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An element instance, representing a PI.
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{SubElement}{parent, tag\optional{, attrib} \optional{, **extra}}
|
|
Subelement factory. This function creates an element instance, and
|
|
appends it to an existing element.
|
|
|
|
The element name, attribute names, and attribute values can be
|
|
either 8-bit ASCII strings or Unicode strings.
|
|
\var{parent} is the parent element.
|
|
\var{tag} is the subelement name.
|
|
\var{attrib} is an optional dictionary, containing element attributes.
|
|
\var{extra} contains additional attributes, given as keyword arguments.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An element instance.
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tostring}{element\optional{, encoding}}
|
|
Generates a string representation of an XML element, including all
|
|
subelements.
|
|
\var{element} is an Element instance.
|
|
\var{encoding} is the output encoding (default is US-ASCII).
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An encoded string containing the XML data.
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{XML}{text}
|
|
Parses an XML section from a string constant. This function can
|
|
be used to embed ``XML literals'' in Python code.
|
|
\var{text} is a string containing XML data.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An Element instance.
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{XMLID}{text}
|
|
Parses an XML section from a string constant, and also returns
|
|
a dictionary which maps from element id:s to elements.
|
|
\var{text} is a string containing XML data.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
A tuple containing an Element instance and a dictionary.
|
|
\end{datadescni}
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{ElementTree Objects\label{elementtree-elementtree-objects}}
|
|
|
|
\begin{classdesc}{ElementTree}{\optional{element,} \optional{file}}
|
|
ElementTree wrapper class. This class represents an entire element
|
|
hierarchy, and adds some extra support for serialization to and from
|
|
standard XML.
|
|
|
|
\var{element} is the root element.
|
|
The tree is initialized with the contents of the XML \var{file} if given.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{_setroot}{element}
|
|
Replaces the root element for this tree. This discards the
|
|
current contents of the tree, and replaces it with the given
|
|
element. Use with care.
|
|
\var{element} is an element instance.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{find}{path}
|
|
Finds the first toplevel element with given tag.
|
|
Same as getroot().find(path).
|
|
\var{path} is the element to look for.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
The first matching element, or None if no element was found.
|
|
\end{datadescni}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{findall}{path}
|
|
Finds all toplevel elements with the given tag.
|
|
Same as getroot().findall(path).
|
|
\var{path} is the element to look for.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
A list or iterator containing all matching elements,
|
|
in section order.
|
|
\end{datadescni}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{findtext}{path\optional{, default}}
|
|
Finds the element text for the first toplevel element with given
|
|
tag. Same as getroot().findtext(path).
|
|
\var{path} is the toplevel element to look for.
|
|
\var{default} is the value to return if the element was not found.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
The text content of the first matching element, or the
|
|
default value no element was found. Note that if the element
|
|
has is found, but has no text content, this method returns an
|
|
empty string.
|
|
\end{datadescni}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getiterator}{\optional{tag}}
|
|
Creates a tree iterator for the root element. The iterator loops
|
|
over all elements in this tree, in section order.
|
|
\var{tag} is the tag to look for (default is to return all elements)
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An iterator.
|
|
\end{datadescni}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getroot}{}
|
|
Gets the root element for this tree.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An element instance.
|
|
\end{datadescni}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{parse}{source\optional{, parser}}
|
|
Loads an external XML section into this element tree.
|
|
\var{source} is a file name or file object.
|
|
\var{parser} is an optional parser instance. If not given, the
|
|
standard XMLTreeBuilder parser is used.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
The section root element.
|
|
\end{datadescni}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{write}{file\optional{, encoding}}
|
|
Writes the element tree to a file, as XML.
|
|
\var{file} is a file name, or a file object opened for writing.
|
|
\var{encoding} is the output encoding (default is US-ASCII).
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{QName Objects\label{elementtree-qname-objects}}
|
|
|
|
\begin{classdesc}{QName}{text_or_uri\optional{, tag}}
|
|
QName wrapper. This can be used to wrap a QName attribute value, in
|
|
order to get proper namespace handling on output.
|
|
\var{text_or_uri} is a string containing the QName value,
|
|
in the form {\{}uri{\}}local, or, if the tag argument is given,
|
|
the URI part of a QName.
|
|
If \var{tag} is given, the first argument is interpreted as
|
|
an URI, and this argument is interpreted as a local name.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An opaque object, representing the QName.
|
|
\end{datadescni}
|
|
\end{classdesc}
|
|
|
|
|
|
\subsection{TreeBuilder Objects\label{elementtree-treebuilder-objects}}
|
|
|
|
\begin{classdesc}{TreeBuilder}{\optional{element_factory}}
|
|
Generic element structure builder. This builder converts a sequence
|
|
of start, data, and end method calls to a well-formed element structure.
|
|
You can use this class to build an element structure using a custom XML
|
|
parser, or a parser for some other XML-like format.
|
|
The \var{element_factory} is called to create new Element instances when
|
|
given.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Flushes the parser buffers, and returns the toplevel documen
|
|
element.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An Element instance.
|
|
\end{datadescni}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{data}{data}
|
|
Adds text to the current element.
|
|
\var{data} is a string. This should be either an 8-bit string
|
|
containing ASCII text, or a Unicode string.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{end}{tag}
|
|
Closes the current element.
|
|
\var{tag} is the element name.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
The closed element.
|
|
\end{datadescni}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{start}{tag, attrs}
|
|
Opens a new element.
|
|
\var{tag} is the element name.
|
|
\var{attrs} is a dictionary containing element attributes.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
The opened element.
|
|
\end{datadescni}
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{XMLTreeBuilder Objects\label{elementtree-xmltreebuilder-objects}}
|
|
|
|
\begin{classdesc}{XMLTreeBuilder}{\optional{html,} \optional{target}}
|
|
Element structure builder for XML source data, based on the
|
|
expat parser.
|
|
\var{html} are predefined HTML entities. This flag is not supported
|
|
by the current implementation.
|
|
\var{target} is the target object. If omitted, the builder uses an
|
|
instance of the standard TreeBuilder class.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Finishes feeding data to the parser.
|
|
|
|
\begin{datadescni}{Returns:}
|
|
An element structure.
|
|
\end{datadescni}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{doctype}{name, pubid, system}
|
|
Handles a doctype declaration.
|
|
\var{name} is the doctype name.
|
|
\var{pubid} is the public identifier.
|
|
\var{system} is the system identifier.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{feed}{data}
|
|
Feeds data to the parser.
|
|
|
|
\var{data} is encoded data.
|
|
\end{methoddesc}
|