Skip to content

This is a fork of the original mariocesar/django-ltree. Which is an ltree extension implementation to support hierarchical tree-like data using the native Postgres extension ltree in django models

License

Notifications You must be signed in to change notification settings

GreenDeploy-io/greendeploy-django-ltree

Repository files navigation

greendeploy-django-ltree

https://img.shields.io/github/actions/workflow/status/GreenDeploy-io/greendeploy-django-ltree/main.yml?branch=main&style=for-the-badge https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge https://img.shields.io/pypi/v/greendeploy-django-ltree.svg?style=for-the-badge https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge pre-commit sourcerank codacy-grade-A

The authoritative and broadly useful Django package for using Postgres ltree fields in your Django models, designed to be transparent and accessible for Django beginners.

Welcome

Welcome to greendeploy-django-ltree, your go-to package for handling PostgreSQL ltree fields in a Django project. We're mindful of the end-to-end context and aim to make this package not just a code repository but a complete learning experience.

We aim to achieve this in three ways:

  1. Beginner-friendly documentation: We specifically tailor the
    documentation to help Django newcomers and include end-to-end demonstrations that make no assumptions about your prior knowledge of ltree or materialized paths.
  2. Quick, early wins in 10 mins each: We have picked 3 base cases as early
    wins for you. Each of these should take you no more than 10 mins to complete, including reading the docs.
    • Install in sandbox project: We show you how to install the package
      in a sandbox project and create the field in your Postgres database.
    • Add materialized path in ltree field: We show you how to add data
      to your ltree field using your Django ORM.
    • Query ltree field: We show you how to query your ltree field using
      Django ORM.
  3. Active maintenance: We are committed to maintaining this package and
    keeping it up to date with the latest Django, Python, and Postgres versions. We have plans to measure the mean time to close the Github issues and will reveal them in the near future.

About ltree

ltree is a data type in Postgres database. It is a tree-like structure where each node is a __label__. The label can be a string or a number.

Thus, the piece of data is basically a string of labels separated by dots. Also known as a __label__ __path__.

A label consists of A-Za-z0-9_ and can be up to 255 characters long.

The length of a label path is a maximum 65535 labels long.

An example of a label path is Top.Countries.Europe.Russia where Top is the root node and Russia is the leaf node.

There's another name for label path that's more better known which is Materialized Path coined by Vadim Tropashko in SQL Design Patterns.

Some good resources to read on the subject are:

Requirements

Postgres 15 supported.

Python 3.8 to 3.11 supported.

Django 4.2 supported.


Setup

Install from pip:

python -m pip install greendeploy-django-ltree

and then add it to your installed apps:

INSTALLED_APPS = [
    ...,
    "greendeploy-django-ltree",
    ...,
]

Make sure you add the trailing comma or you might get a ModuleNotFoundError (see this blog post).

You will also need to run django_ltree migrations before you added the PathField.

See Quick Start below and in documentation for more details.

About

django-ltree (Github repository) was created in March 2020 by Mario-César. It went unmaintained from August 2021.

Kimsia Sim was motivated to fork it under the name greendeploy-django-ltree in September 2023 and make it support Django 4.2. The reason is that Kimsia needed to use it in a Django 4.2 project.

The pypi package name is under greendeploy-django-ltree and formally published on 11th September 2023.

greendeploy-django-ltree has had close to 10 contributors in its time; gratitude and a big thank you to every one of them.

Quick Start

Run tests locally

Pre-requisites:

  • you have Docker installed

Steps:

  1. Spin up a postgres on Docker

    Location: project root Command: docker run --name some-postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres -e POSTGRES_DB=ltree_test -p 5432:5432 -d postgres

    Pre-requisites:
    • the credentials such as password, etc should match conftest.py.
    Leeway:
    • You may change some-postgres to something else.
  2. Start your own venv

  3. Pip install the requirements in that venv

    Location: project root Command: pip install -r requirements.txt

  4. Run pytest

    Location: project root Command: pytest -x -c pytest.ini

    Explain: -x stop on first failure -c pytest.ini use pytest.ini as config

    4a. if you want to run pytest for just one test case or one file

    Command: pytest -k '<test_case_name_or_test_file>'

    Explain: -k the name of file or test case. Can be partial

    4b. if you want to add ipdb breakpoints

    Command: pytest -s -k '<test_case_name_or_test_file>'

    Explain: -s system output for the breakpoints

About

This is a fork of the original mariocesar/django-ltree. Which is an ltree extension implementation to support hierarchical tree-like data using the native Postgres extension ltree in django models

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages