`mptt.managers`¶

A custom manager for working with trees of objects.

class mptt.managers.TreeManager¶

A manager for working with trees of objects.

add_related_count(queryset, rel_model, rel_field, count_attr, cumulative=False, extra_filters={})¶

Adds a related item count to a given QuerySet using its extra method, for a Model class which has a relation to this Manager’s Model class.

Arguments:

rel_model: A Model class which has a relation to this Manager`’s Model class.
rel_field: The name of the field in rel_model which holds the relation.
count_attr: The name of an attribute which should be added to each item in this QuerySet, containing a count of how many instances of rel_model are related to it through rel_field.
cumulative: If True, the count will be for each item and all of its descendants, otherwise it will be for each item itself.
extra_filters: Dict with aditional parameters filtering the related queryset.

build_tree_nodes(data, target=None, position='last-child')¶

Load a tree from a nested dictionary for bulk insert, returning an array of records. Use to efficiently insert many nodes within a tree without an expensive rebuild.

records = MyModel.objects.build_tree_nodes({
    'id': 7,
    'name': 'parent',
    'children': [
        {
            'id': 8,
            'parent_id': 7,
            'name': 'child',
            'children': [
                {
                    'id': 9,
                    'parent_id': 8,
                    'name': 'grandchild',
                }
            ]
        }
    ]
})
MyModel.objects.bulk_create(records)

contribute_to_class(model, name)¶

delay_mptt_updates()¶

Context manager. Delays mptt updates until the end of a block of bulk processing.

NOTE that this context manager causes inconsistencies! MPTT model methods are not guaranteed to return the correct results until the end of the context block.

When to use this method:

If used correctly, this method can be used to speed up bulk updates. This is best for updates in a localised area of the db table, especially if all the updates happen in a single tree and the rest of the forest is left untouched. No subsequent rebuild is necessary.

delay_mptt_updates does a partial rebuild of the modified trees (not the whole table). If used indiscriminately, this can actually be much slower than just letting the updates occur when they’re required.

The worst case occurs when every tree in the table is modified just once. That results in a full rebuild of the table, which can be very slow.

If your updates will modify most of the trees in the table (not a small number of trees), you should consider using TreeManager.disable_mptt_updates, as it does much fewer queries.

Transactions:

This doesn’t enforce any transactional behavior. You should wrap this in a transaction to ensure database consistency.

Exceptions:

If an exception occurs before the processing of the block, delayed updates will not be applied.

Usage:

with transaction.atomic():
    with MyNode.objects.delay_mptt_updates():
        ## bulk updates.

disable_mptt_updates()¶

Context manager. Disables mptt updates.

NOTE that this context manager causes inconsistencies! MPTT model methods are not guaranteed to return the correct results.

When to use this method:

If used correctly, this method can be used to speed up bulk updates.

This doesn’t do anything clever. It will mess up your tree. You should follow this method with a call to TreeManager.rebuild() to ensure your tree stays sane, and you should wrap both calls in a transaction.

This is best for updates that span a large part of the table. If you are doing localised changes (one tree, or a few trees) consider using delay_mptt_updates.

If you are making only minor changes to your tree, just let the updates happen.

Transactions:

This doesn’t enforce any transactional behavior. You should wrap this in a transaction to ensure database consistency.

If updates are already disabled on the model, this is a noop.

Usage:

with transaction.atomic():
    with MyNode.objects.disable_mptt_updates():
        ## bulk updates.
    MyNode.objects.rebuild()

get_queryset(*args, **kwargs)¶: Ensures that this manager always returns nodes in tree order.

get_queryset_ancestors(queryset, include_self=False)¶

Returns a queryset containing the ancestors of all nodes in the given queryset.

If include_self=True, nodes in queryset will also be included in the result.

get_queryset_descendants(queryset, include_self=False)¶

Returns a queryset containing the descendants of all nodes in the given queryset.

If include_self=True, nodes in queryset will also be included in the result.

insert_node(node, target, position='last-child', save=False, allow_existing_pk=False, refresh_target=True)¶

Sets up the tree state for node (which has not yet been inserted into in the database) so it will be positioned relative to a given target node as specified by position (when appropriate) it is inserted, with any necessary space already having been made for it.

A target of None indicates that node should be the last root node.

If save is True, node’s save() method will be called before it is returned.

NOTE: This is a low-level method; it does NOT respect MPTTMeta.order_insertion_by. In most cases you should just set the node’s parent and let mptt call this during save.

left_attr¶

level_attr¶

move_node(node, target, position='last-child')¶

Moves node relative to a given target node as specified by position (when appropriate), by examining both nodes and calling the appropriate method to perform the move.

A target of None indicates that node should be turned into a root node.

Valid values for position are 'first-child', 'last-child', 'left' or 'right'.

node will be modified to reflect its new tree state in the database.

This method explicitly checks for node being made a sibling of a root node, as this is a special case due to our use of tree ids to order root nodes.

NOTE: This is a low-level method; it does NOT respect MPTTMeta.order_insertion_by. In most cases you should just move the node yourself by setting node.parent.

parent_attr¶

partial_rebuild(tree_id)¶: Partially rebuilds a tree i.e. It rebuilds only the tree with given tree_id in database table using parent link.

rebuild()¶: Rebuilds all trees in the database table using parent link.

right_attr¶

root_node(tree_id)¶: Returns the root node of the tree with the given id.

root_nodes()¶: Creates a QuerySet containing root nodes.

tree_id_attr¶

mptt.managers¶

`mptt.managers`¶