docutils.nodes.Element

class documentation

class Element(Node):

Known subclasses: docutils.nodes.admonition, docutils.nodes.attention, docutils.nodes.authors, docutils.nodes.block_quote, docutils.nodes.bullet_list, docutils.nodes.caution, docutils.nodes.citation, docutils.nodes.colspec, docutils.nodes.compound, docutils.nodes.container, docutils.nodes.danger, docutils.nodes.decoration, docutils.nodes.definition, docutils.nodes.definition_list, docutils.nodes.definition_list_item, docutils.nodes.description, docutils.nodes.docinfo, docutils.nodes.document, docutils.nodes.entry, docutils.nodes.enumerated_list, docutils.nodes.error, docutils.nodes.field, docutils.nodes.field_body, docutils.nodes.field_list, docutils.nodes.figure, docutils.nodes.footer, docutils.nodes.footnote, docutils.nodes.header, docutils.nodes.hint, docutils.nodes.image, docutils.nodes.important, docutils.nodes.legend, docutils.nodes.line_block, docutils.nodes.list_item, docutils.nodes.meta, docutils.nodes.note, docutils.nodes.option, docutils.nodes.option_group, docutils.nodes.option_list, docutils.nodes.option_list_item, docutils.nodes.pending, docutils.nodes.row, docutils.nodes.section, docutils.nodes.sidebar, docutils.nodes.system_message, docutils.nodes.table, docutils.nodes.tbody, docutils.nodes.TextElement, docutils.nodes.tgroup, docutils.nodes.thead, docutils.nodes.tip, docutils.nodes.topic, docutils.nodes.transition, docutils.nodes.warning

View In Hierarchy

Element is the superclass to all specific elements.

Elements contain attributes and child nodes. They can be described as a cross between a list and a dictionary.

Elements emulate dictionaries for external [1] attributes, indexing by attribute name (a string). To set the attribute 'att' to 'value', do:

element['att'] = 'value'
[1]External attributes correspond to the XML element attributes. From its Node superclass, Element also inherits "internal" class attributes that are accessed using the standard syntax, e.g. element.parent.

There are two special attributes: 'ids' and 'names'. Both are lists of unique identifiers: 'ids' conform to the regular expression [a-z](-?[a-z0-9]+)* (see the make_id() function for rationale and details). 'names' serve as user-friendly interfaces to IDs; they are case- and whitespace-normalized (see the fully_normalize_name() function).

Elements emulate lists for child nodes (element nodes and/or text nodes), indexing by integer. To get the first child node, use:

element[0]

to iterate over the child nodes (without descending), use:

for child in element:
    ...

Elements may be constructed using the += operator. To add one new child node to element, do:

element += node

This is equivalent to element.append(node).

To add a list of multiple child nodes at once, use the same += operator:

element += [node1, node2]

This is equivalent to element.extend([node1, node2]).

Class Method is​_not​_known​_attribute Returns True if and only if the given attribute is NOT recognized by this class.
Class Method is​_not​_list​_attribute Returns True if and only if the given attribute is NOT one of the basic list attributes defined for all Elements.
Method __add__ Undocumented
Method __contains__ Undocumented
Method __delitem__ Undocumented
Method __getitem__ Undocumented
Method __iadd__ Append a node or a list of nodes to self.children.
Method __init__ Undocumented
Method __len__ Undocumented
Method __radd__ Undocumented
Method __repr__ Undocumented
Method __setitem__ Undocumented
Method __unicode__ Undocumented
Method append Undocumented
Method append​_attr​_list For each element in values, if it does not exist in self[attr], append it.
Method astext Return a string representation of this Node.
Method attlist Undocumented
Method clear Undocumented
Method coerce​_append​_attr​_list First, convert both self[attr] and value to a non-string sequence type; if either is not already a sequence, convert it to a list of one element. Then call append_attr_list.
Method copy Return a copy of self.
Method copy​_attr​_coerce No summary
Method copy​_attr​_concatenate No summary
Method copy​_attr​_consistent If replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.
Method copy​_attr​_convert If attr is an attribute of self, set self[attr] to [self[attr], value], otherwise set self[attr] to value.
Method deepcopy Return a deep copy of self (also copying children).
Method delattr Undocumented
Method emptytag Undocumented
Method endtag Undocumented
Method extend Undocumented
Method first​_child​_matching​_class Return the index of the first child whose class exactly matches.
Method first​_child​_not​_matching​_class Return the index of the first child whose class does not match.
Method get Undocumented
Method get​_language​_code Return node's language tag.
Method hasattr Undocumented
Method index Undocumented
Method insert Undocumented
Method is​_not​_default Undocumented
Method non​_default​_attributes Undocumented
Method note​_referenced​_by Note that this Element has been referenced by its name name or id id.
Method pformat Return an indented pseudo-XML representation, for test purposes.
Method pop Undocumented
Method remove Undocumented
Method replace Replace one child Node with another child or children.
Method replace​_attr If self[attr] does not exist or force is True or omitted, set self[attr] to value, otherwise do nothing.
Method replace​_self Replace self node with new, where new is a node or a list of nodes.
Method set​_class Add a new class to the "classes" attribute.
Method setdefault Undocumented
Method shortrepr Undocumented
Method starttag Undocumented
Method update​_all​_atts Updates all attributes from node or dictionary dict_.
Method update​_all​_atts​_coercion Updates all attributes from node or dictionary dict_.
Method update​_all​_atts​_concatenating Updates all attributes from node or dictionary dict_.
Method update​_all​_atts​_consistantly Updates all attributes from node or dictionary dict_.
Method update​_all​_atts​_convert Updates all attributes from node or dictionary dict_.
Method update​_basic​_atts Update basic attributes ('ids', 'names', 'classes', 'dupnames', but not 'source') from node or dictionary dict_.
Class Variable basic​_attributes Tuple of attributes which are defined for every Element-derived class instance and can be safely transferred to a different node.
Class Variable child​_text​_separator Separator for child nodes, used by astext() method.
Class Variable known​_attributes Tuple of attributes that are known to the Element base class.
Class Variable list​_attributes Tuple of attributes that are automatically initialized to empty lists for all nodes.
Class Variable local​_attributes Tuple of class-specific attributes that should not be copied with the standard attributes when replacing a node.
Instance Variable attributes Dictionary of attribute {name: value}.
Instance Variable children List of child nodes (elements and/or Text).
Instance Variable rawsource The raw text from which this element was constructed.
Instance Variable referenced Undocumented
Instance Variable tagname The element generic identifier. If None, it is set as an instance attribute to the name of the class.
Method ​_dom​_node Undocumented

Inherited from Node:

Method __bool__ Node instances are always true, even if they're empty. A node is more than a simple container. Its boolean "truth" does not depend on having one or more subnodes in the doctree.
Method __str__ Undocumented
Method asdom Return a DOM fragment representation of this Node.
Method document.setter Undocumented
Method findall Return an iterator yielding nodes following self:
Method next​_node Return the first node in the iterator returned by findall(), or None if the iterable is empty.
Method previous​_sibling Return preceding sibling node or None.
Method setup​_child Undocumented
Method traverse Return list of nodes following self.
Method walk No summary
Method walkabout Perform a tree traversal similarly to Node.walk() (which see), except also call the dispatch_departure() method before exiting each node.
Class Variable line The line number (1-based) of the beginning of this Node in source.
Class Variable parent Back-reference to the Node immediately containing this Node.
Class Variable source Path or description of the input source which generated this Node.
Property document Return the document node at the root of the tree containing this Node.
Method ​_fast​_findall Return iterator that only supports instance checks.
Method ​_superfast​_findall Return iterator that doesn't check for a condition.
Instance Variable ​_document Undocumented
@classmethod
def is_not_known_attribute(cls, attr):
Returns True if and only if the given attribute is NOT recognized by this class.
@classmethod
def is_not_list_attribute(cls, attr):
Returns True if and only if the given attribute is NOT one of the basic list attributes defined for all Elements.
def __add__(self, other):

Undocumented

def __contains__(self, key):

Undocumented

def __delitem__(self, key):

Undocumented

def __getitem__(self, key):

Undocumented

def __iadd__(self, other):
Append a node or a list of nodes to self.children.
def __init__(self, rawsource='', *children, **attributes):
overridden in docutils.nodes.document, docutils.nodes.pending, docutils.nodes.system_message, docutils.nodes.TextElement

Undocumented

def __len__(self):

Undocumented

def __radd__(self, other):

Undocumented

def __repr__(self):

Undocumented

def __setitem__(self, key, item):

Undocumented

def __unicode__(self):

Undocumented

def append(self, item):

Undocumented

def append_attr_list(self, attr, values):

For each element in values, if it does not exist in self[attr], append it.

NOTE: Requires self[attr] and values to be sequence type and the former should specifically be a list.

def astext(self):
overrides docutils.nodes.Node.astext
overridden in docutils.nodes.image, docutils.nodes.option_argument, docutils.nodes.system_message
Return a string representation of this Node.
def attlist(self):

Undocumented

def clear(self):

Undocumented

def coerce_append_attr_list(self, attr, value):

First, convert both self[attr] and value to a non-string sequence type; if either is not already a sequence, convert it to a list of one element. Then call append_attr_list.

NOTE: self[attr] and value both must not be None.

def copy(self):
overrides docutils.nodes.Node.copy
overridden in docutils.nodes.document, docutils.nodes.pending
Return a copy of self.
def copy_attr_coerce(self, attr, value, replace):
If attr is an attribute of self and either self[attr] or value is a list, convert all non-sequence values to a sequence of 1 element and then concatenate the two sequence, setting the result to self[attr]. If both self[attr] and value are non-sequences and replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.
def copy_attr_concatenate(self, attr, value, replace):
If attr is an attribute of self and both self[attr] and value are lists, concatenate the two sequences, setting the result to self[attr]. If either self[attr] or value are non-sequences and replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.
def copy_attr_consistent(self, attr, value, replace):
If replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.
def copy_attr_convert(self, attr, value, replace=True):

If attr is an attribute of self, set self[attr] to [self[attr], value], otherwise set self[attr] to value.

NOTE: replace is not used by this function and is kept only for
compatibility with the other copy functions.
def deepcopy(self):
overrides docutils.nodes.Node.deepcopy
Return a deep copy of self (also copying children).
def delattr(self, attr):

Undocumented

def emptytag(self):

Undocumented

def endtag(self):

Undocumented

def extend(self, item):

Undocumented

def first_child_matching_class(self, childclass, start=0, end=sys.maxsize):

Return the index of the first child whose class exactly matches.

Parameters:

  • childclass: A Node subclass to search for, or a tuple of Node classes. If a tuple, any of the classes may match.
  • start: Initial index to check.
  • end: Initial index to not check.
def first_child_not_matching_class(self, childclass, start=0, end=sys.maxsize):

Return the index of the first child whose class does not match.

Parameters:

  • childclass: A Node subclass to skip, or a tuple of Node classes. If a tuple, none of the classes may match.
  • start: Initial index to check.
  • end: Initial index to not check.
def get(self, key, failobj=None):

Undocumented

def get_language_code(self, fallback=''):

Return node's language tag.

Look iteratively in self and parents for a class argument starting with language- and return the remainder of it (which should be a BCP49 language tag) or the fallback.

def hasattr(self, attr):

Undocumented

def index(self, item):

Undocumented

def insert(self, index, item):

Undocumented

def is_not_default(self, key):

Undocumented

def non_default_attributes(self):

Undocumented

def note_referenced_by(self, name=None, id=None):
Note that this Element has been referenced by its name name or id id.
def pformat(self, indent=' ', level=0):
overrides docutils.nodes.Node.pformat
overridden in docutils.nodes.pending

Return an indented pseudo-XML representation, for test purposes.

Override in subclasses.

def pop(self, i=-1):

Undocumented

def remove(self, item):

Undocumented

def replace(self, old, new):
Replace one child Node with another child or children.
def replace_attr(self, attr, value, force=True):
If self[attr] does not exist or force is True or omitted, set self[attr] to value, otherwise do nothing.
def replace_self(self, new):
Replace self node with new, where new is a node or a list of nodes.
def set_class(self, name):
Add a new class to the "classes" attribute.
def setdefault(self, key, failobj=None):

Undocumented

def shortrepr(self):

Undocumented

def starttag(self, quoteattr=None):

Undocumented

def update_all_atts(self, dict_, update_fun=copy_attr_consistent, replace=True, and_source=False):

Updates all attributes from node or dictionary dict_.

Appends the basic attributes ('ids', 'names', 'classes', 'dupnames', but not 'source') and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_, the two values are merged based on the value of update_fun. Generally, when replace is True, the values in self are replaced or merged with the values in dict_; otherwise, the values in self may be preserved or merged. When and_source is True, the 'source' attribute is included in the copy.

NOTE: When replace is False, and self contains a 'source' attribute,
'source' is not replaced even when dict_ has a 'source' attribute, though it may still be merged into a list depending on the value of update_fun.
NOTE: It is easier to call the update-specific methods then to pass
the update_fun method to this function.
def update_all_atts_coercion(self, dict_, replace=True, and_source=False):

Updates all attributes from node or dictionary dict_.

Appends the basic attributes ('ids', 'names', 'classes', 'dupnames', but not 'source') and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ whose values are both not lists and replace is True, the values in self are replaced with the values in dict_; if either of the values from self and dict_ for the given identifier are of list type, then first any non-lists are converted to 1-element lists and then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the 'source' attribute is included in the copy.

NOTE: When replace is False, and self contains a 'source' attribute,
'source' is not replaced even when dict_ has a 'source' attribute, though it may still be merged into a list depending on the value of update_fun.
def update_all_atts_concatenating(self, dict_, replace=True, and_source=False):

Updates all attributes from node or dictionary dict_.

Appends the basic attributes ('ids', 'names', 'classes', 'dupnames', but not 'source') and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ whose values aren't each lists and replace is True, the values in self are replaced with the values in dict_; if the values from self and dict_ for the given identifier are both of list type, then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the 'source' attribute is included in the copy.

NOTE: When replace is False, and self contains a 'source' attribute,
'source' is not replaced even when dict_ has a 'source' attribute, though it may still be merged into a list depending on the value of update_fun.
def update_all_atts_consistantly(self, dict_, replace=True, and_source=False):

Updates all attributes from node or dictionary dict_.

Appends the basic attributes ('ids', 'names', 'classes', 'dupnames', but not 'source') and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ and replace is True, the values in self are replaced with the values in dict_; otherwise, the values in self are preserved. When and_source is True, the 'source' attribute is included in the copy.

NOTE: When replace is False, and self contains a 'source' attribute,
'source' is not replaced even when dict_ has a 'source' attribute, though it may still be merged into a list depending on the value of update_fun.
def update_all_atts_convert(self, dict_, and_source=False):

Updates all attributes from node or dictionary dict_.

Appends the basic attributes ('ids', 'names', 'classes', 'dupnames', but not 'source') and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ then first any non-lists are converted to 1-element lists and then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the 'source' attribute is included in the copy.

NOTE: When replace is False, and self contains a 'source' attribute,
'source' is not replaced even when dict_ has a 'source' attribute, though it may still be merged into a list depending on the value of update_fun.
def update_basic_atts(self, dict_):
Update basic attributes ('ids', 'names', 'classes', 'dupnames', but not 'source') from node or dictionary dict_.
basic_attributes: tuple[str, ...] =
Tuple of attributes which are defined for every Element-derived class instance and can be safely transferred to a different node.
child_text_separator: str =
overridden in docutils.nodes.option, docutils.nodes.option_group, docutils.nodes.option_list_item, docutils.nodes.TextElement
Separator for child nodes, used by astext() method.
known_attributes =
Tuple of attributes that are known to the Element base class.
list_attributes =
Tuple of attributes that are automatically initialized to empty lists for all nodes.
local_attributes: tuple[str, ...] =

Tuple of class-specific attributes that should not be copied with the standard attributes when replacing a node.

NOTE: Derived classes should override this value to prevent any of its attributes being copied by adding to the value in its parent class.

attributes: dict =
Dictionary of attribute {name: value}.
children: list =
List of child nodes (elements and/or Text).
rawsource =

The raw text from which this element was constructed.

NOTE: some elements do not set this value (default '').

referenced: int =

Undocumented

tagname =
The element generic identifier. If None, it is set as an instance attribute to the name of the class.
def _dom_node(self, domroot):

Undocumented