Package lxml :: Module etree :: Class _Element

Class _Element

object --+
         |
        _Element

Known Subclasses:

ElementBase
, unreachable.__ContentOnlyElement

Element class.

References a document object and a libxml node.

By pointing to a Document instance, a reference is kept to _Document as long as there is some pointer to a node in it.

Instance Methods

[hide private]

__contains__(self, element)

__copy__(self)

__deepcopy__(self, memo)

__delitem__(self, x)
Deletes the given subelement or a slice.

__getitem__(...)
Returns the subelement at the given position or the requested slice.

__iter__(self)

__len__(self)
Returns the number of subelements.

a new object with type S, a subtype of T

__new__(T, S, ...)

__nonzero__(x)
x != 0

__repr__(self)
repr(x)

__reversed__(self)

__setitem__(self, x, value)
Replaces the given subelement index or slice.

_init(self)
Called after object initialisation. Custom subclasses may override this if they recursively call _init() in the superclasses.

addnext(self, element)
Adds the element as a following sibling directly after this element.

addprevious(self, element)
Adds the element as a preceding sibling directly before this element.

append(self, element)
Adds a subelement to the end of this element.

clear(self, keep_tail=False)
Resets an element. This function removes all subelements, clears all attributes and sets the text and tail properties to None.

cssselect(...)
Run the CSS expression on this element and its children, returning a list of the results.

extend(self, elements)
Extends the current children by the elements in the iterable.

find(self, path, namespaces=None)
Finds the first matching subelement, by tag name or path.

findall(self, path, namespaces=None)
Finds all matching subelements, by tag name or path.

findtext(self, path, default=None, namespaces=None)
Finds text for the first matching subelement, by tag name or path.

get(self, key, default=None)
Gets an element attribute.

getchildren(self)
Returns all direct children. The elements are returned in document order.

getiterator(self, tag=None, *tags)
Returns a sequence or iterator of all elements in the subtree in document order (depth first pre-order), starting with this element.

getnext(self)
Returns the following sibling of this element or None.

getparent(self)
Returns the parent of this element or None for the root element.

getprevious(self)
Returns the preceding sibling of this element or None.

getroottree(self)
Return an ElementTree for the root node of the document that contains this element.

index(self, child, start=None, stop=None)
Find the position of the child within the parent.

insert(self, index, element)
Inserts a subelement at the given position in this element

items(self)
Gets element attributes, as a sequence. The attributes are returned in an arbitrary order.

iter(self, tag=None, *tags)
Iterate over all elements in the subtree in document order (depth first pre-order), starting with this element.

iterancestors(self, tag=None, *tags)
Iterate over the ancestors of this element (from parent to parent).

iterchildren(self, tag=None, reversed=False, *tags)
Iterate over the children of this element.

iterdescendants(self, tag=None, *tags)
Iterate over the descendants of this element in document order.

iterfind(self, path, namespaces=None)
Iterates over all matching subelements, by tag name or path.

itersiblings(self, tag=None, preceding=False, *tags)
Iterate over the following or preceding siblings of this element.

itertext(self, tag=None, with_tail=True, *tags)
Iterates over the text content of a subtree.

keys(self)
Gets a list of attribute names. The names are returned in an arbitrary order (just like for an ordinary Python dictionary).

makeelement(self, _tag, attrib=None, nsmap=None, **_extra)
Creates a new element associated with the same document.

remove(self, element)
Removes a matching subelement. Unlike the find methods, this method compares elements based on identity, not on tag value or contents.

replace(self, old_element, new_element)
Replaces a subelement with the element passed as second argument.

set(self, key, value)
Sets an element attribute.

values(self)
Gets element attribute values as a sequence of strings. The attributes are returned in an arbitrary order.

xpath(self, _path, namespaces=None, extensions=None, smart_strings=True, **_variables)
Evaluate an xpath expression using the element as context node.

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __init__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties

[hide private]

attrib
Element attribute dictionary. Where possible, use get(), set(), keys(), values() and items() to access element attributes.

base
The base URI of the Element (xml:base or HTML base URL). None if the base URI is unknown.

nsmap
Namespace prefix->URI mapping known in the context of this Element. This includes all namespace declarations of the parents.

prefix
Namespace prefix or None.

sourceline
Original line number as found by the parser or None if unknown.

tag
Element tag

tail
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, if there was no text.

text
Text before the first subelement. This is either a string or the value None, if there was no text.

Inherited from object: __class__

Method Details

[hide private]

new(T, S, ...)

Returns: a new object with type S, a subtype of T
Overrides: object.__new__

repr(self)
(Representation operator)

repr(x)

Overrides: object.__repr__

addnext(self, element)

Adds the element as a following sibling directly after this element.

This is normally used to set a processing instruction or comment after the root node of a document. Note that tail text is automatically discarded when adding at the root level.

addprevious(self, element)

Adds the element as a preceding sibling directly before this element.

This is normally used to set a processing instruction or comment before the root node of a document. Note that tail text is automatically discarded when adding at the root level.

clear(self, keep_tail=False)

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

Pass keep_tail=True to leave the tail text untouched.

cssselect(...)

Run the CSS expression on this element and its children, returning a list of the results.

Equivalent to lxml.cssselect.CSSSelect(expr)(self) -- note that pre-compiling the expression can provide a substantial speedup.

find(self, path, namespaces=None)

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

The optional namespaces argument accepts a prefix-to-namespace mapping that allows the usage of XPath prefixes in the path expression.

findall(self, path, namespaces=None)

Finds all matching subelements, by tag name or path.

The optional namespaces argument accepts a prefix-to-namespace mapping that allows the usage of XPath prefixes in the path expression.

findtext(self, path, default=None, namespaces=None)

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

The optional namespaces argument accepts a prefix-to-namespace mapping that allows the usage of XPath prefixes in the path expression.

getchildren(self)

Returns all direct children. The elements are returned in document order.

Deprecated: Note that this method has been deprecated as of ElementTree 1.3 and lxml 2.0. New code should use list(element) or simply iterate over elements.

getiterator(self, tag=None, *tags)

Returns a sequence or iterator of all elements in the subtree in document order (depth first pre-order), starting with this element.

Can be restricted to find only elements with specific tags, see iter.

Deprecated: Note that this method is deprecated as of ElementTree 1.3 and lxml 2.0. It returns an iterator in lxml, which diverges from the original ElementTree behaviour. If you want an efficient iterator, use the element.iter() method instead. You should only use this method in new code if you require backwards compatibility with older versions of lxml or ElementTree.

getroottree(self)

Return an ElementTree for the root node of the document that contains this element.

This is the same as following element.getparent() up the tree until it returns None (for the root element) and then build an ElementTree for the last parent that was returned.

index(self, child, start=None, stop=None)

Find the position of the child within the parent.

This method is not part of the original ElementTree API.

iter(self, tag=None, *tags)

Iterate over all elements in the subtree in document order (depth first pre-order), starting with this element.

Can be restricted to find only elements with specific tags: pass "{ns}localname" as tag. Either or both of ns and localname can be * for a wildcard; ns can be empty for no namespace. "localname" is equivalent to "{}localname" (i.e. no namespace) but "*" is "{*}*" (any or no namespace), not "{}*".

You can also pass the Element, Comment, ProcessingInstruction and Entity factory functions to look only for the specific element type.

Passing multiple tags (or a sequence of tags) instead of a single tag will let the iterator return all elements matching any of these tags, in document order.

iterancestors(self, tag=None, *tags)

Iterate over the ancestors of this element (from parent to parent).

Can be restricted to find only elements with specific tags, see iter.

iterchildren(self, tag=None, reversed=False, *tags)

Iterate over the children of this element.

As opposed to using normal iteration on this element, the returned elements can be reversed with the 'reversed' keyword and restricted to find only elements with specific tags, see iter.

iterdescendants(self, tag=None, *tags)

Iterate over the descendants of this element in document order.

As opposed to el.iter(), this iterator does not yield the element itself. The returned elements can be restricted to find only elements with specific tags, see iter.

iterfind(self, path, namespaces=None)

Iterates over all matching subelements, by tag name or path.

The optional namespaces argument accepts a prefix-to-namespace mapping that allows the usage of XPath prefixes in the path expression.

itersiblings(self, tag=None, preceding=False, *tags)

Iterate over the following or preceding siblings of this element.

The direction is determined by the 'preceding' keyword which defaults to False, i.e. forward iteration over the following siblings. When True, the iterator yields the preceding siblings in reverse document order, i.e. starting right before the current element and going backwards.

Can be restricted to find only elements with specific tags, see iter.

itertext(self, tag=None, with_tail=True, *tags)

Iterates over the text content of a subtree.

You can pass tag names to restrict text content to specific elements, see iter.

You can set the with_tail keyword argument to False to skip over tail text.

Property Details

[hide private]

base

The base URI of the Element (xml:base or HTML base URL). None if the base URI is unknown.

Note that the value depends on the URL of the document that holds the Element if there is no xml:base attribute on the Element or its ancestors.

Setting this property will set an xml:base attribute on the Element, regardless of the document type (XML or HTML).

nsmap

Namespace prefix->URI mapping known in the context of this Element. This includes all namespace declarations of the parents.

Note that changing the returned dict has no effect on the Element.

Class _Element

__new__(T, S, ...)

__repr__(self) (Representation operator)

addnext(self, element)

addprevious(self, element)

clear(self, keep_tail=False)

cssselect(...)

find(self, path, namespaces=None)

findall(self, path, namespaces=None)

findtext(self, path, default=None, namespaces=None)

getchildren(self)

getiterator(self, tag=None, *tags)

getroottree(self)

index(self, child, start=None, stop=None)

iter(self, tag=None, *tags)

iterancestors(self, tag=None, *tags)

iterchildren(self, tag=None, reversed=False, *tags)

iterdescendants(self, tag=None, *tags)

iterfind(self, path, namespaces=None)

itersiblings(self, tag=None, preceding=False, *tags)

itertext(self, tag=None, with_tail=True, *tags)

base

nsmap

new(T, S, ...)

repr(self)
(Representation operator)