8.13.1 Functions

Comment( [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. text is a string containing the comment string.

Returns:: An element instance, representing a comment.

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.

elem is an element tree or an individual element.

Element( tag[, attrib][, **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. tag is the element name. attrib is an optional dictionary, containing element attributes. extra contains additional attributes, given as keyword arguments.

Returns:: An element instance.

fromstring( text)

Parses an XML section from a string constant. Same as XML. text is a string containing XML data.

Returns:: An Element instance.

iselement( element)

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

Returns:: A true value if this is an element object.

iterparse( source[, events])

Parses an XML section into an element tree incrementally, and reports what's going on to the user. source is a filename or file object containing XML data. events is a list of events to report back. If omitted, only ``end'' events are reported.

Returns:: A (event, elem) iterator.

parse( source[, parser])

Parses an XML section into an element tree. source is a filename or file object containing XML data. parser is an optional parser instance. If not given, the standard XMLTreeBuilder parser is used.

Returns:: An ElementTree instance

ProcessingInstruction( target[, text])

PI element factory. This factory function creates a special element that will be serialized as an XML processing instruction. target is a string containing the PI target. text is a string containing the PI contents, if given.

Returns:: An element instance, representing a PI.

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. parent is the parent element. tag is the subelement name. attrib is an optional dictionary, containing element attributes. extra contains additional attributes, given as keyword arguments.

Returns:: An element instance.

tostring( element[, encoding])

Generates a string representation of an XML element, including all subelements. element is an Element instance. encoding is the output encoding (default is US-ASCII).

Returns:: An encoded string containing the XML data.

XML( text)

Parses an XML section from a string constant. This function can be used to embed ``XML literals'' in Python code. text is a string containing XML data.

Returns:: An Element instance.

XMLID( text)

Parses an XML section from a string constant, and also returns a dictionary which maps from element id:s to elements. text is a string containing XML data.

Returns:: A tuple containing an Element instance and a dictionary.

See About this document... for information on suggesting changes.