# Buildsheet autogenerated by ravenadm tool -- Do not edit.

NAMEBASE=		python-django-tree-queries
VERSION=		0.19.0
KEYWORDS=		python
VARIANTS=		v12 v13
SDESC[v12]=		Tree queries with explicit opt-in (3.12)
SDESC[v13]=		Tree queries with explicit opt-in (3.13)
HOMEPAGE=		https://github.com/matthiask/django-tree-queries/
CONTACT=		Python_Automaton[python@ironwolf.systems]

DOWNLOAD_GROUPS=	main
SITES[main]=		PYPIWHL/3f/0e/8ac15cd2fcc8685be4cdc22ab67e7ca7a9bbbbfbf9ce4daf447513d59a30
DISTFILE[1]=		django_tree_queries-0.19.0-py3-none-any.whl:main
DIST_SUBDIR=		python-src
DF_INDEX=		1
SPKGS[v12]=		single
SPKGS[v13]=		single

OPTIONS_AVAILABLE=	PY312 PY313
OPTIONS_STANDARD=	none
VOPTS[v12]=		PY312=ON PY313=OFF
VOPTS[v13]=		PY312=OFF PY313=ON

DISTNAME=		django_tree_queries-0.19.0.dist-info

GENERATED=		yes

[PY312].USES_ON=			python:v12,wheel

[PY313].USES_ON=			python:v13,wheel

[FILE:3754:descriptions/desc.single]
===================
django-tree-queries
===================

    :alt: CI Status

Query Django model trees using adjacency lists and recursive common
table expressions. Supports PostgreSQL, sqlite3 (3.8.3 or higher) and
MariaDB (10.2.2 or higher) and MySQL (8.0 or higher, if running without
ONLY_FULL_GROUP_BY).

Supports Django 3.2 or better, Python 3.8 or better. See the GitHub actions
build for more details.

Features and limitations
========================

- Supports only integer and UUID primary keys (for now).
- Allows specifying ordering among siblings.
- Uses the correct definition of depth, where root nodes have a depth of
  zero.
- The parent foreign key must be named ``"parent"`` at the moment (but
  why would you want to name it differently?)
- The fields added by the common table expression always are
  tree_depth, tree_path and tree_ordering. The names cannot
  be changed. tree_depth is an integer, tree_path an array of
  primary keys and tree_ordering an array of values used for
  ordering nodes within their siblings. Note that the contents of the
  tree_path and tree_ordering are subject to change. You shouldn't rely
  on their contents.
- Besides adding the fields mentioned above the package only adds queryset
  methods for ordering siblings and filtering ancestors and descendants.
Other
  features may be useful, but will not be added to the package just because
  it's possible to do so.
- Little code, and relatively simple when compared to other tree
  management solutions for Django. No redundant values so the only way
  to end up with corrupt data is by introducing a loop in the tree
  structure (making it a graph). The TreeNode abstract model class
  has some protection against this.
- Supports only trees with max. 50 levels on MySQL/MariaDB, since those
  databases do not support arrays and require us to provide a maximum
  length for the tree_path and tree_ordering upfront.

Here's a blog post offering some additional insight (hopefully) into the
reasons for `django-tree-queries' existence
<https://406.ch/writing/django-tree-queries/>`_.

Usage
=====

- Install ``django-tree-queries`` using pip.
- Extend ``tree_queries.models.TreeNode`` or build your own queryset
  and/or manager using ``tree_queries.query.TreeQuerySet``. The
  TreeNode abstract model already contains a parent foreign key
  for your convenience and also uses model validation to protect against
  loops.
- Call the ``with_tree_fields()`` queryset method if you require the
  additional fields respectively the CTE.
- Call the ``order_siblings_by("field_name")`` queryset method if you want
to
  order tree siblings by a specific model field. Note that Django's
standard
  ``order_by()`` method isn't supported -- nodes are returned according to
the
  `depth-first search algorithm
  <https://en.wikipedia.org/wiki/Depth-first_search>`__.
- Create a manager using
  ``TreeQuerySet.as_manager(with_tree_fields=True)`` if you want to add
  tree fields to queries by default.
- Until documentation is more complete I'll have to refer you to the
  [test suite
 ]
  for additional instructions and usage examples, or check the recipes
below.

Recipes
=======

Basic models
~~~~~~~~~~~~

The following two examples both extend the TreeNode which offers a few
agreeable utilities and a model validation method that prevents loops in
the
tree structure. The common table expression could be hardened against such
loops but this would involve a performance hit which we don't want -- this
is a
documented limitation (non-goal) of the library after all.

Basic tree node
---------------

.. code-block:: python

    from tree_queries.models import TreeNode

    class Node(TreeNode):
        name = models.CharField(max_length=100)



[FILE:133:distinfo]
05b9e3158e31612528f136b4704a8d807e14edc0b4a607a45377e6132517ba2c        13796 python-src/django_tree_queries-0.19.0-py3-none-any.whl