API

Tree

You can call (almost) any method name on the Tree to create a new Node.

class datatree.Tree(*args, **kwargs)

Very top node in a datatree.

The Tree is the top node used to build a datatree.

cdata(text, **attributes)

Add a CDataNode to the current tree.

Note

CData tags are ignored by some of the renderers such as json and dict. Consult the documentation to find out the behaviour.

Parameters:

• text – Text value of the CDATA tag.
• attributes – Additional attributes to be added to the tag.

Returns:

The created CDataNode.

comment(text)

Adds a comment to the node.

Note

Comments are ignored by some of the renderers such as json and dict. Consult the documentation to find out the behaviour.

Parameters:text – Text content of the comment.

declare(name, *attributes)

Add an xml declaration to the datatree.

Note

Declarations are ignored by some of the renderers such as json and dict. Consult the documentation to find out the behaviour.

Warning

This functionality is pretty limited for the time being, hopefully the API for this will become more clear with time.

Parameters:

• name – Name of the declaration node.
• attributes – Extra attributes to be added. Strings will be added as quoted strings. Symbols will be added as unquoted strings. Import the __ object and use it like this: __.SomeValue to add a symbol.

instruct(name='xml', **attributes)

Add an xml processing instruction.

Note

Instructions are ignored by some of the renderers such as json and dict. Consult the documentation to find out the behaviour.

Parameters:

• name – Name of the instruction node. A value of xml will create the instruction <?xml ?>.
• attributes – Any extra attributes for the instruction.

node(name, value=None, **attributes)

Creates and adds Node object to the current tree.

Parameters:

• name – The name identifier for the node..
• value – The value of this node. Note that this will be converted to a string usually during rendering. Default is None which generally means it is ignored during rendering.
• attributes – The key value pairs that will be used as the attributes for the node.

Returns:

The created Node.

static register_renderer(klass)

Register a renderer class with the datatree rendering system.

Parameters:klass – Either a string with the fully qualified name of the renderer class to register, or the actual class itself. The name will be read from the class.

render(renderer='xml', as_root=False, **options)

Render the datatree using the provided renderer.

Parameters:

• renderer – The name of the renderer to use. You may add more renderers by using the register_renderer method.
• as_root – If True, the tree will be rendered from this node down, otherwise rendering will happen from the tree root.
• options – Key value pairs of options that will be passed to the renderer.

to_string(level=0)

Create an ugly representation of the datatree from this node down.

Warning

This is included as a debug aid and is not good for much else. The output is messy and inconsistent.

Node

Node is not instantiated directly, but is created for every node added to the Tree.

class datatree.tree.Node(node_name='root', node_value=None, **attributes)

A node is able to be instantiated directly and added to any Vertex.

cdata(text, **attributes)

Add a CDataNode to the current tree.

Note

CData tags are ignored by some of the renderers such as json and dict. Consult the documentation to find out the behaviour.

Parameters:

• text – Text value of the CDATA tag.
• attributes – Additional attributes to be added to the tag.

Returns:

The created CDataNode.

comment(text)

Adds a comment to the node.

Note

Comments are ignored by some of the renderers such as json and dict. Consult the documentation to find out the behaviour.

Parameters:text – Text content of the comment.

node(name, value=None, **attributes)

Creates and adds Node object to the current tree.

Parameters:

• name – The name identifier for the node..
• value – The value of this node. Note that this will be converted to a string usually during rendering. Default is None which generally means it is ignored during rendering.
• attributes – The key value pairs that will be used as the attributes for the node.

Returns:

The created Node.

static register_renderer(klass)

Register a renderer class with the datatree rendering system.

Parameters:klass – Either a string with the fully qualified name of the renderer class to register, or the actual class itself. The name will be read from the class.

render(renderer='xml', as_root=False, **options)

Render the datatree using the provided renderer.

Parameters:

• renderer – The name of the renderer to use. You may add more renderers by using the register_renderer method.
• as_root – If True, the tree will be rendered from this node down, otherwise rendering will happen from the tree root.
• options – Key value pairs of options that will be passed to the renderer.

to_string(level=0)

Create an ugly representation of the datatree from this node down.

Warning

This is included as a debug aid and is not good for much else. The output is messy and inconsistent.

Renderers

The renderers are responsible for converting the datatree into a usable format. Usually this format is a string, but sometimes other formats are used.

The examples in this section use this datatree:

from datatree import Tree, Node

tree = Tree()
with tree.node("author") as author:
    author.node('name', 'Terry Pratchett')
    author.node('genre', 'Fantasy/Comedy')
    author.comment("Only 2 books listed")
    with author.node('novels', count=2) as novels:
        novels.node('novel', 'Small Gods', year=1992)
        novels.node('novel', 'The Fifth Elephant', year=1999)
        novels.node("novel", "Guards! Guards!", year=1989)

XmlRenderer

Outputs the tree as an xml string. It is available under the alias 'xml'.

Options

Name	Description	Default
pretty	When True, Outputs the xml document with pretty formatting.	False
indent	Used with pretty formatting. It is the string that will be used to indent each level.	'    '

Example Output

tree('xml', pretty=True)

Or even shorter:

tree(pretty=True)

<author>
    <name>Terry Pratchett</name>
    <genre>Fantasy/Comedy</genre>
    <!-- Only 2 books listed -->
    <novels count="2">
        <novel year="1992">Small Gods</novel>
        <novel year="1999">The Fifth Elephant</novel>
        <novel year="1989">Guards! Guards!</novel>
    </novels>
</author>

JsonRenderer

Outputs the tree as json string using the python json module. It is available under the alias 'json', 'jsn' or 'js'.

Options

Name	Description	Default
pretty	Outputs the json document with pretty formatting.	False
sort_keys	Sorts the keys in the json document.	False

Example Output

tree('json', pretty=True)

{
    "author": {
        "genre": "Fantasy/Comedy", 
        "name": "Terry Pratchett", 
        "novels": [
            "Small Gods", 
            "The Fifth Elephant", 
            "Guards! Guards!"
        ]
    }
}

YamlRenderer

Outputs the tree as yaml string using the PyYAML package (which must be installed). It is available under the alias 'yaml' or 'yml'.

Options

Name	Description	Default
None

Example Output

tree('yaml')

author:
  genre: Fantasy/Comedy
  name: Terry Pratchett
  novels: [Small Gods, The Fifth Elephant, Guards! Guards!]

DictRenderer

Outputs the tree as python dict. It is available under the alias 'dict' and 'dictionary'.

Options

Name	Description	Default
pretty_string	When True, outputs the dict as a string with pretty formatting.	False
allow_node_loss	Determines if a duplicate node name will result in a node loss due to duplicate keys in the dict.	False

Example Output

tree('dict', pretty_string=True)

{'author': {'genre': 'Fantasy/Comedy',
            'name': 'Terry Pratchett',
            'novels': ['Small Gods', 'The Fifth Elephant', 'Guards! Guards!']}}

Duplicate Node Names

While xml handles duplicate nodes just fine, python dicts and json for that matter do not allow duplicates. To handle this the DictRenderer will attempt to group nodes with the same name into a sub dictionary. This is why in the above example there is only one key for “novels”.

Implementing a Renderer

You can implement your own renderer. Just look at the source for one of the existing renderers and implement the same methods, and then register your plugin with the register_renderer() method.