Inherits docutils.nodes.Node.

Inherited by docutils.nodes.TextElement, 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.tgroup, docutils.nodes.thead, docutils.nodes.tip, docutils.nodes.topic, docutils.nodes.transition, docutils.nodes.warning, docutils.parsers.recommonmark_wrapper.pending_xref, and sphinx.ext.viewcode.viewcode_anchor.

Collaboration diagram for docutils.nodes.Element:

[legend]

Public Member Functions
	__init__ (self, rawsource='', children, *attributes)

	__repr__ (self)

	shortrepr (self)

	__str__ (self)

	starttag (self, quoteattr=None)

	endtag (self)

	emptytag (self)

	__len__ (self)

	__contains__ (self, key)

	__getitem__ (self, key)

	__setitem__ (self, key, item)

	__delitem__ (self, key)

	__add__ (self, other)

	__radd__ (self, other)

	__iadd__ (self, other)

	astext (self)

	non_default_attributes (self)

	attlist (self)

	get (self, key, failobj=None)

	hasattr (self, attr)

	delattr (self, attr)

	setdefault (self, key, failobj=None)

	get_language_code (self, fallback='')

	append (self, item)

	extend (self, item)

	insert (self, index, item)

	pop (self, i=-1)

	remove (self, item)

	index (self, item, start=0, stop=sys.maxsize)

	previous_sibling (self)

	is_not_default (self, key)

	update_basic_atts (self, dict_)

	append_attr_list (self, attr, values)

	coerce_append_attr_list (self, attr, value)

	replace_attr (self, attr, value, force=True)

	copy_attr_convert (self, attr, value, replace=True)

	copy_attr_coerce (self, attr, value, replace)

	copy_attr_concatenate (self, attr, value, replace)

	copy_attr_consistent (self, attr, value, replace)

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

	update_all_atts_consistantly (self, dict_, replace=True, and_source=False)

	update_all_atts_concatenating (self, dict_, replace=True, and_source=False)

	update_all_atts_coercion (self, dict_, replace=True, and_source=False)

	update_all_atts_convert (self, dict_, and_source=False)

	clear (self)

	replace (self, old, new)

	replace_self (self, new)

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

	first_child_not_matching_class (self, childclass, start=0, end=sys.maxsize)

	pformat (self, indent=' ', level=0)

	copy (self)

	deepcopy (self)

	set_class (self, name)

	note_referenced_by (self, name=None, id=None)

	is_not_list_attribute (cls, attr)

	is_not_known_attribute (cls, attr)

Public Member Functions inherited from docutils.nodes.Node
	document (self)

	document (self, value)

	__bool__ (self)

	asdom (self, dom=None)

	setup_child (self, child)

	walk (self, visitor)

	walkabout (self, visitor)

	traverse (self, condition=None, include_self=True, descend=True, siblings=False, ascend=False)

	findall (self, condition=None, include_self=True, descend=True, siblings=False, ascend=False)

	next_node (self, condition=None, include_self=False, descend=True, siblings=False, ascend=False)

Public Attributes
	rawsource

	children

	attributes

	referenced

Public Attributes inherited from docutils.nodes.Node
	children

Static Public Attributes
tuple	basic_attributes = ('ids', 'classes', 'names', 'dupnames')

tuple	local_attributes = ('backrefs',)

tuple	list_attributes = basic_attributes + local_attributes

tuple	known_attributes = list_attributes + ('source',)

	tagname = None

str	child_text_separator = '\n\n'

	has_key = hasattr

Static Public Attributes inherited from docutils.nodes.Node
	parent = None

	source = None

	line = None

Protected Member Functions
	_dom_node (self, domroot)

Protected Member Functions inherited from docutils.nodes.Node
	_fast_findall (self, cls)

	_superfast_findall (self)

Additional Inherited Members
Static Protected Attributes inherited from docutils.nodes.Node
	_document = None

Detailed Description

`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])``.

Member Function Documentation

◆ iadd()

docutils.nodes.Element.__iadd__	(	self,
		other
	)

Append a node or a list of nodes to `self.children`.

◆ append_attr_list()

docutils.nodes.Element.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.

◆ astext()

docutils.nodes.Element.astext ( self )

Return a string representation of this Node.

Reimplemented from docutils.nodes.Node.

Reimplemented in docutils.nodes.option_argument, docutils.nodes.system_message, and docutils.nodes.image.

◆ coerce_append_attr_list()

docutils.nodes.Element.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.

◆ copy()

docutils.nodes.Element.copy ( self )

Return a copy of self.

Reimplemented from docutils.nodes.Node.

Reimplemented in docutils.nodes.document, and docutils.nodes.pending.

◆ copy_attr_coerce()

docutils.nodes.Element.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.

◆ copy_attr_concatenate()

docutils.nodes.Element.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.

◆ copy_attr_consistent()

docutils.nodes.Element.copy_attr_consistent	(	self,
		attr,
		value,
		replace
	)

If replace is True or self[attr] is None, replace self[attr] with
value.  Otherwise, do nothing.

◆ copy_attr_convert()

docutils.nodes.Element.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.

◆ deepcopy()

docutils.nodes.Element.deepcopy ( self )

Return a deep copy of self (also copying children).

Reimplemented from docutils.nodes.Node.

◆ first_child_matching_class()

docutils.nodes.Element.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.

◆ first_child_not_matching_class()

docutils.nodes.Element.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.

◆ get_language_code()

docutils.nodes.Element.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`.

◆ is_not_known_attribute()

docutils.nodes.Element.is_not_known_attribute	(	cls,
		attr
	)

Returns True if and only if the given attribute is NOT recognized by
this class.

◆ is_not_list_attribute()

docutils.nodes.Element.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.

◆ note_referenced_by()

docutils.nodes.Element.note_referenced_by	(	self,
		name = `None`,
		id = `None`
	)

Note that this Element has been referenced by its name
`name` or id `id`.

◆ pformat()

docutils.nodes.Element.pformat	(	self,
		indent = `' '`,
		level = `0`
	)

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

Override in subclasses.

Reimplemented from docutils.nodes.Node.

Reimplemented in docutils.nodes.pending.

◆ previous_sibling()

docutils.nodes.Element.previous_sibling ( self )

Return preceding sibling node or ``None``.

◆ replace()

docutils.nodes.Element.replace	(	self,
		old,
		new
	)

Replace one child `Node` with another child or children.

◆ replace_attr()

docutils.nodes.Element.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.

◆ replace_self()

docutils.nodes.Element.replace_self	(	self,
		new
	)

Replace `self` node with `new`, where `new` is a node or a
list of nodes.

◆ set_class()

docutils.nodes.Element.set_class	(	self,
		name
	)

Add a new class to the "classes" attribute.

◆ update_all_atts()

docutils.nodes.Element.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.

◆ update_all_atts_coercion()

docutils.nodes.Element.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.

◆ update_all_atts_concatenating()

docutils.nodes.Element.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.

◆ update_all_atts_consistantly()

docutils.nodes.Element.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.

◆ update_all_atts_convert()

docutils.nodes.Element.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.

◆ update_basic_atts()

docutils.nodes.Element.update_basic_atts	(	self,
		dict_
	)

Update basic attributes ('ids', 'names', 'classes',
'dupnames', but not 'source') from node or dictionary `dict_`.

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

docs/help/help-venv/lib/python3.12/site-packages/docutils/nodes.py

Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ __iadd__()

◆ append_attr_list()

◆ astext()

◆ coerce_append_attr_list()

◆ copy()

◆ copy_attr_coerce()

◆ copy_attr_concatenate()

◆ copy_attr_consistent()

◆ copy_attr_convert()

◆ deepcopy()

◆ first_child_matching_class()

◆ first_child_not_matching_class()

◆ get_language_code()

◆ is_not_known_attribute()

◆ is_not_list_attribute()

◆ note_referenced_by()

◆ pformat()

◆ previous_sibling()

◆ replace()

◆ replace_attr()

◆ replace_self()

◆ set_class()

◆ update_all_atts()

◆ update_all_atts_coercion()

◆ update_all_atts_concatenating()

◆ update_all_atts_consistantly()

◆ update_all_atts_convert()

◆ update_basic_atts()

◆ iadd()