django-recurrence

django-recurrence is a utility for working with recurring dates in Django.

Functionality

• Recurrence/Rule objects using a subset of rfc2445 (wraps dateutil.rrule) for specifying recurring date/times,
• RecurrenceField for storing recurring datetimes in the database, and
• JavaScript widget.

RecurrenceField provides a Django model field which serializes recurrence information for storage in the database.

For example - say you were storing information about a university course in your app. You could use a model like this:

import recurrence.fields

class Course(models.Model):
    title = models.CharField(max_length=200)
    start = models.TimeField()
    end = models.TimeField()
    recurrences = recurrence.fields.RecurrenceField()

You’ll notice that I’m storing my own start and end time. The recurrence field only deals with recurrences not with specific time information. I have an event that starts at 2pm. Its recurrences would be “every Friday”.

Documentation

For more information on installation and configuration see the documentation at:

Issues

If you have questions or have trouble using the app please file a bug report at:

Contributions

All contributions are welcome!

It is best to separate proposed changes and PRs into small, distinct patches by type so that they can be merged faster into upstream and released quicker.

One way to organize contributions would be to separate PRs for e.g.

• bugfixes,
• new features,
• code and design improvements,
• documentation improvements, or
• tooling and CI improvements.

Merging contributions requires passing the checks configured with the CI. This includes running tests and linters successfully on the currently officially supported Python and Django versions.

The test automation is run automatically with GitHub Actions, but you can run it locally with the tox command before pushing commits.

Changes

1.11.1 (2021-01-25)

• Fix reStructuredTest syntax to be PyPI compliant.

1.11.0 (2021-01-21)

• Add Django 4.0 and Python 3.10 support. Deprecate EOL Django and Python versions. [aleksihakli]
• Fix weekday deserialization typing bug. [apirobot]
• Fix default recurrence.language_code not being set by using en-us for locale in frontend as the default. [jleclanche]

1.10.3

• Add Hungarian localisation #161.

1.10.2

• Add Hebrew localisation #159.

1.10.1

• Update path to jQuery to match the one Django admin provides #148.

1.10.0

• Fixes and official support for Django 2.1 and 2.2 #143, #142;
• Remove support for Python 2.7 and 3.5, remove support for Django 2.0 #145.

1.9.0

• Fix for using the recurrence widget in admin inlines #137.

1.8.2

• Minor fix for Django 2.0 #134;
• Minor packaging fix #135.

1.8.1

• Bad release, do not use.

1.8.0

This release contains two backwards incompatible changes -please read the notes below for details.

• django-recurrence now returns timezone aware datetime objects in most cases #130. If USE_TZ is True (it defaults to off with a stock Django install) then you'll now get timezone aware datetime objects back from django-recurrence. If you have USE_TZ as True, and you don't want this behaviour, you can set RECURRENCE_USE_TZ to False, but please let us know (via GitHub issues) that you wanted to opt out, so we can understand what your use case is.
• RecurrenceField instances without required=False will now require at least one rule or date. This change is intended to bring django-recurrence into line with how custom fields should behave. If you don't want to require at least one rule or date, just set require=False on your field #133.
• Improvements to avoid inline styles #85;
• Handle changes to javascript_catalog in Django 2 #131.

1.7.0

• Drop official support for Django versions 1.7, 1.8, 1.9, 1.10;
• Fixes for saving None into a RecurrenceField causing a TypeError #89`, #122;
• Drop official support for Python 3.3 and Python 3.4;
• Provisional support for Python 3.7 (only for Django 2.0 and up);
• Ensure use of render on Django widgets always passes the renderer argument, to ensure support for Django 2.1 #125;
• Django 2.0 compatibility fix for usage of django-recurrence with Django REST framework #126.

1.6.0

• Fixes for Python 3 #105;
• Support for Django 2.0 #109, #110;
• Switch back a couple of instances of DeserializationError to ValidationError #111;
• Switch around how we set dates in the date selector widget to avoid issues with short months #113.

1.5.0

• Add Slovakian translations #98;
• Add support for events occurring at a fixed point before the end of the month - e.g. the second last Tuesday before the end of the month #88;
• Add minor style changes to make django-recurrence compatible with Wagtail #100;
• Allow changing the behaviour of generating recurrences on dtstart by default. You can opt in to this by setting include_dtstart=False on your RecurrenceField #93;
• Ensure broken values raise DeserializationError where expected #103.

1.4.1

• Make PO-Revision-Date parseable by babel #75;
• Update installation notes to cover Django 1.10 #74;
• Add German translation #77;
• Add Brazilian translation #79;
• Ensure the migrations are included when installing #78;
• Fix order of arguments to to_dateutil_rruleset #81.

1.4.0

• Improve our testing setup to also cover Python 3.5;
• Fixes for Django 1.10 #69.

1.3.1

• Add Basque translations #67.

1.3.0

• Drop official support for Django 1.4, Django 1.5, Django 1.6 and Python 2.6 (no changes have been made to deliberately break older versions, but older versions will not be tested going forward);
• Add official support for Django 1.8 and Django 1.9 #62;
• Fix for a bug in Rule creation where the weekday parameter is an instance of Weekday rather than an integer #57.

1.2.0

• Added an option for events to occur on the fourth of a given weekday of the month #29;
• Fixed an off-by-one bug in the to_text method for events happening on a regular month each year #30;
• Fixed a bug in the JavaScript widget where the date for monthly events on a fixed date of the month had the description rendered incorrectly if the day selected was more than the number of days in the current calendar month #31;
• Added a French translation #32 - this may be backwards incompatible if have overriden the widget JavaScript such that there is no language_code member of your recurrence object;
• Added a Spanish translation #49;
• Added database migrations - running python manage.py migrate recurrence --fake should be sufficient for this version - nothing has changed about the database schema between 1.1.0 and 1.2.0;
• Fix broken tests for Django 1.4.

1.1.0

• Added experimental Python 3 support.
• Added extensive test coverage (from 0% to 81%).
• Added documentation (including this changelog).
• Removed RecurrenceModelField and RecurrenceModelDescriptor, which don't appear to have worked as expected for some time.
• Fixed a bug introduced in 1.0.3 which prevented the django-recurrence JavaScript from working #27.
• Don't raise ValueError if you save None into a RecurrenceField with null=False #22, for consistency with other field types.
• Make sure an empty recurrence object is falsey #25.
• Fix a copy-paste error in to_recurrence_object which prevented exclusion rules from being populated correctly.
• Fix a typo in create_from_recurrence_object which prevented it working with inclusion or exclusion rules.
• Various other very minor bugfixes.