django-fast-treenode 2.0.11__py3-none-any.whl → 2.1.0__py3-none-any.whl

treenode/admin/mixins.py

@@ -0,0 +1,302 @@
+# -*- coding: utf-8 -*-
+"""
+Views Mixin for TreeNodeAdminModel
+
+Version: 2.1.0
+Author: Timur Kady
+Email: kaduevtr@gmail.com
+"""
+
+import os
+from datetime import datetime
+from django.contrib import admin
+from django.contrib import messages
+from django.contrib.admin.helpers import ACTION_CHECKBOX_NAME
+from django.db import models
+from django.http import JsonResponse
+from django.shortcuts import render, redirect
+from django.shortcuts import resolve_url
+from django.template.loader import render_to_string
+from django.urls import path
+from django.utils.encoding import force_str
+from django.utils.safestring import mark_safe
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class AdminMixin(admin.ModelAdmin):
+    """Admin Mixin with views."""
+
+    def change_list_view(self, request):
+        """
+        View for lazy loading of child nodes.
+
+        Clicking the expand button sends an AJAX request to this view, which
+        returns JSON with the data of the selected node's immediate children.
+        All returned nodes are collapsed by default.
+        """
+        parent_id = request.GET.get("tn_parent_id")
+        if not parent_id:
+            # If there is no AJAX parameter, then it's normal work: show roots
+            return super().change_list_view(request)
+
+        parent = self.model.objects.filter(pk=parent_id).first()
+        if not parent:
+            # If there is no parent, return an empty response
+            return JsonResponse({'html': ''})
+
+        children = parent.get_children_queryset()
+
+        # We take list_display to understand which "columns" are needed
+        list_display = self.get_list_display(request)
+
+        # We collect future "rows"; each as a list of cells
+        rows = []
+        td_classes = []
+        for obj in children:
+            row_data = []
+            checkbox = mark_safe(
+                f'<input type="checkbox" name="{ACTION_CHECKBOX_NAME}"'
+                f' value="{obj.pk}" class="action-select" />'
+            )
+            row_data.append(checkbox)
+            td_classes.append("action-checkbox")
+            for field in list_display:
+                if callable(field):
+                    # If it is a method (drag, toggle, etc.), call
+                    row_data.append(field(obj))
+                    field_name = field.__name__
+                else:
+                    # If it is a string, we try to get the attribute from
+                    # the object
+                    value = getattr(obj, field, '')
+                    if callable(value):
+                        # If suddenly this is also a method
+                        # (for example, property), then call it
+                        value = value()
+                    row_data.append(value)
+                    field_name = field
+                td_classes.append(f"field-{field_name}")
+
+            row_info = {
+                "node_id": obj.pk,
+                "parent_id": parent_id,
+                "cells": zip(row_data, td_classes),
+            }
+            rows.append(row_info)
+
+        # Pass rows to the template
+        html = render_to_string(
+            'admin/treenode_ajax_rows.html',
+            {"rows": rows},
+            request=request
+        )
+
+        return JsonResponse({'html': html})
+
+    def search_view(self, request):
+        """View for finding nodes using get_list_display."""
+        # Get a search query
+        q = request.GET.get("q", "")
+
+        # Perform filtering with annotation to calculate the level
+        queryset = self.model.objects\
+            .annotate(cl_depth=models.Max("parents_set__depth"))\
+            .filter(name__icontains=q)
+        queryset_list = list(queryset)[:20]
+        sorted_list = self.model._sort_node_list(queryset_list)
+
+        # Get the set of columns as it is formed in change_list.
+        # The first two columns (drag and toggle) are not needed for searching,
+        # and the main display column is at index 2.
+        list_display = self.get_list_display(request)
+        display_func = list_display[2]
+
+        results = []
+        for node in sorted_list:
+            # Get the HTML display of the node via the function generated by
+            # get_list_display
+            display_html = display_func(node)
+            results.append({
+                "id": node.pk,
+                "text": display_html,
+                "level": node.cl_depth,
+                "is_leaf": node.is_leaf(),
+            })
+
+        return JsonResponse({"results": results})
+
+    def import_view(self, request):
+        """
+        Import View.
+
+        File upload processing, auto-detection of format, validation and data
+        import.
+        """
+        if not self.import_export:
+            self.message_user(
+                request,
+                "Import functionality is disabled because required \
+packages are not installed."
+            )
+            return redirect("..")
+
+        if request.method == 'POST':
+            if 'file' not in request.FILES:
+                return render(
+                    request,
+                    "admin/tree_node_import.html",
+                    {"errors": ["No file uploaded."]}
+                )
+
+            file = request.FILES['file']
+            ext = os.path.splitext(file.name)[-1].lower().strip(".")
+
+            allowed_formats = {"csv", "json", "xlsx", "yaml", "tsv"}
+            if ext not in allowed_formats:
+                return render(
+                    request,
+                    "admin/tree_node_import.html",
+                    {"errors": [f"Unsupported file format: {ext}"]}
+                )
+
+            # Import data from file
+            importer = self.TreeNodeImporter(self.model, file, ext)
+            raw_data = importer.import_data()
+            clean_result = importer.finalize(raw_data)
+
+            errors = clean_result.get("errors", [])
+            created_count = len(clean_result.get("create", []))
+            updated_count = len(clean_result.get("update", []))
+
+            if errors:
+                return render(
+                    request,
+                    "admin/tree_node_import_report.html",
+                    {
+                        "errors": errors,
+                        "created_count": created_count,
+                        "updated_count": updated_count,
+                    }
+                )
+
+            # If there are no errors, redirect to the list of objects with
+            # a message
+            messages.success(
+                request,
+                f"Successfully imported {created_count} records. "
+                f"Successfully updated {updated_count} records."
+            )
+
+            app_label = self.model._meta.app_label
+            model_name = self.model._meta.model_name
+            admin_changelist_url = f"admin:{app_label}_{model_name}_changelist"
+            path = resolve_url(admin_changelist_url) + "?import_done=1"
+            return redirect(path)
+
+        # If the request is not POST, simply display the import form
+        return render(request, "admin/tree_node_import.html")
+
+    def export_view(self, request):
+        """
+        Export view.
+
+        - If the GET parameters include download, we send the file directly.
+        - If the format parameter is missing, we render the format selection
+          page.
+        - If the format is specified, we perform a test export to catch errors.
+
+        If there are no errors, we render the success page with a message, a
+        link for manual download,
+        and a button to go to the model page.
+        """
+        if not self.import_export:
+            self.message_user(
+                request,
+                "Export functionality is disabled because required \
+packages are not installed."
+            )
+            return redirect("..")
+
+        # If the download parameter is present, we give the file directly
+        if 'download' in request.GET:
+            # Get file format
+            export_format = request.GET.get('format', 'csv')
+            # Filename
+            now = force_str(datetime.now().strftime("%Y-%m-%d %H-%M"))
+            filename = self.model._meta.label + " " + now
+            # Init
+            exporter = self.TreeNodeExporter(
+                self.get_queryset(request),
+                filename=filename
+            )
+            # Export working
+            response = exporter.export(export_format)
+            logger.debug("DEBUG: File response generated.")
+            return response
+
+        # If the format parameter is not passed, we show the format
+        # selection page
+        if 'format' not in request.GET:
+            return render(request, "admin/tree_node_export.html")
+
+        # If the format is specified, we try to perform a test export
+        # (without returning the file)
+        export_format = request.GET['format']
+        exporter = self.TreeNodeExporter(
+            self.model.objects.all(),
+            filename=self.model._meta.model_name
+        )
+        try:
+            # Test call to check for export errors (result not used)
+            exporter.export(export_format)
+        except Exception as e:
+            logger.error("Error during test export: %s", e)
+            errors = [str(e)]
+            return render(
+                request,
+                "admin/tree_node_export.html",
+                {"errors": errors}
+            )
+
+        # Form the correct download URL. If the URL already contains
+        # parameters, add them via &download=1, otherwise via ?download=1
+        current_url = request.build_absolute_uri()
+        if "?" in current_url:
+            download_url = current_url + "&download=1"
+        else:
+            download_url = current_url + "?download=1"
+
+        context = {
+            "download_url": download_url,
+            "message": "Your file is ready for export. \
+The download should start automatically.",
+            "manual_download_label": "If the download does not start, \
+click this link.",
+            # Can be replaced with the desired URL to return to the model
+            "redirect_url": "../",
+            "button_text": "Return to model"
+        }
+        return render(request, "admin/export_success.html", context)
+
+    def get_urls(self):
+        """
+        Extend admin URLs with custom import/export routes.
+
+        Register these URLs only if all the required packages are installed.
+        """
+        urls = super().get_urls()
+        if self.import_export:
+            custom_urls = [
+                path('change_list/', self.change_list_view, name='change_list'),
+                path('search/', self.search_view, name='search'),
+                path('import/', self.import_view, name='tree_node_import'),
+                path('export/', self.export_view, name='tree_node_export'),
+            ]
+        else:
+            custom_urls = []
+        return custom_urls + urls
+
+# The End

treenode/apps.py

@@ -5,13 +5,17 @@ TreeNode Application Configuration
 This module defines the application configuration for the TreeNode app.
 It sets the default auto field and specifies the app's name.
 
-Version: 2.0.0
+Version: 2.1.0
 Author: Timur Kady
 Email: timurkady@yandex.com
 """
 
 
+import logging
 from django.apps import AppConfig
+from django.db.models.signals import post_migrate
+
+logger = logging.getLogger(__name__)
 
 
 class TreeNodeConfig(AppConfig):
@@ -20,4 +24,11 @@ class TreeNodeConfig(AppConfig):
     default_auto_field = "django.db.models.BigAutoField"
     name = "treenode"
 
+    def ready(self):
+        """
+        Attach a post_migrate handler.
 
+        This allows you to perform operations after the migration is complete.
+        """
+        from .utils.db import post_migrate_update
+        post_migrate.connect(post_migrate_update, sender=self)

treenode/cache.py

@@ -212,8 +212,8 @@ def cached_method(func):
             label,
             func.__name__,
             unique_id,
-            args,
-            kwargs
+            *args,
+            **kwargs
         )
 
         # Retrieving from cache

treenode/docs/about.md

@@ -0,0 +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.
+
+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.
+
+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**.
+
+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.

treenode/docs/admin.md

@@ -0,0 +1,104 @@
+## Working with Admin Classes
+
+### Using `TreeNodeModelAdmin`
+The easiest way to integrate tree structures into Django’s admin panel is by inheriting from `TreeNodeModelAdmin`. This base class provides all the necessary functionality for managing hierarchical data.
+
+##### admin.py:
+```python
+from django.contrib import admin
+from treenode.admin import TreeNodeModelAdmin
+
+from .models import Category
+
+@admin.register(Category)
+class CategoryAdmin(TreeNodeModelAdmin):
+
+    # Set the display mode: 'accordion', 'breadcrumbs', or 'indentation'
+    treenode_display_mode = TreeNodeModelAdmin.TREENODE_DISPLAY_MODE_ACCORDION
+    # treenode_display_mode = TreeNodeModelAdmin.TREENODE_DISPLAY_MODE_BREADCRUMBS
+    # treenode_display_mode = TreeNodeModelAdmin.TREENODE_DISPLAY_MODE_INDENTATION
+
+    list_display = ("name",)
+    search_fields = ("name",)
+```
+
+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`**  
+  Displays the tree as a sequence of **breadcrumbs**, making it easy to navigate.
+- **`TREENODE_DISPLAY_MODE_INDENTATION`**  
+  Uses a **long dash** (`———`) to indicate nesting levels, providing a simple visual structure.
+
+The accordion mode is **always active**, and the setting only affects how nodes are displayed.
+
+**Why Dynamic Loading**:  Traditional pagination does not work well for **deep hierarchical trees**, as collapsed trees may contain a **huge number of nodes**, which is in the hundreds of thousands. The dynamic approach allows efficient loading, reducing database load while keeping large trees manageable.
+
+#### Search Functionality
+The search bar helps quickly locate nodes within large trees. As you type, **an AJAX request retrieves up to 20 results** based on relevance. If you don’t find the desired node, keep typing to refine the search until fewer than 20 results remain.
+
+### Working with Forms
+
+#### 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`:
+```python
+from treenode.forms import TreeNodeForm
+from .models import Category
+
+class CategoryForm(TreeNodeForm):
+    """Form for Category model with hierarchical selection."""
+
+    class Meta(TreeNodeForm.Meta):
+        model = Category
+```
+
+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**:
+  
+  ```python
+  CategoryForm = TreeNodeForm.factory(Category)
+  ```
+
+This method ensures that the form correctly associates with different tree models dynamically.
+
+
+### Using TreeWidget Widget
+
+#### 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`
+
+```python
+from django import forms
+from treenode.widgets import TreeWidget
+from .models import Category
+
+class CategorySelectionForm(forms.Form):
+    parent = forms.ModelChoiceField(
+        queryset=Category.objects.all(),
+        widget=TreeWidget(),
+        required=False
+    )
+```
+
+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.
+
+If you plan to use this widget in non-admin templates, make sure the necessary **JavaScript and CSS files** are included:
+```html
+<link rel="stylesheet" href="/static/treenode/tree_widget.css">
+<script src="/static/treenode/js/tree_widget.js"></script>
+```
+
+By following these guidelines, you can seamlessly integrate `TreeNodeModelAdmin`, `TreeNodeForm`, and `TreeWidget` into your Django project, ensuring efficient management of hierarchical data.