Examples

This page provides various examples of how to use django-recurring in your Django projects.

Note

This documentation was generated with AI. Code examples may not be 100% accurate. For tested, working code, see the source for the save() method in forms.py

Creating a CalendarEntry with Multiple Events

from django.utils import timezone
from recurring.models import CalendarEntry, Event, RecurrenceRule, Timezone, MONDAY, FRIDAY

# Create a CalendarEntry for team meetings
calendar_entry = CalendarEntry.objects.create(
    name="Team Meetings",
    description="Regular team sync-ups",
    timezone=Timezone.objects.get(name="UTC")
)

# Create a weekly meeting event
weekly_rule = RecurrenceRule.objects.create(
    frequency=RecurrenceRule.Frequency.WEEKLY,
    interval=1,
    byweekday=[MONDAY]
)

weekly_event = Event.objects.create(
    calendar_entry=calendar_entry,
    start_time=timezone.now().replace(hour=10, minute=0, second=0, microsecond=0),
    end_time=timezone.now().replace(hour=11, minute=0, second=0, microsecond=0),
    recurrence_rule=weekly_rule
)

# Create a monthly meeting event
monthly_rule = RecurrenceRule.objects.create(
    frequency=RecurrenceRule.Frequency.MONTHLY,
    interval=1,
    bysetpos=[1],  # First occurrence
    byweekday=[FRIDAY]
)

monthly_event = Event.objects.create(
    calendar_entry=calendar_entry,
    start_time=timezone.now().replace(hour=14, minute=0, second=0, microsecond=0),
    end_time=timezone.now().replace(hour=15, minute=0, second=0, microsecond=0),
    recurrence_rule=monthly_rule
)

Complex Recurrence Pattern

from recurring.models import CalendarEntry, Event, RecurrenceRule, Timezone, MONDAY, WEDNESDAY, FRIDAY

# Create a CalendarEntry for a complex schedule
calendar_entry = CalendarEntry.objects.create(
    name="Complex Schedule",
    description="A schedule with multiple recurrence patterns",
    timezone=Timezone.objects.get(name="UTC")
)

# Create an event that occurs every Monday, Wednesday, and the first Friday of each month
complex_rule = RecurrenceRule.objects.create(
    frequency=RecurrenceRule.Frequency.WEEKLY,
    interval=1,
    byweekday=[MONDAY, WEDNESDAY],  # Every Monday and Wednesday
)

complex_event = Event.objects.create(
    calendar_entry=calendar_entry,
    start_time=timezone.now().replace(hour=9, minute=0, second=0, microsecond=0),
    end_time=timezone.now().replace(hour=10, minute=0, second=0, microsecond=0),
    recurrence_rule=complex_rule
)

# Add a monthly recurrence for the first Friday
monthly_friday_rule = RecurrenceRule.objects.create(
    frequency=RecurrenceRule.Frequency.MONTHLY,
    interval=1,
    bysetpos=[1],  # First occurrence
    byweekday=[FRIDAY]
)

monthly_friday_event = Event.objects.create(
    calendar_entry=calendar_entry,
    start_time=timezone.now().replace(hour=11, minute=0, second=0, microsecond=0),
    end_time=timezone.now().replace(hour=12, minute=0, second=0, microsecond=0),
    recurrence_rule=monthly_friday_rule
)

Accessing rruleset and rrules

# Get the rruleset for a CalendarEntry
calendar_entry = CalendarEntry.objects.get(name="Complex Schedule")
rruleset = calendar_entry.to_rruleset()

# Get the next 5 occurrences
next_occurrences = list(rruleset)[:5]

# Access individual rrules for each event
for event in calendar_entry.events.all():
    if event.recurrence_rule:
        rrule = event.recurrence_rule.to_rrule(event.start_time)
        # Use the rrule object as needed

Using CalendarEntry in Your Own Model

from django.db import models
from recurring.models import CalendarEntry

class Meeting(models.Model):
    title = models.CharField(max_length=200)
    calendar_entry = models.ForeignKey(CalendarEntry, on_delete=models.CASCADE)

# Create a meeting with a calendar entry
calendar_entry = CalendarEntry.objects.create(
    name="Board Meetings",
    description="Regular board meetings",
    timezone=Timezone.objects.get(name="UTC")
)

# Add an event to the calendar entry
Event.objects.create(
    calendar_entry=calendar_entry,
    start_time=timezone.now().replace(hour=13, minute=0, second=0, microsecond=0),
    end_time=timezone.now().replace(hour=14, minute=0, second=0, microsecond=0),
    recurrence_rule=RecurrenceRule.objects.create(
        frequency=RecurrenceRule.Frequency.MONTHLY,
        interval=1,
        byweekday=["TU"],  # Every Tuesday
        bysetpos=[2]  # Second occurrence
    )
)

meeting = Meeting.objects.create(title="Monthly Board Meeting", calendar_entry=calendar_entry)

# Query meetings within a date range
upcoming_meetings = Meeting.objects.filter(
    calendar_entry__next_occurrence__gte=timezone.now(),
    calendar_entry__next_occurrence__lte=timezone.now() + timezone.timedelta(days=30)
)

Important

See notes on recalculating occurrences

Exporting to iCal Format

django-recurring supports exporting CalendarEntries to iCal format:

calendar_entry = CalendarEntry.objects.get(name="Board Meetings")
ical_string = calendar_entry.to_ical()

# Optionally, you can specify a custom PRODID
custom_ical_string = calendar_entry.to_ical(prod_id="-//My Company//My Product//EN")

# You can then save this to a file or send it as a response
with open('board_meetings.ics', 'w') as f:
    f.write(ical_string)

The resulting iCal file will contain all the events and their recurrence rules, which can be imported into most calendar applications.