django-recurring 0.3.0

Create repeating datetimes in django using dateutil rrulesets

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

• 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.

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 recurrence sets 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 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 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
   )
   
   # 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.