django-fast-treenode 1.1.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

treenode/managers.py

@@ -1,69 +1,281 @@
 # -*- coding: utf-8 -*-
 """
-TreeNode Managers Module
+Managers and QuerySets
 
+This module defines custom managers and query sets for the TreeNode model.
+It includes optimized bulk operations for handling hierarchical data
+using the Closure Table approach.
+
+Features:
+- `ClosureQuerySet` and `ClosureModelManager` for managing closure records.
+- `TreeNodeQuerySet` and `TreeNodeModelManager` for adjacency model operations.
+- Optimized `bulk_create` and `bulk_update` methods with atomic transactions.
+
+Version: 2.0.0
+Author: Timur Kady
+Email: timurkady@yandex.com
 """
 
-from django.db import models
-from django.db.models import Case, When, Value
+
+from django.db import models, transaction
+
+
+# ----------------------------------------------------------------------------
+# Closere Model
+# ----------------------------------------------------------------------------
+
+
+class ClosureQuerySet(models.QuerySet):
+    """QuerySet для ClosureModel."""
+
+    @transaction.atomic
+    def bulk_create(self, objs, batch_size=1000):
+        """
+        Insert new nodes in bulk.
+
+        For newly created AdjacencyModel objects:
+        1. Create self-referential records (parent=child, depth=0).
+        2. Build ancestors for each node based on tn_parent.
+        """
+        # --- 1. Create self-referential closure records for each object.
+        self_closure_records = []
+        for item in objs:
+            self_closure_records.append(
+                self.model(parent=item, child=item, depth=0)
+            )
+        super().bulk_create(self_closure_records, batch_size=batch_size)
+
+        # --- 2. Preparing closure for parents
+        parent_ids = {node.tn_parent.pk for node in objs if node.tn_parent}
+        parent_closures = list(
+            self.filter(child__in=parent_ids)
+                .values('child', 'parent', 'depth')
+        )
+        # Pack them into a dict
+        parent_closures_dict = {}
+        for pc in parent_closures:
+            parent_id = pc['child']
+            parent_closures_dict.setdefault(parent_id, []).append(pc)
+
+        # --- 3. Get closure records for the objs themselves
+        node_ids = [node.pk for node in objs]
+        child_closures = list(
+            self.filter(parent__in=node_ids)
+                .values('parent', 'child', 'depth')
+        )
+        child_closures_dict = {}
+        for cc in child_closures:
+            parent_id = cc['parent']
+            child_closures_dict.setdefault(parent_id, []).append(cc)
+
+        # --- 4. Collecting new links
+        new_records = []
+        for node in objs:
+            if not node.tn_parent:
+                continue
+            # parent closure
+            parents = parent_closures_dict.get(node.tn_parent.pk, [])
+            # closure of descendants
+            # (often this is only the node itself, depth=0, but there can be
+            # nested ones)
+            children = child_closures_dict.get(node.pk, [])
+            # Combine parents x children
+            for p in parents:
+                for c in children:
+                    new_records.append(self.model(
+                        parent_id=p['parent'],
+                        child_id=c['child'],
+                        depth=p['depth'] + c['depth'] + 1
+                    ))
+        # --- 5. bulk_create
+        result = []
+        if new_records:
+            result = super().bulk_create(new_records, batch_size=batch_size)
+        self.model.clear_cache()
+        return result
+
+    @transaction.atomic
+    def bulk_update(self, objs, fields=None, batch_size=1000):
+        """
+        Update the records in the closure table for the list of updated nodes.
+
+        For each node whose tn_parent has changed, the closure records
+        for its entire subtree are recalculated:
+        1. The ancestor chain of the new parent is selected.
+        2. The subtree (with closure records) of the updated node is selected.
+        3. For each combination (ancestor, descendant), a new depth is
+           calculated.
+        4. Old "dangling" records (those where the descendant has a link to
+           a non-subtree) are removed.
+        5. New records are inserted using the bulk_create method.
+        """
+        if not objs:
+            return
+
+        # --- 1. We obtain chains of ancestors for new parents.
+        parent_ids = {node.tn_parent.pk for node in objs if node.tn_parent}
+        parent_closures = list(
+            self.filter(child__in=parent_ids).values(
+                'child',
+                'parent',
+                'depth'
+            )
+        )
+        # We collect in a dictionary: key is the parent ID (tn_parent),
+        # value is the list of records.
+        parent_closures_dict = {}
+        for pc in parent_closures:
+            parent_closures_dict.setdefault(pc['child'], []).append(pc)
+
+        # --- 2. Obtain closing records for the subtrees of the
+        # nodes being updated.
+        updated_ids = [node.pk for node in objs]
+        subtree_closures = list(self.filter(parent__in=updated_ids).values(
+            'parent',
+            'child',
+            'depth'
+        ))
+        # Group by ID of the node being updated (i.e. by parent in the
+        # closing record)
+        subtree_closures_dict = {}
+        for sc in subtree_closures:
+            subtree_closures_dict.setdefault(sc['parent'], []).append(sc)
+
+        # --- 3. Construct new close records for each updated node with
+        # a new parent.
+        new_records = []
+        for node in objs:
+            # If the node has become root (tn_parent=None), then there are
+            # no additional connections with ancestors.
+            if not node.tn_parent:
+                continue
+            # From the closing chain of the new parent we get a list of its
+            # ancestors
+            p_closures = parent_closures_dict.get(node.tn_parent.pk, [])
+            # From the node subtree we get the closing records
+            s_closures = subtree_closures_dict.get(node.pk, [])
+            # If for some reason the subtree entries are missing, we will
+            # ensure that there is a custom entry.
+            if not s_closures:
+                s_closures = [{
+                    'parent': node.pk,
+                    'child': node.pk,
+                    'depth': 0
+                }]
+            # Combine: for each ancestor of the new parent and for each
+            # descendant from the subtree
+            for p in p_closures:
+                for s in s_closures:
+                    new_depth = p['depth'] + s['depth'] + 1
+                    new_records.append(
+                        self.model(
+                            parent_id=p['parent'],
+                            child_id=s['child'],
+                            depth=new_depth
+                        )
+                    )
+
+        # --- 4. Remove old closing records so that there are no "tails".
+        # For each updated node, calculate a subset of IDs related to its
+        # subtree
+        for node in objs:
+            subtree_ids = set()
+            # Be sure to include the node itself (its self-link should
+            # already be there)
+            subtree_ids.add(node.pk)
+            for sc in subtree_closures_dict.get(node.pk, []):
+                subtree_ids.add(sc['child'])
+            # Remove records where the child belongs to the subtree, but the
+            # parent is not included in it.
+            self.filter(child_id__in=subtree_ids).exclude(
+                parent_id__in=subtree_ids).delete()
+
+        # --- 5. Insert new closing records in bulk.
+        if new_records:
+            super().bulk_create(new_records, batch_size=batch_size)
+        self.model.clear_cache()
+        return new_records
+
+
+class ClosureModelManager(models.Manager):
+    """ClosureModel Manager."""
+
+    def get_queryset(self):
+        """get_queryset method."""
+        return ClosureQuerySet(self.model, using=self._db)
+
+    def bulk_create(self, objs, batch_size=1000):
+        """Create objects in bulk."""
+        self.model.clear_cache()
+        return self.get_queryset().bulk_create(objs, batch_size=batch_size)
+
+    def bulk_update(self, objs, fields=None, batch_size=1000):
+        """Move nodes in ClosureModel."""
+        self.model.clear_cache()
+        return self.get_queryset().bulk_update(
+            objs, fields, batch_size=batch_size
+        )
+
+# ----------------------------------------------------------------------------
+# TreeNode Model
+# ----------------------------------------------------------------------------
 
 
 class TreeNodeQuerySet(models.QuerySet):
-    """TreeNode Manager QuerySet Class"""
+    """TreeNodeModel QuerySet."""
 
     def __init__(self, model=None, query=None, using=None, hints=None):
+        """Init."""
         self.closure_model = model.closure_model
         super().__init__(model, query, using, hints)
 
-    def bulk_create(self, objs, batch_size=None, ignore_conflicts=False):
+    @transaction.atomic
+    def bulk_create(self, objs, batch_size=1000, ignore_conflicts=False):
+        """
+        Bulk create.
+
+        Method of bulk creation objects with updating and processing of
+        the Closuse Model.
+        """
+        # Regular bulk_create for TreeNodeModel
         objs = super().bulk_create(objs, batch_size, ignore_conflicts)
+        # Call ClosureModel to insert closure records
+        self.closure_model.objects.bulk_create(objs, batch_size=batch_size)
+        # Возвращаем результат
+        self.model.clear_cache()
+        return self.filter(pk__in=[obj.pk for obj in objs])
 
-        objs = self.model.closure_model.bulk_create([
-            self.model.closure_model(
-                parent=item,
-                child=item,
-                depth=0
-            )
-        ] for item in objs)
+    @transaction.atomic
+    def bulk_update(self, objs, fields, batch_size=1000, **kwargs):
+        """."""
+        closure_model = self.model.closure_model
+        if 'tn_parent' in fields:
+            # Попросим ClosureModel обработать move
+            closure_model.objects.bulk_update(objs)
+        result = super().bulk_update(objs, fields, batch_size, **kwargs)
+        closure_model.clear_cache()
+        return result
 
-        for node in objs:
-            qs = self.model.closure_model.objects.all()
-            parents = qs.filter(child=node.tn_parent).values('parent', 'depth')
-            children = qs.filter(parent=node).values('child', 'depth')
-            objects = [
-                self.model.closure_model(
-                    parent_id=p['parent'],
-                    child_id=c['child'],
-                    depth=p['depth'] + c['depth'] + 1
-                )
-                for p in parents
-                for c in children
-            ]
-            node._closure_model.objects.bulk_create(objects)
-
-        self.model._update_orders()
-        return objs
-
-
-class TreeNodeManager(models.Manager):
-    """TreeNode Manager Class"""
 
-    def get_queryset(self):
-        """
-        Forms a QuerySet ordered by the materialized path.
+class TreeNodeModelManager(models.Manager):
+    """TreeNodeModel Manager."""
+
+    def bulk_create(self, objs, batch_size=1000, ignore_conflicts=False):
         """
+        Bulk Create.
 
-        qs = TreeNodeQuerySet(self.model, using=self._db)
-        node_list = sorted([node for node in qs], key=lambda x: x.tn_order)
-        pk_list = [node.pk for node in node_list]
-
-        # Retrieve the queryset with the desired ordering
-        return qs.filter(pk__in=pk_list).order_by(
-            Case(*[When(pk=pk, then=Value(ordering))
-                   for ordering, pk in enumerate(pk_list)],
-                 default=Value(len(pk_list)),
-                 output_field=models.IntegerField(),
-                 )
+        Override bulk_create for the adjacency model.
+        Here we first clear the cache, then delegate the creation via our
+        custom QuerySet.
+        """
+        self.model.clear_cache()
+        return self.get_queryset().bulk_create(
+            objs, batch_size=batch_size, ignore_conflicts=ignore_conflicts
         )
 
-# End
+    def get_queryset(self):
+        """Return a QuerySet that sorts by 'tn_parent' and 'tn_priority'."""
+        queryset = TreeNodeQuerySet(self.model, using=self._db)
+        return queryset.order_by('tn_parent', 'tn_priority')
+
+# The End

treenode/models/__init__.py

@@ -0,0 +1,7 @@
+from .proxy import TreeNodeModel
+
+
+__all__ = ["TreeNodeModel",]
+
+
+# The End

treenode/models/classproperty.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+"""
+Class Property Decorator
+
+This module provides a `classproperty` decorator that allows defining
+read-only class-level properties.
+
+Features:
+- Enables class-level properties similar to instance properties.
+- Uses a custom descriptor for property-like behavior.
+
+"""
+
+
+class classproperty(object):
+    """Classproperty class."""
+
+    def __init__(self, getter):
+        """Init."""
+        self.getter = getter
+
+    def __get__(self, instance, owner):
+        """Get."""
+        return self.getter(owner)

treenode/models/closure.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Closure Model
+
+This module defines the Closure Table implementation for hierarchical
+data storage in the TreeNode model. It supports efficient queries for
+retrieving ancestors, descendants, breadcrumbs, and tree depth.
+
+Features:
+- Uses a Closure Table for efficient tree operations.
+- Implements cached queries for improved performance.
+- Provides bulk operations for inserting, moving, and deleting nodes.
+
+Version: 2.0.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+
+from django.db import models, transaction
+
+from ..managers import ClosureModelManager
+from ..cache import cached_method, treenode_cache
+
+
+class ClosureModel(models.Model):
+    """
+    Model for Closure Table.
+
+    Implements hierarchy storage using the Closure Table method.
+    """
+
+    parent = models.ForeignKey(
+        'TreeNodeModel',
+        related_name='children_set',
+        on_delete=models.CASCADE,
+    )
+
+    child = models.ForeignKey(
+        'TreeNodeModel',
+        related_name='parents_set',
+        on_delete=models.CASCADE,
+    )
+
+    depth = models.PositiveIntegerField()
+
+    objects = ClosureModelManager()
+
+    class Meta:
+        """Meta Class."""
+
+        abstract = True
+        unique_together = (("parent", "child"),)
+        indexes = [
+            models.Index(fields=["parent", "child"]),
+        ]
+
+    def __str__(self):
+        """Display information about a class object."""
+        return f"{self.parent} — {self.child} — {self.depth}"
+
+    # ----------- Methods of working with tree structure ----------- #
+
+    @classmethod
+    def clear_cache(cls):
+        """Clear cache for this model only."""
+        treenode_cache.invalidate(cls._meta.label)
+
+    @classmethod
+    @cached_method
+    def get_ancestors_queryset(cls, node, include_self=True, depth=None):
+        """Get the ancestors QuerySet (ordered from root to parent)."""
+        filters = {"child__pk": node.pk}
+        if depth is not None:
+            filters["depth__lte"] = depth
+        qs = cls.objects.all().filter(**filters)
+        if not include_self:
+            qs = qs.exclude(parent=node, child=node)
+        return qs
+
+    @classmethod
+    @cached_method
+    def get_breadcrumbs(cls, node, attr=None):
+        """Get the breadcrumbs to current node (included)."""
+        qs = cls.get_ancestors_queryset(
+            node, include_self=True).order_by('-depth')
+        if attr:
+            return [getattr(item.parent, attr)
+                    if hasattr(item.parent, attr) else None for item in qs]
+        else:
+            return [item.parent.pk for item in qs]
+
+    @classmethod
+    @cached_method
+    def get_descendants_queryset(cls, node, include_self=False, depth=None):
+        """Get the descendants QuerySet (ordered from parent to leaf)."""
+        filters = {"parent__pk": node.pk}
+        if depth is not None:
+            filters["depth__lte"] = depth
+        qs = cls.objects.all().filter(**filters).select_related('parent')
+        if not include_self:
+            qs = qs.exclude(parent=node, child=node)
+        return qs
+
+    @classmethod
+    @cached_method
+    def get_root(cls, node):
+        """Get the root node for the given node."""
+        return cls.objects.filter(child=node).values_list(
+            "parent", flat=True).order_by('-depth').first()
+
+    @classmethod
+    @cached_method
+    def get_depth(cls, node):
+        """Get the node depth (how deep the node is in the tree)."""
+        result = cls.objects.filter(child__pk=node.pk).aggregate(
+            models.Max("depth")
+        )["depth__max"]
+        return result if result is not None else 0
+
+    @classmethod
+    @cached_method
+    def get_level(cls, node):
+        """Get the node level (starting from 1)."""
+        return cls.objects.filter(child__pk=node.pk).aggregate(
+            models.Max("depth"))["depth__max"] + 1
+
+    @classmethod
+    @cached_method
+    def get_path(cls, node, delimiter='.', format_str=""):
+        """Return Materialized Path of node."""
+        str_ = "{%s}" % format_str
+        priorities = cls.get_breadcrumbs(node, attr='tn_priority')
+        path = delimiter.join([str_.format(p) for p in priorities])
+        return path
+
+    @classmethod
+    @transaction.atomic
+    def insert_node(cls, node):
+        """Add a node to a Closure table."""
+        # Call bulk_create passing a single object
+        cls.objects.bulk_create([node], batch_size=1000)
+        # Clear cache
+        cls.clear_cache()
+
+    @classmethod
+    @transaction.atomic
+    def move_node(cls, node):
+        """Move a node (and its subtree) to a new parent."""
+        # Call bulk_update passing a single object
+        cls.objects.bulk_update([node], batch_size=1000)
+        # Clear cache
+        cls.clear_cache()
+
+    @classmethod
+    @transaction.atomic
+    def delete_all(cls):
+        """Clear the Closure Table."""
+        # Clear cache
+        cls.clear_cache()
+        cls.objects.all().delete()
+
+    def save(self, force_insert=False, *args, **kwargs):
+        """Save method."""
+        super().save(force_insert, *args, **kwargs)
+        self._meta.model.clear_cache()
+
+# The End

treenode/models/factory.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Factory for Closure Table
+
+This module provides a metaclass `TreeFactory` that automatically binds
+a model to a Closure Table for hierarchical data storage.
+
+Features:
+- Ensures non-abstract, non-proxy models get a corresponding Closure Table.
+- Dynamically creates and assigns a Closure Model for each TreeNodeModel.
+- Facilitates the management of hierarchical relationships.
+
+Version: 2.0.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+
+import sys
+from django.db import models
+from .closure import ClosureModel  # Используем готовый ClosureModel
+
+
+class TreeFactory(models.base.ModelBase):
+    """
+    Metaclass for binding a model to a Closure Table.
+
+    For each non-abstract, non-proxy, and "top" (without parents) model,
+    assigns the `ClosureModel` as the closure table.
+    """
+
+    def __init__(cls, name, bases, dct):
+        """Class initialization.
+
+        We check that the model:
+            - is not abstract
+            - is not a proxy
+            - is not a child
+        and only then assign the ClosureModel.
+        """
+        super().__init__(name, bases, dct)
+
+        if (cls._meta.abstract or cls._meta.proxy or
+                cls._meta.get_parent_list()):
+            return
+
+        closure_name = f"{cls._meta.object_name}ClosureModel"
+        if getattr(cls, "closure_model", None) is not None:
+            return
+
+        fields = {
+            "parent": models.ForeignKey(
+                cls._meta.model,
+                related_name="children_set",
+                on_delete=models.CASCADE
+            ),
+
+            "child": models.ForeignKey(
+                cls._meta.model,
+                related_name="parents_set",
+                on_delete=models.CASCADE,
+            ),
+
+            "__module__": cls.__module__
+        }
+        closure_model = type(closure_name, (ClosureModel,), fields)
+        setattr(sys.modules[cls.__module__], closure_name, closure_model)
+
+        cls.closure_model = closure_model
+
+# The End