django-fast-treenode 2.1.2__tar.gz → 2.1.3__tar.gz

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/MANIFEST.in

@@ -3,3 +3,4 @@ include README.md
 recursive-include treenode/static *
 recursive-include treenode/templates *
 recursive-include docs *
+

{django_fast_treenode-2.1.2/django_fast_treenode.egg-info → django_fast_treenode-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: django-fast-treenode
-Version: 2.1.2
+Version: 2.1.3
 Summary: Application for supporting tree (hierarchical) data structure in Django projects
 Home-page: https://django-fast-treenode.readthedocs.io/
 Author: Timur Kady
@@ -63,6 +63,10 @@ Requires-Dist: xlsxwriter; extra == "import-export"
 # Django-fast-treenode 
 **Combining Adjacency List and Closure Table for Optimal Performance**
 
+[![Tests](https://github.com/TimurKady/django-fast-treenode/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/TimurKady/django-fast-treenode/actions/workflows/test.yaml)
+[![Docs](https://readthedocs.org/projects/django-fast-treenode/badge/?version=latest)](https://django-fast-treenode.readthedocs.io/)
+[![PyPI](https://img.shields.io/pypi/v/django-fast-treenode.svg)](https://pypi.org/project/django-fast-treenode/)
+[![Published on Django Packages](https://img.shields.io/badge/Published%20on-Django%20Packages-0c3c26)](https://djangopackages.org/packages/p/django-fast-treenode/)
 
 **Django Fast TreeNode** is a high-performance Django application for working with tree structures, combining **Adjacency List** and **Closure Table** models. Each **TreeNodeModel** instance maintains two synchronized tables, enabling most operations to be performed with a single database query.
 

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/README.md

@@ -1,6 +1,10 @@
 # Django-fast-treenode 
 **Combining Adjacency List and Closure Table for Optimal Performance**
 
+[![Tests](https://github.com/TimurKady/django-fast-treenode/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/TimurKady/django-fast-treenode/actions/workflows/test.yaml)
+[![Docs](https://readthedocs.org/projects/django-fast-treenode/badge/?version=latest)](https://django-fast-treenode.readthedocs.io/)
+[![PyPI](https://img.shields.io/pypi/v/django-fast-treenode.svg)](https://pypi.org/project/django-fast-treenode/)
+[![Published on Django Packages](https://img.shields.io/badge/Published%20on-Django%20Packages-0c3c26)](https://djangopackages.org/packages/p/django-fast-treenode/)
 
 **Django Fast TreeNode** is a high-performance Django application for working with tree structures, combining **Adjacency List** and **Closure Table** models. Each **TreeNodeModel** instance maintains two synchronized tables, enabling most operations to be performed with a single database query.
 

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3/django_fast_treenode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: django-fast-treenode
-Version: 2.1.2
+Version: 2.1.3
 Summary: Application for supporting tree (hierarchical) data structure in Django projects
 Home-page: https://django-fast-treenode.readthedocs.io/
 Author: Timur Kady
@@ -63,6 +63,10 @@ Requires-Dist: xlsxwriter; extra == "import-export"
 # Django-fast-treenode 
 **Combining Adjacency List and Closure Table for Optimal Performance**
 
+[![Tests](https://github.com/TimurKady/django-fast-treenode/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/TimurKady/django-fast-treenode/actions/workflows/test.yaml)
+[![Docs](https://readthedocs.org/projects/django-fast-treenode/badge/?version=latest)](https://django-fast-treenode.readthedocs.io/)
+[![PyPI](https://img.shields.io/pypi/v/django-fast-treenode.svg)](https://pypi.org/project/django-fast-treenode/)
+[![Published on Django Packages](https://img.shields.io/badge/Published%20on-Django%20Packages-0c3c26)](https://djangopackages.org/packages/p/django-fast-treenode/)
 
 **Django Fast TreeNode** is a high-performance Django application for working with tree structures, combining **Adjacency List** and **Closure Table** models. Each **TreeNodeModel** instance maintains two synchronized tables, enabling most operations to be performed with a single database query.
 

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/django_fast_treenode.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ docs/migration.md
 docs/models.md
 docs/requirements.txt
 docs/roadmap.md
+tests/test_suite.py
 treenode/__init__.py
 treenode/apps.py
 treenode/cache.py
@@ -72,7 +73,6 @@ treenode/templates/admin/tree_node_import_report.html
 treenode/templates/admin/treenode_ajax_rows.html
 treenode/templates/widgets/tree_widget.css
 treenode/templates/widgets/tree_widget.html
-treenode/tests/tests.py
 treenode/utils/__init__.py
 treenode/utils/aid.py
 treenode/utils/base16.py

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/docs/about.md

@@ -1,31 +1,36 @@
 ## About the project
 ### The Debut Idea
+
 The idea of ​​this package belongs to **[Fabio Caccamo](https://github.com/fabiocaccamo)**. His idea was to use the **Adjacency List** method to store the data tree. The most probable and time-consuming requests are calculated in advance and stored in the database. Also, most requests are cached. As a result, query processing is carried out in one call to the database or without it at all.
 
 The original application **[django-treenode](https://github.com/fabiocaccamo/django-treenode)** has significant advantages over other analogues, and indeed, is one of the best implementations of support for hierarchical structures for Django.
 
 However, this application has a number of undeniable shortcomings:
-* the selected pre-calculations scheme entails high costs for adding a new element;
-* inserting new elements uses signals, which leads to failures when using bulk-operations;
-* the problem of ordering elements by priority inside the parent node has not been resolved.
+
+- the selected pre-calculations scheme entails high costs for adding a new element;
+- inserting new elements uses signals, which leads to failures when using bulk-operations;
+- the problem of ordering elements by priority inside the parent node has not been resolved.
 
 That is, an excellent debut idea, in my humble opinion, should have been improved.
 
 ### The Development of the Idea
+
 My idea was to solve these problems by combining the **Adjacency List** with the **Closure Table**. Main advantages:
-* the Closure Model is generated automatically;
-* maintained compatibility with the original package at the level of documented functions;
-* most requests are satisfied in one call to the database;
-* inserting a new element takes two calls to the database without signals usage;
-* bulk-operations are supported;
-* the cost of creating a new dependency is reduced many times;
-* useful functionality added for some methods (e.g.  the `include_self=False` and `depth` parameters has been added to functions that return lists/querysets);
-* additionally, the package includes a tree view widget for the `tn_parent` field in the change form.
+
+- the Closure Model is generated automatically;
+- maintained compatibility with the original package at the level of documented functions;
+- most requests are satisfied in one call to the database;
+- inserting a new element takes two calls to the database without signals usage;
+- bulk-operations are supported;
+- the cost of creating a new dependency is reduced many times;
+- useful functionality added for some methods (e.g.  the `include_self=False` and `depth` parameters has been added to functions that return lists/querysets);
+- additionally, the package includes a tree view widget for the `tn_parent` field in the change form.
 
 Of course, at large levels of nesting, the use of the Closure Table leads to an increase in resource costs. However, the combined approach still outperforms both the original application and other available Django solutions in terms of performance, especially in large trees with over 100k nodes.
 
 ### The Theory
 You can get a basic understanding of what is a **Closure Table** from:
+
 * [presentation](https://www.slideshare.net/billkarwin/models-for-hierarchical-data) by **Bill Karwin**;
 * [article](https://dirtsimple.org/2010/11/simplest-way-to-do-tree-based-queries.html) by blogger **Dirt Simple**;
 * [article](https://towardsdatascience.com/closure-table-pattern-to-model-hierarchies-in-nosql-c1be6a87e05b) by **Andriy Zabavskyy**.
@@ -33,4 +38,6 @@ You can get a basic understanding of what is a **Closure Table** from:
 You can easily find additional information on your own on the Internet.
 
 ### Our days
-Over the course of development, the package has undergone significant improvements, with a strong emphasis on performance optimization, database efficiency, and seamless integration with Django’s admin interface. The introduction of a hybrid model combining **Adjacency List** and **Closure Table** has substantially reduced query overhead, improved scalability, and enhanced flexibility when managing hierarchical data. These advancements have made the package not only a powerful but also a practical solution for working with large tree structures. Moving forward, the project will continue to evolve, focusing on refining caching mechanisms, expanding compatibility with Django’s ecosystem, and introducing further optimizations to ensure maximum efficiency and ease of use.
+Over the course of development, the package has undergone significant improvements, with a strong emphasis on performance optimization, database efficiency, and seamless integration with Django’s admin interface. 
+
+The introduction of a hybrid model combining **Adjacency List** and **Closure Table** has substantially reduced query overhead, improved scalability, and enhanced flexibility when managing hierarchical data. These advancements have made the package not only a powerful but also a practical solution for working with large tree structures. Moving forward, the project will continue to evolve, focusing on refining caching mechanisms, expanding compatibility with Django’s ecosystem, and introducing further optimizations to ensure maximum efficiency and ease of use.

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/docs/admin.md

@@ -25,6 +25,7 @@ class CategoryAdmin(TreeNodeModelAdmin):
 The tree structure in the admin panel **loads dynamically as nodes are expanded**. This allows handling **large datasets** efficiently, preventing performance issues.
 
 You can choose from three display modes:
+
 - **`TREENODE_DISPLAY_MODE_ACCORDION` (default)**  
   Expands/collapses nodes dynamically.
 - **`TREENODE_DISPLAY_MODE_BREADCRUMBS`**  
@@ -43,10 +44,11 @@ The search bar helps quickly locate nodes within large trees. As you type, **an
 
 #### Using TreeNodeForm
 If you need to customize forms for tree-based models, inherit from `TreeNodeForm`. It provides:
+
 - A **custom tree widget** for selecting parent nodes.
 - Automatic **exclusion of self and descendants** from the parent selection to prevent circular references.
 
-##### `forms.py`:
+##### forms.py:
 ```python
 from treenode.forms import TreeNodeForm
 from .models import Category
@@ -59,6 +61,7 @@ class CategoryForm(TreeNodeForm):
 ```
 
 Key Considerations:
+
 - This form automatically ensures that **a node cannot be its own parent**.
 - It uses **`TreeWidget`**, a custom hierarchical dropdown for selecting parent nodes.
 - If you need a form for another tree-based model, use the **dynamic factory method**:
@@ -75,7 +78,7 @@ This method ensures that the form correctly associates with different tree model
 #### The TreeWidget Class
 The `TreeWidget` class is a **custom Select2-like widget** that enables hierarchical selection in forms. While it is used inside the Django admin panel by default, it can **also be used in regular forms** outside the admin panel.
 
-##### `widgets.py`
+##### widgets.py
 
 ```python
 from django import forms
@@ -91,6 +94,7 @@ class CategorySelectionForm(forms.Form):
 ```
 
 Important Notes:
+
 - **Requires jQuery**: The widget relies on AJAX requests, so ensure jQuery is available when using it outside Django’s admin.
 - **Dynamically Fetches Data**: It loads the tree structure asynchronously, preventing performance issues with large datasets.
 - **Customizable Data Source**: The `data-url` attribute can be adjusted to fetch tree data from a custom endpoint.

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/docs/api.md

@@ -94,6 +94,7 @@ These methods are designed to manage **direct child nodes** within the tree stru
 obj.add_child(position=None, **kwargs)
 ```
 `position` specifies the order position of the object being added in the list of children of this node. It can be `'first-child'`, `'last-child'`, `'sorted-child'`, or an integer value.
+
 The `**kwargs` parameters contain the object creation data that will be passed to the inherited node model. Instead of passing the object creation data, you can pass an already created (but not yet saved) model instance to insert into the tree using the `instance` keyword.
 
 ```python
@@ -201,10 +202,10 @@ obj.get_family()
 ### Node Utility Methods
 This set of methods helps manage node-related operations such as:
 
-- **Breadcrumbs generation**
-- **Depth, index, and level calculations**
-- **Materialized path retrieval for sorting**
-- **Dynamic node positioning within the tree** 
+- Breadcrumbs generation
+- Depth, index, and level calculations
+- Materialized path retrieval for sorting
+- Dynamic node positioning within the tree 
 
 #### get_breadcrumbs
 Returns the **breadcrumbs** to current node (included):
@@ -246,19 +247,20 @@ obj.insert_at(target, position='first-child', save=False)
 ```
 
 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.
+    - `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.
@@ -268,9 +270,11 @@ Moves the model instance relative to the target node and sets its position (if n
 ```python
 obj.move_to(target, position=0)
 ```
+
 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. For detals see [insert_at](#insert_at) method.
+
+- `target`: the 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. For detals see [insert_at](#insert_at) method.
 
 #### get_path
 Returns Materialized Path of node. The materialized path is constructed by recording the position of each node within its parent's list of children, tracing this sequence back through all its ancestors.
@@ -538,6 +542,7 @@ Something like this will be returned:
 All nodes are ordered by materialized path. 
 
 This can be used with a template like this:
+
 ```html
 {% for item, info in annotated_list %}
     {% if info.open %}
@@ -546,7 +551,7 @@ This can be used with a template like this:
         </li><li>
     {% endif %}
 
-{{ item }}
+        {{ item }}
 
     {% for close in info.close %}
         </li></ul>
@@ -663,7 +668,7 @@ Returns the children pks list. See [`get_children_pks()`](#get_children_pks) met
 #### obj.depth
 Returns the node depth. See [`get_depth()`](#get_depth) method.
 
-### obj.descendants:
+#### obj.descendants:
 Returns a list containing all descendants (itself is not included). See [`get_descendants()`](#get_descendants) method.
 
 #### obj.descendants_count
@@ -693,7 +698,7 @@ Returns node parent pk. See [`get_parent_pk()`](#get_parent_pk) method.
 #### obj.priority
 Returns node oder position (priority). See [`get_priority()`](#get_priority) method.
 
-### cls.roots
+#### cls.roots
 Returns a list with all root nodes. See [`get_roots()`](#get_roots) method.
 
 #### obj.root

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/docs/cache.md

@@ -27,6 +27,7 @@ TREENODE_CACHE_LIMIT = 100
 **Automatic Management**. In most cases, users don’t need to manually manage cache operations.All methods that somehow change the state of models reset the tree cache automatically.
 
 **Manual Cache Clearing**. If for some reason you need to reset the cache, you can do it in two ways:
+
 - **Clear cache for a single model**: Use `clear_cache()` at the model level:
     ```python
     MyTreeNodeModel.clear_cache()
@@ -116,6 +117,7 @@ treenode_cache.clear()
 This completely resets the cache, removing **all stored values**.
 
 Best Practices:
+
 - **Always use `generate_cache_key()`** instead of hardcoding cache keys to ensure consistency.
 - **Use `invalidate()` instead of `clear()`** when targeting a specific model’s cache.
 - **Apply `@cached_method` wisely**, ensuring it is used **only for** `TreeNodeModel`-based methods to avoid conflicts.
@@ -137,6 +139,7 @@ The cache is now divided into two queues:
 - **LRU (20%-30%)** – for frequently accessed objects (Least Recently Used).
 
 How it works:
+
 - If tree queries are evenly distributed, the cache behaves like a standard FIFO.
 - If certain nodes receive frequent queries, those records automatically move to LRU, reducing database load.
 
@@ -145,10 +148,12 @@ How it works:
 Each new entry initially goes into **FIFO**. If accessed **more than N times**, it moves to **LRU**, where it remains longer.
 
 **How N is determined:**
+
 - A threshold is set based on **mathematical statistics**: N = 1 / sqrt(2).
 - An absolute threshold limit is added.
 
 **LRU Behavior:**
+
 - When accessed, a record moves to the top of the list.
 - New records are also placed at the top.
 - If LRU reaches capacity, **the evicted record returns to FIFO** instead of being deleted.
@@ -162,11 +167,13 @@ When data is modified or deleted, the cache **automatically resets** to prevent
 To automatically clear outdated records, an **adaptive mechanism** is used. Instead of a static TTL, the **DTT parameter** is dynamically calculated based on **Poisson distribution**.
 
 How DTT is calculated:
+
 1. Compute the **average interval between queries (T)**: ``` T = (1/N) * Σ (t_i - t_(i-1)), i=1...N```
 2. Store **averaged value** `ΣΔt / N`
 3. Set **DTT = 3T**, which removes **95% of infrequent queries**.
 
 **Why this is better than a fixed TTL:**
+
 - If queries are rare → DTT **increases**, preventing premature deletions.
 - If queries are frequent → DTT **decreases**, accelerating cache clearing.
 

django_fast_treenode-2.1.3/docs/index.md

@@ -0,0 +1,95 @@
+# Django Fast TreeNode
+**A Powerful Solution for Hierarchical Data Management**
+
+Welcome to the **django-fast-treenode** documentation!
+
+## Overview
+
+**Django Fast TreeNode** is a specialized Django package designed to efficiently handle hierarchical data structures. It leverages **combining Adjacency List and Closure Table** to optimize querying and management of tree-like structures, making it an excellent choice for applications that require fast traversal, retrieval, and manipulation of nested relationships.
+
+The package is particularly useful in scenarios such as:
+
+- **Categories and taxonomies**: Manage product categories, tags, and classification systems.
+- **Menus and navigation**: Create tree-like menus and nested navigation structures.
+- **Forums and comments**: Store threaded discussions and nested comment chains.
+- **Geographical data**: Represent administrative divisions, regions, and areas of influence.
+- **Organizational and Business Structures**: Model company hierarchies, business processes, employees and departments.
+
+**django-fast-treenode** models show excellent **performance** and **stability** in all applications.
+
+## Key Features
+
+1. **Efficient Tree Operations**:
+    * Supports fast retrieval of ancestors, descendants, and siblings.
+    * Uses a **closure table approach** for optimal query performance.
+
+2. **Django ORM Integration**:
+    * Extends Django’s `models.Model`, making it easy to integrate into existing applications.
+    * Custom manager (`TreeNodeManager`) provides useful tree-related query optimizations.
+
+
+3. **Query Optimization via Closure Table**
+    * Instead of naive recursive queries, the package precomputes relationships in a separate closure table.This allows you to run constant-time queries for retrieval using a **single database query**:
+        * Ancestors (`get_ancestors()`),
+        * Depth (`det_depth()`),
+        * Descendants (`get_descendants()`),
+        * Family (`get_family()`),
+        * Materialized Path(`get_breadcrumbs()` and `get_path()`),
+        * Roots (`get_root()`),
+        * Siblings (`get_siblings()`) and so on.
+
+4. **Automatic Ordering and Priority Management**:
+    * Nodes can be assigned priority values for custom sorting.
+    * Provides automatic ordering based on a **materialized path**.
+
+5. **Admin Interface Enhancements**:
+    * Supports multiple tree display modes in the Django Admin:
+        * **Indentation mode** (classic hierarchical view)
+        * **Breadcrumbs mode** (for easy navigation)
+        * **Accordion mode** (collapsible structures)
+    * Uses a **custom admin widget** (`TreeWidget`) to enhance usability.
+
+
+6. **Caching for Performance**:
+    * Uses Django’s caching framework to optimize frequently accessed tree operations.
+    * Cached tree methods reduce redundant computations.
+
+
+7. **Bulk Operations Support**:
+    * Implements efficient **bulk creation** of nodes.
+    * Provides methods for **batch updates** and **tree rebuilding**.
+
+By leveraging combining with Closure Tables, it offers superior performance compared to traditional tree structures.
+
+## Use Cases and Benefits
+
+### When to Use Django Fast TreeNode?
+- **You need a nested structure with frequent reads**: Closure tables provide **fast lookups** compared to recursive Common Table Expressions (CTEs).
+- **You want an easy-to-use Django model**: The package **extends Django ORM** and integrates seamlessly.
+- **You require hierarchical display in Django Admin**: The **custom admin integration** makes managing trees much easier.
+
+### Benefits Over Other Approaches
+- **Better than adjacency lists** (which require multiple queries for deep trees).
+- **More efficient than recursive queries** (which can be slow on large datasets).
+- **Scalable for large trees** (by leveraging precomputed paths and caching).
+
+Django Fast TreeNode is a powerful and efficient package for managing hierarchical data in Django applications. Its seamless ORM integration and Django Admin support make it a great choice for developers looking to implement **fast, scalable** tree-based data structures.
+
+## Contents
+- [About the Project](about.md)
+- [Installation, Configuration, and Fine-Tuning](installation.md)
+- [Model Inheritance and Extensions](models.md)
+- [Working with Admin Classes](admin.md)
+- [API Reference](api.md)
+- [Import & Export](import_export.md)
+- [Caching and Cache Management](cache.md)
+- [Migration and Upgrade Guide](migration.md)
+- [Roadmap](roadmap.md)
+
+## Links
+- [Issues](https://github.com/TimurKady/django-fast-treenode/issues)
+- [Pull Requests](https://github.com/TimurKady/django-fast-treenode/pulls)
+- [Discussions](https://github.com/TimurKady/django-fast-treenode/discussions)
+
+## License
+Released under the [MIT License](https://github.com/TimurKady/django-fast-treenode/blob/main/LICENSE).

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/docs/migration.md

@@ -111,7 +111,7 @@ The `django-fast-treenode` package contains the full set of methods you are used
 
 |**django-treebeard** | **django-fast-treenode** |**Features of use**|
 |---------------------|----------------------|----------------------|
-| The `pos` parameter in `add_sibling()` and `move()` methods |  The parameter `pos` has the name `position` | • The `position` parameter in `django-fast-treenode` always consists of two parts separated by `-`: the first part determines the insertion method (_first, left, right, last, sorted_), the second — the placement type (_child, sibling_). <br> • Instead of a string format, you can also pass position as an integer indicating the exact position of the node in the list.|
+| The `pos` parameter in `add_sibling()` and `move()` methods |  The parameter `pos` has the name `position` | • The `position` parameter in `django-fast-treenode` always consists of two parts separated by <br>`-`: the first part determines the insertion method (_first, left, right, last, sorted_), the second — the placement type (_child, sibling_). <br> • Instead of a string format, you can also pass position as an integer indicating the exact position of the node in the list.|
 |`get_siblings()`, `get_ancestors()` end ect. | Similar methods have parameters `include_self` and `depth` |• The `include_self` parameter specifies whether to include the node itself in the selection. <br> • The  `depth` parameter specifies the depth of the search. |
 |`move(target, pos)` metiod| The method `move()` has the name `move_to(target, position)` | - |
 

django_fast_treenode-2.1.3/docs/roadmap.md

@@ -0,0 +1,63 @@
+## Roadmap
+
+### Last Update
+The latest version provides optimized database operations, an improved caching mechanism, and enhanced integration capabilities, making it a **robust and efficient choice** for handling tree structures.
+
+**Version 2.1 – Compatibility and Optimization**
+Reducing dependencies and simplifying migration from other libraries.
+
+- **Expanding functionality** to simplify migration from other tree packages.
+- Introducing node **filtering and search with AJAX**.
+- **Optimizing query performance** by reducing query complexity and improving indexing strategies.
+- **Reducing database load** from the `TreeNodeAdmin` when working with large trees.
+- Removing `numpy` in favor of lighter alternatives.
+- Removing `Select2` in favor of light custom select2-like implementation.
+
+
+### Planned Roadmap for Future Versions
+The **django-fast-treenode** package will continue to evolve from its original concept—combining the benefits of the **Adjacency List** and **Closure Table** models—into a high-performance solution for managing and visualizing hierarchical data in Django projects. The focus is on **speed, usability, and flexibility**.
+
+#### Version 2.2 – Performance Enhancements
+Focusing on optimizing query efficiency, reducing database load, and improving API interactions.
+
+- **Optimized Query Execution**: Minimize query overhead by restructuring SQL operations, reducing redundant lookups, and introducing batched operations for bulk inserts.
+- **API-First CRUD Implementation**: Introduce full Create, Read, Update, and Delete (CRUD) operations for tree structures, ensuring seamless API-based interaction with hierarchical data.
+- **Efficient Serialization**: Develop a lightweight tree serialization format optimized for API responses, reducing payload size while preserving structural integrity.
+- **Advanced Node Filtering & Search**: Implement AJAX-based filtering and search mechanisms in Django Admin and API endpoints to enhance usability and response time.
+
+#### Version 2.3 – Drag-and-Drop and Admin UI Improvements
+Improving the usability and management of hierarchical structures in Django Admin.
+
+- **Drag-and-Drop Node Reordering**: Introduce interactive drag-and-drop functionality for reordering nodes within the tree structure directly in Django Admin.
+- **Hierarchical Sorting Strategies**: Enable various sorting methods, including manual ordering, weight-based prioritization, and hybrid approaches that combine automatic and manual sorting.
+- **Admin Panel Enhancements**: Expand Django Admin capabilities for tree structures, including better visualization, inline node editing, and bulk actions.
+
+#### Version 3.0 – Third-Generation Cache Management System
+Introducing a more advanced caching system to improve scalability and efficiency.
+
+- **Two-Level FIFO/LRU Cache**: Implement a hybrid caching mechanism combining First-In-First-Out (FIFO) and Least Recently Used (LRU) strategies to optimize cache retention for tree nodes.
+- **Multi-Process Cache Synchronization**: Ensure cache consistency across different execution environments (WSGI, Gunicorn, Uvicorn) with a distributed synchronization mechanism.
+- **Background Synchronization**: Introduce delayed closure table updates via Celery or RQ, preventing blocking operations while maintaining data consistency.
+
+#### Version 4.0 – Asynchronous Operations
+Refactoring the package to support fully asynchronous operations for non-blocking execution.
+
+- **Asynchronous API Execution**: Convert existing synchronous operations to asynchronous, leveraging `async/await` for improved performance.
+- **Async Database Support**: Implement async-friendly database operations compatible with Django’s evolving asynchronous ORM.
+- **Optimized Tree Node Caching**: Shift from caching precomputed query results to caching raw tree nodes, reducing recomputation overhead and improving retrieval speed.
+- **Asynchronous Testing**: Expand the test suite to cover async behavior and the new caching mechanism under concurrent loads.
+- **Documentation Update**: Revise and expand documentation to reflect changes in the asynchronous execution model and best practices for implementation.
+
+#### Version 5.0 – Beyond Django ORM
+Decoupling tree structure management from Django’s ORM to increase flexibility and adaptability.
+
+- **Multi-Backend Storage Support**: Introduce support for alternative storage engines beyond Django ORM, such as SQLAlchemy, custom PostgreSQL functions, and other database frameworks.
+- **Redis Integration for In-Memory Trees**: Implement an optional Redis-based tree storage system, allowing high-speed in-memory hierarchy operations.
+- **JSON-Based Storage Option**: Enable lightweight embedded tree storage using JSON structures, facilitating easier use in API-driven and microservice architectures.
+- **ORM-Agnostic API Layer**: Design an API-first approach that allows tree structures to function independently from Django models, making the package usable in broader contexts.
+
+So, each milestone is designed to improve performance, scalability, and flexibility, ensuring that the package remains relevant for modern web applications, API-driven architectures, and high-performance data processing environments support.
+
+Stay tuned for updates!
+
+Your wishes, objections, and comments are welcome.

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "django-fast-treenode"
-version = "2.1.2"
+version = "2.1.3"
 description = "Application for supporting tree (hierarchical) data structure in Django projects"
 readme = "README.md"
 authors = [{ name = "Timur Kady", email = "timurkady@yandex.com" }]
@@ -48,3 +48,4 @@ Homepage = "https://github.com/TimurKady/django-fast-treenode"
 Documentation = "https://django-fast-treenode.readthedocs.io/"
 Source = "https://github.com/TimurKady/django-fast-treenode"
 Issues = "https://github.com/TimurKady/django-fast-treenode/issues"
+

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = django-fast-treenode
-version = 2.1.2
+version = 2.1.3
 description = Application for supporting tree (hierarchical) data structure in Django projects
 long_description = file: README.md
 long_description_content_type = text/markdown

django_fast_treenode-2.1.2/treenode/tests/tests.py → django_fast_treenode-2.1.3/tests/test_suite.py

@@ -1,9 +1,18 @@
+import os
+import django
 import time
 import traceback
+from django.db import models
 from django.test import TestCase, TransactionTestCase
-from devapp.models import Entity
+from . import settings
+from .models import TestModel
 
 
+if "DJANGO_SETTINGS_MODULE" not in os.environ:
+    os.environ["DJANGO_SETTINGS_MODULE"] = "tests.settings"
+
+django.setup()
+
 class BasicOperationsTest(TestCase):
     """
     Tests basic operations with nodes: insertion (using three methods), deletion,
@@ -16,7 +25,7 @@ class BasicOperationsTest(TestCase):
 
         # 1. Insertion via node.save()
         try:
-            node1 = Entity(name='Node via save()')
+            node1 = TestModel(name='Node via save()')
             node1.save()
             if not node1.pk:
                 errors.append("Insertion via save() did not assign a PK.")
@@ -25,7 +34,7 @@ class BasicOperationsTest(TestCase):
 
         # 2. Insertion via objects.create()
         try:
-            node2 = Entity.objects.create(name='Node via create()')
+            node2 = TestModel.objects.create(name='Node via create()')
             if not node1.pk:
                 errors.append(
                     "Insertion via objects.create() did not assign a PK.")
@@ -36,11 +45,11 @@ class BasicOperationsTest(TestCase):
         # 3. Alternative method (insert_at or get_or_create)
         try:
             # For demonstration, use node1 as the parent if the insert_at method exists
-            if hasattr(Entity, 'insert_at'):
-                node3 = Entity(name='Node via insert_at()')
+            if hasattr(TestModel, 'insert_at'):
+                node3 = TestModel(name='Node via insert_at()')
                 node3.insert_at(node1)
-            elif hasattr(Entity.objects, 'get_or_create'):
-                node3, created = Entity.objects.get_or_create(
+            elif hasattr(TestModel.objects, 'get_or_create'):
+                node3, created = TestModel.objects.get_or_create(
                     name='Node via get_or_create()', defaults={'tn_parent': node1})
             else:
                 errors.append(
@@ -52,8 +61,8 @@ class BasicOperationsTest(TestCase):
         # Checking access methods (e.g. get_children)
         try:
             # Create a small tree
-            root = Entity.objects.create(name='Root')
-            child = Entity.objects.create(name='Child', tn_parent=root)
+            root = TestModel.objects.create(name='Root')
+            child = TestModel.objects.create(name='Child', tn_parent=root)
             # If the model defines a get_children() method, check its functionality
             if hasattr(root, 'get_children'):
                 children = root.get_children()
@@ -62,7 +71,7 @@ class BasicOperationsTest(TestCase):
                         "Method get_children() did not return the added child.")
             else:
                 # If the method does not exist, perform a simple filter by parent
-                children = Entity.objects.filter(tn_parent=root)
+                children = TestModel.objects.filter(tn_parent=root)
                 if child not in children:
                     errors.append(
                         "Filter by parent did not return the added child.")
@@ -99,25 +108,24 @@ class DeepTreePerformanceTest(TransactionTestCase):
         try:
             # Insertion of the root node
             start = time.time()
-            root = Entity.objects.create(name="Deep Root")
+            root = TestModel.objects.create(name="Deep Root")
             end = time.time()
             timings[0] = end - start
             nodes.append(root)
 
             current_parent = root
 
-            for level in range(1, 201):
+            for level in range(1, 101):
                 start = time.time()
-                new_node = Entity.objects.create(
+                new_node = TestModel.objects.create(
                     name=f"Node Level {level}", tn_parent=current_parent)
                 end = time.time()
                 timings[level] = end - start
                 nodes.append(new_node)
                 current_parent = new_node  # the next node will be a child of the one just created
 
-            # Generate report for levels: 0, 1, 10, 20, 30, 40, 50, 70, 80, 90, 100, 150, 200
-            levels_to_report = [0, 1, 10, 20, 30,
-                                40, 50, 70, 80, 90, 100, 150, 200]
+            # Generate report for levels: 0, 1, 10, 20, 30, 40, 50, 70, 80, 90, 100
+            levels_to_report = [0, 1, 10, 20, 30,40, 50, 70, 80, 90, 100]
             # to avoid division by zero
             root_time = timings[0] if timings[0] > 0 else 1e-6
             print("Deep tree - node insertion times:")
@@ -154,11 +162,11 @@ class WideTreePerformanceTest(TransactionTestCase):
             # For 100 trees
             for root_index in range(1, 101):
                 tree_start = time.time()
-                root = Entity.objects.create(name=f"Wide Root {root_index}")
+                root = TestModel.objects.create(name=f"Wide Root {root_index}")
                 current_parent = root
                 # Create 5 levels of nesting for each root
                 for level in range(1, 6):
-                    new_node = Entity.objects.create(
+                    new_node = TestModel.objects.create(
                         name=f"Node {root_index}-{level}", tn_parent=current_parent)
                     current_parent = new_node
                 tree_end = time.time()
@@ -190,29 +198,29 @@ class MassInsertionTest(TestCase):
             for i in range(50, 76):
                 # 1. Insertion via save()
                 try:
-                    node = Entity(name=f"Mass Node {i} via save()")
+                    node = TestModel(name=f"Mass Node {i} via save()")
                     node.save()
                 except Exception as e:
                     errors.append(f"Error inserting node {i} via save(): {e}")
 
                 # 2. Insertion via objects.create()
                 try:
-                    Entity.objects.create(name=f"Mass Node {i} via create()")
+                    TestModel.objects.create(name=f"Mass Node {i} via create()")
                 except Exception as e:
                     errors.append(f"Error inserting node {i} via create(): {e}")
 
                 # 3. Alternative method (insert_at or get_or_create)
                 try:
                     # Take the first node in the database or create a parent
-                    parent = Entity.objects.first()
+                    parent = TestModel.objects.first()
                     if not parent:
-                        parent = Entity.objects.create(name="Default Parent")
+                        parent = TestModel.objects.create(name="Default Parent")
 
-                    if hasattr(Entity, 'insert_at'):
-                        node = Entity(name=f"Mass Node {i} via insert_at()")
+                    if hasattr(TestModel, 'insert_at'):
+                        node = TestModel(name=f"Mass Node {i} via insert_at()")
                         node.insert_at(parent)
-                    elif hasattr(Entity.objects, 'get_or_create'):
-                        Entity.objects.get_or_create(
+                    elif hasattr(TestModel.objects, 'get_or_create'):
+                        TestModel.objects.get_or_create(
                             name=f"Mass Node {i} via get_or_create()", defaults={'tn_parent': parent})
                     else:
                         errors.append(
@@ -246,20 +254,20 @@ class NodeDeletionTest(TestCase):
         errors = []
         print("\n=== NodeDeletionTest ===")
         try:
-            parent = Entity.objects.create(name="Deletion Parent")
-            child1 = Entity.objects.create(name="Child 1", tn_parent=parent)
-            child2 = Entity.objects.create(name="Child 2", tn_parent=parent)
+            parent = TestModel.objects.create(name="Deletion Parent")
+            child1 = TestModel.objects.create(name="Child 1", tn_parent=parent)
+            child2 = TestModel.objects.create(name="Child 2", tn_parent=parent)
 
             # Delete child1
             child1.delete()
-            remaining_children = Entity.objects.filter(tn_parent=parent)
+            remaining_children = TestModel.objects.filter(tn_parent=parent)
             if child1 in remaining_children:
                 errors.append(
                     "The deleted child1 is still present among the parent's children.")
 
             # Delete the parent and check cascading deletion
             parent.delete()
-            if Entity.objects.filter(pk=child2.pk).exists():
+            if TestModel.objects.filter(pk=child2.pk).exists():
                 errors.append(
                     "Child2 was not deleted after the parent was deleted (cascading deletion was expected).")
         except Exception as e:
@@ -288,17 +296,17 @@ class NodeMovingTest(TestCase):
         errors = []
         print("\n=== NodeMovingTest ===")
         try:
-            parent1 = Entity.objects.create(name="Original Parent")
-            parent2 = Entity.objects.create(name="New Parent")
-            child = Entity.objects.create(
+            parent1 = TestModel.objects.create(name="Original Parent")
+            parent2 = TestModel.objects.create(name="New Parent")
+            child = TestModel.objects.create(
                 name="Movable Child", tn_parent=parent1)
 
             # Moving the node
             child.set_parent(parent2)
             child.save()
 
-            children1 = Entity.objects.filter(tn_parent=parent1)
-            children2 = Entity.objects.filter(tn_parent=parent2)
+            children1 = TestModel.objects.filter(tn_parent=parent1)
+            children2 = TestModel.objects.filter(tn_parent=parent2)
             if child in children1:
                 errors.append(
                     "The node is still present in the original parent's children after moving.")
@@ -330,10 +338,10 @@ class NodeUpdateTest(TestCase):
         errors = []
         print("\n=== NodeUpdateTest ===")
         try:
-            node = Entity.objects.create(name="Original Name")
+            node = TestModel.objects.create(name="Original Name")
             node.name = "Updated Name"
             node.save()
-            updated_node = Entity.objects.get(pk=node.pk)
+            updated_node = TestModel.objects.get(pk=node.pk)
             if updated_node.name != "Updated Name":
                 errors.append("The node's name was not updated correctly.")
         except Exception as e:
@@ -362,12 +370,12 @@ class DataIntegrityTest(TestCase):
         errors = []
         print("\n=== DataIntegrityTest ===")
         try:
-            root = Entity.objects.create(name="Integrity Root")
-            child1 = Entity.objects.create(
+            root = TestModel.objects.create(name="Integrity Root")
+            child1 = TestModel.objects.create(
                 name="Integrity Child 1", tn_parent=root)
-            child2 = Entity.objects.create(
+            child2 = TestModel.objects.create(
                 name="Integrity Child 2", tn_parent=root)
-            grandchild = Entity.objects.create(
+            grandchild = TestModel.objects.create(
                 name="Integrity Grandchild", tn_parent=child1)
 
             # Move child2 under child1
@@ -381,7 +389,7 @@ class DataIntegrityTest(TestCase):
             grandchild.delete()
 
             # Verify relationships
-            root_children = Entity.objects.filter(tn_parent=root)
+            root_children = TestModel.objects.filter(tn_parent=root)
             if child1 not in root_children:
                 errors.append(
                     "Child1 not found among the root node's children.")
@@ -389,12 +397,12 @@ class DataIntegrityTest(TestCase):
                 errors.append(
                     "Child2 is present among the root node's children after moving.")
 
-            child1_children = Entity.objects.filter(tn_parent=child1)
+            child1_children = TestModel.objects.filter(tn_parent=child1)
             if child2 not in child1_children:
                 errors.append(
                     "Child2 not found among child1's children after moving.")
 
-            if Entity.objects.filter(name="Integrity Grandchild").exists():
+            if TestModel.objects.filter(name="Integrity Grandchild").exists():
                 errors.append("Grandchild still exists after deletion.")
         except Exception as e:
             errors.append("Exception in DataIntegrityTest: " + str(e))
@@ -421,14 +429,14 @@ class LargeVolumeTest(TransactionTestCase):
         errors = []
         print("\n=== LargeVolumeTest ===")
         try:
-            initial_count = Entity.objects.count()
+            initial_count = TestModel.objects.count()
             for i in range(1000):
                 try:
-                    Entity.objects.create(name=f"Large Node {i}")
+                    TestModel.objects.create(name=f"Large Node {i}")
                 except Exception as e:
                     errors.append(
                         f"Error inserting node {i} in large data volume: {e}")
-            final_count = Entity.objects.count()
+            final_count = TestModel.objects.count()
             if final_count - initial_count != 1000:
                 errors.append(
                     f"Expected 1000 new nodes, but got {final_count - initial_count}.")
@@ -459,7 +467,7 @@ class InvalidDataTest(TestCase):
         try:
             try:
                 # Attempt to create a node with invalid data
-                Entity.objects.create(name=None)
+                TestModel.objects.create(name=None)
                 errors.append(
                     "Creating a node with None for name did not raise an exception as expected.")
             except Exception:
@@ -468,7 +476,7 @@ class InvalidDataTest(TestCase):
 
             # Additionally, one can test creating a node with an empty string if that is not allowed
             try:
-                node = Entity(name="")
+                node = TestModel(name="")
                 node.save()
                 # If an empty string is allowed, then no error should be recorded
             except Exception as e:

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/treenode/cache.py

@@ -12,7 +12,7 @@ Features:
 - Automatic cache eviction when memory limits are exceeded.
 - Decorator `@cached_method` for caching method results.
 
-Version: 2.0.0
+Version: 2.1.0
 Author: Timur Kady
 Email: timurkady@yandex.com
 """

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/treenode/models/mixins/node.py

@@ -23,7 +23,7 @@ class TreeNodeNodeMixin(models.Model):
         abstract = True
 
     @cached_method
-    def get_breadcrumbs(self, attr='pk'):
+    def get_breadcrumbs(self, attr='id'):
         """Optimized breadcrumbs retrieval with direct cache check."""
         try:
             self._meta.get_field(attr)

{django_fast_treenode-2.1.2 → django_fast_treenode-2.1.3}/treenode/version.py

@@ -10,4 +10,4 @@ Email: timurkady@yandex.com
 """
 
 
-__version__ = '2.1.2'
+__version__ = '2.1.3'

django_fast_treenode-2.1.2/docs/index.md

@@ -1,30 +0,0 @@
-# Django Fast TreeNode
-
-Welcome to the **django-fast-treenode** documentation!
-
-## Key Features
-**django-fast-treenode** is a high-performance solution for managing tree structures in Django.
-
-- **Fast processing** even with deep trees  
-- **Intuitive API** for seamless integration  
-- **Django Admin support** for easy management  
-- **Optimized caching** for enhanced performance  
-
-## Contents
-- [About the Project](about.md)
-- [Installation, Configuration, and Fine-Tuning](installation.md)
-- [Model Inheritance and Extensions](models.md)
-- [Working with Admin Classes](admin.md)
-- [API Reference](api.md)
-- [Import & Export](import_export.md)
-- [Caching and Cache Management](cache.md)
-- [Migration and Upgrade Guide](migration.md)
-- [Roadmap](roadmap.md)
-
-## Links
-- [Issues](https://github.com/TimurKady/django-fast-treenode/issues)
-- [Pull Requests](https://github.com/TimurKady/django-fast-treenode/pulls)
-- [Discussions](https://github.com/TimurKady/django-fast-treenode/discussions)
-
-## License
-Released under the [MIT License](https://github.com/TimurKady/django-fast-treenode/blob/main/LICENSE).

django_fast_treenode-2.1.2/docs/roadmap.md

@@ -1,45 +0,0 @@
-## Roadmap
-The latest version provides optimized database operations, an improved caching mechanism, and enhanced integration capabilities, making it a **robust and efficient choice** for handling tree structures.
-
-But the **django-fast-treenode** package will continue to evolve from its original concept—combining the benefits of the **Adjacency List** and **Closure Table** models—into a high-performance solution for managing and visualizing hierarchical data in Django projects. The focus is on **speed, usability, and flexibility**.
-
-In future versions, I plan to implement:
-
-### **Version 2.1 – Compatibility and Optimization**
-Reducing dependencies and simplifying migration from other libraries.
-- **Expanding functionality** to simplify migration from other tree packages.
-- Introducing node **filtering and search with AJAX**.
-- **Optimizing query performance** by reducing query complexity and improving indexing strategies.
-- **Reducing database load** from the `TreeNodeAdmin` when working with large trees.
-- Removing `numpy` in favor of lighter alternatives.
-
-### **Version 2.2 – Caching Improvements**
-Speeding up tree operations and reducing database load.
-- **Implementing a more efficient caching algorithm** to optimize performance and reduce recomputation.
-- **Refining cache expiration strategies** for better memory management.
-
-### **Version 2.3 – Performance Enhancements**
-- **Reducing query overhead** and optimizing bulk operations for large datasets.
-- **Django REST Framework (DRF)**: Adding initial integration for efficient tree-based API handling.
-- **Serialization**: Developing lightweight tree serialization for API-first projects.
-- **Enhancing node filtering and search** with AJAX-driven interfaces.
-
-### **Version 2.4 – Drag-and-Drop and Admin UI Improvements**
-- **Drag-and-Drop**: Adding drag-and-drop support for node sorting in Django admin.
-- **Advanced Sorting**: Adding multiple sorting strategies for tree nodes, including manual ordering and hierarchical priority rules.
-- **Admin Panel Enhancements**: Expanding the functionality of the Django admin interface for managing hierarchical data more efficiently.
-
-### **Version 3.0 – Asynchronous operations and Fourth-Generation Cache Management System**
-- **Asynchronous operations** support, ensuring efficient working and data processing in non-blocking environments.
-- **Shifting from caching computed results to directly caching tree nodes**, reducing recomputation overhead and improving cache efficiency.
-- **Reworking Adjacency List and Closure Table managers** for a new caching system.
-- **Enhancing cache consistency** across multiple processes (WSGI, Gunicorn, Uvicorn) with a global synchronization mechanism.
-
-### **Version 4.0 – Moving Beyond Django ORM**
-Enabling tree structures to function without a strict dependency on Django ORM while maintaining compatibility.
-- **Introducing support for various storage backends**, allowing greater flexibility.
-- **Adding compatibility with Redis for in-memory tree storage** and JSON-based trees for lightweight embedded storage.
-- **Expanding usage in API-first projects**, enabling tree structures to work independently from Django models.
-
-Stay tuned for updates!
-Your wishes, objections, and comments are welcome.