Back to index

python3.2  3.2.2
Classes | Functions | Variables
xml.etree.ElementTree Namespace Reference

Classes

class  _SimpleElementPath
class  ParseError
 Parser error. More...
class  Element
 Element class. More...
class  QName
 QName wrapper. More...
class  ElementTree
 ElementTree wrapper class. More...
class  _IterParseIterator
class  TreeBuilder
 Generic element structure builder. More...
class  XMLParser
 Element structure builder for XML source data, based on the expat parser. More...

Functions

def iselement
 Checks if an object appears to be a valid element object.
def SubElement
 Subelement factory.
def Comment
 Comment element factory.
def ProcessingInstruction
 PI element factory.
def _namespaces
def _serialize_xml
def _serialize_html
def _serialize_text
def register_namespace
 Registers a namespace prefix.
def _raise_serialization_error
def _escape_cdata
def _escape_attrib
def _escape_attrib_html
def tostring
 Generates a string representation of an XML element, including all subelements.
def tostringlist
 Generates a string representation of an XML element, including all subelements.
def dump
 Writes an element tree or element structure to sys.stdout.
def parse
 Parses an XML document into an element tree.
def iterparse
 Parses an XML document into an element tree incrementally, and reports what's going on to the user.
def XML
 Parses an XML document from a string constant.
def XMLID
 Parses an XML document from a string constant, and also returns a dictionary which maps from element id:s to elements.
def fromstringlist
 Parses an XML document from a sequence of string fragments.

Variables

list __all__
string VERSION = "1.3.0"
tuple ElementPath = _SimpleElementPath()
 _Element = _ElementInterfaceElement
 PI = ProcessingInstruction
tuple HTML_EMPTY
dictionary _serialize
dictionary _namespace_map
 fromstring = XML
 XMLTreeBuilder = XMLParser

Class Documentation

class xml::etree::ElementTree::ParseError

Parser error.

This is a subclass of SyntaxError.

In addition to the exception value, an exception instance contains a specific exception code in the code attribute, and the line and column of the error in the position attribute.

Definition at line 138 of file ElementTree.py.


Function Documentation

def xml.etree.ElementTree._escape_attrib (   text) [private]

Definition at line 1110 of file ElementTree.py.

01110 
01111 def _escape_attrib(text):
01112     # escape attribute value
01113     try:
01114         if "&" in text:
01115             text = text.replace("&", "&")
01116         if "<" in text:
01117             text = text.replace("<", "&lt;")
01118         if ">" in text:
01119             text = text.replace(">", "&gt;")
01120         if "\"" in text:
01121             text = text.replace("\"", "&quot;")
01122         if "\n" in text:
01123             text = text.replace("\n", "&#10;")
01124         return text
01125     except (TypeError, AttributeError):
01126         _raise_serialization_error(text)

Here is the call graph for this function:

Here is the caller graph for this function:

Definition at line 1127 of file ElementTree.py.

01127 
01128 def _escape_attrib_html(text):
01129     # escape attribute value
01130     try:
01131         if "&" in text:
01132             text = text.replace("&", "&amp;")
01133         if ">" in text:
01134             text = text.replace(">", "&gt;")
01135         if "\"" in text:
01136             text = text.replace("\"", "&quot;")
01137         return text
01138     except (TypeError, AttributeError):
01139         _raise_serialization_error(text)
01140 
01141 # --------------------------------------------------------------------

Here is the call graph for this function:

Here is the caller graph for this function:

def xml.etree.ElementTree._escape_cdata (   text) [private]

Definition at line 1094 of file ElementTree.py.

01094 
01095 def _escape_cdata(text):
01096     # escape character data
01097     try:
01098         # it's worth avoiding do-nothing calls for strings that are
01099         # shorter than 500 character, or so.  assume that's, by far,
01100         # the most common case in most applications.
01101         if "&" in text:
01102             text = text.replace("&", "&amp;")
01103         if "<" in text:
01104             text = text.replace("<", "&lt;")
01105         if ">" in text:
01106             text = text.replace(">", "&gt;")
01107         return text
01108     except (TypeError, AttributeError):
01109         _raise_serialization_error(text)

Here is the call graph for this function:

Here is the caller graph for this function:

def xml.etree.ElementTree._namespaces (   elem,
  default_namespace = None 
) [private]

Definition at line 873 of file ElementTree.py.

00873 
00874 def _namespaces(elem, default_namespace=None):
00875     # identify namespaces used in this tree
00876 
00877     # maps qnames to *encoded* prefix:local names
00878     qnames = {None: None}
00879 
00880     # maps uri:s to prefixes
00881     namespaces = {}
00882     if default_namespace:
00883         namespaces[default_namespace] = ""
00884 
00885     def add_qname(qname):
00886         # calculate serialized qname representation
00887         try:
00888             if qname[:1] == "{":
00889                 uri, tag = qname[1:].rsplit("}", 1)
00890                 prefix = namespaces.get(uri)
00891                 if prefix is None:
00892                     prefix = _namespace_map.get(uri)
00893                     if prefix is None:
00894                         prefix = "ns%d" % len(namespaces)
00895                     if prefix != "xml":
00896                         namespaces[uri] = prefix
00897                 if prefix:
00898                     qnames[qname] = "%s:%s" % (prefix, tag)
00899                 else:
00900                     qnames[qname] = tag # default element
00901             else:
00902                 if default_namespace:
00903                     # FIXME: can this be handled in XML 1.0?
00904                     raise ValueError(
00905                         "cannot use non-qualified names with "
00906                         "default_namespace option"
00907                         )
00908                 qnames[qname] = qname
00909         except TypeError:
00910             _raise_serialization_error(qname)
00911 
00912     # populate qname and namespaces table
00913     try:
00914         iterate = elem.iter
00915     except AttributeError:
00916         iterate = elem.getiterator # cET compatibility
00917     for elem in iterate():
00918         tag = elem.tag
00919         if isinstance(tag, QName):
00920             if tag.text not in qnames:
00921                 add_qname(tag.text)
00922         elif isinstance(tag, str):
00923             if tag not in qnames:
00924                 add_qname(tag)
00925         elif tag is not None and tag is not Comment and tag is not PI:
00926             _raise_serialization_error(tag)
00927         for key, value in elem.items():
00928             if isinstance(key, QName):
00929                 key = key.text
00930             if key not in qnames:
00931                 add_qname(key)
00932             if isinstance(value, QName) and value.text not in qnames:
00933                 add_qname(value.text)
00934         text = elem.text
00935         if isinstance(text, QName) and text.text not in qnames:
00936             add_qname(text.text)
00937     return qnames, namespaces

Here is the call graph for this function:

Here is the caller graph for this function:

Definition at line 1089 of file ElementTree.py.

01089 
01090 def _raise_serialization_error(text):
01091     raise TypeError(
01092         "cannot serialize %r (type %s)" % (text, type(text).__name__)
01093         )

Here is the caller graph for this function:

def xml.etree.ElementTree._serialize_html (   write,
  elem,
  qnames,
  namespaces 
) [private]

Definition at line 993 of file ElementTree.py.

00993 
00994 def _serialize_html(write, elem, qnames, namespaces):
00995     tag = elem.tag
00996     text = elem.text
00997     if tag is Comment:
00998         write("<!--%s-->" % _escape_cdata(text))
00999     elif tag is ProcessingInstruction:
01000         write("<?%s?>" % _escape_cdata(text))
01001     else:
01002         tag = qnames[tag]
01003         if tag is None:
01004             if text:
01005                 write(_escape_cdata(text))
01006             for e in elem:
01007                 _serialize_html(write, e, qnames, None)
01008         else:
01009             write("<" + tag)
01010             items = list(elem.items())
01011             if items or namespaces:
01012                 if namespaces:
01013                     for v, k in sorted(namespaces.items(),
01014                                        key=lambda x: x[1]):  # sort on prefix
01015                         if k:
01016                             k = ":" + k
01017                         write(" xmlns%s=\"%s\"" % (
01018                             k,
01019                             _escape_attrib(v)
01020                             ))
01021                 for k, v in sorted(items):  # lexical order
01022                     if isinstance(k, QName):
01023                         k = k.text
01024                     if isinstance(v, QName):
01025                         v = qnames[v.text]
01026                     else:
01027                         v = _escape_attrib_html(v)
01028                     # FIXME: handle boolean attributes
01029                     write(" %s=\"%s\"" % (qnames[k], v))
01030             write(">")
01031             tag = tag.lower()
01032             if text:
01033                 if tag == "script" or tag == "style":
01034                     write(text)
01035                 else:
01036                     write(_escape_cdata(text))
01037             for e in elem:
01038                 _serialize_html(write, e, qnames, None)
01039             if tag not in HTML_EMPTY:
01040                 write("</" + tag + ">")
01041     if elem.tail:
01042         write(_escape_cdata(elem.tail))

Here is the call graph for this function:

def xml.etree.ElementTree._serialize_text (   write,
  elem 
) [private]

Definition at line 1043 of file ElementTree.py.

01043 
01044 def _serialize_text(write, elem):
01045     for part in elem.itertext():
01046         write(part)
01047     if elem.tail:
01048         write(elem.tail)

Here is the call graph for this function:

Here is the caller graph for this function:

def xml.etree.ElementTree._serialize_xml (   write,
  elem,
  qnames,
  namespaces 
) [private]

Definition at line 938 of file ElementTree.py.

00938 
00939 def _serialize_xml(write, elem, qnames, namespaces):
00940     tag = elem.tag
00941     text = elem.text
00942     if tag is Comment:
00943         write("<!--%s-->" % text)
00944     elif tag is ProcessingInstruction:
00945         write("<?%s?>" % text)
00946     else:
00947         tag = qnames[tag]
00948         if tag is None:
00949             if text:
00950                 write(_escape_cdata(text))
00951             for e in elem:
00952                 _serialize_xml(write, e, qnames, None)
00953         else:
00954             write("<" + tag)
00955             items = list(elem.items())
00956             if items or namespaces:
00957                 if namespaces:
00958                     for v, k in sorted(namespaces.items(),
00959                                        key=lambda x: x[1]):  # sort on prefix
00960                         if k:
00961                             k = ":" + k
00962                         write(" xmlns%s=\"%s\"" % (
00963                             k,
00964                             _escape_attrib(v)
00965                             ))
00966                 for k, v in sorted(items):  # lexical order
00967                     if isinstance(k, QName):
00968                         k = k.text
00969                     if isinstance(v, QName):
00970                         v = qnames[v.text]
00971                     else:
00972                         v = _escape_attrib(v)
00973                     write(" %s=\"%s\"" % (qnames[k], v))
00974             if text or len(elem):
00975                 write(">")
00976                 if text:
00977                     write(_escape_cdata(text))
00978                 for e in elem:
00979                     _serialize_xml(write, e, qnames, None)
00980                 write("</" + tag + ">")
00981             else:
00982                 write(" />")
00983     if elem.tail:
00984         write(_escape_cdata(elem.tail))

Here is the call graph for this function:

def xml.etree.ElementTree.Comment (   text = None)

Comment element factory.

This factory function creates a special element that will be serialized as an XML comment by the standard serializer.

The comment string can be either an 8-bit ASCII string or a Unicode string.

Parameters:
textA string containing the comment string.
Returns:
An element instance, representing a comment. Element

Definition at line 546 of file ElementTree.py.

00546 
00547 def Comment(text=None):
00548     element = Element(Comment)
00549     element.text = text
00550     return element

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.

Parameters:
elemAn element tree or an individual element.

Definition at line 1201 of file ElementTree.py.

01201 
01202 def dump(elem):
01203     # debugging
01204     if not isinstance(elem, ElementTree):
01205         elem = ElementTree(elem)
01206     elem.write(sys.stdout, encoding="unicode")
01207     tail = elem.getroot().tail
01208     if not tail or tail[-1] != "\n":
01209         sys.stdout.write("\n")
01210 
01211 # --------------------------------------------------------------------
01212 # parsing

def xml.etree.ElementTree.fromstringlist (   sequence,
  parser = None 
)

Parses an XML document from a sequence of string fragments.

Parameters:
sequenceA list or other sequence containing XML data fragments.
parserAn optional parser instance. If not given, the standard XMLParser parser is used.
Returns:
An Element instance. Element
Since:
1.3

Definition at line 1374 of file ElementTree.py.

01374 
01375 def fromstringlist(sequence, parser=None):
01376     if not parser:
01377         parser = XMLParser(target=TreeBuilder())
01378     for text in sequence:
01379         parser.feed(text)
01380     return parser.close()
01381 
01382 # --------------------------------------------------------------------

Checks if an object appears to be a valid element object.

Parameters:
Anelement instance.
Returns:
A true value if this is an element object. flag

Definition at line 150 of file ElementTree.py.

00150 
00151 def iselement(element):
00152     # FIXME: not sure about this; might be a better idea to look
00153     # for tag/attrib/text attributes
00154     return isinstance(element, Element) or hasattr(element, "tag")

def xml.etree.ElementTree.iterparse (   source,
  events = None,
  parser = None 
)

Parses an XML document into an element tree incrementally, and reports what's going on to the user.

Parameters:
sourceA filename or file object containing XML data.
eventsA list of events to report back. If omitted, only "end" events are reported.
parserAn optional parser instance. If not given, the standard XMLParser parser is used.
Returns:
A (event, elem) iterator.

Definition at line 1237 of file ElementTree.py.

01237 
01238 def iterparse(source, events=None, parser=None):
01239     close_source = False
01240     if not hasattr(source, "read"):
01241         source = open(source, "rb")
01242         close_source = True
01243     if not parser:
01244         parser = XMLParser(target=TreeBuilder())
01245     return _IterParseIterator(source, events, parser, close_source)

def xml.etree.ElementTree.parse (   source,
  parser = None 
)

Parses an XML document into an element tree.

Parameters:
sourceA filename or file object containing XML data.
parserAn optional parser instance. If not given, the standard XMLParser parser is used.
Returns:
An ElementTree instance

Definition at line 1221 of file ElementTree.py.

01221 
01222 def parse(source, parser=None):
01223     tree = ElementTree()
01224     tree.parse(source, parser)
01225     return tree

def xml.etree.ElementTree.ProcessingInstruction (   target,
  text = None 
)

PI element factory.

This factory function creates a special element that will be serialized as an XML processing instruction by the standard serializer.

Parameters:
targetA string containing the PI target.
textA string containing the PI contents, if any.
Returns:
An element instance, representing a PI. Element

Definition at line 561 of file ElementTree.py.

00561 
00562 def ProcessingInstruction(target, text=None):
00563     element = Element(ProcessingInstruction)
00564     element.text = target
00565     if text:
00566         element.text = element.text + " " + text
00567     return element

def xml.etree.ElementTree.register_namespace (   prefix,
  uri 
)

Registers a namespace prefix.

The registry is global, and any existing mapping for either the given prefix or the namespace URI will be removed.

Parameters:
prefixNamespace prefix.
uriNamespace uri. Tags and attributes in this namespace will be serialized with the given prefix, if at all possible.
Exceptions:
ValueErrorIf the prefix is reserved, or is otherwise invalid.

Definition at line 1068 of file ElementTree.py.

01068 
01069 def register_namespace(prefix, uri):
01070     if re.match("ns\d+$", prefix):
01071         raise ValueError("Prefix format reserved for internal use")
01072     for k, v in list(_namespace_map.items()):
01073         if k == uri or v == prefix:
01074             del _namespace_map[k]
01075     _namespace_map[uri] = prefix

Here is the call graph for this function:

def xml.etree.ElementTree.SubElement (   parent,
  tag,
  attrib = {},
  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.

Parameters:
parentThe parent element.
tagThe subelement name.
attribAn optional dictionary, containing element attributes.
**extraAdditional attributes, given as keyword arguments.
Returns:
An element instance. Element

Definition at line 527 of file ElementTree.py.

00527 
00528 def SubElement(parent, tag, attrib={}, **extra):
00529     attrib = attrib.copy()
00530     attrib.update(extra)
00531     element = parent.makeelement(tag, attrib)
00532     parent.append(element)
00533     return element

def xml.etree.ElementTree.tostring (   element,
  encoding = None,
  method = None 
)

Generates a string representation of an XML element, including all subelements.

If encoding is "unicode", the return type is a string; otherwise it is a bytes array.

Parameters:
elementAn Element instance. encoding Optional output encoding (default is US-ASCII). Use "unicode" to return a Unicode string. method Optional output method ("xml", "html", "text" or "c14n"; default is "xml").
Returns:
An (optionally) encoded string containing the XML data. string

Definition at line 1155 of file ElementTree.py.

01155 
01156 def tostring(element, encoding=None, method=None):
01157     class dummy:
01158         pass
01159     data = []
01160     file = dummy()
01161     file.write = data.append
01162     ElementTree(element).write(file, encoding, method=method)
01163     if encoding in (str, "unicode"):
01164         return "".join(data)
01165     else:
01166         return b"".join(data)

Here is the caller graph for this function:

def xml.etree.ElementTree.tostringlist (   element,
  encoding = None,
  method = None 
)

Generates a string representation of an XML element, including all subelements.

If encoding is False, the string is returned as a sequence of string fragments; otherwise it is a sequence of bytestrings.

Parameters:
elementAn Element instance. encoding Optional output encoding (default is US-ASCII). Use "unicode" to return a Unicode string. method Optional output method ("xml", "html", "text" or "c14n"; default is "xml").
Returns:
A sequence object containing the XML data. sequence
Since:
1.3

Definition at line 1182 of file ElementTree.py.

01182 
01183 def tostringlist(element, encoding=None, method=None):
01184     class dummy:
01185         pass
01186     data = []
01187     file = dummy()
01188     file.write = data.append
01189     ElementTree(element).write(file, encoding, method=method)
01190     # FIXME: merge small fragments into larger parts
01191     return data

def xml.etree.ElementTree.XML (   text,
  parser = None 
)

Parses an XML document from a string constant.

This function can be used to embed "XML literals" in Python code.

Parameters:
sourceA string containing XML data.
parserAn optional parser instance. If not given, the standard XMLParser parser is used.
Returns:
An Element instance. Element

Definition at line 1326 of file ElementTree.py.

01326 
01327 def XML(text, parser=None):
01328     if not parser:
01329         parser = XMLParser(target=TreeBuilder())
01330     parser.feed(text)
01331     return parser.close()

Here is the caller graph for this function:

def xml.etree.ElementTree.XMLID (   text,
  parser = None 
)

Parses an XML document from a string constant, and also returns a dictionary which maps from element id:s to elements.

Parameters:
sourceA string containing XML data.
parserAn optional parser instance. If not given, the standard XMLParser parser is used.
Returns:
A tuple containing an Element instance and a dictionary. (Element, dictionary)

Definition at line 1342 of file ElementTree.py.

01342 
01343 def XMLID(text, parser=None):
01344     if not parser:
01345         parser = XMLParser(target=TreeBuilder())
01346     parser.feed(text)
01347     tree = parser.close()
01348     ids = {}
01349     for elem in tree.iter():
01350         id = elem.get("id")
01351         if id:
01352             ids[id] = elem
01353     return tree, ids


Variable Documentation

Initial value:
00001 [
00002     # public symbols
00003     "Comment",
00004     "dump",
00005     "Element", "ElementTree",
00006     "fromstring", "fromstringlist",
00007     "iselement", "iterparse",
00008     "parse", "ParseError",
00009     "PI", "ProcessingInstruction",
00010     "QName",
00011     "SubElement",
00012     "tostring", "tostringlist",
00013     "TreeBuilder",
00014     "VERSION",
00015     "XML",
00016     "XMLParser", "XMLTreeBuilder",
00017     ]

Definition at line 57 of file ElementTree.py.

xml.etree.ElementTree._Element = _ElementInterfaceElement

Definition at line 511 of file ElementTree.py.

Initial value:
00001 {
00002     # "well-known" namespace prefixes
00003     "http://www.w3.org/XML/1998/namespace": "xml",
00004     "http://www.w3.org/1999/xhtml": "html",
00005     "http://www.w3.org/1999/02/22-rdf-syntax-ns#": "rdf",
00006     "http://schemas.xmlsoap.org/wsdl/": "wsdl",
00007     # xml schema
00008     "http://www.w3.org/2001/XMLSchema": "xs",
00009     "http://www.w3.org/2001/XMLSchema-instance": "xsi",
00010     # dublin core
00011     "http://purl.org/dc/elements/1.1/": "dc",
00012 }

Definition at line 1076 of file ElementTree.py.

Initial value:
00001 {
00002     "xml": _serialize_xml,
00003     "html": _serialize_html,
00004     "text": _serialize_text,
00005 # this optional method is imported at the end of the module
00006 #   "c14n": _serialize_c14n,
00007 }

Definition at line 1049 of file ElementTree.py.

Definition at line 129 of file ElementTree.py.

Definition at line 1362 of file ElementTree.py.

Initial value:
00001 ("area", "base", "basefont", "br", "col", "frame", "hr",
00002               "img", "input", "isindex", "link", "meta" "param")

Definition at line 985 of file ElementTree.py.

Definition at line 568 of file ElementTree.py.

Definition at line 75 of file ElementTree.py.

Definition at line 1680 of file ElementTree.py.