recurring package

Submodules

recurring.forms module

class recurring.forms.CalendarEntryForm(*args: Any, **kwargs: Any)

Bases: ModelForm

class Meta

Bases: object

fields = ['name', 'description', 'timezone']

model

alias of CalendarEntry

base_fields = {'calendar_entry': <django.forms.fields.CharField object>, 'description': <django.forms.fields.CharField object>, 'name': <django.forms.fields.CharField object>, 'timezone': <django.forms.models.ModelChoiceField object>}

clean() → Dict[str, Any]

Hook for doing any extra form-wide cleaning after Field.clean() has been called on every field. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field named ‘__all__’.

declared_fields = {'calendar_entry': <django.forms.fields.CharField object>}

property media

Return all media required to render the widgets on this form.

save(commit: bool = True) → CalendarEntry

Save this form’s self.instance object if commit=True. Otherwise, add a save_m2m() method to the form which can be called after the instance is saved manually at a later time. Return the model instance.

recurring.models module

class recurring.models.CalendarEntry(*args, **kwargs)

Bases: Model

Represents a calendar entry with associated events and recurrence rules.

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

calculate_occurrences(window_days: int = 365, window_multiple: int = 3) → None

Recalculates the cached occurrences of the CalendarEntry in UTC. Calculated occurrences include:

• first_occurrence/last_occurrence (across all events in the CalendarEntry). Capped based on the window parameters for performance reasons.

• previous_occurrence/next_occurrence (relative to the time this method was last called)

Parameters:

• window_days – The number of days to use as the basis for calculating the delta from now for the ‘first’/’last’ occurrences

• window_multiple – Multiplied by occurence_window_days to create the delta from now to use to calculate the ‘first’/’last’ occurrences. E.g. if window_days=365 and window_multiple=5, we’ll only look forwards and backwards 5 years to calculate the ‘first’ and ‘last’ occurrences.

created_at

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

delete(*args: Any, **kwargs: Any) → None

Deletes the CalendarEntry and associated events and recurrence rules.

Parameters:

• args – Variable length argument list

• kwargs – Arbitrary keyword arguments

description

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

events

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

first_occurrence

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

from_dict(data: Dict[str, Any]) → None

Populates the CalendarEntry from a dictionary representation.

Parameters:

data (Dict[str, Any]) – A dictionary containing CalendarEntry data

get_next_by_created_at(*, field=<django.db.models.fields.DateTimeField: created_at>, is_next=True, **kwargs)

get_next_by_updated_at(*, field=<django.db.models.fields.DateTimeField: updated_at>, is_next=True, **kwargs)

get_previous_by_created_at(*, field=<django.db.models.fields.DateTimeField: created_at>, is_next=False, **kwargs)

get_previous_by_updated_at(*, field=<django.db.models.fields.DateTimeField: updated_at>, is_next=False, **kwargs)

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

last_occurrence

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

next_occurrence

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>

previous_occurrence

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

save(*args: Any, **kwargs: Any) → None

Saves the CalendarEntry and optionally recalculates occurrences.

Parameters:

• args – Variable length argument list

• kwargs – Arbitrary keyword arguments

• recalculate (bool) – Whether to recalculate occurrences. Defaults to True.

timezone

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

timezone_id

to_dict() → Dict[str, Any]

Converts the CalendarEntry to a dictionary representation.

Returns:

A dictionary representation of the CalendarEntry

Return type:

Dict[str, Any]

to_ical(prod_id: str | None = None) → str

Convert the CalendarEntry to an iCal string representation.

Parameters:

prod_id (Optional[str]) – The PRODID to use in the iCal. Defaults to None.

Returns:

The iCal string representation of the calendar entry.

Return type:

str

to_rruleset()

Converts the CalendarEntry to an rruleset object.

Returns:

An rruleset object representing the CalendarEntry

Return type:

rruleset

updated_at

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

class recurring.models.Event(*args, **kwargs)

Bases: Model

Represents an event within a CalendarEntry.

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

calendar_entry

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

calendar_entry_id

clean() → None

Validates the Event object.

Raises:

ValidationError – If the event data is invalid

delete(*args: Any, **kwargs: Any) → None

Deletes all associated recurrence rules.

Parameters:

• args – Variable length argument list

• kwargs – Arbitrary keyword arguments

end_time

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

exclusions

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

get_next_by_start_time(*, field=<django.db.models.fields.DateTimeField: start_time>, is_next=True, **kwargs)

get_previous_by_start_time(*, field=<django.db.models.fields.DateTimeField: start_time>, is_next=False, **kwargs)

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

is_full_day

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>

recurrence_rule

Accessor to the related object on the forward side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

Restaurant.place is a ForwardOneToOneDescriptor instance.

recurrence_rule_id

save(*args: Any, **kwargs: Any) → None

Saves the Event object after full cleaning and updates exclusions.

Parameters:

• args – Variable length argument list

• kwargs – Arbitrary keyword arguments

start_time

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

update_exclusions() → None

Updates the time component of all exclusions associated with this event.

class recurring.models.ExclusionDateRange(*args, **kwargs)

Bases: Model

Represents a date range for which an event should be excluded from recurrence.

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

clean() → None

Validates the ExclusionDateRange object.

Raises:

ValidationError – If the start date is not less than the end date

delete(*args: Any, **kwargs: Any) → None

Deletes the ExclusionDateRange object and recalculates occurrences for the associated CalendarEntry.

Parameters:

• args – Variable length argument list

• kwargs – Arbitrary keyword arguments

end_date

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

event

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

event_id

get_all_dates() → list[datetime]

Returns a list of all dates within the ExclusionDateRange.

Returns:

A list of datetime objects

Return type:

list[datetime]

get_next_by_end_date(*, field=<django.db.models.fields.DateTimeField: end_date>, is_next=True, **kwargs)

get_next_by_start_date(*, field=<django.db.models.fields.DateTimeField: start_date>, is_next=True, **kwargs)

get_previous_by_end_date(*, field=<django.db.models.fields.DateTimeField: end_date>, is_next=False, **kwargs)

get_previous_by_start_date(*, field=<django.db.models.fields.DateTimeField: start_date>, is_next=False, **kwargs)

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>

save(*args: Any, **kwargs: Any) → None

Saves the ExclusionDateRange object after full cleaning and optionally syncs time component.

Parameters:

• args – Variable length argument list

• kwargs – Arbitrary keyword arguments

start_date

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

sync_time_component() → None

Synchronizes the time component of the start and end dates with the event’s start time.

to_rrule() → rrule

Converts the ExclusionDateRange to an rrule object.

Returns:

An rrule object representing the ExclusionDateRange

Return type:

rrule

class recurring.models.RecurrenceRule(*args, **kwargs)

Bases: Model

Represents a recurrence rule for calendar events.

This model defines the parameters for recurring events, including frequency, interval, and various constraints on recurrence.

exception DoesNotExist

Bases: ObjectDoesNotExist

class Frequency(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntegerChoices

Enumeration of possible frequency values for recurrence.

DAILY = 3

HOURLY = 4

MINUTELY = 5

MONTHLY = 1

SECONDLY = 6

WEEKLY = 2

YEARLY = 0

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

WEEKDAYS = ((0, 'MO'), (1, 'TU'), (2, 'WE'), (3, 'TH'), (4, 'FR'), (5, 'SA'), (6, 'SU'))

byhour

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

byminute

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

bymonth

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

bymonthday

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

bysecond

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

bysetpos

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

byweekday

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

byweekno

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

byyearday

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

clean() → None

Validates the RecurrenceRule object.

Raises:

ValidationError – If both count and until are set

count

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

event

Accessor to the related object on the reverse side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

Place.restaurant is a ReverseOneToOneDescriptor instance.

frequency

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

property frequency_name

get_frequency_display() → str

Returns the display name of the frequency.

Returns:

The name of the frequency

Return type:

str

get_wkst_display() → str | None

Returns the display name of the week start day.

Returns:

The name of the week start day, or None if not set

Return type:

Optional[str]

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

interval

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>

save(*args: Any, **kwargs: Any) → None

Saves the RecurrenceRule object after full cleaning.

Parameters:

• args – Variable length argument list

• kwargs – Arbitrary keyword arguments

to_dict() → Dict[str, Any]

Converts the RecurrenceRule to a dictionary representation.

Returns:

A dictionary representation of the RecurrenceRule

Return type:

Dict[str, Any]

to_rrule(start_date: datetime) → rrule

Creates an rrule object from the RecurrenceRule.

Parameters:

start_date (datetime) – The start date for the recurrence rule

Returns:

An rrule object

Return type:

rrule

until

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

wkst

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

class recurring.models.Timezone(*args, **kwargs)

Bases: Model

Represents a timezone in the system.

This is just an optimisation to denormalise data. You’ll probably want your own Timezone model with extra fields that you actually display to users (if you let them select timezones, etc).

Parameters:

name (str) – The name of the timezone

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

property as_tz

Returns the timezone as a ZoneInfo timezone object.

Returns:

A ZoneInfo timezone object

Return type:

ZoneInfo

calendarentry_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

clean() → None

Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>

save(*args: Any, **kwargs: Any) → None

Saves the TimeZone object after full cleaning.

Parameters:

• args – Variable length argument list

• kwargs – Arbitrary keyword arguments

class recurring.models.WeekDay

Bases: object

FRIDAY = 'FR'

MONDAY = 'MO'

SATURDAY = 'SA'

SUNDAY = 'SU'

THURSDAY = 'TH'

TUESDAY = 'TU'

WEDNESDAY = 'WE'

Module contents

Top-level package for django-recurring.