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

{django_fast_treenode-1.1.3.dist-info → django_fast_treenode-2.0.0.dist-info}/METADATA

@@ -1,28 +1,44 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: django-fast-treenode
-Version: 1.1.3
+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: 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
+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 >=3.0
+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__
@@ -76,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`
@@ -143,6 +158,8 @@ CACHES = {
     },
     "treenode": {
         "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+        "KEY_PREFIX": "",   # This is important!
+        "VERSION": None,    # This is important!
     },
 }
 ```
@@ -150,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)
@@ -213,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:
@@ -339,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
@@ -347,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
@@ -570,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-2.0.0.dist-info/RECORD

@@ -0,0 +1,41 @@
+treenode/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+treenode/admin.py,sha256=x5vJDiZjqcsUAVlK1qkZPK66lQeJq8zYgWwwejentYM,14077
+treenode/apps.py,sha256=M0O9IKEnJZFfhfz12v4wksYJ-0ECyj1Cy3qXrfywos8,472
+treenode/cache.py,sha256=Z_FpaS0vTKXqAI4n1QkZ7A_ILsLU3Q8rLgerA6pYyAA,7210
+treenode/forms.py,sha256=imoLzr7qFlOBdeMQK12rAFp6hINpe0PS_U4-V8RRcDU,2802
+treenode/managers.py,sha256=7z8GU64A2_jEonJyQDTyIpdOocaBbM352DkwZTHjdQk,10828
+treenode/urls.py,sha256=7N0d4XiI6880sc8P89eWGr-ZjmOqPorA-fWfcnviqAM,876
+treenode/version.py,sha256=-zaHoXRvTvJ0QzwA9ocYp7O38iBtIarACZbCNzwyc4s,222
+treenode/views.py,sha256=vBDIxmYXBwmJxRnInvUVGy75FQmt-XN_HnEaKIu-fVs,3365
+treenode/widgets.py,sha256=4Q6WlPPT5fggEuTXiZ_Z40pjb46CylSp28pa0xBT_Ps,2079
+treenode/docs/Documentation,sha256=6USAESU8MuY1vlj95yY8S6T0o_0RsktGv6S_0SdSkwk,21030
+treenode/models/__init__.py,sha256=gjDwVai0jf-l0hMaeeEBTYLR-DXkxUZMLUMGGs_tnuo,83
+treenode/models/classproperty.py,sha256=IrwBWpmyjsAXpkpfDSOIMsnX6EMcbXql3mZjurHgRcw,556
+treenode/models/closure.py,sha256=chTa9T9yC3H_2LaZXR7KLdNh1pc50iUolut5GB4Bm-Q,5297
+treenode/models/factory.py,sha256=Wt1szWhbeICPwm0-RUy9p4VovcxltHECVxTSRyCQHc8,2100
+treenode/models/proxy.py,sha256=6BFElk_NL1ARTEAikOOfMneUK5wEjofNnfXQWFSZUsA,21766
+treenode/static/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+treenode/static/treenode/.gitkeep,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+treenode/static/treenode/css/.gitkeep,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+treenode/static/treenode/css/tree_widget.css,sha256=Qsnr9cExetL7BFKErRSns4APzM8-9DM4g6nqMelPzUI,1972
+treenode/static/treenode/css/treenode_admin.css,sha256=GiCJ_zNZs7JmJgjCHsn1tJinNEU_lTOYYPZ7S0fnvis,2195
+treenode/static/treenode/js/.gitkeep,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+treenode/static/treenode/js/tree_widget.js,sha256=Du3a76tojdIqWndji88Omt5MvajXK7GpypC9DYIFBMk,6571
+treenode/static/treenode/js/treenode_admin.js,sha256=3fdvy1VoHb3rmzI19YXw4JPt6ZGKn_AhTEky8YQEilU,6821
+treenode/templates/.gitkeep,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+treenode/templates/admin/.gitkeep,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+treenode/templates/admin/export_success.html,sha256=xN2D-BCH249CJB10fo_vHYUyFenQ9mFKqq7UTWcrXS4,747
+treenode/templates/admin/tree_node_changelist.html,sha256=ykksipIBMy2LvH6UqPuM-y00UlXAjsypMHqiMm_KlTg,261
+treenode/templates/admin/tree_node_export.html,sha256=vJxEoGI-US6VdFddxAFgL5r3MgGt6mgA43vltCsbA2k,1043
+treenode/templates/admin/tree_node_import.html,sha256=ZFoveJ08X99EGiwFCfQowXI9oS9VgcFtRLYVDIWq-Fg,969
+treenode/templates/widgets/tree_widget.css,sha256=2bEaxu1x7QJZ7erbs2SLMaxeaiMkjQXadfcDEW8wfok,551
+treenode/templates/widgets/tree_widget.html,sha256=GKcCU-B2FkkJ2BSOuXOw9e_PdYTtADcvyITEXqOlZ9Y,723
+treenode/utils/__init__.py,sha256=jAVT-uNGQDKPVq5ET4JE2GhRpzbxFdHU25w9sLC3_To,134
+treenode/utils/base36.py,sha256=ydgu9hqDaK-WyS8zG-mtSWo7hJqbB4iHqkGz4-IVrb4,834
+treenode/utils/exporter.py,sha256=l-IEsk2fK8xe-E-Hi7SMOV7ZIwxM6mZih5-0rhvsx9E,5396
+treenode/utils/importer.py,sha256=n23PBFPXN-6S_Dl8Qmx56sp0eLy_lWfpxrzJqwygQf0,14190
+django_fast_treenode-2.0.0.dist-info/LICENSE,sha256=GiiEe4Y9oOCbn9eGuNew1mMYHU_bJWaCK9zOusnKvvU,1091
+django_fast_treenode-2.0.0.dist-info/METADATA,sha256=4KtUbAU7CMjjTFPk_5cv5jfkPZTID5Onf-U8p-gycr8,23215
+django_fast_treenode-2.0.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+django_fast_treenode-2.0.0.dist-info/top_level.txt,sha256=fmgxHbXyx1O2MPi_9kjx8aL9L-8TmV0gre4Go8XgqFk,9
+django_fast_treenode-2.0.0.dist-info/RECORD,,

{django_fast_treenode-1.1.3.dist-info → django_fast_treenode-2.0.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.43.0)
+Generator: setuptools (75.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

treenode/__init__.py

@@ -1,7 +0,0 @@
-class classproperty(object):
-
-    def __init__(self, getter):
-        self.getter = getter
-
-    def __get__(self, instance, owner):
-        return self.getter(owner)