ReSTDocument

class documentationtools.ReSTDocument(children=None, name=None)

A ReST document tree.

>>> document = documentationtools.ReSTDocument()
>>> document
ReSTDocument()
>>> document.append(documentationtools.ReSTHeading(
...     level=0, text='Hello World!'))
>>> document.append(documentationtools.ReSTParagraph(
...     text='blah blah blah'))
>>> toc = documentationtools.ReSTTOCDirective()
>>> toc.append('foo/bar')
>>> toc.append('bar/baz')
>>> toc.append('quux')
>>> document.append(toc)
>>> document
ReSTDocument(
    children=(
        ReSTHeading(
            level=0,
            text='Hello World!'
            ),
        ReSTParagraph(
            text='blah blah blah',
            wrap=True
            ),
        ReSTTOCDirective(
            children=(
                ReSTTOCItem(
                    text='foo/bar'
                    ),
                ReSTTOCItem(
                    text='bar/baz'
                    ),
                ReSTTOCItem(
                    text='quux'
                    ),
                ),
            directive='toctree'
            ),
        )
    )
>>> print(document.rest_format)
############
Hello World!
############

blah blah blah

.. toctree::

   foo/bar
   bar/baz
   quux

Lineage

digraph InheritanceGraph { graph [background=transparent, bgcolor=transparent, color=lightslategrey, fontname=Arial, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, root="__builtin__.object", splines=spline, style="dotted, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=12, penwidth=2, style="filled, rounded"]; edge [color=lightsteelblue2, penwidth=2]; subgraph cluster_abctools { graph [label=abctools]; "abjad.tools.abctools.AbjadObject.AbjadObject" [color=1, group=0, label=AbjadObject, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" [color=1, group=0, label=AbstractBase, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" -> "abjad.tools.abctools.AbjadObject.AbjadObject"; } subgraph cluster_datastructuretools { graph [label=datastructuretools]; "abjad.tools.datastructuretools.TreeContainer.TreeContainer" [color=3, group=2, label=TreeContainer, shape=box]; "abjad.tools.datastructuretools.TreeNode.TreeNode" [color=3, group=2, label=TreeNode, shape=box]; "abjad.tools.datastructuretools.TreeNode.TreeNode" -> "abjad.tools.datastructuretools.TreeContainer.TreeContainer"; } subgraph cluster_documentationtools { graph [label=documentationtools]; "abjad.tools.documentationtools.ReSTDocument.ReSTDocument" [color=black, fontcolor=white, group=3, label=<<B>ReSTDocument</B>>, shape=box, style="filled, rounded"]; } subgraph cluster_builtins { graph [label=builtins]; "builtins.object" [color=2, group=1, label=object, shape=box]; } "abjad.tools.abctools.AbjadObject.AbjadObject" -> "abjad.tools.datastructuretools.TreeNode.TreeNode"; "abjad.tools.datastructuretools.TreeContainer.TreeContainer" -> "abjad.tools.documentationtools.ReSTDocument.ReSTDocument"; "builtins.object" -> "abjad.tools.abctools.AbjadObject.AbstractBase"; }

Attribute summary

append(node) Appends node to tree container.
children Children of tree container.
depth The depth of a node in a rhythm-tree structure.
depthwise_inventory A dictionary of all nodes in a rhythm-tree, organized by their depth relative the root node.
extend(expr) Extendes expr against tree container.
graph_order Graph order of tree node.
improper_parentage The improper parentage of a node in a rhythm-tree, being the sequence of node beginning with itself and ending with the root node of the tree.
index(node) Indexes node in tree container.
insert(i, node) Insert node in tree container at index i.
leaves Leaves of tree container.
name Named of tree node.
node_class Node class of ReST document.
nodes The collection of tree nodes produced by iterating tree container depth-first.
parent Parent of tree node.
pop([i]) Pops node i from tree container.
proper_parentage The proper parentage of a node in a rhythm-tree, being the sequence of node beginning with the node’s immediate parent and ending with the root node of the tree.
remove(node) Remove node from tree container.
rest_format ReST format of ReST document.
root The root node of the tree: that node in the tree which has no parent.
__contains__(expr) True if expr is in container.
__copy__() Copies tree node.
__delitem__(i) Deletes node i in tree container.
__eq__(expr) Is true when ID of expr equals ID of Abjad object.
__format__([format_specification]) Formats Abjad object.
__getitem__(i) Gets node i in tree container.
__hash__() Hashes Abjad object.
__iter__() Iterates tree container.
__len__() Returns nonnegative integer number of nodes in container.
__ne__(expr) Is true when Abjad object does not equal expr.
__repr__() Gets interpreter representation of Abjad object.
__setitem__(i, expr) Sets expr in self at nonnegative integer index i, or set expr in self at slice i.

Read-only properties

(TreeContainer).children

Children of tree container.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeContainer()
>>> c = datastructuretools.TreeNode()
>>> d = datastructuretools.TreeNode()
>>> e = datastructuretools.TreeContainer()
>>> a.extend([b, c])
>>> b.extend([d, e])
>>> a.children == (b, c)
True
>>> b.children == (d, e)
True
>>> e.children == ()
True

Returns tuple of tree nodes.

(TreeNode).depth

The depth of a node in a rhythm-tree structure.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeContainer()
>>> c = datastructuretools.TreeNode()
>>> a.append(b)
>>> b.append(c)
>>> a.depth
0
>>> a[0].depth
1
>>> a[0][0].depth
2

Returns int.

(TreeNode).depthwise_inventory

A dictionary of all nodes in a rhythm-tree, organized by their depth relative the root node.

>>> a = datastructuretools.TreeContainer(name='a')
>>> b = datastructuretools.TreeContainer(name='b')
>>> c = datastructuretools.TreeContainer(name='c')
>>> d = datastructuretools.TreeContainer(name='d')
>>> e = datastructuretools.TreeContainer(name='e')
>>> f = datastructuretools.TreeContainer(name='f')
>>> g = datastructuretools.TreeContainer(name='g')
>>> a.extend([b, c])
>>> b.extend([d, e])
>>> c.extend([f, g])
>>> inventory = a.depthwise_inventory
>>> for depth in sorted(inventory):
...     print('DEPTH: {}'.format(depth))
...     for node in inventory[depth]:
...         print(node.name)
...
DEPTH: 0
a
DEPTH: 1
b
c
DEPTH: 2
d
e
f
g

Returns dictionary.

(TreeNode).graph_order

Graph order of tree node.

Returns tuple.

(TreeNode).improper_parentage

The improper parentage of a node in a rhythm-tree, being the sequence of node beginning with itself and ending with the root node of the tree.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeContainer()
>>> c = datastructuretools.TreeNode()
>>> a.append(b)
>>> b.append(c)
>>> a.improper_parentage == (a,)
True
>>> b.improper_parentage == (b, a)
True
>>> c.improper_parentage == (c, b, a)
True

Returns tuple of tree nodes.

(TreeContainer).leaves

Leaves of tree container.

>>> a = datastructuretools.TreeContainer(name='a')
>>> b = datastructuretools.TreeContainer(name='b')
>>> c = datastructuretools.TreeNode(name='c')
>>> d = datastructuretools.TreeNode(name='d')
>>> e = datastructuretools.TreeContainer(name='e')
>>> a.extend([b, c])
>>> b.extend([d, e])
>>> for leaf in a.leaves:
...     print(leaf.name)
...
d
e
c

Returns tuple.

ReSTDocument.node_class

Node class of ReST document.

(TreeContainer).nodes

The collection of tree nodes produced by iterating tree container depth-first.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeContainer()
>>> c = datastructuretools.TreeNode()
>>> d = datastructuretools.TreeNode()
>>> e = datastructuretools.TreeContainer()
>>> a.extend([b, c])
>>> b.extend([d, e])
>>> nodes = a.nodes
>>> len(nodes)
5
>>> nodes[0] is a
True
>>> nodes[1] is b
True
>>> nodes[2] is d
True
>>> nodes[3] is e
True
>>> nodes[4] is c
True

Returns tuple.

(TreeNode).parent

Parent of tree node.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeContainer()
>>> c = datastructuretools.TreeNode()
>>> a.append(b)
>>> b.append(c)
>>> a.parent is None
True
>>> b.parent is a
True
>>> c.parent is b
True

Returns tree node.

(TreeNode).proper_parentage

The proper parentage of a node in a rhythm-tree, being the sequence of node beginning with the node’s immediate parent and ending with the root node of the tree.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeContainer()
>>> c = datastructuretools.TreeNode()
>>> a.append(b)
>>> b.append(c)
>>> a.proper_parentage == ()
True
>>> b.proper_parentage == (a,)
True
>>> c.proper_parentage == (b, a)
True

Returns tuple of tree nodes.

ReSTDocument.rest_format

ReST format of ReST document.

(TreeNode).root

The root node of the tree: that node in the tree which has no parent.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeContainer()
>>> c = datastructuretools.TreeNode()
>>> a.append(b)
>>> b.append(c)
>>> a.root is a
True
>>> b.root is a
True
>>> c.root is a
True

Returns tree node.

Read/write properties

(TreeNode).name

Named of tree node.

Returns string.

Methods

(TreeContainer).append(node)

Appends node to tree container.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeNode()
>>> c = datastructuretools.TreeNode()
>>> a
TreeContainer()
>>> a.append(b)
>>> a
TreeContainer(
    children=(
        TreeNode(),
        )
    )
>>> a.append(c)
>>> a
TreeContainer(
    children=(
        TreeNode(),
        TreeNode(),
        )
    )

Returns none.

(TreeContainer).extend(expr)

Extendes expr against tree container.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeNode()
>>> c = datastructuretools.TreeNode()
>>> a
TreeContainer()
>>> a.extend([b, c])
>>> a
TreeContainer(
    children=(
        TreeNode(),
        TreeNode(),
        )
    )

Returns none.

(TreeContainer).index(node)

Indexes node in tree container.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeNode()
>>> c = datastructuretools.TreeNode()
>>> a.extend([b, c])
>>> a.index(b)
0
>>> a.index(c)
1

Returns nonnegative integer.

(TreeContainer).insert(i, node)

Insert node in tree container at index i.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeNode()
>>> c = datastructuretools.TreeNode()
>>> d = datastructuretools.TreeNode()
>>> a.extend([b, c])
>>> a
TreeContainer(
    children=(
        TreeNode(),
        TreeNode(),
        )
    )
>>> a.insert(1, d)
>>> a
TreeContainer(
    children=(
        TreeNode(),
        TreeNode(),
        TreeNode(),
        )
    )

Return None.

(TreeContainer).pop(i=-1)

Pops node i from tree container.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeNode()
>>> c = datastructuretools.TreeNode()
>>> a.extend([b, c])
>>> a
TreeContainer(
    children=(
        TreeNode(),
        TreeNode(),
        )
    )
>>> node = a.pop()
>>> node == c
True
>>> a
TreeContainer(
    children=(
        TreeNode(),
        )
    )

Returns node.

(TreeContainer).remove(node)

Remove node from tree container.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeNode()
>>> c = datastructuretools.TreeNode()
>>> a.extend([b, c])
>>> a
TreeContainer(
    children=(
        TreeNode(),
        TreeNode(),
        )
    )
>>> a.remove(b)
>>> a
TreeContainer(
    children=(
        TreeNode(),
        )
    )

Returns none.

Special methods

(TreeContainer).__contains__(expr)

True if expr is in container. Otherwise false:

>>> container = datastructuretools.TreeContainer()
>>> a = datastructuretools.TreeNode()
>>> b = datastructuretools.TreeNode()
>>> container.append(a)
>>> a in container
True
>>> b in container
False

Returns true or false.

(TreeNode).__copy__()

Copies tree node.

(TreeContainer).__delitem__(i)

Deletes node i in tree container.

>>> container = datastructuretools.TreeContainer()
>>> leaf = datastructuretools.TreeNode()
>>> container.append(leaf)
>>> container.children == (leaf,)
True
>>> leaf.parent is container
True
>>> del(container[0])
>>> container.children == ()
True
>>> leaf.parent is None
True

Return None.

(AbjadObject).__eq__(expr)

Is true when ID of expr equals ID of Abjad object. Otherwise false.

Returns true or false.

(AbjadObject).__format__(format_specification='')

Formats Abjad object.

Set format_specification to ‘’ or ‘storage’. Interprets ‘’ equal to ‘storage’.

Returns string.

(TreeContainer).__getitem__(i)

Gets node i in tree container.

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeNode()
>>> c = datastructuretools.TreeContainer()
>>> d = datastructuretools.TreeNode()
>>> e = datastructuretools.TreeNode()
>>> f = datastructuretools.TreeNode()
>>> a.extend([b, c, f])
>>> c.extend([d, e])
>>> a[0] is b
True
>>> a[1] is c
True
>>> a[2] is f
True

If i is a string, the container will attempt to return the single child node, at any depth, whose name matches i:

>>> foo = datastructuretools.TreeContainer(name='foo')
>>> bar = datastructuretools.TreeContainer(name='bar')
>>> baz = datastructuretools.TreeNode(name='baz')
>>> quux = datastructuretools.TreeNode(name='quux')
>>> foo.append(bar)
>>> bar.extend([baz, quux])
>>> foo['bar'] is bar
True
>>> foo['baz'] is baz
True
>>> foo['quux'] is quux
True

Return TreeNode instance.

(AbjadObject).__hash__()

Hashes Abjad object.

Required to be explicitly redefined on Python 3 if __eq__ changes.

Returns integer.

(TreeContainer).__iter__()

Iterates tree container.

Yields children of tree container.

(TreeContainer).__len__()

Returns nonnegative integer number of nodes in container.

(AbjadObject).__ne__(expr)

Is true when Abjad object does not equal expr. Otherwise false.

Returns true or false.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.

(TreeContainer).__setitem__(i, expr)

Sets expr in self at nonnegative integer index i, or set expr in self at slice i. Replace contents of self[i] with expr. Attach parentage to contents of expr, and detach parentage of any replaced nodes:

>>> a = datastructuretools.TreeContainer()
>>> b = datastructuretools.TreeNode()
>>> c = datastructuretools.TreeNode()
>>> a.append(b)
>>> b.parent is a
True
>>> a.children == (b,)
True
>>> a[0] = c
>>> c.parent is a
True
>>> b.parent is None
True
>>> a.children == (c,)
True

Returns none.