django-fast-treenode 2.0.11__py3-none-any.whl → 2.1.1__py3-none-any.whl

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

treenode/models/mixins/roots.py

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Roots Mixin
+
+Version: 2.1.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from django.db import models
+from treenode.cache import cached_method
+
+
+class TreeNodeRootsMixin(models.Model):
+    """TreeNode Roots Mixin."""
+
+    class Meta:
+        """Moxin Meta Class."""
+
+        abstract = True
+
+    @classmethod
+    def add_root(cls, position=None, **kwargs):
+        """
+        Add a root node to the tree.
+
+        Adds a new root node at the specified position. If no position is
+        specified, the new node will be the last element in the root.
+        Parameters:
+        position: can be 'first-root', 'last-root', 'sorted-root' or integer
+        value.
+        **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
+        else:
+            if position not in ['first-root', 'last-root', 'sorted-root']:
+                raise ValueError(f"Invalid position format: {position}")
+
+            parent, priority = cls._get_place(None, position)
+
+        instance = kwargs.get("instance")
+        if instance is None:
+            instance = cls(**kwargs)
+
+        parent, priority = cls._get_place(None, position)
+        instance.tn_parent = None
+        instance.tn_priority = priority
+        instance.save()
+        return instance
+
+    @classmethod
+    @cached_method
+    def get_roots_queryset(cls):
+        """Get root nodes queryset with preloaded children."""
+        qs = cls.objects.filter(tn_parent=None).prefetch_related('tn_children')
+        return qs
+
+    @classmethod
+    @cached_method
+    def get_roots_pks(cls):
+        """Get a list with all root nodes."""
+        pks = cls.objects.filter(tn_parent=None).values_list("id", flat=True)
+        return list(pks)
+
+    @classmethod
+    def get_roots(cls):
+        """Get a list with all root nodes."""
+        qs = cls.get_roots_queryset()
+        return list(qs)
+
+    @classmethod
+    def get_roots_count(cls):
+        """Get a list with all root nodes."""
+        return len(cls.get_roots_pks())
+
+    @classmethod
+    def get_first_root(cls):
+        """Return the first root node in the tree or None if it is empty."""
+        roots = cls.get_roots_queryset()
+        return roots.fiest() if roots.count() > 0 else None
+
+    @classmethod
+    def get_last_root(cls):
+        """Return the last root node in the tree or None if it is empty."""
+        roots = cls.get_roots_queryset()
+        return roots.last() if roots.count() > 0 else None
+
+# The End

treenode/models/mixins/siblings.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Siblings Mixin
+
+Version: 2.1.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from django.db import models
+from treenode.cache import cached_method
+
+
+class TreeNodeSiblingsMixin(models.Model):
+    """TreeNode Siblings Mixin."""
+
+    class Meta:
+        """Moxin Meta Class."""
+
+        abstract = True
+
+    def add_sibling(self, position=None, **kwargs):
+        """
+        Add a new node as a sibling to the current node object.
+
+        Returns the created node object or None if failed. It will be saved
+        by this method.
+        """
+        if isinstance(position, int):
+            priority = position
+            parent = self.tn_parent
+        else:
+            if position not in [
+                    'first-sibling', 'left-sibling', 'right-sibling',
+                    'last-sibling', 'sorted-sibling']:
+                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_priority = priority
+        instance.tn_priority = parent
+        instance.save()
+        return instance
+
+    @cached_method
+    def get_siblings_queryset(self):
+        """Get the siblings queryset with prefetch."""
+        if self.tn_parent:
+            qs = self.tn_parent.tn_children.prefetch_related('tn_children')
+        else:
+            qs = self._meta.model.objects.filter(tn_parent__isnull=True)
+        return qs.exclude(pk=self.pk)
+
+    def get_siblings(self):
+        """Get a list with all the siblings."""
+        return list(self.get_siblings_queryset())
+
+    def get_siblings_count(self):
+        """Get the siblings count."""
+        return self.get_siblings_queryset().count()
+
+    def get_siblings_pks(self):
+        """Get the siblings pks list."""
+        return [item.pk for item in self.get_siblings_queryset()]
+
+    def get_first_sibling(self):
+        """
+        Return the fist node’s sibling.
+
+        Method can return the node itself if it was the leftmost sibling.
+        """
+        return self.get_siblings_queryset().fist()
+
+    def get_previous_sibling(self):
+        """Return the previous sibling in the tree, or None."""
+        priority = self.tn_priority - 1
+        if priority < 0:
+            return None
+        return self.get_siblings_queryset.filter(tn_priority=priority)
+
+    def get_next_sibling(self):
+        """Return the next sibling in the tree, or None."""
+        priority = self.tn_priority = 1
+        queryset = self.get_siblings_queryset()
+        if priority == queryset.count():
+            return None
+        return queryset.filter(tn_priority=priority)
+
+    def get_last_sibling(self):
+        """
+        Return the fist node’s sibling.
+
+        Method can return the node itself if it was the leftmost sibling.
+        """
+        return self.get_siblings_queryset().last()
+
+# The End