django-fast-treenode 2.0.10__py3-none-any.whl → 2.1.0__py3-none-any.whl

treenode/models/mixins/children.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Children Mixin
+
+Version: 2.1.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from django.db import models
+from treenode.cache import cached_method
+
+
+class TreeNodeChildrenMixin(models.Model):
+    """TreeNode Ancestors Mixin."""
+
+    class Meta:
+        """Moxin Meta Class."""
+
+        abstract = True
+
+    def add_child(self, position=None, **kwargs):
+        """
+        Add a child to the node.
+
+        position:
+        Can be 'first-child', 'last-child', 'sorted-child' or integer value.
+
+        Parameters:
+        **kwargs – Object creation data that will be passed to the inherited
+          Node model
+        instance – Instead of passing object creation data, you can pass
+          an already-constructed (but not yet saved) model instance to be
+          inserted into the tree.
+
+        Returns:
+        The created node object. It will be save()d by this method.
+        """
+        if isinstance(position, int):
+            priority = position
+            parent = self
+        else:
+            if position not in ['first-child', 'last-child', 'sorted-child']:
+                raise ValueError(f"Invalid position format: {position}")
+            parent, priority = self._meta.model._get_place(self, position)
+
+        instance = kwargs.get("instance")
+        if instance is None:
+            instance = self._meta.model(**kwargs)
+        instance.tn_parent = parent
+        instance.tn_priority = priority
+        instance.save()
+        return instance
+
+    @cached_method
+    def get_children_pks(self):
+        """Get the children pks list."""
+        return list(self.get_children_queryset().values_list("id", flat=True))
+
+    @cached_method
+    def get_children_queryset(self):
+        """Get the children queryset with prefetch."""
+        return self.tn_children.prefetch_related('tn_children')
+
+    def get_children(self):
+        """Get a list containing all children."""
+        return list(self.get_children_queryset())
+
+    def get_children_count(self):
+        """Get the children count."""
+        return len(self.get_children_pks())
+
+    def get_first_child(self):
+        """Get the first child node or None if it has no children."""
+        return self.get_children_queryset().first() if self.is_leaf else None
+
+    def get_last_child(self):
+        """Get the last child node or None if it has no children."""
+        return self.get_children_queryset().last() if self.is_leaf else None
+
+# The End

treenode/models/mixins/descendants.py

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Descendants Mixin
+
+Version: 2.1.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from django.db import models
+from treenode.cache import treenode_cache, cached_method
+
+
+class TreeNodeDescendantsMixin(models.Model):
+    """TreeNode Descendants Mixin."""
+
+    class Meta:
+        """Moxin Meta Class."""
+
+        abstract = True
+
+    @cached_method
+    def get_descendants_queryset(self, include_self=False, depth=None):
+        """Get the descendants queryset."""
+        queryset = self._meta.model.objects\
+            .annotate(min_depth=models.Min("parents_set__depth"))\
+            .filter(parents_set__parent=self.pk)
+
+        if depth is not None:
+            queryset = queryset.filter(min_depth__lte=depth)
+        if include_self and not queryset.filter(pk=self.pk).exists():
+            queryset = queryset | self._meta.model.objects.filter(pk=self.pk)
+
+        return queryset.order_by("min_depth", "tn_priority")
+
+    @cached_method
+    def get_descendants_pks(self, include_self=False, depth=None):
+        """Get the descendants pks list."""
+        cache_key = treenode_cache.generate_cache_key(
+            label=self._meta.label,
+            func_name=getattr(self, "get_descendants_queryset").__name__,
+            unique_id=self.pk,
+            arg={
+                "include_self": include_self,
+                "depth": depth
+            }
+        )
+        queryset = treenode_cache.get(cache_key)
+        if queryset is not None:
+            return list(queryset.values_list("id", flat=True))
+        elif hasattr(self, "closure_model"):
+            return self.closure_model.get_descendants_pks(
+                self, include_self, depth
+            )
+        return []
+
+    def get_descendants(self, include_self=False, depth=None):
+        """Get a list containing all descendants."""
+        queryset = self.get_descendants_queryset(include_self, depth)
+        return list(queryset)
+
+    def get_descendants_count(self, include_self=False, depth=None):
+        """Get the descendants count."""
+        return len(self.get_descendants_pks(include_self, depth))
+
+# The End

treenode/models/mixins/family.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Descendants Mixin
+
+Version: 2.1.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from django.db import models
+from treenode.cache import cached_method
+
+
+class TreeNodeFamilyMixin(models.Model):
+    """TreeNode Family Mixin."""
+
+    class Meta:
+        """Moxin Meta Class."""
+
+        abstract = True
+
+    @cached_method
+    def get_family_queryset(self):
+        """
+        Return node family.
+
+        Return a QuerySet containing the ancestors, itself and the descendants,
+        in tree order.
+        """
+        model = self._meta.model
+        queryset = model.objects.filter(
+            models.Q(tn_closure__child=self.pk) |
+            models.Q(tn_closure__parent=self.pk) |
+            models.Q(pk=self.pk)
+        ).distinct().order_by("tn_closure__depth", "tn_parent", "tn_priority")
+        return queryset
+
+    @cached_method
+    def get_family_pks(self):
+        """
+        Return node family.
+
+        Return a pk-list containing the ancestors, the model itself and
+        the descendants, in tree order.
+        """
+        pks = self.get_family_queryset().values_list("id", flat=True)
+        return list(pks)
+
+    def get_family(self):
+        """
+        Return node family.
+
+        Return a list containing the ancestors, the model itself and
+        the descendants, in tree order.
+        """
+        queryset = self.get_family_queryset()
+        return list(queryset)
+
+    def get_family_count(self):
+        """Return number of nodes in family."""
+        return self.get_family_queryset().count()
+
+# The End

treenode/models/mixins/logical.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Logical methods Mixin
+
+Version: 2.1.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from django.db import models
+
+
+class TreeNodeLogicalMixin(models.Model):
+    """TreeNode Logical Mixin."""
+
+    class Meta:
+        """Moxin Meta Class."""
+
+        abstract = True
+
+    def is_ancestor_of(self, target_obj):
+        """Return True if the current node is ancestor of target_obj."""
+        return self in target_obj.get_ancestors(include_self=False)
+
+    def is_child_of(self, target_obj):
+        """Return True if the current node is child of target_obj."""
+        return self in target_obj.get_children()
+
+    def is_descendant_of(self, target_obj):
+        """Return True if the current node is descendant of target_obj."""
+        return self in target_obj.get_descendants()
+
+    def is_first_child(self):
+        """Return True if the current node is the first child."""
+        return self.tn_priority == 0
+
+    def has_children(self):
+        """Return True if the node has children."""
+        return self.tn_children.exists()
+
+    def is_last_child(self):
+        """Return True if the current node is the last child."""
+        return self.tn_priority == self.get_siblings_count() - 1
+
+    def is_leaf(self):
+        """Return True if the current node is a leaf."""
+        return self.tn_children.count() == 0
+
+    def is_parent_of(self, target_obj):
+        """Return True if the current node is parent of target_obj."""
+        return self == target_obj.tn_parent
+
+    def is_root(self):
+        """Return True if the current node is root."""
+        return self.tn_parent is None
+
+    def is_root_of(self, target_obj):
+        """Return True if the current node is root of target_obj."""
+        return self == target_obj.get_root()
+
+    def is_sibling_of(self, target_obj):
+        """Return True if the current node is sibling of target_obj."""
+        if target_obj.tn_parent is None and self.tn_parent is None:
+            # Both objects are roots
+            return True
+        return (self.tn_parent == target_obj.tn_parent)
+
+# The End

treenode/models/mixins/node.py

@@ -0,0 +1,210 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Node Mixin
+
+Version: 2.1.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from django.db import models
+from django.core.exceptions import FieldDoesNotExist
+
+from ...cache import cached_method, treenode_cache
+from ...utils.base36 import to_base36
+
+
+class TreeNodeNodeMixin(models.Model):
+    """TreeNode Node Mixin."""
+
+    class Meta:
+        """Moxin Meta Class."""
+
+        abstract = True
+
+    @cached_method
+    def get_breadcrumbs(self, attr='pk'):
+        """Optimized breadcrumbs retrieval with direct cache check."""
+        try:
+            self._meta.get_field(attr)
+        except FieldDoesNotExist:
+            raise ValueError(f"Invalid attribute name: {attr}")
+
+        # Easy logics for roots
+        if self.tn_parent is None:
+            return [getattr(self, attr)]
+
+        # Generate parents cache key
+        cache_key = treenode_cache.generate_cache_key(
+            self._meta.label,
+            self.get_breadcrumbs.__name__,
+            self.tn_parent.pk,
+            attr
+        )
+
+        # Try get value from cache
+        breadcrumbs = treenode_cache.get(cache_key)
+        if breadcrumbs is not None:
+            return breadcrumbs + [getattr(self, attr)]
+
+        queryset = self.get_ancestors_queryset(include_self=True).only(attr)
+        return [getattr(item, attr) for item in queryset]
+
+    @cached_method
+    def get_depth(self):
+        """Get the node depth (self, how many levels of descendants)."""
+        return self.closure_model.get_depth(self)
+
+    @cached_method
+    def get_index(self):
+        """Get the node index (self, index in node.parent.children list)."""
+        if self.tn_parent is None:
+            return self.tn_priority
+        source = list(self.tn_parent.tn_children.all())
+        return source.index(self) if self in source else self.tn_priority
+
+    @cached_method
+    def get_level(self):
+        """Get the node level (self, starting from 1)."""
+        return self.closure_model.get_level(self)
+
+    def get_order(self):
+        """Return the materialized path."""
+        path = self.get_breadcrumbs(attr='tn_priority')
+        segments = [to_base36(i).rjust(6, '0') for i in path]
+        return ''.join(segments)
+
+    def insert_at(self, target, position='first-child', save=False):
+        """
+        Insert a node into the tree relative to the target node.
+
+        Parameters:
+        target: еhe target node relative to which this node will be placed.
+
+        position – the position, relative to the target node, where the
+        current node object will be moved to, can be one of:
+
+        - first-root: the node will be the first root node;
+        - last-root: the node will be the last root node;
+        - sorted-root: the new node will be moved after sorting by
+          the treenode_sort_field field;
+
+        - first-sibling: the node will be the new leftmost sibling of the
+          target node;
+        - left-sibling: the node will take the target node’s place, which will
+          be moved to the target position with shifting follows nodes;
+        - right-sibling: the node will be moved to the position after the
+          target node;
+        - last-sibling: the node will be the new rightmost sibling of the
+          target node;
+        - sorted-sibling: the new node will be moved after sorting by
+          the treenode_sort_field field;
+
+        - first-child: the node will be the first child of the target node;
+        - last-child: the node will be the new rightmost child of the target
+        - sorted-child: the new node will be moved after sorting by
+          the treenode_sort_field field.
+
+        save : if `save=true`, the node will be saved in the tree. Otherwise,
+        the method will return a model instance with updated fields: parent
+        field and position in sibling list.
+
+        Before using this method, the model instance must be correctly created
+        with all required fields defined. If the model has required fields,
+        then simply creating an object and calling insert_at() will not work,
+        because Django will raise an exception.
+        """
+        # This method seems to have very dubious practical value.
+        parent, priority = self._meta.model._get_place(target, position)
+        self.tn_parent = parent
+        self.tn_priority = priority
+
+        if save:
+            self.save()
+
+    def move_to(self, target, position=0):
+        """
+        Move node relative to target node and position.
+
+        Moves the model instance relative to the target node and sets its
+        position (if necessary).
+
+        position – the position, relative to the target node, where the
+        current node object will be moved to, can be one of:
+
+        - first-root: the node will be the first root node;
+        - last-root: the node will be the last root node;
+        - sorted-root: the new node will be moved after sorting by
+          the treenode_sort_field field;
+          Note: if `position` contains `root`, then `target` parametr is ignored
+
+        - first-sibling: the node will be the new leftmost sibling of the
+          target node;
+        - left-sibling: the node will take the target node’s place, which will
+          be moved to the target position with shifting follows nodes;
+        - right-sibling: the node will be moved to the position after the
+          target node;
+        - last-sibling: the node will be the new rightmost sibling of the
+          target node;
+        - sorted-sibling: the new node will be moved after sorting by
+          the treenode_sort_field field;
+
+        - first-child: the node will be the first child of the target node;
+        - last-child: the node will be the new rightmost child of the target
+        - sorted-child: the new node will be moved after sorting by
+          the treenode_sort_field field;
+        """
+        parent, priority = self._meta.model._get_place(target, position)
+        self.tn_parent = parent
+        self.tn_priority = priority
+        self.save()
+
+    def get_path(self, prefix='', suffix='', delimiter='.', format_str=''):
+        """Return Materialized Path of node."""
+        priorities = self.get_breadcrumbs(attr='tn_priority')
+        if not priorities or all(p is None for p in priorities):
+            return prefix + suffix
+
+        str_ = "{%s}" % format_str
+        path = delimiter.join([
+            str_.format(p)
+            for p in priorities
+            if p is not None
+        ])
+        return prefix + path + suffix
+
+    @cached_method
+    def get_parent(self):
+        """Get the parent node."""
+        return self.tn_parent
+
+    def set_parent(self, parent_obj):
+        """Set the parent node."""
+        self.tn_parent = parent_obj
+        self.save()
+
+    def get_parent_pk(self):
+        """Get the parent node pk."""
+        return self.get_parent().pk if self.tn_parent else None
+
+    @cached_method
+    def get_priority(self):
+        """Get the node priority."""
+        return self.tn_priority
+
+    def set_priority(self, priority=0):
+        """Set the node priority."""
+        self.tn_priority = priority
+        self.save()
+
+    @cached_method
+    def get_root(self):
+        """Get the root node for the current node."""
+        return self.closure_model.get_root(self)
+
+    def get_root_pk(self):
+        """Get the root node pk for the current node."""
+        root = self.get_root()
+        return root.pk if root else None
+
+# The End

treenode/models/mixins/properties.py

@@ -0,0 +1,156 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Properties Mixin
+
+Version: 2.1.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from ..classproperty import classproperty
+
+
+class TreeNodePropertiesMixin:
+    """
+    TreeNode Properties Mixin.
+
+    Public properties.
+    All properties map a get_{{property}}() method.
+    """
+
+    @property
+    def ancestors(self):
+        """Get a list with all ancestors; self included."""
+        return self.get_ancestors()
+
+    @property
+    def ancestors_count(self):
+        """Get the ancestors count."""
+        return self.get_ancestors_count()
+
+    @property
+    def ancestors_pks(self):
+        """Get the ancestors pks list; self included."""
+        return self.get_ancestors_pks()
+
+    @property
+    def breadcrumbs(self):
+        """Get the breadcrumbs to current node(self, included)."""
+        return self.get_breadcrumbs()
+
+    @property
+    def children(self):
+        """Get a list containing all children; self included."""
+        return self.get_children()
+
+    @property
+    def children_count(self):
+        """Get the children count."""
+        return self.get_children_count()
+
+    @property
+    def children_pks(self):
+        """Get the children pks list."""
+        return self.get_children_pks()
+
+    @property
+    def depth(self):
+        """Get the node depth."""
+        return self.get_depth()
+
+    @property
+    def descendants(self):
+        """Get a list containing all descendants; self not included."""
+        return self.get_descendants()
+
+    @property
+    def descendants_count(self):
+        """Get the descendants count; self not included."""
+        return self.get_descendants_count()
+
+    @property
+    def descendants_pks(self):
+        """Get the descendants pks list; self not included."""
+        return self.get_descendants_pks()
+
+    @property
+    def first_child(self):
+        """Get the first child node."""
+        return self.get_first_child()
+
+    @property
+    def index(self):
+        """Get the node index."""
+        return self.get_index()
+
+    @property
+    def last_child(self):
+        """Get the last child node."""
+        return self.get_last_child()
+
+    @property
+    def level(self):
+        """Get the node level."""
+        return self.get_level()
+
+    @property
+    def parent(self):
+        """Get node parent."""
+        return self.tn_parent
+
+    @property
+    def parent_pk(self):
+        """Get node parent pk."""
+        return self.get_parent_pk()
+
+    @property
+    def priority(self):
+        """Get node priority."""
+        return self.get_priority()
+
+    @classproperty
+    def roots(cls):
+        """Get a list with all root nodes."""
+        return cls.get_roots()
+
+    @property
+    def root(self):
+        """Get the root node for the current node."""
+        return self.get_root()
+
+    @property
+    def root_pk(self):
+        """Get the root node pk for the current node."""
+        return self.get_root_pk()
+
+    @property
+    def siblings(self):
+        """Get a list with all the siblings."""
+        return self.get_siblings()
+
+    @property
+    def siblings_count(self):
+        """Get the siblings count."""
+        return self.get_siblings_count()
+
+    @property
+    def siblings_pks(self):
+        """Get the siblings pks list."""
+        return self.get_siblings_pks()
+
+    @classproperty
+    def tree(cls):
+        """Get an n-dimensional dict representing the model tree."""
+        return cls.get_tree()
+
+    @classproperty
+    def tree_display(cls):
+        """Get a multiline string representing the model tree."""
+        return cls.get_tree_display()
+
+    @property
+    def tn_order(self):
+        """Return the materialized path."""
+        return self.get_order()
+
+# The End