docutils.nodes.Node

class documentation

class Node(object):

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

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	`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	`pformat`	Return an indented pseudo-XML representation, for test purposes.
Method	`previous_sibling`	Return preceding sibling node or `None`.
Method	`setup_child`	Undocumented
Method	`traverse`	Return list of nodes following `self`.
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	`_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

def __bool__(self):

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.

def __str__(self):

Undocumented

def asdom(self, dom=None):

overridden in docutils.nodes.document

Return a DOM fragment representation of this Node.

def astext(self):

overridden in docutils.nodes.Element, docutils.nodes.Text

Return a string representation of this Node.

def copy(self):

overridden in docutils.nodes.Element, docutils.nodes.Text

Return a copy of self.

def deepcopy(self):

overridden in docutils.nodes.Element, docutils.nodes.Text

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

@document.setter
def document(self, value):

Undocumented

def findall(self, 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 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.

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>]

def next_node(self, 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 traverse. Note that include_self defaults to False, though.

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

overridden in docutils.nodes.Element, docutils.nodes.Text

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

Override in subclasses.

def previous_sibling(self):

Return preceding sibling node or None.

def setup_child(self, child):

Undocumented

def traverse(self, 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.

def walk(self, 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.

def walkabout(self, 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.

line =

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

parent =

Back-reference to the Node immediately containing this Node.

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.

def _fast_findall(self, cls):

Return iterator that only supports instance checks.

def _superfast_findall(self):

Return iterator that doesn't check for a condition.

_document =

overridden in docutils.nodes.document

Undocumented