icalendar.prop.recur.recur module

RECUR property type from RFC 5545.

class icalendar.prop.recur.recur.vRecur(*args, params=None, **kwargs)

Bases: CaselessDict

Recurrence definition.

Property Name:

RRULE

Purpose:

This property defines a rule or repeating pattern for recurring events, to-dos, journal entries, or time zone definitions.

Value Type:

RECUR

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in recurring "VEVENT", "VTODO", and "VJOURNAL" calendar components as well as in the "STANDARD" and "DAYLIGHT" sub-components of the "VTIMEZONE" calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple "RRULE" properties is undefined.

Description:

The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial "DTSTART" property along with the "RRULE", "RDATE", and "EXDATE" properties contained within the recurring component. The "DTSTART" property defines the first instance in the recurrence set. The "DTSTART" property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a "DTSTART" property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified "RRULE" and "RDATE" properties, and then excluding any start DATE-TIME values specified by "EXDATE" properties. This implies that start DATE- TIME values specified by "EXDATE" properties take precedence over those specified by inclusion properties (i.e., "RDATE" and "RRULE"). Where duplicate instances are generated by the "RRULE" and "RDATE" properties, only one recurrence is considered. Duplicate instances are ignored.

The "DTSTART" property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a "DTSTART" property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

If the duration of the recurring component is specified with the "DTEND" or "DUE" property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the "DURATION" property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an "RDATE" property of PERIOD value type.

Examples

The following RRULE specifies daily events for 10 occurrences.

RRULE:FREQ=DAILY;COUNT=10

Below, we parse the RRULE ical string.

>>> from icalendar.prop import vRecur
>>> rrule = vRecur.from_ical('FREQ=DAILY;COUNT=10')
>>> rrule
vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})

You can choose to add an rrule to an icalendar.cal.Event or icalendar.cal.Todo.

>>> from icalendar import Event
>>> event = Event()
>>> event.add('RRULE', 'FREQ=DAILY;COUNT=10')
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

Set keys to upper for initial dict.

property VALUE: str

The VALUE parameter or the default.

Purpose:

VALUE explicitly specify the value type format for a property value.

Description:

This parameter specifies the value type and format of the property value. The property values MUST be of a single value type. For example, a "RDATE" property cannot have a combination of DATE-TIME and TIME value types.

If the property's value is the default value type, then this parameter need not be specified. However, if the property's default value type is overridden by some other allowable value type, then this parameter MUST be specified.

Applications MUST preserve the value data for x-name and iana-token values that they don't recognize without attempting to interpret or parse the value data.

Returns:

The VALUE parameter or the default.

Examples

The VALUE defaults to the name of the property. Note that it is case-insensitive but always uppercase.

>>> from icalendar import vBoolean
>>> b = vBoolean(True)
>>> b.VALUE
'BOOLEAN'

Setting the VALUE parameter of a typed property usually does not make sense. For convenience, using this property, the value will be converted to an uppercase string. If you have some custom property, you might use it like this:

>>> from icalendar import vUnknown, Event
>>> v = vUnknown("Some property text.")
>>> v.VALUE = "x-type"  # lower case
>>> v.VALUE
'X-TYPE'
>>> event = Event()
>>> event.add("x-prop", v)
>>> print(event.to_ical())
BEGIN:VEVENT
X-PROP;VALUE=X-TYPE:Some property text.
END:VEVENT

canonical_order = ('RSCALE', 'FREQ', 'UNTIL', 'COUNT', 'INTERVAL', 'BYSECOND', 'BYMINUTE', 'BYHOUR', 'BYDAY', 'BYWEEKDAY', 'BYMONTHDAY', 'BYYEARDAY', 'BYWEEKNO', 'BYMONTH', 'BYSETPOS', 'WKST', 'SKIP')

default_value: ClassVar[str] = 'RECUR'

classmethod examples()

Examples of vRecur.

Return type:

list[None]

frequencies = ['SECONDLY', 'MINUTELY', 'HOURLY', 'DAILY', 'WEEKLY', 'MONTHLY', 'YEARLY']

classmethod from_ical(ical)

classmethod from_jcal(jcal_property)

Parse jCal from RFC 7265.

Parameters:

jcal_property (list) – The jCal property to parse.

Raises:

JCalParsingError – If the provided jCal is invalid.

Return type:

None

jcal_not_a_list = {'COUNT', 'FREQ', 'INTERVAL', 'RSCALE', 'SKIP', 'UNTIL', 'WKST'}

params: Parameters

classmethod parse_type(key, values)

to_ical()

to_jcal(name)

The jCal representation of this property according to RFC 7265.

Return type:

list

types = {'BYDAY': <class 'icalendar.prop.recur.weekday.vWeekday'>, 'BYHOUR': <class 'icalendar.prop.integer.vInt'>, 'BYMINUTE': <class 'icalendar.prop.integer.vInt'>, 'BYMONTH': <class 'icalendar.prop.recur.month.vMonth'>, 'BYMONTHDAY': <class 'icalendar.prop.integer.vInt'>, 'BYSECOND': <class 'icalendar.prop.integer.vInt'>, 'BYSETPOS': <class 'icalendar.prop.integer.vInt'>, 'BYWEEKDAY': <class 'icalendar.prop.recur.weekday.vWeekday'>, 'BYWEEKNO': <class 'icalendar.prop.integer.vInt'>, 'BYYEARDAY': <class 'icalendar.prop.integer.vInt'>, 'COUNT': <class 'icalendar.prop.integer.vInt'>, 'FREQ': <class 'icalendar.prop.recur.frequency.vFrequency'>, 'INTERVAL': <class 'icalendar.prop.integer.vInt'>, 'RSCALE': <class 'icalendar.prop.text.vText'>, 'SKIP': <enum 'vSkip'>, 'UNTIL': <class 'icalendar.prop.dt.types.vDDDTypes'>, 'WKST': <class 'icalendar.prop.recur.weekday.vWeekday'>}