django-clade 0.3.0

A Django module for managing hierarchical data models through a node tree, with kinship relationship queries and optional database-native optimisations.

Clade

A Django module for managing hierarchical data models through a tree of nodes, with kinship relationship queries and optional database-native optimisations.

---

Status

Pre-alpha — v0.3.0 published. API not yet stable.

Version	Status	Content
v0.3.0	✅ Current	LtreeField, PostgreSQL ltree backend, backend dispatch, integration tests
v0.4.0	🔄 Next	Extended kinship (pibling, nibling, cousin)

See the milestones and open issues on GitLab for the full roadmap.

---

What it does

Clade provides a Django application for modelling and querying tree-structured data. It exposes the full set of kinship relationships derivable from a node tree — not only parent/child pairs, but ancestors, descendants, siblings, and collateral lines (piblings, niblings, cousins…) — using gender-neutral terminology throughout.

It also introduces Affinity: a lateral relationship between nodes that share attribute values without any hierarchical link between them (planned for v0.5.0).

The module targets multiple database backends:

• PostgreSQL with ltree — native optimisation (v0.3.0)
• SQLite / other — pure-Django Materialized Path fallback (current)

---

Install

pip install django-clade

# settings.py
INSTALLED_APPS = [
    ...
    "clade",
]

---

Usage

from clade.models import CladeNode
from django.db import models


class Category(CladeNode):
    name = models.CharField(max_length=255)


# Build a tree
root  = Category.objects.create(name="Root")
child = Category.objects.create(name="Child", parent=root)
leaf  = Category.objects.create(name="Leaf",  parent=child)

# Traverse
leaf.ancestors()             # QuerySet → [root, child]  (ordered by path)
root.descendants()           # QuerySet → [child, leaf]
child.siblings()             # QuerySet → []

leaf.is_root                 # False
leaf.is_leaf                 # True
leaf.root                    # → root

# Manager API
Category.objects.ancestors_of(leaf)
Category.objects.descendants_of(root)

# Deletion strategies
from clade.deletion import ADOPT

class Department(CladeNode):
    name = models.CharField(max_length=255)
    parent = models.ForeignKey(
        "self", null=True, blank=True,
        on_delete=ADOPT,          # re-parents children on delete
        related_name="children",
    )

---

Requirements

• Python 3.10+
• Django 5.2+

---

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

---

Licence

Apache License 2.0 — see LICENSE.txt and NOTICE.