
"mptt.managers"
***************

A custom manager for working with trees of objects.

class class mptt.managers.TreeManager

   A manager for working with trees of objects.

   add_related_count(queryset, rel_model, rel_field, count_attr, cumulative=False)

      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.

   delay_mptt_updates(*args, **kwds)

      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.commit_on_success():
             with MyNode.objects.delay_mptt_updates():
                 ## bulk updates.

   disable_mptt_updates(*args, **kwds)

      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 (1 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.commit_on_success():
             with MyNode.objects.disable_mptt_updates():
                 ## bulk updates.
             MyNode.objects.rebuild()

   get_query_set()

      Returns a "QuerySet" which contains all tree items, ordered in
      such a way that that root nodes appear in tree id order and
      their subtrees appear in depth-first order.

   init_from_model(model)

      Sets things up. This would normally be done in
      contribute_to_class(), but Django calls that before we've
      created our extra tree fields on the model (which we need). So
      it's done here instead, after field setup.

   insert_node(node, target, position=u'last-child', save=False, allow_existing_pk=False)

      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 neccessary 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=u'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)

   rebuild()

      Rebuilds whole tree in database 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
