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.4.0 published. API not yet stable.

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 — inter-model by design, declared via Meta.affinity_rules (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",
    )

# Extended kinship (v0.4.0) — pibling, nibling, cousin
grandparent = Category.objects.create(name="Grandparent")
parent      = Category.objects.create(name="Parent", parent=grandparent)
aunt        = Category.objects.create(name="Aunt",   parent=grandparent)
me          = Category.objects.create(name="Me",     parent=parent)
cousin      = Category.objects.create(name="Cousin", parent=aunt)

me.piblings()                 # QuerySet → [aunt]      (siblings of my parent)
aunt.niblings()               # QuerySet → [me]        (children of my siblings)
me.cousins()                  # QuerySet → [cousin]    (degree=2, the default)

# Manager API
Category.objects.piblings_of(me)
Category.objects.cousins_of(me, degree=2)

cousins()/cousins_of() use a symmetric degree, not the genealogical (degree, removed) convention: degree=2 (the default) matches "1st cousin"; degree=3 matches "2nd cousin". Candidates at a different depth than the node itself (genealogically "once removed", etc.) are not covered — see issue #56 for the full rationale and the planned post-v1.0.0 extension.

Affinity (v0.5.0)

Affinity models a non-hierarchical relationship: two nodes that share an attribute value, with no parent/child link between them. It's inter-model by design — a Department and a Project can be in Affinity even though they're unrelated concrete models, as long as both inherit CladeNode.

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


class Department(CladeNode):
    name    = models.CharField(max_length=255)
    region  = models.CharField(max_length=255, null=True, blank=True)
    manager = models.CharField(max_length=255, null=True, blank=True)

    class Meta(CladeNode.Meta):
        affinity_rules = [
            AffinityRule("region",  to="myapp.Project", target_field="cost_center", channel="geo"),
            AffinityRule("manager", to="myapp.Project", target_field="lead",         channel="management"),
        ]


class Project(CladeNode):
    title       = models.CharField(max_length=255)
    cost_center = models.CharField(max_length=255, null=True, blank=True)
    lead        = models.CharField(max_length=255, null=True, blank=True)


# Affinity rows are materialised automatically on save — no manual sync.
paris_dept = Department.objects.create(name="Paris office", region="paris", manager="alice")
paris_proj = Project.objects.create(title="Metro extension", cost_center="paris", lead="alice")

paris_dept.affinities(channel="geo")         # QuerySet[Project] → [paris_proj]
paris_dept.affinities(channel="management")  # QuerySet[Project] → [paris_proj]

# Works from either side — a passive target model (Project here) never
# itself declares affinity_rules, but still resyncs on its own save.
paris_proj.affinities(channel="geo")         # QuerySet[Department] → [paris_dept]

affinities(channel=None) returns a single QuerySet and raises HeterogeneousAffinityError if the result would span more than one partner model — this can happen when two different source models reuse the same channel name toward the same target (channel uniqueness is per declaring model, not global). Use affinities_grouped() for that case: it never raises, returning {model: QuerySet} instead of a single QuerySet.

paris_dept.affinities_grouped(channel="geo")
# {Project: <QuerySet [paris_proj]>}

Constraints:

• local_field/target_field must be one of a fixed allowlist of scalar field types (CharField, IntegerField, DateField, BooleanField, and similar) — checked at manage.py check / CI startup (clade.E002). ManyToManyField, FileField, JSONField, FloatField, and ForeignKey/OneToOneField are rejected.
• channel must be unique within a single model's affinity_rules list (clade.E001) — but is freely reusable across different source models.
• Multi-hop transitive closure (AB and BC ⟹ A~C through an intermediate node neither A nor B declares a rule toward) is not computed in v0.5.0 — deferred to v0.6.0. Only the direct relationships an AffinityRule explicitly names are materialised.

See issue #5 (DD-005) for the full design rationale.

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.