Utilities for working with trees

Contents

• Utilities for working with trees

  • List/tree utilities

    • previous_current_next()

    • tree_item_iterator()

    • drilldown_tree_for_node()

    • get_cached_trees()

List/tree utilities

The mptt.utils module contains the following functions for working with and creating lists of model instances which represent trees.

previous_current_next()

From http://www.wordaligned.org/articles/zippy-triples-served-with-python

Creates an iterator which returns (previous, current, next) triples, with None filling in when there is no previous or next available.

This function is useful if you want to step through a tree one item at a time and you need to refer to the previous or next item in the tree. It is used in the implementation of tree_item_iterator().

Required arguments

items

A list or other iterable item.

tree_item_iterator()

This function is used to implement the tree_info template filter, yielding two-tuples of (tree item, tree structure information dict).

See the tree_info documentation for more information.

Required arguments

items

A list or iterable of model instances which represent a tree.

Optional arguments

ancestors

Boolean. If True, a list of unicode representations of the ancestors of the current node, in descending order (root node first, immediate parent last), will be added to the tree structure information dict` under the key ``'ancestors'.

drilldown_tree_for_node()

This function is used in the implementation of the drilldown_tree_for_node template tag.

It creates an iterable which yields model instances representing a drilldown tree for a given node.

A drilldown tree consists of a node’s ancestors, itself and its immediate children or all descendants, all in tree order.

Optional arguments may be given to specify details of a relationship between the given node’s class and another model class, for the purpose of adding related item counts to the node’s children.

Required arguments

node

A model instance which represents a node in a tree.

Optional arguments

rel_cls

A model class which has a relationship to the node’s class.

rel_field

The name of the field in rel_cls which holds the relationship to the node’s class.

count_attr

The name of an attribute which should be added to each child of the node in the drilldown tree (if any), containing a count of how many instances of rel_cls are related to it through rel_field.

cumulative

If True, the count will be for items related to the child node and all of its descendants. Defaults to False.

get_cached_trees()

Takes a list/queryset of model objects in MPTT left (depth-first) order and caches the children and parent on each node. This allows up and down traversal through the tree without the need for further queries. Use cases include using a recursively included template or arbitrarily traversing trees.

Returns a list of top-level nodes. If a single tree was provided in its entirety, the list will of course consist of just the tree’s root node.

Aliases to this function are also available:

mptt.templatetags.mptt_tag.cache_tree_children

Use for recursive rendering in templates.

mptt.querysets.TreeQuerySet.get_cached_trees

Useful for chaining with queries; e.g., Node.objects.filter(**kwargs).get_cached_trees()

Required arguments

queryset

An iterable that consists of all nodes which are to be cached.