docutils.nodes.Element

class documentation

class Element(Node): (source)

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.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, docutils.parsers.rst.directives.html.MetaBody.meta

View In Hierarchy

Element is the superclass to all specific elements.

Elements contain attributes and child nodes. Elements emulate dictionaries for attributes, indexing by attribute name (a string). To set the attribute 'att' to 'value', do:

element['att'] = 'value'

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

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

element[0]

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 List 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 List attributes that are known to the Element base class.
Class Variable list​_attributes List attributes, automatically initialized to empty lists for all nodes.
Class Variable local​_attributes A list 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 next​_node Return the first node in the iterable returned by traverse(), or None if the iterable is empty.
Method setup​_child Undocumented
Method traverse Return an iterable containing
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 _all​_traverse Return iterator that doesn't check for a condition.
Method _fast​_traverse Return iterator that only supports instance checks.
Method _traverse Return iterator over nodes following self. See traverse().
Instance Variable _document Undocumented
@classmethod
def is_not_known_attribute(cls, attr): (source)
Returns True if and only if the given attribute is NOT recognized by this class.
@classmethod
def is_not_list_attribute(cls, attr): (source)
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): (source)

Undocumented

def __contains__(self, key): (source)

Undocumented

def __delitem__(self, key): (source)

Undocumented

def __getitem__(self, key): (source)

Undocumented

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

Undocumented

def __len__(self): (source)

Undocumented

def __radd__(self, other): (source)

Undocumented

def __repr__(self): (source)

Undocumented

def __setitem__(self, key, item): (source)

Undocumented

def __unicode__(self): (source)

Undocumented

def append(self, item): (source)

Undocumented

def append_attr_list(self, attr, values): (source)

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): (source)
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): (source)

Undocumented

def clear(self): (source)

Undocumented

def coerce_append_attr_list(self, attr, value): (source)

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): (source)
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): (source)
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): (source)
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): (source)
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): (source)

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): (source)
overrides docutils.nodes.Node.deepcopy
Return a deep copy of self (also copying children).
def delattr(self, attr): (source)

Undocumented

def emptytag(self): (source)

Undocumented

def endtag(self): (source)

Undocumented

def extend(self, item): (source)

Undocumented

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

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): (source)

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): (source)

Undocumented

def get_language_code(self, fallback=''): (source)

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): (source)

Undocumented

def index(self, item): (source)

Undocumented

def insert(self, index, item): (source)

Undocumented

def is_not_default(self, key): (source)

Undocumented

def non_default_attributes(self): (source)

Undocumented

def note_referenced_by(self, name=None, id=None): (source)
Note that this Element has been referenced by its name name or id id.
def pformat(self, indent=' ', level=0): (source)
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): (source)

Undocumented

def remove(self, item): (source)

Undocumented

def replace(self, old, new): (source)
Replace one child Node with another child or children.
def replace_attr(self, attr, value, force=True): (source)
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): (source)
Replace self node with new, where new is a node or a list of nodes.
def set_class(self, name): (source)
Add a new class to the "classes" attribute.
def setdefault(self, key, failobj=None): (source)

Undocumented

def shortrepr(self): (source)

Undocumented

def starttag(self, quoteattr=None): (source)

Undocumented

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

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): (source)

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): (source)

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): (source)

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): (source)

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_): (source)
Update basic attributes ('ids', 'names', 'classes', 'dupnames', but not 'source') from node or dictionary dict_.
basic_attributes: tuple[str, ...] = (source)
List attributes which are defined for every Element-derived class instance and can be safely transferred to a different node.
child_text_separator: str = (source)
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 = (source)
List attributes that are known to the Element base class.
list_attributes = (source)
List attributes, automatically initialized to empty lists for all nodes.
local_attributes: tuple[str, ...] = (source)

A list 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 = (source)
Dictionary of attribute {name: value}.
children: list = (source)
List of child nodes (elements and/or Text).
rawsource = (source)

The raw text from which this element was constructed.

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

referenced: int = (source)

Undocumented

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

Undocumented