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.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 [#]_ attributes, indexing by attribute name (a string). To set the attribute 'att' to 'value', do:: element['att'] = 'value' .. [#] 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 __str__ 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 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]...
Method copy_attr_concatenate 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...
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 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 Traverse a tree of `Node` objects, calling the `dispatch_visit()` method of `visitor` when entering each node. (The `walkabout()` method is similar, except it also calls the `dispatch_departure()` method before exiting each node...
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` root node 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): (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 __str__(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, start=0, stop=sys.maxsize): (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)

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 = (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)

Tuple of attributes that are known to the Element base class.

list_attributes = (source)

Tuple of attributes that are automatically initialized to empty lists for all nodes.

local_attributes: tuple[str, ...] = (source)

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 = (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