django-fast-treenode 3.2.0__tar.gz → 3.2.1__tar.gz

{django_fast_treenode-3.2.0/django_fast_treenode.egg-info → django_fast_treenode-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-fast-treenode
-Version: 3.2.0
+Version: 3.2.1
 Summary: Treenode Framework for supporting tree (hierarchical) data structure in Django projects
 Home-page: https://django-fast-treenode.readthedocs.io/
 Author: Timur Kady

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1/django_fast_treenode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-fast-treenode
-Version: 3.2.0
+Version: 3.2.1
 Summary: Treenode Framework for supporting tree (hierarchical) data structure in Django projects
 Home-page: https://django-fast-treenode.readthedocs.io/
 Author: Timur Kady

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/django_fast_treenode.egg-info/SOURCES.txt

@@ -61,6 +61,7 @@ treenode/models/mixins/logical.py
 treenode/models/mixins/node.py
 treenode/models/mixins/properties.py
 treenode/models/mixins/roots.py
+treenode/models/mixins/search.py
 treenode/models/mixins/siblings.py
 treenode/models/mixins/tree.py
 treenode/models/mixins/update.py

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/docs/api.md

@@ -11,6 +11,7 @@ The API is divided into several logical groups, each serving a specific purpose:
 - **[Descendant Methods](#descendant-methods)** – Work with entire subtrees of nodes.
 - **[Family Methods](#family-methods)** – Retrieve and analyze relationships within a node's family (ancestors, siblings, descendants).
 - **[Node Utility Methods](#node-utility-methods)** – Additional methods for retrieving node order, paths, levels, and priorities.
+- **[Search Methods](#search-methods)** – Quick node lookup utilities.
 - **[Root Node Methods](#root-node-methods)** – Manage and retrieve root nodes of trees.
 - **[Sibling Methods](#sibling-methods)** – Handle relationships between sibling nodes.
 - **[Tree Methods](#tree-methods)** – Serialize and manipulate the entire tree structure, including JSON export/import.
@@ -351,6 +352,28 @@ obj.get_root_pk()
 
 ---
 
+### Search Methods
+These methods provide convenient helpers for finding nodes by
+breadcrumb paths or within a subtree.
+
+#### find_by_path
+Find a node by a path previously generated via `get_breadcrumbs`.
+```python
+cls.find_by_path("root/A/D", attr="name", delimiter="/")
+```
+
+Returns the matching node or `None`.
+
+#### find_in_subtree
+Search for a node among the descendants of a parent node.
+```python
+cls.find_in_subtree(parent, "D", attr="name")
+```
+
+Returns the first found node or `None`.
+
+---
+
 ### Root Node Methods
 These methods allow managing **root nodes** efficiently. They provide retrieval, counting, and manipulation of the first and last root nodes in the tree.
 

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/docs/migration.md

@@ -77,7 +77,7 @@ python manage.py shell
 Then execute:
 
 ```python
-YourTreeNodeModel.rebuild()
+YourTreeNodeModel.update_tree()
 ```
 
 !!! note

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "django-fast-treenode"
-version = "3.2.0"
+version = "3.2.1"
 description = "Treenode Framework for supporting tree (hierarchical) data structure in Django projects"
 readme = "README.md"
 authors = [{ name = "Timur Kady", email = "timurkady@yandex.com" }]

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name='django-fast-treenode',
-    version='3.2.0',
+    version='3.2.1',
     description='Treenode Framework for supporting tree (hierarchical) data structure in Django projects',
     long_description=open('README.md', encoding='utf-8').read(),
     long_description_content_type='text/markdown',

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/tests/test_suite.py

@@ -93,3 +93,14 @@ class TreeNodeModelTests(TestCase):
         qs = TestModel.objects.filter(pk__in=[self.a.pk, self.c.pk]).all()
         self.assertFalse(TestModel.objects.filter(pk=self.a.pk).exists())
         self.assertTrue(TestModel.objects.filter(pk=self.c.pk).exists())
+
+    # --- 6. Search ----------------------------------------------------------
+
+    def test_find_by_path(self):
+        path = "/".join(self.d.get_breadcrumbs(attr="name"))
+        node = TestModel.find_by_path(path, attr="name", delimiter="/")
+        self.assertEqual(node, self.d)
+
+    def test_find_in_subtree(self):
+        node = TestModel.find_in_subtree(self.a, "D", attr="name")
+        self.assertEqual(node, self.d)

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/treenode/managers/tasks.py

@@ -137,7 +137,25 @@ class TreeTaskQueue:
             if not merged:
                 result_set.add(current)
 
-        return [{"mode": "update", "parent_id": pk} for pk in sorted(result_set)]
+        if not result_set:
+            return []
+
+        depth_lookup = {}
+        if result_set:
+            with connection.cursor() as cursor:
+                format_ids = ', '.join(['%s'] * len(result_set))
+                sql = f"""
+                    SELECT id, _depth
+                    FROM {self.model._meta.db_table}
+                    WHERE id IN ({format_ids})
+                """
+                cursor.execute(sql, list(result_set))
+                for node_id, depth in cursor.fetchall():
+                    depth_lookup[node_id] = depth
+
+
+        ordered_pks = sorted(result_set, key=lambda pk: (depth_lookup.get(pk, 0), pk))
+        return [{"mode": "update", "parent_id": pk} for pk in ordered_pks]
 
     def _get_root_ids(self):
         """Return root node IDs."""

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/treenode/models/mixins/__init__.py

@@ -7,6 +7,7 @@ from .family import TreeNodeFamilyMixin
 from .logical import TreeNodeLogicalMixin
 from .node import TreeNodeNodeMixin
 from .properties import TreeNodePropertiesMixin
+from .search import TreeNodeSearchMixin
 from .roots import TreeNodeRootsMixin
 from .siblings import TreeNodeSiblingsMixin
 from .tree import TreeNodeTreeMixin
@@ -16,7 +17,8 @@ from .update import RawSQLMixin
 __all__ = [
     "TreeNodeAncestorsMixin", "TreeNodeChildrenMixin", "TreeNodeFamilyMixin",
     "TreeNodeDescendantsMixin", "TreeNodeLogicalMixin", "TreeNodeNodeMixin",
-    "TreeNodePropertiesMixin", "TreeNodeRootsMixin", "TreeNodeSiblingsMixin",
+    "TreeNodeSearchMixin", "TreeNodePropertiesMixin", "TreeNodeRootsMixin",
+    "TreeNodeSiblingsMixin", "TreeNodeTreeMixin", "RawSQLMixin"
     "TreeNodeTreeMixin", "RawSQLMixin"
 ]
 

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/treenode/models/mixins/children.py

@@ -86,4 +86,4 @@ class TreeNodeChildrenMixin(models.Model):
         """Get the last child node or None if it has no children."""
         return self.get_children_queryset().last()
 
-# The End
+# The End

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/treenode/models/mixins/descendants.py

@@ -74,4 +74,4 @@ class TreeNodeDescendantsMixin(models.Model):
         )
 
 
-# The End
+# The End

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/treenode/models/mixins/roots.py

@@ -137,4 +137,4 @@ class TreeNodeRootsMixin(models.Model):
             cursor.execute(query, params)
 
 
-# The End
+# The End

django_fast_treenode-3.2.1/treenode/models/mixins/search.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Search Mixin
+
+Version: 3.2.1
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from django.db import models
+
+
+class TreeNodeSearchMixin(models.Model):
+    """Mixin that provides helper methods for quick node lookup."""
+
+    class Meta:
+        """Mixin Meta Class."""
+        abstract = True
+
+    @classmethod
+    def find_by_path(cls, path, attr="id", delimiter="/"):
+        """Return a node referenced by breadcrumbs path.
+
+        The ``path`` argument may be a string or an iterable of breadcrumb
+        values previously produced by :py:meth:`get_breadcrumbs`.
+        If the path cannot be resolved, ``None`` is returned.
+        """
+        if path is None:
+            return None
+
+        if not isinstance(path, (list, tuple)):
+            path = [p for p in str(path).strip(delimiter).split(delimiter) if p]
+
+        parent = None
+        for token in path:
+            lookup = {attr: token}
+            if parent is None:
+                qs = cls.objects.filter(parent_id__isnull=True, **lookup)
+            else:
+                qs = cls.objects.filter(parent=parent, **lookup)
+            parent = qs.first()
+            if parent is None:
+                return None
+        return parent
+
+    @classmethod
+    def find_in_subtree(cls, parent, value, attr="id"):
+        """Search ``parent`` descendants for attribute ``attr`` equal to ``value``."""
+        if parent is None:
+            return None
+        prefix = parent.get_order() + "."
+        return cls.objects.filter(_path__startswith=prefix, **{attr: value}).first()
+
+
+# The End

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/treenode/models/mixins/siblings.py

@@ -99,4 +99,4 @@ class TreeNodeSiblingsMixin(models.Model):
         qs = self._meta.model.objects.filter(parent_id=self._parent_id)
         return qs.last()
 
-# The End
+# The End

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/treenode/models/models.py

@@ -45,8 +45,9 @@ class TreeNodeModel(
         mx.TreeNodeAncestorsMixin, mx.TreeNodeChildrenMixin,
         mx.TreeNodeFamilyMixin, mx.TreeNodeDescendantsMixin,
         mx.TreeNodeLogicalMixin, mx.TreeNodeNodeMixin,
-        mx.TreeNodePropertiesMixin, mx.TreeNodeRootsMixin,
-        mx.TreeNodeSiblingsMixin, mx.TreeNodeTreeMixin, mx.RawSQLMixin,
+        mx.TreeNodeSearchMixin, mx.TreeNodePropertiesMixin,
+        mx.TreeNodeRootsMixin, mx.TreeNodeSiblingsMixin,
+        mx.TreeNodeTreeMixin, mx.RawSQLMixin,
         models.Model, metaclass=TreeNodeModelBase):
     """
     Abstract tree node model.
@@ -186,6 +187,7 @@ class TreeNodeModel(
         is_new = False
         is_shift = False
         is_move = False
+        sorting_changed = False
 
         if self.pk:
             state = self.get_db_state()
@@ -194,6 +196,14 @@ class TreeNodeModel(
                 is_move = self.parent_id != state["parent_id"]
                 if is_move:
                     self._meta.model.tasks.add("update", state["parent_id"])
+
+                if self.sorting_field != "priority":
+                    old_value = self.__class__.objects.filter(
+                        pk=self.pk
+                    ).values_list(self.sorting_field, flat=True).first()
+                    sorting_changed = old_value != getattr(
+                        self, self.sorting_field
+                    )
             else:
                 logger.error(
                     "TreeNodeModel save error: object with pk %s not found in DB",
@@ -231,12 +241,14 @@ class TreeNodeModel(
             pass
         """
 
-        if is_new or is_move or is_shift:
+        if is_new or is_move or is_shift or sorting_changed:
             # Step 1: Shift siblings
             if (is_new or is_move) and (self.priority is not None):
                 self._shift_siblings_forward()
             # Step 2: Update paths for the new parent -> sqlq
-            self._meta.model.tasks.add("update", self.parent_id)
+            path_ids = self.query.get_relative_pks(objects="ancestors", include_self=True)
+            update_root_id = path_ids[0] if path_ids else self.parent_id
+            self._meta.model.tasks.add("update", update_root_id)
             # Step 3: Clear model cache
             self.clear_cache()
 
@@ -245,7 +257,7 @@ class TreeNodeModel(
               disable_signals(post_save, model)):
             super().save(*args, **kwargs)
 
-            if is_new or is_move or is_shift:
+            if is_new or is_move or is_shift or sorting_changed:
                 # Run sql
                 # self.sqlq.flush()
                 setattr(model, 'is_dry', True)

django_fast_treenode-3.2.1/treenode/utils/db/compiler.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+"""
+Tree update task compiler class.
+
+Compiles tasks to low-level SQL to update the materialized path (_path), depth
+(_depth), and node order (priority) when they are shifted or moved.
+
+Version: 3.1.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+from django.db import connection
+
+from ...settings import SEGMENT_LENGTH
+from .sqlcompat import SQLCompat
+
+
+class TreePathCompiler:
+    """
+    Tree Task compiler class.
+
+    Efficient, ORM-free computation of _path, _depth and priority
+    for tree structures based on Materialized Path.
+    """
+
+    @classmethod
+    def update_path(cls, model, parent_id=None):
+        """Rebuild subtree using BFS so parents update before children."""
+        table = model._meta.db_table
+        sort_field = model.sorting_field
+
+        def fetch_children(pid):
+            if pid is None:
+                where = "parent_id IS NULL"
+                params = []
+            else:
+                where = "parent_id = %s"
+                params = [pid]
+            with connection.cursor() as cursor:
+                cursor.execute(
+                    f"SELECT id FROM {table} WHERE {where} ORDER BY {sort_field}, id",
+                    params,
+                )
+                return [row[0] for row in cursor.fetchall()]
+
+        queue = []
+
+        if parent_id is None:
+            for idx, node_id in enumerate(fetch_children(None)):
+                queue.append((node_id, "", 0, idx))
+        else:
+            parent_data = model.objects.filter(pk=parent_id).values("_path", "_depth").first()
+            parent_path = parent_data["_path"] if parent_data else ""
+            depth = (parent_data["_depth"] + 1) if parent_data else 0
+            for idx, node_id in enumerate(fetch_children(parent_id)):
+                queue.append((node_id, parent_path, depth, idx))
+
+        while queue:
+            node_id, base_path, depth, index = queue.pop(0)
+            segment = f"{index:0{SEGMENT_LENGTH}X}"
+            path = segment if base_path == "" else f"{base_path}.{segment}"
+            with connection.cursor() as cursor:
+                cursor.execute(
+                    f"UPDATE {table} SET priority=%s, _path=%s, _depth=%s WHERE id=%s",
+                    [index, path, depth, node_id],
+                )
+            for child_idx, child_id in enumerate(fetch_children(node_id)):
+                queue.append((child_id, path, depth + 1, child_idx))
+
+
+# The End

{django_fast_treenode-3.2.0 → django_fast_treenode-3.2.1}/treenode/version.py

@@ -4,9 +4,9 @@ TreeNode Version Module
 
 This module defines the current version of the TreeNode package.
 
-Version: 3.2.0
+Version: 3.2.1
 Author: Timur Kady
 Email: timurkady@yandex.com
 """
 
-__version__ = '3.2.0'
+__version__ = '3.2.1'

django_fast_treenode-3.2.0/treenode/utils/db/compiler.py

@@ -1,113 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-Tree update task compiler class.
-
-Compiles tasks to low-level SQL to update the materialized path (_path), depth
-(_depth), and node order (priority) when they are shifted or moved.
-
-Version: 3.1.0
-Author: Timur Kady
-Email: timurkady@yandex.com
-"""
-
-from django.db import connection
-
-from ...settings import SEGMENT_LENGTH
-from .sqlcompat import SQLCompat
-
-
-class TreePathCompiler:
-    """
-    Tree Task compiler class.
-
-    Efficient, ORM-free computation of _path, _depth and priority
-    for tree structures based on Materialized Path.
-    """
-
-    @classmethod
-    def update_path(cls, model, parent_id=None):
-        """
-        Rebuild subtree starting from parent_id.
-
-        If parent_id=None, then the whole tree is rebuilt.
-        Uses only fields: parent_id and id. All others (priority, _path,
-        _depth) are recalculated.
-        """
-        db_table = model._meta.db_table
-        # Will eliminate the risk if the user names the model order or user.
-        qname = connection.ops.quote_name(db_table)
-
-        sorting_field = model.sorting_field
-        sorting_fields = ["priority", "id"] if sorting_field == "priority" else [sorting_field]  # noqa: D5017
-        sort_expr = ", ".join([
-            f"c.{field}" if "." not in field else field
-            for field in sorting_fields
-        ])
-
-        cte_header = "(id, parent_id, new_priority, new_path, new_depth)"
-
-        row_number_expr = f"ROW_NUMBER() OVER (ORDER BY {sort_expr}) - 1"
-        hex_expr = SQLCompat.to_hex(row_number_expr)
-        lpad_expr = SQLCompat.lpad(hex_expr, SEGMENT_LENGTH, "'0'")
-
-        if parent_id is None:
-            new_path_expr = lpad_expr
-            base_sql = f"""
-                SELECT
-                    c.id,
-                    c.parent_id,
-                    {row_number_expr} AS new_priority,
-                    {new_path_expr} AS new_path,
-                    0 AS new_depth
-                FROM {qname} AS c
-                WHERE c.parent_id IS NULL
-            """
-            params = []
-        else:
-            path_expr = SQLCompat.concat("p._path", "'.'", lpad_expr)
-            base_sql = f"""
-                SELECT
-                    c.id,
-                    c.parent_id,
-                    {row_number_expr} AS new_priority,
-                    {path_expr} AS new_path,
-                    p._depth + 1 AS new_depth
-                FROM {qname} c
-                JOIN {qname} p ON c.parent_id = p.id
-                WHERE p.id = %s
-            """
-            params = [parent_id]
-
-        recursive_row_number_expr = f"ROW_NUMBER() OVER (PARTITION BY c.parent_id ORDER BY {sort_expr}) - 1"
-        recursive_hex_expr = SQLCompat.to_hex(recursive_row_number_expr)
-        recursive_lpad_expr = SQLCompat.lpad(
-            recursive_hex_expr, SEGMENT_LENGTH, "'0'")
-        recursive_path_expr = SQLCompat.concat(
-            "t.new_path", "'.'", recursive_lpad_expr)
-
-        recursive_sql = f"""
-            SELECT
-                c.id,
-                c.parent_id,
-                {recursive_row_number_expr} AS new_priority,
-                {recursive_path_expr} AS new_path,
-                t.new_depth + 1 AS new_depth
-            FROM {qname} c
-            JOIN tree_cte t ON c.parent_id = t.id
-        """
-
-        final_sql = SQLCompat.update_from(
-            db_table=db_table,
-            cte_header=cte_header,
-            base_sql=base_sql,
-            recursive_sql=recursive_sql,
-            update_fields=["priority", "_path", "_depth"]
-        )
-
-        with connection.cursor() as cursor:
-            # Make params read-only
-            params = tuple(params)
-            cursor.execute(final_sql, params)
-
-
-# The End