Metadata-Version: 2.4
Name: django-fast-treenode
Version: 3.2.5
Summary: Treenode Framework for supporting tree (hierarchical) data structure in Django projects
Home-page: https://django-fast-treenode.readthedocs.io/
Author: Timur Kady
Author-email: Timur Kady <timurkady@yandex.com>
License: MIT License
        
        Copyright (c) 2020-2025 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://django-fast-treenode.readthedocs.io/
Project-URL: Source, https://github.com/TimurKady/django-fast-treenode
Project-URL: Issues, https://github.com/TimurKady/django-fast-treenode/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=5.0
Requires-Dist: msgpack>=1.0.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: pyyaml>=5.1
Requires-Dist: PyJWT>=2.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Treenode Framework
**A hybrid open-source framework for working with trees in Django**

[![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/)
[![Sponsor](https://img.shields.io/github/sponsors/TimurKady)](https://github.com/sponsors/TimurKady)

## About The Treenode Framework
### Overview

**Treenode Framework** is an advanced tree management system for Django applications.It is designed to handle large-scale, deeply nested, and highly dynamic tree structures while maintaining excellent performance, data integrity, and ease of use.

Unlike traditional solutions, **Treenode Framework** is built for serious real-world applications where trees may consist of:

- Number nodes to 50-100 thousands nodes,
- Nesting depths to 1,000 levels,
- Complex mutation patterns (bulk moves, merges, splits),
- Real-time data access via API.

Its core philosophy: **maximum scalability, minimum complexity**.

### Key Features
#### Common operations
The `django-fast-Treenode` package supports all the basic operations needed to work with tree structures:

- Extracting **ancestors** (queryset, list, pks, count);
- Extracting **children** (queryset, list, pks, count);
- Extracting **descendants** (queryset, list, pks, count);
- Extracting a **family**: ancestors, the node itself and its descendants (queryset, list, pks, count);
- Enumerating all the nodes (queryset, dicts);
- **Adding** a new node at a **certain position** on the tree;
- Automatic **sorting of node order** by the value of the specified field;
- **Deleting** an node;
- **Pruning**: Removing a whole section of a tree;
- **Grafting**: Adding a whole section to a tree;
- Finding the **root** for any node;
- Finding the **lowest common ancestor** of two nodes;
- Finding the **shortest path** between two nodes.

Due to its high performance and ability to support deep nesting and large tree sizes, the `django-fast-treeode` package can be used for any tasks that involve the use of tree-like data, with virtually no restrictions.

### Where Massive Trees Really Matter?

**Treenode Framework** is designed to handle not only toy examples, but also real trees with strict requirements for the number of nodes and their nesting.

Typical applications include:

- **Digital Twin Systems** for industrial asset management (plants, machinery, vehicles), where full structural decomposition is critical for maintenance planning and cost optimization.
- **Decision Support Systems** in medicine, law, and insurance, where large and dynamic decision trees drive critical reasoning processes.
- **AI Planning Engines** based on hierarchical task networks, allowing intelligent agents to decompose and execute complex strategies.
- **Biological and Genetic Research**, where large phylogenetic trees model evolutionary relationships or genetic hierarchies.

In all these domains, scalable and fast tree management is not a luxury — it's a necessity.

### Why Treenode Framework?
At the moment, django-fast-treeenode is, if not the best, then one of the best packages for working with tree data under Djangjo.

- **High performance**: [tests show](docs/about.md#benchmark-tests) that on trees of 5k-10k nodes with a nesting depth of 500-600 levels, **Treenode Framework** (`django-fast-Treenode`) shows **performance 4-7 times better** than the main popular packages.
- **Flexible API**: today contains the widest set of methods for working with a tree in comparison with other packages.
- **Convenient administration**: the admin panel interface was developed taking into account the experience of using other packages. It provides convenience and intuitiveness with ease of programming.
- **Scalability**: **Treenode Framework** suitable for solving simple problems such as menus, directories, parsing arithmetic expressions, as well as complex problems such as program optimization, image layout, multi-step decision making problems, or machine learning..
- **Lightweight**: All functionality is implemented within the package without heavyweight dependencies such as `djangorestframework` or `django-import-export`.
- **Optional JWT authentication**: enable token-based protection for the API with a single setting.

All this makes **Treenode Framework** a prime candidate for your needs.

## Quick Start
To get started quickly, you need to follow these steps:

- Simply install the package via `pip`:
  ```sh
  pip install django-fast-Treenode
  ```
- Once installed, add `'treenode'` to your `INSTALLED_APPS` in **settings.py**:
  ```python {title="settings.py"}
  INSTALLED_APPS = [
      ...
      'treenode',
      ...
  ]
  ```

- Open **models.py** and create your own tree class:
  ```
  from Treenode.models import TreenodeModel

  class MyTree(TreenodeModel):
    name = models.CharField(max_length=255)
    display_field = "name"
  ```

- Open **admin.py** and create a model for the admin panel
  ```
  from django.contrib import admin
  from Treenode.admin import TreenodeModelAdmin
  from .models import MyTree

  @admin.register(MyTree)
  class MyTreeAdmin(TreenodeModelAdmin):
    list_display = ("name",)
    search_fields = ("name",)
  ```

- Then, apply migrations:
  ```sh
  python manage.py makemigrations
  python manage.py migrate
  ```

- Run server
  ```sh
  python manage.py runserver
  ```
Everything is ready, enjoy 🎉!

## Documentation
Full documentation is available at **[ReadTheDocs](https://django-fast-Treenode.readthedocs.io/)**.

Quick access links:
* [Installation, configuration and fine tuning](https://django-fast-Treenode.readthedocs.io/installation/)
* [Model Inheritance and Extensions](https://django-fast-Treenode.readthedocs.io/models/)
* [Working with Admin Classes](https://django-fast-Treenode.readthedocs.io/admin/)
* [API Reference](https://django-fast-Treenode.readthedocs.io/api/)
* [Import & Export](https://django-fast-Treenode.readthedocs.io/import_export/)
* [Caching and working with cache](https://django-fast-Treenode.readthedocs.io/cache/)
* [Migration and upgrade guide](https://django-fast-Treenode.readthedocs.io/migration/)

Your wishes, objections, comments are welcome.

## License
Released under [MIT License](https://github.com/TimurKady/django-fast-Treenode/blob/main/LICENSE).

## Credits
Thanks to everyone who contributed to the development and testing of this package, as well as the Django community for their inspiration and support. 

Special thanks to [Fabio Caccamo](https://github.com/fabiocaccamo) for the idea behind creating a fast Django application for handling hierarchies.

Also special thanks to everyone who supports the project with their [sponsorship donations](https://github.com/sponsors/TimurKady).
