django-fast-treenode 1.1.3__tar.gz → 2.0.0__tar.gz

django_fast_treenode-1.1.3/README.md → django_fast_treenode-2.0.0/PKG-INFO

@@ -1,3 +1,45 @@
+Metadata-Version: 2.2
+Name: django-fast-treenode
+Version: 2.0.0
+Summary: Application for supporting tree (hierarchical) data structure in Django projects
+Home-page: https://github.com/TimurKady/fast-treenode
+Author: Timur Kady
+Author-email: Timur Kady <kaduevtr@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2020-2023 Timur Kady
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/TimurKady/django-fast-treenode
+Project-URL: Documentation, https://github.com/TimurKady/django-fast-treenode#readme
+Project-URL: Source, https://github.com/TimurKady/django-fast-treenode
+Project-URL: Issues, https://github.com/TimurKady/django-fast-treenode/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django<5.0,>=3.2
+Requires-Dist: pympler>=1.0
+Provides-Extra: import-export
+Requires-Dist: openpyxl; extra == "import-export"
+Requires-Dist: pyyaml; extra == "import-export"
+Requires-Dist: pandas; extra == "import-export"
+
 # Django-fast-treenode 
 __Combination of Adjacency List and Closure Table__
 
@@ -50,8 +92,7 @@ You can easily find additional information on your own on the Internet.
 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`
@@ -117,6 +158,8 @@ CACHES = {
     },
     "treenode": {
         "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+        "KEY_PREFIX": "",   # This is important!
+        "VERSION": None,    # This is important!
     },
 }
 ```
@@ -124,15 +167,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)
@@ -187,11 +257,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 +389,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 +399,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
@@ -544,27 +624,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 provided code is already being used in production projects, even though I have only done general testing. That is why the risk of using the code lies entirely with you.
+Your wishes, objections, comments are welcome.
 
-**Warning**: don't access the tree node fields directly! Most of them have been removed as unnecessary. In the future, only `tn_parent` and `tn_priority` will be kept. Use the functions described in the documentation above or the documentation for the [original 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:
-* may be will add the ability to determine the priority of the parent by any field, for example, by creation date or alphabetical order;
-* drug-and-drop support;
-* 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.

django_fast_treenode-1.1.3/django_fast_treenode.egg-info/PKG-INFO → django_fast_treenode-2.0.0/README.md

@@ -1,29 +1,3 @@
-Metadata-Version: 2.1
-Name: django-fast-treenode
-Version: 1.1.3
-Summary: Application for supporting tree (hierarchical) data structure in Django projects
-Home-page: https://github.com/TimurKady/fast-treenode
-Author: Timur Kady
-Author-email: timurkady@yandex.com
-License: MIT
-Classifier: Environment :: Web Environment
-Classifier: Framework :: Django
-Classifier: Framework :: Django :: 3.0
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Framework :: Django
-Classifier: Framework :: Django :: 3.0
-Classifier: Framework :: Django :: 4.0
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: Django>=3.0
-
 # Django-fast-treenode 
 __Combination of Adjacency List and Closure Table__
 
@@ -76,8 +50,7 @@ You can easily find additional information on your own on the Internet.
 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`
@@ -143,6 +116,8 @@ CACHES = {
     },
     "treenode": {
         "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+        "KEY_PREFIX": "",   # This is important!
+        "VERSION": None,    # This is important!
     },
 }
 ```
@@ -150,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)
@@ -213,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:
@@ -339,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
@@ -347,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
@@ -570,27 +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 provided code is already being used in production projects, even though I have only done general testing. That is why the risk of using the code lies entirely with you.
+Your wishes, objections, comments are welcome.
 
-**Warning**: don't access the tree node fields directly! Most of them have been removed as unnecessary. In the future, only `tn_parent` and `tn_priority` will be kept. Use the functions described in the documentation above or the documentation for the [original 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:
-* may be will add the ability to determine the priority of the parent by any field, for example, by creation date or alphabetical order;
-* drug-and-drop support;
-* 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.