{"id":15495945,"url":"https://github.com/omenapps/django-range-merge","last_synced_at":"2025-04-22T21:04:55.064Z","repository":{"id":61088934,"uuid":"548189432","full_name":"OmenApps/django-range-merge","owner":"OmenApps","description":"Enables the range_merge Aggregate for Django on Postgres. range_merge \"Computes the smallest range that includes ... the given ranges\".","archived":false,"fork":false,"pushed_at":"2025-03-25T13:51:24.000Z","size":175,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T21:03:36.685Z","etag":null,"topics":["aggregates","django","function","postgres","postgresql","range"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OmenApps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-10-09T04:23:33.000Z","updated_at":"2025-03-25T13:51:28.000Z","dependencies_parsed_at":"2023-01-19T20:18:40.234Z","dependency_job_id":null,"html_url":"https://github.com/OmenApps/django-range-merge","commit_stats":null,"previous_names":["jacklinke/django-range-merge"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2Fdjango-range-merge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2Fdjango-range-merge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2Fdjango-range-merge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2Fdjango-range-merge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OmenApps","download_url":"https://codeload.github.com/OmenApps/django-range-merge/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250324689,"owners_count":21411943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aggregates","django","function","postgres","postgresql","range"],"created_at":"2024-10-02T08:20:42.428Z","updated_at":"2025-04-22T21:04:55.032Z","avatar_url":"https://github.com/OmenApps.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# django-range-merge\n\nA Django package that enables the PostgreSQL `range_merge` aggregate function for use with Django’s ORM.\n\n`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`.\n\n![Visualization of what range_merge does, returning smallest range that includes input ranges in the QuerySet](https://raw.githubusercontent.com/omenapps/django-range-merge/main/media/range_merge.png)\n\nThis package should only be used with Django projects using the Postgres database. See [Postgres docs on Range Functions](https://www.postgresql.org/docs/14/functions-range.html#RANGE-FUNCTIONS-TABLE).\n\nNote: This app is still a work-in-progress, but currently works. Tests have not yet been implemented.\n\n\n## Installation\n\n```bash\npip install django-range-merge\n```\n\nAdd to `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = [\n    ...\n    \"django_range_merge\",\n    ...\n]\n```\n\nMigrate to apply the aggregation to your database:\n\n```bash\n\u003e python manage.py migrate\n```\n\n## Getting Started\n\nHere 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.\n\nWe want two different views to help Event organizers understand some aggregate details about Events.\n\n- **range_of_visitors_this_month**: Show the overall lowest and greatest number of people we expect for all events this month\n- **overall_dates_of_funded_events**: Shows the overall range of dates for Events which are funded (the `is_funded` BooleanField is set to True)\n\nmodels.py\n\n```python\nclass Event(models.Model):\n    name = models.TextField()\n    period = models.DateTimeRangeField()\n    potential_visitors = models.IntegerRangeField()\n    is_funded = BooleanField(default=False)\n\n    class Meta:\n        verbose_name = \"Event\"\n        verbose_name_plural = \"Events\"\n\n    def __str__(self):\n        return self.name\n\n```\n\ndate_utils.py (get a range covering the entire current month)\n\n```python\nfrom django.utils import timezone\nfrom dateutil.relativedelta import relativedelta\nfrom psycopg2.extras import DateTimeTZRange\n\ndef get_month_range():\n    \"\"\"Return a DateTimeRange range covering this entire month\"\"\"\n    today = timezone.now().date()\n    if today.day \u003e 25:\n        today += timezone.timedelta(7)\n    this_month_start = today.replace(day=1)\n    next_month_start = this_month_start + relativedelta(months=1)\n    return DateTimeTZRange(this_month_start, next_month_start)\n```\n\nviews.py\n\n```python\nfrom django.db.models import F, Aggregate\nfrom django.template.response import TemplateResponse\n\nfrom .date_utils import get_month_range\n\ndef range_of_visitors_this_month(request):\n    \"\"\"\n    e.g., given the following instances:\n        {\"id\" : 1, \"name\" : \"Birthday\",     \"potential_visitors\" : \"[2, 3)\", ...}\n        {\"id\" : 2, \"name\" : \"Bake Sale\",    \"potential_visitors\" : \"[30, 50)\", ...}\n        {\"id\" : 3, \"name\" : \"Band Camp\",    \"potential_visitors\" : \"[22, 28)\", ...}\n        {\"id\" : 4, \"name\" : \"Cooking Show\", \"potential_visitors\" : \"[7, 20)\", ...}\n        {\"id\" : 5, \"name\" : \"Pajama Day\",   \"potential_visitors\" : \"[15, 30)\", ...}\n\n    The result would be:\n        {'output': NumericRange(2, 50, '[)')}\n    \"\"\"\n    template = \"base.html\"\n\n    context = Event.objects.filter(period__overlap=get_month_range()).aggregate(\n        output=Aggregate(F(\"potential_visitors\"), function=\"range_merge\")\n    )\n\n    return TemplateResponse(request, template, context)\n\ndef overall_dates_of_funded_events(request):\n    template = \"base.html\"\n\n    context = Event.objects.filter(is_funded=True).aggregate(\n        output=Aggregate(F(\"period\"), function=\"range_merge\")\n    )\n    # Example result: {'output': DateTimeRange(\"2022-10-01 02:00:00\", \"2022-12-07 12:00:00\", '[)')}\n\n    return TemplateResponse(request, template, context)\n\n```\n\nbase.html\n\n```html\n\u003chtml\u003e\n    \u003chead\u003e\u003c/head\u003e\n    \u003cbody\u003e\n        {{ output }}\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Performance Considerations\n\n- The `range_merge` aggregate operates efficiently on server side\n- Indexes on range fields can improve query performance\n- Consider using `values()` to limit data transfer when only ranges are needed\n\n\n## Development and Testing Setup\n\nThis project uses Docker Compose for development and testing. Follow these steps to get started:\n\n\n### Prerequisites\n\n1. Make sure you have Docker and Docker Compose installed\n2. Install `uv` tool: `pip install uv`\n\n\n### Setting Up the Development Environment\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/OmenApps/django-range-merge.git\n   cd django-range-merge\n   ```\n\n2. Create a virtual environment and install dependencies:\n   ```bash\n   uv venv\n   source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n   uv sync --prerelease=allow --extra=dev\n   ```\n\n3. Build and start the Docker containers:\n   ```bash\n   docker-compose up -d --build postgres\n   ```\n\n4. Run migrations:\n   ```bash\n    python manage.py migrate\n    ```\n\n### Running Tests\n\nUsing `nox`:\n\n   ```bash\n   nox -s tests\n   ```\n   This will run tests across multiple Django versions.\n\n\n### Development Database Setup\n\nThe project uses PostgreSQL for testing. The Docker Compose setup includes a PostgreSQL instance with the following configuration:\n\n- Host: localhost\n- Port: 5436  # To avoid conflicts with local PostgreSQL installations\n- Database: postgres\n- Username: postgres\n- Password: postgres\n\nThe database is automatically configured when running tests through Docker Compose.\n\n\n## License\n\nThe code in this repository is licensed under The MIT License. See LICENSE.md in the repository for more details.\n\n\n## Contributing\n\nContributions are very welcome.\n\nThis project is currently accepting all types of contributions, bug fixes,\nsecurity fixes, maintenance work, or new features.  However, please make sure\nto have a discussion about your new feature idea with the maintainers prior to\nbeginning development to maximize the chances of your change being accepted.\nYou can start a conversation by creating a new issue on this repo summarizing\nyour idea.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomenapps%2Fdjango-range-merge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomenapps%2Fdjango-range-merge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomenapps%2Fdjango-range-merge/lists"}