sphinx_reports.Node

Classes

• Landscape: A container node used in LaTeX to render content in landscape view in PDF pages.

---

Classes

class sphinx_reports.Node.Landscape(rawsource='', *children, **attributes)

A container node used in LaTeX to render content in landscape view in PDF pages.

Inheritance

Parameters:

• rawsource (str)

• attributes (Any)

__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.

Use len() to check node length.

Return type:

Literal[True]

__iadd__(other)

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

Return type:

Self

__init__(rawsource='', *children, **attributes)

Parameters:

• rawsource (str)

• attributes (Any)

Return type:

None

__repr__()

Return repr(self).

Return type:

str

__str__()

Return str(self).

Return type:

str

_fast_findall(cls)

Return iterator that only supports instance checks.

Return type:

Iterator

Parameters:

cls (type)

_superfast_findall()

Return iterator that doesn’t check for a condition.

Return type:

Iterator

append_attr_list(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.

Return type:

None

Parameters:

• attr (str)

• values (Iterable[Any])

asdom(dom=None)

Return a DOM fragment representation of this Node.

Return type:

Document | Element | Text

Parameters:

dom (ModuleType | None)

astext()

Return a string representation of this Node.

Return type:

str

basic_attributes = ('ids', 'classes', 'names', 'dupnames')

Common list attributes. Deprecated. Will be removed in Docutils 2.0.

child_text_separator = '\n\n'

Separator for child nodes, used by astext() method.

coerce_append_attr_list(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.

Return type:

None

Parameters:

• attr (str)

• value (list[Any] | Any)

common_attributes = ('ids', 'classes', 'names', 'dupnames', 'source')

Tuple of common attributes known to all Doctree Element classes.

content_model = ((<class 'docutils.nodes.Body'>, '+'),)

Python representation of the element’s content model (cf. docutils.dtd).

A tuple of (category, quantifier) tuples with

Category:

class or tuple of classes that are expected at this place(s) in the list of children

Quantifier:

string representation stating how many elements of category are expected. Value is one of: ‘.’ (exactly one), ‘?’ (zero or one), ‘+’ (one or more), ‘*’ (zero or more).

NOTE: The default describes the empty element. Derived classes should update this value to match their content model.

Provisional.

copy()

Monkey-patch `nodes.Element.copy` to not copy the _document attribute.

See: https://github.com/sphinx-doc/sphinx/issues/11116#issuecomment-1376767086

Return type:

Element

Parameters:

el (Element)

copy_attr_coerce(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.

Return type:

None

Parameters:

• attr (str)

• value (Any)

• replace (bool)

copy_attr_concatenate(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.

Return type:

None

Parameters:

• attr (str)

• value (Any)

• replace (bool)

copy_attr_consistent(attr, value, replace)

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

Return type:

None

Parameters:

• attr (str)

• value (Any)

• replace (bool)

copy_attr_convert(attr, value, replace=True)

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

Return type:

None

Parameters:

• attr (str)

• value (Any)

• replace (bool)

NOTE: replace is not used by this function and is kept only for

compatibility with the other copy functions.

deepcopy()

Monkey-patch `nodes.Element.deepcopy` for speed.

Return type:

Element

Parameters:

el (Element)

property document: document | None

Return the document root node of the tree containing this Node.

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

Return an iterator yielding nodes following self:

• self (if include_self is true)

• all descendants in tree traversal order (if descend is true)

• the following siblings (if siblings is true) and their descendants (if also descend is true)

• the following siblings of the parent (if ascend is true) and their descendants (if also descend is true), and so on.

If condition is not None, the iterator yields only nodes for which condition(node) is true. If condition is a type cls, it is equivalent to a function consisting of return isinstance(node, cls).

If ascend is true, assume siblings to be true as well.

If the tree structure is modified during iteration, the result is undefined.

For example, given the following tree:

<paragraph>
    <emphasis>      <--- emphasis.traverse() and
        <strong>    <--- strong.traverse() are called.
            Foo
        Bar
    <reference name="Baz" refid="baz">
        Baz

Then tuple(emphasis.traverse()) equals

(<emphasis>, <strong>, <#text: Foo>, <#text: Bar>)

and list(strong.traverse(ascend=True) equals

[<strong>, <#text: Foo>, <#text: Bar>, <reference>, <#text: Baz>]

Return type:

Iterator

Parameters:

• condition (type | Callable[[Node], bool] | None)

• include_self (bool)

• descend (bool)

• siblings (bool)

• ascend (bool)

first_child_matching_class(childclass, start=0, end=9223372036854775807)

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.

Return type:

int | None

Parameters:

• childclass (type[Element] | type[Text] | tuple[type[Element] | type[Text], ...])

• start (int)

• end (int)

first_child_not_matching_class(childclass, start=0, end=9223372036854775807)

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.

Return type:

int | None

Parameters:

• childclass (type[Element] | type[Text] | tuple[type[Element] | type[Text], ...])

• start (int)

• end (int)

get_language_code(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.

Return type:

str

Parameters:

fallback (str)

classmethod is_not_known_attribute(attr)

Return True if attr is NOT defined for all Element instances.

Provisional. May be removed in Docutils 2.0.

Return type:

bool

Parameters:

attr (str)

classmethod is_not_list_attribute(attr)

Returns True if and only if the given attribute is NOT one of the basic list attributes defined for all Elements.

Return type:

bool

Parameters:

attr (str)

known_attributes = ('ids', 'classes', 'names', 'dupnames', 'source')

Alias for common_attributes. Will be removed in Docutils 2.0.

line = None

The line number (1-based) of the beginning of this Node in source.

list_attributes = ('ids', 'classes', 'names', 'dupnames')

Tuple of attributes that are initialized to empty lists.

NOTE: Derived classes should update this value when supporting

additional list attributes.

local_attributes = ('backrefs',)

Obsolete. Will be removed in Docutils 2.0.

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

Return the first node in the iterator returned by findall(), or None if the iterable is empty.

Parameter list is the same as of findall(). Note that include_self defaults to False, though.

Return type:

Node | None

Parameters:

• condition (type | Callable[[Node], bool] | None)

• include_self (bool)

• descend (bool)

• siblings (bool)

• ascend (bool)

note_referenced_by(name=None, id=None)

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

Return type:

None

Parameters:

• name (str | None)

• id (str | None)

parent = None

Back-reference to the Node immediately containing this Node.

pformat(indent='    ', level=0)

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

Override in subclasses.

Return type:

str

Parameters:

• indent (str)

• level (int)

previous_sibling()

Return preceding sibling node or None.

replace(old, new)

Replace one child Node with another child or children.

Return type:

None

replace_attr(attr, value, force=True)

If self[attr] does not exist or force is True or omitted, set self[attr] to value, otherwise do nothing.

Return type:

None

Parameters:

• attr (str)

• value (Any)

• force (bool)

replace_self(new)

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

Provisional: the handling of node attributes will be revised.

Return type:

None

section_hierarchy()

Return the element’s section anchestors.

Return a list of all <section> elements that contain self (including self if it is a <section>) and have a parent node.

List item [i] is the parent <section> of level i+1 (1: section, 2: subsection, 3: subsubsection, …). The length of the list is the element’s section level.

See docutils.parsers.rst.states.RSTState.check_subsection() for a usage example.

Provisional. May be changed or removed without warning.

Return type:

list[section]

source = None

Path or description of the input source which generated this Node.

tagname = None

The element generic identifier.

If None, it is set as an instance attribute to the name of the class.

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

Return list of nodes following self.

For looping, Node.findall() is faster and more memory efficient.

Return type:

list

Parameters:

• condition (type | Callable[[Node], bool] | None)

• include_self (bool)

• descend (bool)

• siblings (bool)

• ascend (bool)

update_all_atts(dict_, update_fun=<function Element.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.

Return type:

None

Parameters:

• dict_ (Mapping[str, Any] | Element)

• update_fun (_UpdateFun)

• replace (bool)

• and_source (bool)

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

Return type:

None

Parameters:

• dict_ (Mapping[str, Any] | Element)

• replace (bool)

• and_source (bool)

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

Return type:

None

Parameters:

• dict_ (Mapping[str, Any] | Element)

• replace (bool)

• and_source (bool)

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

Return type:

None

Parameters:

• dict_ (Mapping[str, Any] | Element)

• replace (bool)

• and_source (bool)

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

Return type:

None

Parameters:

• dict_ (Mapping[str, Any] | Element)

• and_source (bool)

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

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

Provisional.

Return type:

None

Parameters:

dict_ (Mapping[str, Any] | Element)

valid_attributes = ('ids', 'classes', 'names', 'dupnames', 'source')

Tuple of attributes that are valid for elements of this class.

NOTE: Derived classes should update this value when supporting

additional attributes.

validate(recursive=True)

Validate Docutils Document Tree element (“doctree”).

Raise ValidationError if there are violations. If recursive is True, validate also the element’s descendants.

See The Docutils Document Tree for details of the Docutils Document Model.

Provisional (work in progress).

Return type:

None

Parameters:

recursive (bool)

validate_attributes()

Normalize and validate element attributes.

Convert string values to expected datatype. Normalize values.

Raise ValidationError for invalid attributes or attribute values.

Provisional.

Return type:

None

validate_content(model=None, elements=None)

Test compliance of elements with model.

Model:

content model description, default self.content_model,

Elements:

list of doctree elements, default self.children.

Parameters:

• model (_ContentModelTuple | None)

• elements (Sequence | None)

Return type:

list

Return list of children that do not fit in the model or raise ValidationError if the content does not comply with the model.

Provisional.

Return type:

list

Parameters:

• model (_ContentModelTuple | None)

• elements (Sequence | None)

validate_position()

Hook for additional checks of the parent’s content model.

Raise ValidationError, if self is at an invalid position.

Override in subclasses with complex validity constraints. See subtitle.validate_position() and transition.validate_position().

Return type:

None

walk(visitor)

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

This tree traversal supports limited in-place tree modifications. Replacing one node with one or more nodes is OK, as is removing an element. However, if the node removed or replaced occurs after the current node, the old node will still be traversed, and any new nodes will not.

Within visit methods (and depart methods for walkabout()), TreePruningException subclasses may be raised (SkipChildren, SkipSiblings, SkipNode, SkipDeparture).

Parameter visitor: A NodeVisitor object, containing a visit implementation for each Node subclass encountered.

Return true if we should stop the traversal.

Return type:

bool

Parameters:

visitor (NodeVisitor)

walkabout(visitor)

Perform a tree traversal similarly to Node.walk() (which see), except also call the dispatch_departure() method before exiting each node.

Parameter visitor: A NodeVisitor object, containing a visit and depart implementation for each Node subclass encountered.

Return true if we should stop the traversal.

Return type:

bool

Parameters:

visitor (NodeVisitor)

rawsource

The raw text from which this element was constructed.

For informative and debugging purposes. Don’t rely on its value!

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

children

List of child nodes (elements and/or Text).

attributes

Dictionary of attribute {name: value}.