api.rst

API

treebeard.models

Node

Node

This is the base class that defines the API of all tree models in this library:

• treebeard.mp_tree.MP_Node (materialized path)
• treebeard.ns_tree.NS_Node (nested sets)
• treebeard.al_tree.AL_Node (adjacency list)

Warning

Please be aware of the caveats when using this library.

Node.add_root

Example:

MyNode.add_root(numval=1, strval='abcd')

Or, to pass in an existing instance:

new_node = MyNode(numval=1, strval='abcd')
MyNode.add_root(instance=new_node)

add_child

Example:

node.add_child(numval=1, strval='abcd')

Or, to pass in an existing instance:

new_node = MyNode(numval=1, strval='abcd')
node.add_child(instance=new_node)

add_sibling

Examples:

node.add_sibling('sorted-sibling', numval=1, strval='abc')

Or, to pass in an existing instance:

new_node = MyNode(numval=1, strval='abc')
node.add_sibling('sorted-sibling', instance=new_node)

delete

Note

Call our queryset's delete to handle children removal. Subclasses will handle extra maintenance.

get_tree

get_depth

Example:

node.get_depth()

get_ancestors

Example:

node.get_ancestors()

get_children

Example:

node.get_children()

get_children_count

Example:

node.get_children_count()

get_descendants

Example:

node.get_descendants()

get_descendant_count

Example:

node.get_descendant_count()

get_first_child

Example:

node.get_first_child()

get_last_child

Example:

node.get_last_child()

get_first_sibling

Example:

node.get_first_sibling()

get_last_sibling

Example:

node.get_last_sibling()

get_prev_sibling

Example:

node.get_prev_sibling()

get_next_sibling

Example:

node.get_next_sibling()

get_parent

Example:

node.get_parent()

get_root

Example:

node.get_root()

get_siblings

Example:

node.get_siblings()

is_child_of

Example:

node.is_child_of(node2)

is_descendant_of

Example:

node.is_descendant_of(node2)

is_sibling_of

Example:

node.is_sibling_of(node2)

is_root

Example:

node.is_root()

is_leaf

Example:

node.is_leaf()

move

Note

The node can be moved under another root node.

Examples:

node.move(node2, 'sorted-child')
node.move(node2, 'prev-sibling')

save

get_first_root_node

Example:

MyNodeModel.get_first_root_node()

get_last_root_node

Example:

MyNodeModel.get_last_root_node()

get_root_nodes

Example:

MyNodeModel.get_root_nodes()

load_bulk

Note

Any internal data that you may have stored in your nodes' data (path, depth) will be ignored.

Note

If your node model has a ForeignKey this method will try to load the related object before loading the data. If the related object doesn't exist it won't load anything and will raise a DoesNotExist exception. This is done because the dump_data method uses integers to dump related objects.

Note

If your node model has node_order_by enabled, it will take precedence over the order in the structure.

Example:

data = [{'data':{'desc':'1'}},
        {'data':{'desc':'2'}, 'children':[
          {'data':{'desc':'21'}},
          {'data':{'desc':'22'}},
          {'data':{'desc':'23'}, 'children':[
            {'data':{'desc':'231'}},
          ]},
          {'data':{'desc':'24'}},
        ]},
        {'data':{'desc':'3'}},
        {'data':{'desc':'4'}, 'children':[
          {'data':{'desc':'41'}},
        ]},
]
# parent = None
MyNodeModel.load_bulk(data, None)

Will create:

load_bulk_digraph

"1"; "2"; "2" -> "21"; "2" -> "22"; "2" -> "23" -> "231"; "2" -> "24"; "3"; "4"; "4" -> "41";

dump_bulk

Example:

tree = MyNodeModel.dump_bulk()
branch = MyNodeModel.dump_bulk(node_obj)

find_problems

fix_tree

get_descendants_group_count

Example:

# get a list of the root nodes
root_nodes = MyModel.get_descendants_group_count()

for node in root_nodes:
    print '%s by %s (%d replies)' % (node.comment, node.author,
                                     node.descendants_count)

get_annotated_list

Example:

annotated_list = MyModel.get_annotated_list()

With data:

get_annotated_list_digraph

"a"; "a" -> "ab"; "ab" -> "aba"; "ab" -> "abb"; "ab" -> "abc"; "a" -> "ac";

Will return:

[
    (a,     {'open':True,  'close':[],    'level': 0})
    (ab,    {'open':True,  'close':[],    'level': 1})
    (aba,   {'open':True,  'close':[],    'level': 2})
    (abb,   {'open':False, 'close':[],    'level': 2})
    (abc,   {'open':False, 'close':[0,1], 'level': 2})
    (ac,    {'open':False, 'close':[0],   'level': 1})
]

This can be used with a template like:

{% for item, info in annotated_list %}
    {% if info.open %}
        <ul><li>
    {% else %}
        </li><li>
    {% endif %}

    {{ item }}

    {% for close in info.close %}
        </li></ul>
    {% endfor %}
{% endfor %}

Note

This method was contributed originally by Alexey Kinyov, using an idea borrowed from django-mptt.

1.55

get_annotated_list_qs

get_database_vendor

Example:

MyNodeModel.get_database_vendor("write")

1.61