django-fast-treenode 2.1.4__py3-none-any.whl → 3.0.0__py3-none-any.whl

treenode/forms.py

@@ -10,12 +10,12 @@ Functions:
 - __init__: Initializes the form and filters out invalid parent choices.
 - factory: Dynamically creates a form class for a given TreeNode model.
 
-Version: 2.1.0
+Version: 3.0.0
 Author: Timur Kady
 Email: timurkady@yandex.com
 """
 
-from django import forms
+from django.forms import ModelForm
 from django.forms.models import ModelChoiceField, ModelChoiceIterator
 from django.utils.translation import gettext_lazy as _
 
@@ -27,13 +27,10 @@ class SortedModelChoiceIterator(ModelChoiceIterator):
 
     def __iter__(self):
         """Return sorted choices based on tn_order."""
-        qs_list = list(self.queryset.all())
-
-        # Sort objects
-        sorted_objects = self.queryset.model._sort_node_list(qs_list)
+        qs_list = list(self.queryset.order_by('_path').all())
 
         # Iterate yield (value, label) pairs.
-        for obj in sorted_objects:
+        for obj in qs_list:
             yield (
                 self.field.prepare_value(obj),
                 self.field.label_from_instance(obj)
@@ -60,68 +57,51 @@ class SortedModelChoiceField(ModelChoiceField):
     choices = property(_get_choices, _set_choices)
 
 
-class TreeNodeForm(forms.ModelForm):
-    """
-    TreeNode Form Class.
+class TreeNodeForm(ModelForm):
+    """TreeNodeModelAdmin Form Class."""
 
-    ModelForm for dynamically determined TreeNode model.
-    Uses TreeWidget and excludes self and descendants from the parent choices.
-    """
+    def __init__(self, *args, **kwargs):
+        """Init Form."""
+        super(TreeNodeForm, self).__init__(*args, **kwargs)
+        self.model = self.instance._meta.model
+
+        if 'parent' not in self.fields:
+            return
+
+        exclude_pks = []
+        if self.instance.pk:
+            exclude_pks = self.instance.query(
+                objects='descendants',
+                include_self=True
+            )
 
-    class Meta:
-        """Meta Class."""
+        queryset = self.model.objects\
+            .exclude(pk__in=exclude_pks)\
+            .order_by('_path')\
+            .all()
 
-        model = None
-        fields = "__all__"
-        widgets = {
-            "tn_parent": TreeWidget()
-        }
+        self.fields['parent'].queryset = queryset
+        self.fields["parent"].required = False
+        self.fields["parent"].empty_label = _("Root")
 
-    def __init__(self, *args, **kwargs):
-        """Init Method."""
-        super().__init__(*args, **kwargs)
-
-        model = self._meta.model
-
-        if "tn_parent" in self.fields:
-            self.fields["tn_parent"].required = False
-            self.fields["tn_parent"].empty_label = _("Root")
-            queryset = model.objects.all()
-
-            original_field = self.fields["tn_parent"]
-            self.fields["tn_parent"] = SortedModelChoiceField(
-                queryset=queryset,
-                label=original_field.label,
-                widget=original_field.widget,
-                empty_label=original_field.empty_label,
-                required=False
-            )
-            self.fields["tn_parent"].widget.model = queryset.model
-
-            # If there is a current value, set it
-            if self.instance and self.instance.pk and self.instance.tn_parent:
-                self.fields["tn_parent"].initial = self.instance.tn_parent
-
-    @classmethod
-    def factory(cls, model):
-        """
-        Create a form class dynamically for the given TreeNode model.
-
-        This ensures that the form works with different concrete models.
-        """
-        class Meta:
-            model = model
-            fields = "__all__"
-            widgets = {
-                "tn_parent": TreeWidget(
-                    attrs={
-                        "data-autocomplete-light": "true",
-                        "data-url": "/tree-autocomplete/",
-                    }
-                )
-            }
-
-        return type(f"{model.__name__}Form", (cls,), {"Meta": Meta})
+        original_field = self.fields["parent"]
+
+        self.fields["parent"] = SortedModelChoiceField(
+            queryset=queryset,
+            label=original_field.label,
+            widget=original_field.widget,
+            empty_label=original_field.empty_label,
+            required=False
+        )
+        self.fields["parent"].widget.model = self.model
+
+        # If there is a current value, set it
+        if self.instance and self.instance.pk and self.instance.parent:
+            self.fields["parent"].initial = self.instance.parent
 
+    class Meta:
+        widgets = {
+            'parent': TreeWidget(),
+        }
 
 # The End

treenode/managers/__init__.py

@@ -1,21 +1,5 @@
-# -*- coding: utf-8 -*-
-"""
-Managers and QuerySets
+from .managers import TreeNodeManager
+from .queries import TreeQueryManager
+from .tasks import TreeTaskManager
 
-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:
-- `ClosureModelManager` for managing closure records.
-- `TreeNodeModelManager` for adjacency model operations.
-
-Version: 2.1.0
-Author: Timur Kady
-Email: timurkady@yandex.com
-"""
-
-from .closure import ClosureModelManager
-from .adjacency import TreeNodeModelManager
-
-__all__ = ["TreeNodeModelManager", "ClosureModelManager"]
+__all__ = ['TreeNodeManager', 'TreeQueryManager', 'TreeTaskManager']

treenode/managers/managers.py

@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+"""
+Manager and Query Set Customization Module
+
+This module defines custom managers and query sets for the TreeNodeModel.
+It includes operations for synchronizing additional fields associated with
+the Materialized Path method implementation.
+
+Version: 3.0.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from django.db import models  # , transaction
+from django.utils.translation import gettext_lazy as _
+import logging
+
+from ..cache import treenode_cache as cache
+
+
+class TreeNodeQuerySet(models.QuerySet):
+    """TreeNodeModel QuerySet."""
+
+    def create(self, **kwargs):
+        """Create an object."""
+        obj = self.model(**kwargs)
+        obj.save()
+        return obj
+
+    def get_or_create(self, defaults=None, **kwargs):
+        """Get or create an object."""
+        defaults = defaults or {}
+        created = False
+
+        try:
+            obj = super().get(**kwargs)
+        except models.DoesNotExist:
+            params = {k: v for k, v in kwargs.items() if "__" not in k}
+            params.update(
+                {k: v() if callable(v) else v for k, v in defaults.items()}
+            )
+            obj = self.model(**params)
+            obj.save()
+            created = True
+        return obj, created
+
+    def update(self, **kwargs):
+        """Update method for TreeNodeQuerySet.
+
+        If kwargs contains updates for 'parent' or 'priority',
+        then specialized bulk_update logic is used, which:
+        - Updates allowed fields directly;
+        - If parent is updated, calls _bulk_move (updates _path and parent);
+        - If priority is updated (without parent), updates sibling order.
+        Otherwise, the standard update is called.
+        """
+        forbidden = {'_path', '_depth'}
+        if forbidden.intersection(kwargs.keys()):
+            raise ValueError(
+                _(f"Fields cannot be updated directly: {', '.join(forbidden)}")
+            )
+
+        result = 0
+        excluded_fields = {"parent", "priority", "_path", "_depth"}
+        params = {key: value for key,
+                  value in kwargs.items() if key not in excluded_fields}
+
+        if params:
+            # Normal update
+            result = super().update(**params)
+
+        cache.invalidate(self.model._meta.label)
+        return result
+
+    def update_or_create(self, defaults=None, **kwargs):
+        """Update or create an object."""
+        params = {**(defaults or {}), **kwargs}
+        created = False
+        try:
+            obj = super().get(**kwargs)
+            obj.update(**params)
+        except models.DoesNotExist:
+            obj = self.model(**params)
+            obj.save()
+            created = True
+        return obj, created
+
+    def _raw_update(self, **kwargs):
+        """
+        Bypass custom update() logic (e.g. field protection).
+
+        WARNING: Unsafe low-level update bypassing all TreeNode protections.
+        Use only when bypassing _path/_depth/priority safety checks is
+        intentional.
+        """
+        result = models.QuerySet(self.model, using=self.db).update(**kwargs)
+        return result
+
+    #  batch_size=None, **kwargs):
+    def _raw_bulk_update(self, objs, fields, *args, **kwargs):
+        """
+        Bypass custom bulk_update logic (e.g. field protection).
+
+        WARNING: Unsafe low-level update bypassing all TreeNode protections.
+        Use only when bypassing _path/_depth/priority safety checks is
+        intentional.
+        """
+        base_qs = models.QuerySet(self.model, using=self.db)
+        result = base_qs.bulk_update(objs, fields, *args, **kwargs)
+
+        return result
+
+    def _raw_delete(self, using=None):
+        return models.QuerySet(self.model, using=using or self.db)\
+            ._raw_delete(using=using or self.db)
+
+    def __iter__(self):
+        """Iterate queryset."""
+        try:
+            if len(self.model.tasks.queue) > 0:
+                # print("🌲 TreeNodeQuerySet: auto-run (iter)")
+                self.model.tasks.run()
+        except Exception as e:
+            logging.error("⚠️ Tree flush failed silently (iter): %s", e)
+        return super().__iter__()
+
+    def _fetch_all(self):
+        """Extract data for a queryset from the database."""
+        try:
+            tasks = self.model.tasks
+            if len(tasks.queue) > 0:
+                # print("🌲 TreeNodeQuerySet: auto-run (_fetch_all)")
+                tasks.run()
+        except Exception as e:
+            logging.error("⚠️ Tree flush failed silently: %s", e)
+        super()._fetch_all()
+
+# ------------------------------------------------------------------
+#
+# Managers
+#
+# ------------------------------------------------------------------
+
+
+class TreeNodeManager(models.Manager):
+    """Tree Manager Class."""
+
+    def get_queryset(self):
+        """Get QuerySet."""
+        return TreeNodeQuerySet(self.model, using=self._db).order_by(
+            "_depth", "priority"
+        )
+
+    def bulk_create(self, objs, *args, **kwargs):
+        """Create objects in bulk and schedule tree rebuilds."""
+        result = super().bulk_create(objs, *args, **kwargs)
+
+        # Collect parent_ids, stop at first None
+        parent_ids = set()
+        for obj in objs:
+            pid = obj.parent_id
+            if pid is None:
+                self.model.tasks.queue.clear()
+                self.model.tasks.add("update", None)
+                break
+            parent_ids.add(pid)
+        else:
+            for pid in parent_ids:
+                self.model.tasks.add("update", pid)
+
+        # self.model.tasks.run()
+        return result
+
+    def bulk_update(self, objs, fields, batch_size=None):
+        """Update objects in bulk and schedule tree rebuilds if needed."""
+        result = super().bulk_update(objs, fields, batch_size)
+
+        parent_ids = set()
+        for obj in objs:
+            pid = obj.parent_id
+            if pid is None:
+                self.model.tasks.queue.clear()
+                self.model.tasks.add("update", None)
+                break
+            parent_ids.add(pid)
+        else:
+            for pid in parent_ids:
+                self.model.tasks.add("update", pid)
+
+        # self.model.tasks.run()
+        return result
+
+    def _raw_update(self, *args, **kwargs):
+        """
+        Update objects in bulk.
+
+        WARNING: Unsafe low-level update bypassing all TreeNode protections.
+        Use only when bypassing _path/_depth/priority safety checks is
+        intentional.
+        """
+        return models.QuerySet(self.model, using=self.db)\
+            .update(*args, **kwargs)
+
+    def _raw_bulk_update(self, *args, **kwargs):
+        """
+        Update objects in bulk.
+
+        WARNING: Unsafe low-level update bypassing all TreeNode protections.
+        Use only when bypassing _path/_depth/priority safety checks is
+        inte
+        """
+        return models.QuerySet(self.model, using=self.db)\
+            .bulk_update(*args, **kwargs)
+
+
+# The End

treenode/managers/queries.py

@@ -0,0 +1,233 @@
+# -*- coding: utf-8 -*-
+"""
+Low-level SQL Query Manager.
+
+Encapsulates all logic to retrieve related primary keys based on relationships
+(e.g., ancestors, children, descendants, siblings, family, root) using raw SQL.
+
+Version: 3.0.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+
+from django.db import connection
+
+
+class TreeQuery:
+    """Class to manage tree-structure SQL queries."""
+
+    def __init__(self, instance):
+        """Initialize with the given model instance."""
+        self.node = instance
+        self.db_table = instance._meta.db_table
+
+    def __call__(self, *args, **kwargs):
+        """Call function."""
+        return self.get_relative_pks(*args, **kwargs)
+
+    def execute_query(self, sql, params):
+        """Execute the given SQL with parameters and fetch all the results."""
+        with connection.cursor() as cursor:
+            cursor.execute(sql, params)
+            return cursor.fetchall()
+
+    def wrap_union_all(self, queries):
+        """
+        Combine multiple SQL queries using UNION ALL.
+
+        Each query is a tuple: (sql, params).
+        Returns a tuple: (combined_sql, combined_params).
+        """
+        union_query = " UNION ALL ".join(f"({q[0]})" for q in queries)
+        combined_params = []
+        for q in queries:
+            combined_params.extend(q[1])
+        return union_query, combined_params
+
+    def order_by(self, sql, order_by_clause):
+        """Wrap the SQL in an outer query to enforce ordering."""
+        return f"SELECT * FROM ({sql}) AS combined ORDER BY {order_by_clause}"
+
+    def get_children(self):
+        """
+        Build SQL for the 'children' relationship.
+
+        The current node is not included.
+        """
+        sql = f"SELECT id, priority FROM {self.db_table} WHERE parent_id = %s ORDER BY priority"  # noqa: D501
+        params = [self.node.pk]
+        return sql, params
+
+    def get_siblings(self, include_self=True):
+        """
+        Build SQL for the 'siblings' relationship.
+
+        If include_self is True, the current node is included by performing
+        a UNION ALL.
+        """
+        if self.node.parent_id is None:
+            sql1 = f"SELECT id, priority FROM {self.db_table} WHERE parent_id IS NULL AND id <> %s"  # noqa: D501
+            params1 = [self.node.pk]
+        else:
+            sql1 = f"SELECT id, priority FROM {self.db_table} WHERE parent_id = %s AND id <> %s"  # noqa: D501
+            params1 = [self.node.parent_id, self.node.pk]
+
+        if include_self:
+            sql2 = f"SELECT id, priority FROM {self.db_table} WHERE id = %s"
+            params2 = [self.node.pk]
+            combined_sql, combined_params = self.wrap_union_all(
+                [(sql1, params1), (sql2, params2)])
+            sql = self.order_by(combined_sql, "priority")
+            return sql, combined_params
+        else:
+            sql = self.order_by(sql1, "priority")
+            return sql, params1
+
+    def get_descendants(self, include_self, depth):
+        """
+        Build SQL for the 'descendants' relationship.
+
+        Optionally limits the depth, and includes the current node if requested.
+        """
+        from_path = self.node._path + "."
+        to_path = self.node._path + "/"
+        base_sql = f"SELECT id, _depth, priority FROM {self.db_table} WHERE _path >= %s AND _path < %s"  # noqa: D501
+        params = [from_path, to_path]
+
+        if depth is not None:
+            # Use values_list to fetch _depth without loading the full model
+            depth_val = getattr(self.node, "_depth", None)
+            if depth_val is None:
+                depth_val = type(self.node).objects.values_list(
+                    "_depth", flat=True).get(pk=self.node.pk)
+            base_sql += " AND _depth <= %s"
+            params.append(depth_val + depth)
+
+        if include_self:
+            sql_self = f"SELECT id, _depth, priority FROM {self.db_table} WHERE id = %s"  # noqa: D501
+            union_sql, union_params = self.wrap_union_all(
+                [(base_sql, params), (sql_self, [self.node.pk])])
+        else:
+            union_sql, union_params = base_sql, params
+
+        union_sql = self.order_by(union_sql, "_depth, priority")
+        return union_sql, union_params
+
+    def get_ancestors(self, include_self):
+        """
+        Retrieve ancestors using a recursive CTE.
+
+        Returns the list of IDs in order (from root to immediate parent).
+        """
+        sql = (
+            f"WITH RECURSIVE ancestors_cte(id, lvl) AS ("
+            f"  SELECT (SELECT parent_id FROM {self.db_table} WHERE id = %s), 1 "  # noqa: D501
+            f"  UNION ALL "
+            f"  SELECT p.parent_id, lvl + 1 FROM ancestors_cte a "
+            f"  JOIN {self.db_table} p ON p.id = a.id "
+            f"  WHERE a.id IS NOT NULL"
+            f") "
+            f"SELECT id FROM ancestors_cte WHERE id IS NOT NULL"
+        )
+        params = [self.node.pk]
+        rows = self.execute_query(sql, params)
+        ancestor_ids = [row[0] for row in rows]
+        if include_self:
+            ancestor_ids.insert(0, self.node.pk)
+        # Reverse the order to get from the root to the immediate parent.
+        return ancestor_ids[::-1]
+
+    def get_family(self, include_self, depth):
+        """
+        Build SQL for the 'family' relationship.
+
+        Family is defined as the union of ancestors and descendants.
+        The ancestors condition uses _path less than current node’s _path,
+        and the descendants condition uses a range on _path.
+        """
+        ancestors_condition = "_path < %s"
+        descendants_condition = "(_path >= %s AND _path < %s)"
+        family_sql = f"SELECT id, _depth, priority FROM {self.db_table} WHERE {ancestors_condition} OR {descendants_condition}"  # noqa: D501
+        params = [self.node._path, self.node._path + ".", self.node._path + "/"]
+
+        queries = [(family_sql, params)]
+        if include_self:
+            sql_self = f"SELECT id, _depth, priority FROM {self.db_table} WHERE id = %s"  # noqa: D501
+            queries.append((sql_self, [self.node.pk]))
+        combined_sql, combined_params = self.wrap_union_all(queries)
+        combined_sql = self.order_by(combined_sql, "_depth, priority")
+        return combined_sql, combined_params
+
+    def get_root(self):
+        """
+        Build SQL for the 'root' relationship.
+
+        Retrieves the root node, identified by the first segment of _path.
+        """
+        segments = self.node._path.split(".")
+        root_segment = segments[0]
+        sql = f"SELECT id, priority FROM {self.db_table} WHERE _path = %s ORDER BY priority"  # noqa: D501
+        params = [root_segment]
+        return sql, params
+
+    def get_relative_pks(self, objects="children", include_self=True, depth=None, mode=None):  # noqa: D501
+        """
+        Get related primary keys from the tree using raw SQL queries.
+
+        Arguments:
+            objects (str): Relationship type. Options are: "ancestors",
+                           "children", "descendants", "family", "root", or
+                           "siblings".
+            include_self (bool): Whether to include the current node in the
+                           result (ignored for 'children').
+            depth (int|None): Maximum depth to consider (only for 'descendants'
+                           and 'family').
+            mode (str|None): 'count' returns the number of nodes, 'exist'
+                           returns a boolean, or None returns a list of IDs.
+
+        Returns:
+            list | int | bool: Depending on mode, returns a list of IDs, count,
+                           or boolean.
+        """
+        if objects == "children":
+            sql, params = self.get_children()
+        elif objects == "siblings":
+            sql, params = self.get_siblings(include_self=include_self)
+        elif objects == "descendants":
+            sql, params = self.get_descendants(include_self, depth)
+        elif objects == "ancestors":
+            result = self.get_ancestors(include_self)
+            if mode == "count":
+                return len(result)
+            elif mode == "exist":
+                return bool(result)
+            else:
+                return result
+        elif objects == "family":
+            sql, params = self.get_family(include_self, depth)
+        elif objects == "root":
+            sql, params = self.get_root()
+        else:
+            raise ValueError(f"Unknown relationship type: {objects}")
+
+        # Execute the query for all branches except 'ancestors'
+        rows = self.execute_query(sql, params)
+        result_ids = [row[0] for row in rows]
+
+        if mode == "count":
+            return len(result_ids)
+        elif mode == "exist":
+            return bool(result_ids)
+        else:
+            return result_ids
+
+
+class TreeQueryManager:
+    """Desctiptor for TreeQueryManager."""
+
+    def __get__(self, instance, owner):
+        """Get query for instance."""
+        if instance is None:
+            return self
+        return TreeQuery(instance)