Enables the range_merge Aggregate for Django on Postgres. range_merge 'Computes the smallest range that includes ... the given ranges'.

These details have not been verified by PyPI

Project description

django-range-merge

A Django package that enables the PostgreSQL range_merge aggregate function for use with Django’s ORM.

django-range-merge provides access to PostgreSQL's range_merge aggregate function, which computes the smallest range that includes all input ranges. This is particularly useful when working with Django's range fields like DateTimeRangeField, DateRangeField, or IntegerRangeField.

Visualization of what range_merge does, returning smallest range that includes input ranges in the QuerySet

This package should only be used with Django projects using the Postgres database. See Postgres docs on Range Functions.

Note: This app is still a work-in-progress, but currently works. Tests have not yet been implemented.

Installation

pip install django-range-merge

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "django_range_merge",
    ...
]

Migrate to apply the aggregation to your database:

> python manage.py migrate

Getting Started

Here is a quick example. We have an Event model with two different range fields: period, which contains the datetime range period during which the Event occurs; and potential_visitors, which is an approximation of the minimum and maximum number of people attending the Event.

We want two different views to help Event organizers understand some aggregate details about Events.

range_of_visitors_this_month: Show the overall lowest and greatest number of people we expect for all events this month
overall_dates_of_funded_events: Shows the overall range of dates for Events which are funded (the is_funded BooleanField is set to True)

models.py

class Event(models.Model):
    name = models.TextField()
    period = models.DateTimeRangeField()
    potential_visitors = models.IntegerRangeField()
    is_funded = BooleanField(default=False)

    class Meta:
        verbose_name = "Event"
        verbose_name_plural = "Events"

    def __str__(self):
        return self.name

date_utils.py (get a range covering the entire current month)

from django.utils import timezone
from dateutil.relativedelta import relativedelta
from psycopg2.extras import DateTimeTZRange

def get_month_range():
    """Return a DateTimeRange range covering this entire month"""
    today = timezone.now().date()
    if today.day > 25:
        today += timezone.timedelta(7)
    this_month_start = today.replace(day=1)
    next_month_start = this_month_start + relativedelta(months=1)
    return DateTimeTZRange(this_month_start, next_month_start)

views.py

from django.db.models import F, Aggregate
from django.template.response import TemplateResponse

from .date_utils import get_month_range

def range_of_visitors_this_month(request):
    """
    e.g., given the following instances:
        {"id" : 1, "name" : "Birthday",     "potential_visitors" : "[2, 3)", ...}
        {"id" : 2, "name" : "Bake Sale",    "potential_visitors" : "[30, 50)", ...}
        {"id" : 3, "name" : "Band Camp",    "potential_visitors" : "[22, 28)", ...}
        {"id" : 4, "name" : "Cooking Show", "potential_visitors" : "[7, 20)", ...}
        {"id" : 5, "name" : "Pajama Day",   "potential_visitors" : "[15, 30)", ...}

    The result would be:
        {'output': NumericRange(2, 50, '[)')}
    """
    template = "base.html"

    context = Event.objects.filter(period__overlap=get_month_range()).aggregate(
        output=Aggregate(F("potential_visitors"), function="range_merge")
    )

    return TemplateResponse(request, template, context)

def overall_dates_of_funded_events(request):
    template = "base.html"

    context = Event.objects.filter(is_funded=True).aggregate(
        output=Aggregate(F("period"), function="range_merge")
    )
    # Example result: {'output': DateTimeRange("2022-10-01 02:00:00", "2022-12-07 12:00:00", '[)')}

    return TemplateResponse(request, template, context)

base.html

<html>
    <head></head>
    <body>
        {{ output }}
    </body>
</html>

Performance Considerations

The range_merge aggregate operates efficiently on server side
Indexes on range fields can improve query performance
Consider using values() to limit data transfer when only ranges are needed

Development and Testing Setup

This project uses Docker Compose for development and testing. Follow these steps to get started:

Prerequisites

Make sure you have Docker and Docker Compose installed
Install uv tool: pip install uv

Setting Up the Development Environment

Clone the repository:

git clone https://github.com/OmenApps/django-range-merge.git
cd django-range-merge

Create a virtual environment and install dependencies:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync --prerelease=allow --extra=dev

Build and start the Docker containers:
```
docker-compose up -d --build postgres
```
Run migrations:
```
 python manage.py migrate
```

Running Tests

Using nox:

nox -s tests

This will run tests across multiple Django versions.

Development Database Setup

The project uses PostgreSQL for testing. The Docker Compose setup includes a PostgreSQL instance with the following configuration:

Host: localhost
Port: 5436 # To avoid conflicts with local PostgreSQL installations
Database: postgres
Username: postgres
Password: postgres

The database is automatically configured when running tests through Docker Compose.

License

The code in this repository is licensed under The MIT License. See LICENSE.md in the repository for more details.

Contributing

Contributions are very welcome.

This project is currently accepting all types of contributions, bug fixes, security fixes, maintenance work, or new features. However, please make sure to have a discussion about your new feature idea with the maintainers prior to beginning development to maximize the chances of your change being accepted. You can start a conversation by creating a new issue on this repo summarizing your idea.

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

This version

2024.10.1

Oct 26, 2024

0.2.6

Oct 11, 2022

0.2.5

Oct 9, 2022

0.2.4

Oct 9, 2022

0.2.3

Oct 9, 2022

0.2.2

Oct 9, 2022

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_range_merge-2024.10.1.tar.gz (9.1 kB view details)

Uploaded Oct 26, 2024 Source

Built Distribution

django_range_merge-2024.10.1-py3-none-any.whl (6.7 kB view details)

Uploaded Oct 26, 2024 Python 3

File details

Details for the file django_range_merge-2024.10.1.tar.gz.

File metadata

Download URL: django_range_merge-2024.10.1.tar.gz
Upload date: Oct 26, 2024
Size: 9.1 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.4.18

File hashes

Hashes for django_range_merge-2024.10.1.tar.gz
Algorithm	Hash digest
SHA256	`94c88d4f6b462a557db76514c387bd94e35586eb69db3c79ce6e2f9ed426262b`
MD5	`4532c82a125164f077ea6a5296fd463b`
BLAKE2b-256	`7428553e05e69ad51e3011f07eb9f492cfab7f52fd4f1181a55b6485505394a3`

See more details on using hashes here.

File details

Details for the file django_range_merge-2024.10.1-py3-none-any.whl.

File metadata

Download URL: django_range_merge-2024.10.1-py3-none-any.whl
Upload date: Oct 26, 2024
Size: 6.7 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.4.18

File hashes

Hashes for django_range_merge-2024.10.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`038047dfb3fa28f0ccc713dacdaadcefb23b6624cb5f5711c8bae433f751594a`
MD5	`f69e150a7c193f74287cbf3072a73247`
BLAKE2b-256	`29e6877f21add0ee51a58c5aa9b0f0b673b4402576f6c4bbf70d5b523e34c2a7`