docutils.nodes.Node

class documentation

class Node(object): (source)

Known subclasses: docutils.nodes.Element, docutils.nodes.Text

View In Hierarchy

Abstract base class of nodes in a document tree.
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 astext Return a string representation of this Node.
Method copy Return a copy of self.
Method deepcopy Return a deep copy of self (also copying children).
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 pformat Return an indented pseudo-XML representation, for test purposes.
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
def __bool__(self): (source)

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. Use None to represent a boolean false value.

def __str__(self): (source)

Undocumented

def asdom(self, dom=None): (source)
overridden in docutils.nodes.document
Return a DOM fragment representation of this Node.
def astext(self): (source)
overridden in docutils.nodes.Element, docutils.nodes.Text
Return a string representation of this Node.
def copy(self): (source)
overridden in docutils.nodes.Element, docutils.nodes.Text
Return a copy of self.
def deepcopy(self): (source)
overridden in docutils.nodes.Element, docutils.nodes.Text
Return a deep copy of self (also copying children).
@document.setter
def document(self, value): (source)

Undocumented

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

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

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

def pformat(self, indent=' ', level=0): (source)
overridden in docutils.nodes.Element, docutils.nodes.Text

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

Override in subclasses.

def setup_child(self, child): (source)

Undocumented

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

Return an iterable containing

  • self (if include_self is true)
  • all descendants in tree traversal order (if descend is true)
  • all siblings (if siblings is true) and their descendants (if also descend is true)
  • the 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 iterable contains only nodes for which condition(node) is true. If condition is a node class cls, it is equivalent to a function consisting of return isinstance(node, cls).

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

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 list(emphasis.traverse()) equals

[<emphasis>, <strong>, <#text: Foo>, <#text: Bar>]

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

[<strong>, <#text: Foo>, <#text: Bar>, <reference>, <#text: Baz>]
def walk(self, visitor): (source)

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.

def walkabout(self, visitor): (source)

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.

line = (source)
The line number (1-based) of the beginning of this Node in source.
parent = (source)
Back-reference to the Node immediately containing this Node.
source = (source)
Path or description of the input source which generated this Node.
@property
document = (source)
Return the document node at the root of the tree containing this Node.
def _all_traverse(self): (source)
Return iterator that doesn't check for a condition.
def _fast_traverse(self, cls): (source)
Return iterator that only supports instance checks.
def _traverse(self, condition=None, include_self=True, descend=True, siblings=False, ascend=False): (source)
Return iterator over nodes following self. See traverse().
_document = (source)
overridden in docutils.nodes.document

Undocumented