Treenode Framework¶

A hybrid open-source framework for working with trees in Django

Welcome to the django-fast-treenode documentation!

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.

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 that on trees of 5k-10k nodes with a nesting depth of 500-600 levels, django-fast-treenode shows performance 4-7 times better than the main popular packages.
Flexible API: today django-fast-treenode 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: django-fast-treenode 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.

All this makes django-fast-treenode a prime candidate for your needs.

Quick Start¶

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

Simply install the package via pip:
```
pip install django-fast-treenode
```
Once installed, add 'treenode' to your INSTALLED_APPS in settings.py:
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:

python manage.py makemigrations
python manage.py migrate

Run server
```
python manage.py runserver
```

Everything is ready, enjoy 🎉!

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.

Additional features¶

The django-fast-treenode package has several additional features, some of which are unique to similar packages:

API-first support (without DRF);
Flexible Admin Class: tree widgets support and drag and drop functionality;
Import and Export tree data to/from file (CSV, JSON, TSV, XLSX, YAML).

All these features are available "out of the box".

Supported Versions¶

Supported Django Versions¶

The project supports Django versions starting from Django 4.0 and higher:

Django 4.0, 4.1, 4.2 (LTS)
Django 5.0
Django 5.1
Django 5.2 (support is ready and tested)

The project is designed for long-term compatibility with future Django versions without requiring architectural changes.

Supported Databases and Minimum Versions¶

All SQL queries are adapted through a universal compatibility layer, ensuring support for major databases without the need to rewrite SQL code.

Database	Minimum Version	Status	Notes
PostgreSQL	≥ 10.0	Full tested	Recommended ≥ 12
MySQL	≥ 8.0	Partially tested
MariaDB	≥ 10.5	Not tested
SQLite	≥ 3.35.0	Partially tested
Oracle	≥ 12c R2	Full tested	Recommended ≥ 19c
MS SQL Server	≥ 2016	Partially tested

The project is ready for production use across all modern versions of Django and major relational databases without manual SQL corrections.

License¶

Released under the MIT License.