- SF patch #1657613: add documentation for the Element interface
- clean up bogus use of the {datadescni} environment everywhere
This commit is contained in:
Fred Drake
parent
714b112ae5
commit
5a3e812444
|
|
@ -38,10 +38,7 @@ 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}
|
||||
Returns an element instance representing a comment.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{dump}{elem}
|
||||
|
|
@ -65,28 +62,19 @@ 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}
|
||||
Returns an element instance.
|
||||
\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}
|
||||
Returns an Element instance.
|
||||
\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}
|
||||
Returns a true value if this is an element object.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{iterparse}{source\optional{, events}}
|
||||
|
|
@ -95,10 +83,7 @@ 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}
|
||||
Returns an iterator providing \code{(\var{event}, \var{elem})} pairs.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{parse}{source\optional{, parser}}
|
||||
|
|
@ -106,10 +91,7 @@ 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}
|
||||
Returns an ElementTree instance.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{ProcessingInstruction}{target\optional{, text}}
|
||||
|
|
@ -117,13 +99,11 @@ 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}
|
||||
Returns an element instance, representing a processing instruction.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{SubElement}{parent, tag\optional{, attrib} \optional{, **extra}}
|
||||
\begin{funcdesc}{SubElement}{parent, tag\optional{,
|
||||
attrib\optional{, **extra}}}
|
||||
Subelement factory. This function creates an element instance, and
|
||||
appends it to an existing element.
|
||||
|
||||
|
|
@ -133,10 +113,7 @@ either 8-bit ASCII strings or Unicode strings.
|
|||
\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}
|
||||
Returns an element instance.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{tostring}{element\optional{, encoding}}
|
||||
|
|
@ -144,33 +121,162 @@ 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}
|
||||
Returns an encoded string containing the XML data.
|
||||
\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}
|
||||
Returns an Element instance.
|
||||
\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}
|
||||
Returns a tuple containing an Element instance and a dictionary.
|
||||
\end{funcdesc}
|
||||
|
||||
|
||||
\subsection{The Element Interface\label{elementtree-element-interface}}
|
||||
|
||||
Element objects returned by Element or SubElement have the
|
||||
following methods and attributes.
|
||||
|
||||
\begin{memberdesc}{tag}
|
||||
A string identifying what kind of data this element represents
|
||||
(the element type, in other words).
|
||||
\end{memberdesc}
|
||||
|
||||
\begin{memberdesc}{text}
|
||||
The \var{text} attribute can be used to hold additional data
|
||||
associated with the element.
|
||||
As the name implies this attribute is usually a string but may be any
|
||||
application-specific object.
|
||||
If the element is created from an XML file the attribute will contain
|
||||
any text found between the element tags.
|
||||
\end{memberdesc}
|
||||
|
||||
\begin{memberdesc}{tail}
|
||||
The \var{tail} attribute can be used to hold additional data
|
||||
associated with the element.
|
||||
This attribute is usually a string but may be any application-specific object.
|
||||
If the element is created from an XML file the attribute will contain
|
||||
any text found after the element's end tag and before the next tag.
|
||||
\end{memberdesc}
|
||||
|
||||
\begin{memberdesc}{attrib}
|
||||
A dictionary containing the element's attributes.
|
||||
Note that while the \var{attrib} value is always a real mutable Python
|
||||
dictionary, an ElementTree implementation may choose to use another
|
||||
internal representation, and create the dictionary only if someone
|
||||
asks for it. To take advantage of such implementations, use the
|
||||
dictionary methods below whenever possible.
|
||||
\end{memberdesc}
|
||||
|
||||
The following dictionary-like methods work on the element attributes.
|
||||
|
||||
\begin{methoddesc}{clear}{}
|
||||
Resets an element. This function removes all subelements, clears
|
||||
all attributes, and sets the text and tail attributes to None.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{get}{key\optional{, default=None}}
|
||||
Gets the element attribute named \var{key}.
|
||||
|
||||
Returns the attribute value, or \var{default} if the
|
||||
attribute was not found.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{items}{}
|
||||
Returns the element attributes as a sequence of (name, value) pairs.
|
||||
The attributes are returned in an arbitrary order.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{keys}{}
|
||||
Returns the elements attribute names as a list.
|
||||
The names are returned in an arbitrary order.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{set}{key, value}
|
||||
Set the attribute \var{key} on the element to \var{value}.
|
||||
\end{methoddesc}
|
||||
|
||||
The following methods work on the element's children (subelements).
|
||||
|
||||
\begin{methoddesc}{append}{subelement}
|
||||
Adds the element \var{subelement} to the end of this elements internal list
|
||||
of subelements.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{find}{match}
|
||||
Finds the first subelement matching \var{match}.
|
||||
\var{match} may be a tag name or path.
|
||||
Returns an element instance or \code{None}.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{findall}{match}
|
||||
Finds all subelements matching \var{match}.
|
||||
\var{match} may be a tag name or path.
|
||||
Returns an iterable yielding all matching elements in document order.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{findtext}{condition\optional{, default=None}}
|
||||
Finds text for the first subelement matching \var{condition}.
|
||||
\var{condition} may be a tag name or path.
|
||||
Returns the text content of the first matching element, or
|
||||
\var{default} if no element was found. Note that if the
|
||||
matching element has no text content an empty string is returned.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{getchildren}{}
|
||||
Returns all subelements. The elements are returned in document order.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{getiterator}{\optional{tag=None}}
|
||||
Creates a tree iterator with the current element as the root.
|
||||
The iterator iterates over this element and all elements below it
|
||||
that match the given tag. If tag
|
||||
is \code{None} or \code{'*'} then all elements are iterated over.
|
||||
Returns an iterable that provides element objects in document (depth first)
|
||||
order.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{insert}{index, element}
|
||||
Inserts a subelement at the given position in this element.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{makeelement}{tag, attrib}
|
||||
Creates a new element object of the same type as this element.
|
||||
Do not call this method, use the SubElement factory function instead.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{remove}{subelement}
|
||||
Removes \var{subelement} from the element.
|
||||
Unlike the findXXX methods this method compares elements based on
|
||||
the instance identity, not on tag value or contents.
|
||||
\end{methoddesc}
|
||||
|
||||
Element objects also support the following sequence type methods for
|
||||
working with subelements: \method{__delitem__()},
|
||||
\method{__getitem__()}, \method{__setitem__()}, \method{__len__()}.
|
||||
|
||||
Caution: Because Element objects do not define a
|
||||
\method{__nonzero__()} method, elements with no subelements will test
|
||||
as \code{False}.
|
||||
|
||||
\begin{verbatim}
|
||||
element = root.find('foo')
|
||||
|
||||
if not element: # careful!
|
||||
print "element not found, or element has no subelements"
|
||||
|
||||
if element is None:
|
||||
print "element not found"
|
||||
\end{verbatim}
|
||||
|
||||
|
||||
\subsection{ElementTree Objects\label{elementtree-elementtree-objects}}
|
||||
|
||||
\begin{classdesc}{ElementTree}{\optional{element,} \optional{file}}
|
||||
|
|
@ -193,21 +299,15 @@ element. Use with care.
|
|||
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}
|
||||
Returns the first matching element, or \code{None} if no element was found.
|
||||
\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}
|
||||
Returns a list or iterator containing all matching elements,
|
||||
in document order.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{findtext}{path\optional{, default}}
|
||||
|
|
@ -215,31 +315,20 @@ 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
|
||||
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
|
||||
Creates and returns 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}
|
||||
Returns the root element for this tree.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{parse}{source\optional{, parser}}
|
||||
|
|
@ -247,10 +336,7 @@ 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}
|
||||
Returns the section root element.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{write}{file\optional{, encoding}}
|
||||
|
|
@ -270,10 +356,7 @@ 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}
|
||||
\class{QName} instances are opaque.
|
||||
\end{classdesc}
|
||||
|
||||
|
||||
|
|
@ -291,10 +374,7 @@ given.
|
|||
\begin{methoddesc}{close}{}
|
||||
Flushes the parser buffers, and returns the toplevel documen
|
||||
element.
|
||||
|
||||
\begin{datadescni}{Returns:}
|
||||
An Element instance.
|
||||
\end{datadescni}
|
||||
Returns an Element instance.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{data}{data}
|
||||
|
|
@ -306,20 +386,14 @@ containing ASCII text, or a Unicode string.
|
|||
\begin{methoddesc}{end}{tag}
|
||||
Closes the current element.
|
||||
\var{tag} is the element name.
|
||||
|
||||
\begin{datadescni}{Returns:}
|
||||
The closed element.
|
||||
\end{datadescni}
|
||||
Returns the closed element.
|
||||
\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}
|
||||
Returns the opened element.
|
||||
\end{methoddesc}
|
||||
|
||||
|
||||
|
|
@ -336,10 +410,7 @@ instance of the standard TreeBuilder class.
|
|||
|
||||
\begin{methoddesc}{close}{}
|
||||
Finishes feeding data to the parser.
|
||||
|
||||
\begin{datadescni}{Returns:}
|
||||
An element structure.
|
||||
\end{datadescni}
|
||||
Returns an element structure.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{doctype}{name, pubid, system}
|
||||
|
|
@ -351,6 +422,5 @@ Handles a doctype declaration.
|
|||
|
||||
\begin{methoddesc}{feed}{data}
|
||||
Feeds data to the parser.
|
||||
|
||||
\var{data} is encoded data.
|
||||
\end{methoddesc}
|
||||
|
|
|
|||
Loading…
Reference in New Issue