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

treenode/cache.py

@@ -0,0 +1,231 @@
+# -*- coding: utf-8 -*-
+"""
+TreeNode Cache Module
+
+This module provides a singleton-based caching system for TreeNode models.
+It includes optimized key generation, cache size tracking,
+and an eviction mechanism to ensure efficient memory usage.
+
+Features:
+- Singleton cache instance to prevent redundant allocations.
+- Custom cache key generation using function parameters.
+- Automatic cache eviction when memory limits are exceeded.
+- Decorator `@cached_method` for caching method results.
+
+Version: 2.0.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
+
+
+from django.core.cache import caches
+from django.conf import settings
+import threading
+import hashlib
+import json
+import logging
+from pympler import asizeof
+
+from .utils.base36 import to_base36
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------
+# Caching
+# ---------------------------------------------------
+
+class TreeNodeCache:
+    """Singleton-класс для управления кэшем TreeNode."""
+
+    _instance = None
+    _lock = threading.Lock()
+    _keys = dict()
+    _total_size = 0
+    _cache_limit = 0
+
+    def __new__(cls):
+        """Create only one instance of the class (Singleton)."""
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = super(TreeNodeCache, cls).__new__(cls)
+                cls._instance._initialize()
+        return cls._instance
+
+    def _initialize(self):
+        """Initialize cache."""
+        self.cache_timeout = None
+        limit = getattr(settings, 'TREENODE_CACHE_LIMIT', 100)*1024*1024
+        self._cache_limit = limit
+        self.cache_timeout = None
+        cache_name = 'treenode' if 'treenode' in settings.CACHES else 'default'
+        self.cache = caches[cache_name]
+        self._total_size = 0
+        self.cache.clear()
+
+    def generate_cache_key(self, label, func_name, unique_id, *args, **kwargs):
+        """
+        Generate Cache Key.
+
+        Generates a cache key of the form:
+            <model_name>_<func_name>_<id>_<hash>,
+        where <hash> is calculated from the function parameters
+        (args and kwargs).
+        If the parameters can be serialized via JSON, use this, otherwise we
+        use repr to generate the string.
+        """
+        try:
+            # Sort dictionary keys to ensure determinism.
+            params_repr = json.dumps(
+                (args, kwargs),
+                sort_keys=True,
+                default=str
+            )
+        except (TypeError, ValueError) as e:
+            # If JSON serialization fails, use repr.
+            params_repr = repr((args, kwargs))
+            logger.warning(f"Failed to serialize cache key params: {e}")
+
+        # Calculate the MD5 hash from the received string.
+        hash_value = hashlib.sha256(params_repr.encode("utf-8")).hexdigest()
+
+        # Forming the final key.
+        cache_key = f"{label}_{func_name}_{unique_id}_{hash_value}"
+
+        return cache_key
+
+    def get_obj_size(self, value):
+        """Determine the size of the object in bytes."""
+        try:
+            return len(json.dumps(value).encode("utf-8"))
+        except (TypeError, ValueError):
+            return asizeof.asizeof(value)
+
+    def cache_size(self):
+        """Return the total size of the cache in bytes."""
+        return self._total_size
+
+    def set(self, cache_key, value):
+        """Push to cache."""
+        size = self.get_obj_size(value)
+        self.cache.set(cache_key, value, timeout=self.cache_timeout)
+
+        # Update cache size
+        if cache_key in self._keys:
+            self._total_size -= self._keys[cache_key]
+        self._keys[cache_key] = size
+        self._total_size += size
+
+        # Check if the limit has been exceeded
+        self._evict_cache()
+
+    def get(self, cache_key):
+        """Get from cache."""
+        return self.cache.get(cache_key)
+
+    def invalidate(self, label):
+        """Clear cache for a specific model only."""
+        prefix = f"{label}_"
+        keys_to_remove = [key for key in self._keys if key.startswith(prefix)]
+        for key in keys_to_remove:
+            self.cache.delete(key)
+            self._total_size -= self._keys.pop(key, 0)
+            if self._total_size < 0:
+                self._total_size = 0
+
+    def clear(self):
+        """Full cache clearing."""
+        self.cache.clear()
+        self._keys.clear()
+        self._total_size = 0
+
+    def _evict_cache(self):
+        """Delete old entries if the cache has exceeded the limit."""
+        if self._total_size <= self._cache_limit:
+            # If the size is within the limit, do nothing
+            return
+
+        if not self._keys:
+            self.clear()
+
+        logger.warning(f"Cache limit exceeded! Current size: \
+{self._total_size}, Limit: {self._cache_limit}")
+
+        # Sort keys by insertion order (FIFO)
+        keys_sorted = list(self._keys.keys())
+
+        keys_to_delete = []
+        freed_size = 0
+
+        # Delete old keys until we reach the limit
+        for key in keys_sorted:
+            freed_size += self._keys[key]
+            keys_to_delete.append(key)
+            if self._total_size - freed_size <= self._cache_limit:
+                break
+
+        # Delete keys in batches (delete_many)
+        self.cache.delete_many(keys_to_delete)
+
+        # Update data in `_keys` and `_total_size`
+        for key in keys_to_delete:
+            self._total_size -= self._keys.pop(key, 0)
+
+        logger.info(f"Evicted {len(keys_to_delete)} keys from cache, \
+freed {freed_size} bytes.")
+
+
+# Create a global cache object (there is only one for the entire system)
+treenode_cache = TreeNodeCache()
+
+
+# ---------------------------------------------------
+# Decorator
+# ---------------------------------------------------
+
+
+def cached_method(func):
+    """
+    Decorate instance methods for caching.
+
+    The decorator caches the results of the decorated class or instance method.
+    If the cache is cleared or invalidated, the cached results will be
+    recalculated.
+
+    Usage:
+        @cached_tree_method
+        def model_method(self):
+            # Tree method logic
+    """
+
+    def wrapper(self, *args, **kwargs):
+        # Generate a cache key.
+        if isinstance(self, type):
+            # Если self — класс, используем его имя
+            unique_id = to_base36(id(self))
+            label = getattr(self._meta, 'label', self.__name__)
+        else:
+            unique_id = getattr(self, "pk", id(self))
+            label = self._meta.label
+
+        cache_key = treenode_cache.generate_cache_key(
+            label,
+            func.__name__,
+            unique_id,
+            args,
+            kwargs
+        )
+
+        # Retrieving from cache
+        value = treenode_cache.get(cache_key)
+
+        if value is None:
+            value = func(self, *args, **kwargs)
+
+            # Push to cache
+            treenode_cache.set(cache_key, value)
+        return value
+    return wrapper
+
+
+# The End

treenode/docs/Documentation

@@ -1,15 +1,16 @@
 # Django-fast-treenode 
 __Combination of Adjacency List and Closure Table__
 
-## Features
+## Functions
 Application for supporting tree (hierarchical) data structure in Django projects
-* faster,
-* synced: in-memory model instances are automatically updated,
-* compatibility: you can easily add treenode to existing projects,
+* fast: the fastest of the two methods is used to process requests, combining the advantages of an **Adjacency Table** and a **Closure Table**,
+* even faster: the main resource-intensive operations are **cached**; **bulk operations** are used for inserts and changes,
+* synchronized: model instances in memory are automatically updated,
+* compatibility: you can easily add a tree node to existing projects using TreeNode without changing the code,
 * no dependencies,
-* easy configuration: just extend the abstract model / model-admin,
-* admin integration: visualization options (accordion, breadcrumbs or indentation),
-* widget: build-in Select2-to-Tree extends Select2 to support arbitrary level of nesting.
+* easy setup: just extend the abstract model/model-admin,
+* admin integration: visualization options (accordion, breadcrumbs or padding),
+* widget: Built-in Select2-to-Tree extends Select2 to support arbitrary nesting levels.
 
 ## Debut idea
 This is a modification of the reusable [django-treenode](https://github.com/fabiocaccamo/django-treenode) application developed by [Fabio Caccamo](https://github.com/fabiocaccamo).
@@ -44,13 +45,12 @@ You can easily find additional information on your own on the Internet.
 
 ## Quick start
 1. Run ```pip install django-fast-treenode```
-2. Add ```django-fast-treenode``` to ```settings.INSTALLED_APPS```
+2. Add ```treenode``` to ```settings.INSTALLED_APPS```
 3. Make your model inherit from ```treenode.models.TreeNodeModel``` (described below)
 4. Make your model-admin inherit from ```treenode.admin.TreeNodeModelAdmin``` (described below)
 5. Run python manage.py makemigrations and ```python manage.py migrate```
 
-When updating an existing project, simply call ```cls.update_tree()``` function once. 
-It will automatically build a new and complete Closure Table for your tree.
+For more information on migrating from the **django-treenode** package and upgrading to version 2.0, see [below](#migration-guide).
 
 ## Configuration
 ### `models.py`
@@ -116,6 +116,8 @@ CACHES = {
     },
     "treenode": {
         "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+        "KEY_PREFIX": "",   # This is important!
+        "VERSION": None,    # This is important!
     },
 }
 ```
@@ -123,15 +125,42 @@ CACHES = {
 
 ```
 class YoursForm(TreeNodeForm):
-
-    class Meta:
-        widgets = {
-            'tn_parent': TreeWidget(attrs={'style': 'min-width:400px'}),
-        }
+    # Your code is here
 ```
 
-## Usage
+## Updating to django-fast-treenode 2.X
+### Overview
+If you are upgrading from a previous version, you need to follow these steps to ensure compatibility and proper functionality.
+
+### Update Process
+1. **Upgrade the package**
+   Run the following command to install the latest version:
+
+   ```bash
+   pip install --upgrade django-fast-treenode
+   ```
+
+2. **Apply database migrations**
+   After upgrading, you need to apply the necessary database migrations:
+
+   ```bash
+   python manage.py makemigrations
+   python manage.py migrate
+   ```
+
+3. **Restart the application**
+   Finally, restart your Django application to apply all changes:
+
+   ```bash
+   python manage.py runserver
+   ```
+
+**Important Notes**: Failing to apply migrations (`migrate`) after upgrading may lead to errors when interacting with tree nodes.
 
+By following these steps, you will ensure a smooth transition to the latest version of django-fast-treenode without data inconsistencies.
+
+
+## Usage
 ### Methods/Properties
 
 -   [`delete`](#delete)
@@ -157,7 +186,6 @@ class YoursForm(TreeNodeForm):
 -   [`get_last_child`](#get_last_child)
 -   [`get_level`](#get_level)
 -   [`get_order`](#get_order)
--   [`get_ordered_queryset`](#get_ordered_queryset)
 -   [`get_parent`](#get_parent)
 -   [`get_parent_pk`](#get_parent_pk)
 -   [`set_parent`](#set_parent)
@@ -187,11 +215,17 @@ class YoursForm(TreeNodeForm):
 -   [`update_tree`](#update_tree)
 
 #### `delete`
-**Delete a node** if `cascade=True` (default behaviour), children and descendants will be deleted too,
-otherwise children's parent will be set to `None` (then children become roots):
+**Delete a node** provides two deletion strategies:
+- **Cascade Delete (`cascade=True`)**: Removes the node along with all its descendants.
+- **Reparenting (`cascade=False`)**: Moves the children of the deleted node up one level in the hierarchy before removing the node itself.
+
 ```python
-obj.delete(cascade=True)
+node.delete(cascade=True)  # Deletes node and all its descendants
+node.delete(cascade=False)  # Moves children up and then deletes the node
 ```
+This ensures greater flexibility in managing tree structures while preventing orphaned nodes.
+
+---
 
 #### `delete_tree`
 **Delete the whole tree** for the current node class:
@@ -313,6 +347,8 @@ obj.get_descendants_tree()
 obj.descendants_tree
 ```
 
+**Important**: In future projects, avoid using `get_descendants_tree()`. It will be removed in the next version.
+
 #### `get_descendants_tree_display`
 Get a **multiline** `string` representing the **model tree**:
 ```python
@@ -321,6 +357,8 @@ obj.get_descendants_tree_display(include_self=False, depth=None)
 obj.descendants_tree_display
 ```
 
+**Important**: In future projects, avoid using `get_descendants_tree_display()`. It will be removed in the next version.
+
 #### `get_first_child`
 Get the **first child node**:
 ```python
@@ -361,23 +399,6 @@ obj.get_order()
 obj.order
 ```
 
-#### `get_ordered_queryset`
-Returns a queryset of nodes ordered by tn_priority each node. 
-```python
-cls.get_ordered_queryset()
-```
-For example:
-- A.1
-- A.1.1
-- A.1.1.1
-- A.1.1.2
-- A.2
-- A.2.1
-- ...
-
-This method uses a lot of memory, ```RawSQL()``` and ```.extra()``` QuerySet method. Use of this method is deprecated due to concerns that Django's ```.extra()``` method **will be deprecated in the future**. 
-Use it only if you cannot otherwise assemble an ordered tree from an Adjacency Table and a Closure Table. In most cases, the data in one Adjacency Table is sufficient for such an assembly. You can easily find the corresponding algorithms (two-pass and one-pass) on the Internet.
-
 #### `get_parent`
 Get the **parent node**:
 ```python
@@ -561,28 +582,83 @@ obj.is_sibling_of(target_obj)
 ```python
 cls.update_tree()
 ```
+## **Cache Management**
+### **Overview**
+In v2.0, the caching mechanism has been improved to prevent excessive memory usage when multiple models inherit from `TreeNode`. The new system introduces **FIFO (First-In-First-Out) cache eviction**, with plans to test and integrate more advanced algorithms in future releases.
+
+### **Key Features**
+**Global Cache Limit**: The setting `TREENODE_CACHE_LIMIT` defines the maximum cache size (in MB) for all models inheriting from `TreeNode`. Default is **100MB** if not explicitly set in `settings.py`.
+**settings.py**
+``` python
+TREENODE_CACHE_LIMIT = 100
+```
+**Automatic Management**: In most cases, users don’t need to manually manage cache operations.
+**Manual Cache Clearing**:
+- **Clear cache for a single model**: Use `clear_cache()` at the model level:
+    ```python
+    MyTreeNodeModel.clear_cache()
+    ```
+ - **Clear cache for all models**: Use the global `treenode_cache.clear()` method:
+    ```python
+    from treenode.cache import treenode_cache
+    treenode_cache.clear()
+    ```
+
+## **Export and Import Functionality**
+### **Overview**
+TreeNode v2.0 includes **built-in export and import features** for easier data migration. Supported Formats: `csv`, `json`, `xlsx`, `yaml`, `tsv`
+### Installation for Import/Export Features
+By default, import/export functionality is **not included** to keep the package lightweight. If you need these features, install the package with:
+```bash
+pip install django-fast-treenode[import_export]
+```
+Once installed, **import/export buttons will appear** in the Django admin interface.
+### **Important Considerations**
+Exporting objects with M2M fields may lead to serialization issues. Some formats (e.g., CSV) do not natively support many-to-many relationships. If you encounter errors, consider exporting data in `json` or `yaml` format, which better handle nested structures.
+
+## Migration Guide
+#### Switching from `django-treenode`
+The migration process from `django-treenode` is fully automated. No manual steps are required. Upon upgrading, the necessary data structures will be checked and updated automatically. In exceptional cases, you can call the update code `cls.update_tree()` manually.
+
+
+#### Upgrading to `django-fast-treenode` 2.0
+To upgrade to version 2.0, simply run:
+```bash
+pip install --upgrade django-fast-treenode
+```
+or
+```bash
+pip install django-fast-treenode[import_export]
+```
+After upgrading, ensure that your database schema is up to date by running:
+```bash
+python manage.py makemigrations
+python manage.py migrate
+```
+This will apply any necessary database changes automatically.
 
-## License
-Released under [MIT License](https://github.com/TimurKady/django-fast-treenode/blob/main/LICENSE).
+## To do
+These improvements aim to enhance usability, performance, and maintainability for all users of `django-fast-treenode`:
+* **Cache Algorithm Optimization**: Testing and integrating more advanced cache eviction strategies.
+* **Drag-and-Drop UI Enhancements**: Adding intuitive drag-and-drop functionality for tree node management.
+* to be happy, to don't worry, until die.
 
-## Cautions
-The code provided is intended for testing by developers and is not recommended for use in production projects. Only general tests were carried out. The risk of using the code lies entirely with you.
+Your wishes, objections, comments are welcome.
 
-Don't access treenode fields directly! Most of them have been removed as unnecessary. Use functions documented in the [source application](https://github.com/fabiocaccamo/django-treenode).
 
-## Credits
-This software contains, uses, including in a modified form:
-*  [django-treenode](https://github.com/fabiocaccamo/django-treenode) by [Fabio Caccamo](https://github.com/fabiocaccamo);
-*  [Select2-to-Tree](https://github.com/clivezhg/select2-to-tree) Select2 extension by [clivezhg](https://github.com/clivezhg)
+# Django-fast-treenode
+## License
+Released under [MIT License](https://github.com/TimurKady/django-fast-treenode/blob/main/LICENSE).
 
-Special thanks to [Mathieu Leplatre](https://blog.mathieu-leplatre.info/pages/about.html) for the advice used in writing this application
+## Cautions
+**Warning**: Do not access the tree node fields directly! Most of *django-treenode* model fields have been removed as unnecessary. Now only `tn_parent` and `tn_priority` are supported and  will be kept in the future. 
 
-## To do
-Future plans:
-* drug-and-drop support;
-* may be will restore caching;
-* may be will add the ability to determine the priority of the parent by any field, for example, by creation date or alphabetical order;
-* to be happy, to don't worry, until die.
+**Risks of Direct Field Access:**
+- **Database Integrity Issues**: Directly modifying fields may break tree integrity, causing inconsistent parent-child relationships.
+- **Loss of Cached Data**: The caching system relies on controlled updates. Bypassing methods like `set_parent()` or `update_tree()` may lead to outdated or incorrect data.
+- **Unsupported Behavior**: Future versions may change field structures or remove unnecessary fields. Relying on them directly risks breaking compatibility.
 
+Instead, always use the **documented methods** described above or refer to the [original application documentation](https://github.com/fabiocaccamo/django-treenode). 
 
-Your wishes, objections, comments are welcome.
+## Credits
+This software contains, uses, and includes, in a modified form, [django-treenode](https://github.com/fabiocaccamo/django-treenode) by [Fabio Caccamo](https://github.com/fabiocaccamo). Special thanks to [Mathieu Leplatre](https://blog.mathieu-leplatre.info/pages/about.html) for the advice used in writing this application.

treenode/forms.py

@@ -1,32 +1,88 @@
-# -*- coding: utf-8 -*-
+"""
+TreeNode Form Module.
+
+This module defines the TreeNodeForm class, which dynamically determines the TreeNode model.
+It utilizes TreeWidget and automatically excludes the current node and its descendants
+from the parent choices.
+
+Functions:
+- __init__: Initializes the form and filters out invalid parent choices.
+- factory: Dynamically creates a form class for a given TreeNode model.
+
+Version: 2.0.0
+Author: Timur Kady
+Email: timurkady@yandex.com
+"""
 
 from django import forms
 from .widgets import TreeWidget
+from django.db.models import Case, When, Value, IntegerField
 
 
 class TreeNodeForm(forms.ModelForm):
+    """
+    TreeNode Form Class.
+
+    ModelForm for dynamically determined TreeNode model.
+    Uses TreeWidget and excludes self and descendants from the parent choices.
+    """
+
+    class Meta:
+        """Meta Class."""
+
+        model = None
+        fields = "__all__"
+        widgets = {
+            "tn_parent": TreeWidget()
+        }
 
     def __init__(self, *args, **kwargs):
+        """Init Method."""
+        super().__init__(*args, **kwargs)
 
-        super(TreeNodeForm, self).__init__(*args, **kwargs)
+        # Get the model from the form instance
+        # Use a model bound to a form
+        model = self._meta.model
 
-        if 'tn_parent' not in self.fields:
-            return
-        exclude_pks = []
-        obj = self.instance
-        if obj.pk:
-            exclude_pks += [obj.pk]
-            # tn_get_descendants_pks changed to get_descendants_pks()
-            # exclude_pks += split_pks(obj.get_descendants_pks())
-            exclude_pks += obj.get_descendants_pks()
+        # Проверяем наличие tn_parent и исключаем текущий узел и его потомков
+        if "tn_parent" in self.fields and self.instance.pk:
+            excluded_ids = [self.instance.pk] + list(
+                self.instance.get_descendants_pks())
 
-        # Cheaged to "legal" call
-        manager = obj._meta.model.objects
+            # Sort by tn_order
+            queryset = model.objects.exclude(pk__in=excluded_ids)
+            node_list = sorted(queryset, key=lambda x: x.tn_order)
+            pk_list = [node.pk for node in node_list]
+            queryset = queryset.filter(pk__in=pk_list).order_by(
+                Case(*[When(pk=pk, then=Value(index))
+                       for index, pk in enumerate(pk_list)],
+                     default=Value(len(pk_list)),
+                     output_field=IntegerField())
+            )
 
-        self.fields['tn_parent'].queryset = manager.prefetch_related(
-            'tn_children').exclude(pk__in=exclude_pks)
+            # Set QuerySet
+            self.fields["tn_parent"].queryset = queryset
 
-    class Meta:
-        widgets = {
-            'tn_parent': TreeWidget(attrs={'style': 'min-width:400px'}),
-        }
+    @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})
+
+
+# The End