Metadata-Version: 2.4
Name: django-psycopg-infinity
Version: 0.1.1
Summary: Django field and PostgreSQL backend for infinity timestamp support with psycopg3
Project-URL: Source, https://github.com/Uninett/django-psycopg-infinity
Author-email: Sikt <kontakt@sikt.no>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: django>=5.2
Requires-Dist: psycopg>=3.1
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: tox; extra == 'test'
Description-Content-Type: text/x-rst

=======================
django-psycopg-infinity
=======================

Django field and PostgreSQL backend for infinity timestamp support with psycopg >=3.

Maps PostgreSQL's ``infinity`` / ``-infinity`` timestamp values to
``datetime.max`` / ``datetime.min`` in Python, making them usable as
regular ``DateTimeField`` values in Django models.

Currently only ``DateTimeField`` is supported. ``DateField`` and ``TimeField``
infinity values are not yet handled. Contributions welcome!

Installation
============

.. code-block:: bash

    pip install django-psycopg-infinity

Configuration
=============

Set the custom database backend in your Django settings:

.. code-block:: python

    DATABASES = {
        "default": {
            "ENGINE": "django_psycopg_infinity.backends.postgresql",
            # ... other settings
        },
    }

Then use ``DateTimeInfinityField`` in your models:

.. code-block:: python

    from django.db import models
    from django_psycopg_infinity.fields import DateTimeInfinityField

    class MyModel(models.Model):
        valid_until = DateTimeInfinityField(null=True, blank=True)

Usage
=====

.. code-block:: python

    from datetime import datetime

    # Store positive infinity
    obj.valid_until = datetime.max
    obj.save()

    # Or use the string representation
    obj.valid_until = "infinity"
    obj.save()

    # Retrieve - the returned datetime matches the column type:
    # aware (UTC) for `timestamp with time zone` columns,
    # naive for `timestamp without time zone` columns.
    obj.refresh_from_db()
    assert obj.valid_until == datetime.max

Convenience constants
=====================

The package avoids calling ``timezone.get_default_timezone()`` at import time
so it can be imported before Django is fully configured. If you need
timezone-aware infinity sentinels (e.g. for model field defaults), derive them
in your own module:

.. code-block:: python

    from django_psycopg_infinity.utils import INFINITY, NEGATIVE_INFINITY, make_aware

    LOCAL_INFINITY = make_aware(INFINITY)
    LOCAL_NEGATIVE_INFINITY = make_aware(NEGATIVE_INFINITY)

Then use them as defaults:

.. code-block:: python

    class MyModel(models.Model):
        end_time = DateTimeInfinityField(default=LOCAL_INFINITY)

For fields backed by ``timestamp without time zone`` columns, use the bare
``INFINITY`` / ``NEGATIVE_INFINITY`` constants instead — a tz-aware default
would mismatch the naive values that the loader returns from those columns.

Development
===========

Tests require a running PostgreSQL instance:

.. code-block:: bash

    cp .env.example .env   # edit as needed
    uv run runtests.py

Releasing
=========

Releases are published to PyPI automatically when a version tag is pushed.
The CI runs the full test suite before publishing.

Create a new release on GitHub with a ``v``-prefixed tag (e.g. ``v0.1.0``)
and the workflow handles the rest.

Versioning is derived from git tags via ``hatch-vcs``, so there are no
version strings to update manually.

License
=======

Apache-2.0
