Back to index

python3.2  3.2.2
Public Member Functions | Static Public Attributes | Private Attributes
xml.etree.ElementTree.Element Class Reference

Element class. More...

List of all members.

Public Member Functions

def __init__
def __repr__
def makeelement
 Creates a new element object of the same type as this element.
def copy
 (Experimental) Copies the current element.
def __len__
 Returns the number of subelements.
def __bool__
def __getitem__
 Returns the given subelement, by index.
def __setitem__
 Replaces the given subelement, by index.
def __delitem__
 Deletes the given subelement, by index.
def append
 Adds a subelement to the end of this element.
def extend
 Appends subelements from a sequence.
def insert
 Inserts a subelement at the given position in this element.
def remove
 Removes a matching subelement.
def getchildren
 (Deprecated) Returns all subelements.
def find
 Finds the first matching subelement, by tag name or path.
def findtext
 Finds text for the first matching subelement, by tag name or path.
def findall
 Finds all matching subelements, by tag name or path.
def iterfind
 Finds all matching subelements, by tag name or path.
def clear
 Resets an element.
def get
 Gets an element attribute.
def set
 Sets an element attribute.
def keys
 Gets a list of attribute names.
def items
 Gets element attributes, as a sequence.
def iter
 Creates a tree iterator.
def getiterator
def itertext
 Creates a text iterator.

Static Public Attributes

 tag = None
 (Attribute) Element tag.
 attrib = None
 (Attribute) Element attribute dictionary.
 text = None
 (Attribute) Text before first subelement.
 tail = None
 (Attribute) Text after this element's end tag, but before the next sibling element's start tag.

Private Attributes

 _children

Detailed Description

Element class.

This class defines the Element interface, and provides a reference implementation of this interface.

The element name, attribute names, and attribute values can be either ASCII strings (ordinary Python strings containing only 7-bit ASCII characters) or Unicode strings.

Parameters:
tagThe element name.
attribAn optional dictionary, containing element attributes.
**extraAdditional attributes, given as keyword arguments.
See also:
Element
SubElement
Comment
ProcessingInstruction

Definition at line 171 of file ElementTree.py.


Constructor & Destructor Documentation

def xml.etree.ElementTree.Element.__init__ (   self,
  tag,
  attrib = {},
  extra 
)

Definition at line 207 of file ElementTree.py.

00207 
00208     def __init__(self, tag, attrib={}, **extra):
00209         attrib = attrib.copy()
00210         attrib.update(extra)
00211         self.tag = tag
00212         self.attrib = attrib
00213         self._children = []

Here is the caller graph for this function:


Member Function Documentation

Definition at line 250 of file ElementTree.py.

00250 
00251     def __bool__(self):
00252         warnings.warn(
00253             "The behavior of this method will change in future versions.  "
00254             "Use specific 'len(elem)' or 'elem is not None' test instead.",
00255             FutureWarning, stacklevel=2
00256             )
00257         return len(self._children) != 0 # emulate old behaviour, for now

Here is the call graph for this function:

def xml.etree.ElementTree.Element.__delitem__ (   self,
  index 
)

Deletes the given subelement, by index.

Parameters:
indexWhat subelement to delete.
Exceptions:
IndexErrorIf the given element does not exist.

Definition at line 289 of file ElementTree.py.

00289 
00290     def __delitem__(self, index):
00291         del self._children[index]

def xml.etree.ElementTree.Element.__getitem__ (   self,
  index 
)

Returns the given subelement, by index.

Parameters:
indexWhat subelement to return.
Returns:
The given subelement.
Exceptions:
IndexErrorIf the given element does not exist.

Definition at line 265 of file ElementTree.py.

00265 
00266     def __getitem__(self, index):
00267         return self._children[index]

Returns the number of subelements.

Note that this only counts full elements; to check if there's any content in an element, you have to check both the length and the text attribute.

Returns:
The number of subelements.

Definition at line 247 of file ElementTree.py.

00247 
00248     def __len__(self):
00249         return len(self._children)

Definition at line 214 of file ElementTree.py.

00214 
00215     def __repr__(self):
00216         return "<Element %s at 0x%x>" % (repr(self.tag), id(self))

def xml.etree.ElementTree.Element.__setitem__ (   self,
  index,
  element 
)

Replaces the given subelement, by index.

Parameters:
indexWhat subelement to replace.
elementThe new element value.
Exceptions:
IndexErrorIf the given element does not exist.

Definition at line 275 of file ElementTree.py.

00275 
00276     def __setitem__(self, index, element):
00277         # if isinstance(index, slice):
00278         #     for elt in element:
00279         #         assert iselement(elt)
00280         # else:
00281         #     assert iselement(element)
00282         self._children[index] = element

def xml.etree.ElementTree.Element.append (   self,
  element 
)

Adds a subelement to the end of this element.

In document order, the new element will appear after the last existing subelement (or directly after the text, if it's the first subelement), but before the end tag for this element.

Parameters:
elementThe element to add.

Definition at line 300 of file ElementTree.py.

00300 
00301     def append(self, element):
00302         # assert iselement(element)
00303         self._children.append(element)

Here is the caller graph for this function:

Resets an element.

This function removes all subelements, clears all attributes, and sets the text and tail attributes to None.

Definition at line 409 of file ElementTree.py.

00409 
00410     def clear(self):
00411         self.attrib.clear()
00412         self._children = []
00413         self.text = self.tail = None

(Experimental) Copies the current element.

This creates a shallow copy; subelements will be shared with the original tree.

Returns:
A new element instance.

Definition at line 233 of file ElementTree.py.

00233 
00234     def copy(self):
00235         elem = self.makeelement(self.tag, self.attrib)
00236         elem.text = self.text
00237         elem.tail = self.tail
00238         elem[:] = self
00239         return elem

Here is the call graph for this function:

def xml.etree.ElementTree.Element.extend (   self,
  elements 
)

Appends subelements from a sequence.

Parameters:
elementsA sequence object with zero or more elements.
Since:
1.3

Definition at line 310 of file ElementTree.py.

00310 
00311     def extend(self, elements):
00312         # for element in elements:
00313         #     assert iselement(element)
00314         self._children.extend(elements)

def xml.etree.ElementTree.Element.find (   self,
  path,
  namespaces = None 
)

Finds the first matching subelement, by tag name or path.

Parameters:
pathWhat element to look for. namespaces Optional namespace prefix map.
Returns:
The first matching element, or None if no element was found. Element or None

Definition at line 362 of file ElementTree.py.

00362 
00363     def find(self, path, namespaces=None):
00364         return ElementPath.find(self, path, namespaces)

def xml.etree.ElementTree.Element.findall (   self,
  path,
  namespaces = None 
)

Finds all matching subelements, by tag name or path.

Parameters:
pathWhat element to look for. namespaces Optional namespace prefix map.
Returns:
A list or other sequence containing all matching elements, in document order. list of Element instances

Definition at line 389 of file ElementTree.py.

00389 
00390     def findall(self, path, namespaces=None):
00391         return ElementPath.findall(self, path, namespaces)

def xml.etree.ElementTree.Element.findtext (   self,
  path,
  default = None,
  namespaces = None 
)

Finds text for the first matching subelement, by tag name or path.

Parameters:
pathWhat element to look for.
defaultWhat to return if the element was not found. namespaces Optional namespace prefix map.
Returns:
The text content of the first matching element, or the default value no element was found. Note that if the element is found, but has no text content, this method returns an empty string. string

Definition at line 377 of file ElementTree.py.

00377 
00378     def findtext(self, path, default=None, namespaces=None):
00379         return ElementPath.findtext(self, path, default, namespaces)

def xml.etree.ElementTree.Element.get (   self,
  key,
  default = None 
)

Gets an element attribute.

Equivalent to attrib.get, but some implementations may handle this a bit more efficiently.

Parameters:
keyWhat attribute to look for.
defaultWhat to return if the attribute was not found.
Returns:
The attribute value, or the default value, if the attribute was not found. string or None

Definition at line 424 of file ElementTree.py.

00424 
00425     def get(self, key, default=None):
00426         return self.attrib.get(key, default)

Here is the caller graph for this function:

(Deprecated) Returns all subelements.

The elements are returned in document order.

Returns:
A list of subelements. list of Element instances

Definition at line 346 of file ElementTree.py.

00346 
00347     def getchildren(self):
00348         warnings.warn(
00349             "This method will be removed in future versions.  "
00350             "Use 'list(elem)' or iteration over elem instead.",
00351             DeprecationWarning, stacklevel=2
00352             )
00353         return self._children

Here is the call graph for this function:

def xml.etree.ElementTree.Element.getiterator (   self,
  tag = None 
)

Definition at line 481 of file ElementTree.py.

00481 
00482     def getiterator(self, tag=None):
00483         # Change for a DeprecationWarning in 1.4
00484         warnings.warn(
00485             "This method will be removed in future versions.  "
00486             "Use 'elem.iter()' or 'list(elem.iter())' instead.",
00487             PendingDeprecationWarning, stacklevel=2
00488         )
00489         return list(self.iter(tag))

Here is the call graph for this function:

def xml.etree.ElementTree.Element.insert (   self,
  index,
  element 
)

Inserts a subelement at the given position in this element.

Parameters:
indexWhere to insert the new subelement.

Definition at line 320 of file ElementTree.py.

00320 
00321     def insert(self, index, element):
00322         # assert iselement(element)
00323         self._children.insert(index, element)

Gets element attributes, as a sequence.

The attributes are returned in an arbitrary order. Equivalent to attrib.items().

Returns:
A list of (name, value) tuples for all attributes. list of (string, string) tuples

Definition at line 455 of file ElementTree.py.

00455 
00456     def items(self):
00457         return self.attrib.items()

Here is the caller graph for this function:

def xml.etree.ElementTree.Element.iter (   self,
  tag = None 
)

Creates a tree iterator.

The iterator loops over this element and all subelements, in document order, and returns all elements with a matching tag.

If the tree structure is modified during iteration, new or removed elements may or may not be included. To get a stable set, use the list() function on the iterator, and loop over the resulting list.

Parameters:
tagWhat tags to look for (default is to return all elements).
Returns:
An iterator containing all the matching elements. iterator

Definition at line 471 of file ElementTree.py.

00471 
00472     def iter(self, tag=None):
00473         if tag == "*":
00474             tag = None
00475         if tag is None or self.tag == tag:
00476             yield self
00477         for e in self._children:
00478             for e in e.iter(tag):
00479                 yield e

Here is the caller graph for this function:

def xml.etree.ElementTree.Element.iterfind (   self,
  path,
  namespaces = None 
)

Finds all matching subelements, by tag name or path.

Parameters:
pathWhat element to look for. namespaces Optional namespace prefix map.
Returns:
An iterator or sequence containing all matching elements, in document order. a generated sequence of Element instances

Definition at line 401 of file ElementTree.py.

00401 
00402     def iterfind(self, path, namespaces=None):
00403         return ElementPath.iterfind(self, path, namespaces)

Creates a text iterator.

The iterator loops over this element and all subelements, in document order, and returns all inner text.

Returns:
An iterator containing all inner text. iterator

Definition at line 498 of file ElementTree.py.

00498 
00499     def itertext(self):
00500         tag = self.tag
00501         if not isinstance(tag, str) and tag is not None:
00502             return
00503         if self.text:
00504             yield self.text
00505         for e in self:
00506             for s in e.itertext():
00507                 yield s
00508             if e.tail:
00509                 yield e.tail
00510 
# compatibility

Gets a list of attribute names.

The names are returned in an arbitrary order (just like for an ordinary Python dictionary). Equivalent to attrib.keys().

Returns:
A list of element attribute names. list of strings

Definition at line 445 of file ElementTree.py.

00445 
00446     def keys(self):
00447         return self.attrib.keys()

def xml.etree.ElementTree.Element.makeelement (   self,
  tag,
  attrib 
)

Creates a new element object of the same type as this element.

Parameters:
tagElement tag.
attribElement attributes, given as a dictionary.
Returns:
A new element instance.

Definition at line 224 of file ElementTree.py.

00224 
00225     def makeelement(self, tag, attrib):
00226         return self.__class__(tag, attrib)

Here is the caller graph for this function:

def xml.etree.ElementTree.Element.remove (   self,
  element 
)

Removes a matching subelement.

Unlike the find methods, this method compares elements based on identity, not on tag value or contents. To remove subelements by other means, the easiest way is often to use a list comprehension to select what elements to keep, and use slice assignment to update the parent element.

Parameters:
elementWhat element to remove.
Exceptions:
ValueErrorIf a matching element could not be found.

Definition at line 335 of file ElementTree.py.

00335 
00336     def remove(self, element):
00337         # assert iselement(element)
00338         self._children.remove(element)

Here is the caller graph for this function:

def xml.etree.ElementTree.Element.set (   self,
  key,
  value 
)

Sets an element attribute.

Equivalent to attrib[key] = value, but some implementations may handle this a bit more efficiently.

Parameters:
keyWhat attribute to set.
valueThe attribute value.

Definition at line 434 of file ElementTree.py.

00434 
00435     def set(self, key, value):
00436         self.attrib[key] = value

Here is the caller graph for this function:


Member Data Documentation

Definition at line 212 of file ElementTree.py.

(Attribute) Element attribute dictionary.

Where possible, use Element.get, Element.set, Element.keys, and Element.items to access element attributes.

Definition at line 187 of file ElementTree.py.

(Attribute) Element tag.

Definition at line 177 of file ElementTree.py.

(Attribute) Text after this element's end tag, but before the next sibling element's start tag.

This is either a string or the value None. Note that if there was no text, this attribute may be either None or an empty string, depending on the parser.

Definition at line 203 of file ElementTree.py.

(Attribute) Text before first subelement.

This is either a string or the value None. Note that if there was no text, this attribute may be either None or an empty string, depending on the parser.

Definition at line 195 of file ElementTree.py.


The documentation for this class was generated from the following file: