django-relativedelta 2.0.0

Usage

Using the field is straightforward. You can add the field to your model like so:

from django.db import models
from relativedeltafield import RelativeDeltaField

class MyModel(models.Model):
  rdfield=RelativeDeltaField()

Then later, you can use it:

from dateutil.relativedelta import relativedelta

rd = relativedelta(months=2,days=1,hours=6)
my_model = MyModel(rdfield=rd)
my_model.save()

Or, alternatively, you can use a string with the ISO8601 “format with designators” time interval syntax:

from dateutil.relativedelta import relativedelta

my_model = MyModel(rdfield='P2M1DT6H')
my_model.save()

For convenience, a standard Python datetime.timedelta object is also accepted:

from datetime import timedelta

td = timedelta(days=62,hours=6)
my_model = MyModel(rdfield=td)
my_model.save()

After a full_clean(), the object will always be converted to a _normalized_ relativedelta instance. It is highly recommended you use the django-fullclean app to always force full_clean() on save(), so you can be sure that after a save(), your fields are both normalized and validated.

Limitations and pitfalls

Because this field is backed by an INTERVAL column, it neither supports the relative weekday, leapdays, yearday and nlyearday arguments, nor the absolute arguments year, month, day, hour, second and microsecond.

The microseconds field is converted to a fractional seconds value, which might lead to some precision loss due to floating-point representation.

The weeks field is “virtual”, being derived from the multiple of 7 days. Thus, any week value in the input interval specification is converted to days and added to the days field of the interval. When serializing back to a string, weeks will never be written. Similarly, if the interval contains a multiple of 7 days, you can read this back out from the weeks property.

Support for databases other than PostgreSQL is limited.

For consistency reasons, when a relativedelta object is assigned to a RelativeDeltaField, it automatically calls normalized() on full_clean. This ensures that the database representation is as similar to the relativedelta as possible (for instance, fractional days are always converted to hours).