django-recurring 0.3.1

Complex recurring datetimes in django using dateutil rrulesets, exportable as ical files

Create ical-compatible calendar events in django. This library is good if you need:

• iCal-compatible calendar entries with multiple events and (optionally) complex recurrence rules and multiple exclusions

• Calendar entries you can export to iCal format (.ics files)

• To add complex recurrence rules to your models and interact with them as dateutil rrulesets

Free software: MIT license

Links

• Documentation: https://django-recurring.readthedocs.io

• Git repo: https://github.com/boosh/django_recurring

Status

Initial release. There are likely to be bugs.

The 0.x series is for development only and should not be used in live projects. Semver is ignored on the 0.x branch.

Features

• Create calendar entries/schedules with multiple events, recurrence rules and exclusions

  • E.g. Every Monday in Jan & Feb, every Tuesday in Mar and Apr, except the 3rd weeks of Feb and Apr.

• Access recurrences using dateutil rrulesets

• Automatically calculate previous and next occurrences for efficient date range queries

• Timezone-aware datetime handling

• Export to iCal format (.ics files)

• Admin widget for creating and editing recurrence patterns

Quick Start

1. Install django-recurring:

   pip install django-recurring

2. Add ‘recurring’ to your INSTALLED_APPS:

   INSTALLED_APPS = [
       ...
       'recurring',
   ]

3. Run migrations:

   python manage.py migrate recurring

4. Add CalendarEntry or Event to your model:

   For a calendar entry with multiple events:

   from django.db import models
   from recurring.models import CalendarEntry
   
   class Meeting(models.Model):
       name = models.CharField(max_length=200)
       calendar = models.ForeignKey(CalendarEntry, on_delete=models.CASCADE)

   For more basic instances of a single recurring event:

   from django.db import models
   from recurring.models import Event
   
   class Task(models.Model):
       name = models.CharField(max_length=200)
       schedule = models.ForeignKey(Event, on_delete=models.CASCADE)

5. Use CalendarEntry or Event in your code:

   from django.utils import timezone
   from recurring.models import CalendarEntry, Event, RecurrenceRule, Timezone, MONDAY
   
   # Create a CalendarEntry with multiple events
   calendar = CalendarEntry.objects.create(
       name="Team Meetings",
       timezone=Timezone.objects.get(name="UTC")
   )
   
   weekly_rule = RecurrenceRule.objects.create(
       frequency=RecurrenceRule.Frequency.WEEKLY,
       interval=1,
       byweekday=[MONDAY]
   )
   
   Event.objects.create(
       calendar_entry=calendar,
       start_time=timezone.now(),
       end_time=timezone.now() + timezone.timedelta(hours=1),
       recurrence_rule=weekly_rule
   )
   
   # Create a single recurring event
   monthly_rule = RecurrenceRule.objects.create(
       frequency=RecurrenceRule.Frequency.MONTHLY,
       interval=1,
       bysetpos=[1],
       byweekday=[MONDAY]
   )
   
   task = Event.objects.create(
       start_time=timezone.now(),
       end_time=timezone.now() + timezone.timedelta(hours=2),
       recurrence_rule=monthly_rule
   )
   
   # automatically recalculate occurrences now there are some
   # events and recurrence rules
   calendar.save()
   
   # Query upcoming meetings
   upcoming_meetings = Meeting.objects.filter(
       calendar__next_occurrence__gte=timezone.now(),
       calendar__next_occurrence__lte=timezone.now() + timezone.timedelta(days=30)
   )
   
   # Query upcoming tasks
   upcoming_tasks = Task.objects.filter(
       schedule__start_time__gte=timezone.now(),
       schedule__start_time__lte=timezone.now() + timezone.timedelta(days=30)
   )

6. Export to iCal format:

   ical_string = calendar.to_ical()
   with open('team_meetings.ics', 'w') as f:
       f.write(ical_string)

For more detailed usage and examples, see the documentation.

Why?

django-recurrence lacks multiple features (e.g. times, hourly intervals, etc) that don’t seem possible to solve. A new library was in order.