icalendar.prop.recur.recur module#

RECUR property type from RFC 5545.

class icalendar.prop.recur.recur.vRecur(*args, params=None, **kwargs)[source]#

Bases: CaselessDict

Recurrence definition.

The dateutil spelling byweekday is accepted as an alias for the iCalendar BYDAY rule part. It is normalized to BYDAY when a recurrence is parsed or serialized.

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]})]

Parameters:

*args (Any) – Positional arguments passed to OrderedDict.
**kwargs (Any) – Keyword arguments passed to OrderedDict.

Example

Create a new CaselessDict and normalize existing keys to uppercase.

>>> from icalendar.caselessdict import CaselessDict
>>> d = CaselessDict(summary="Meeting")
>>> d["SUMMARY"]
'Meeting'
>>> "summary" in d
True

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

Setter accepts:: str | None

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

property count: int | None#

The COUNT part of the recurrence rule.

This is the number of occurrences at which to range-bound the recurrence, as an alternative to specifying an UNTIL value (RFC 5545 Section 3.3.10). COUNT and UNTIL are mutually exclusive; this accessor does not enforce that.

The RFC 5545 grammar for COUNT is 1*DIGIT, so 0 is a valid value and is returned as such, not treated as missing.

If multiple values are present, the first one is returned. If the value is missing or an empty sequence, None is returned.

Setting this to None deletes the value, as does del.

Raises:

InvalidCalendar – if a value is present but cannot be read as an int. Parsing rejects a non-numeric COUNT before it can be stored, so this only happens when the value was assigned directly (recur["COUNT"] = "abc").
InvalidCalendar – when setting a negative value.
TypeError – when setting a value that is not an int.

Example

>>> from icalendar.prop import vRecur
>>> vRecur.from_ical("FREQ=DAILY;COUNT=10").count
10
>>> vRecur.from_ical("FREQ=DAILY;COUNT=0").count
0
>>> vRecur.from_ical("FREQ=DAILY").count is None
True

default_value: ClassVar[str] = 'RECUR'#

classmethod examples()[source]#

Examples of vRecur.

Return type:: list[Self]

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

classmethod from_ical(ical)[source]#

classmethod from_jcal(jcal_property)[source]#

Parse jCal from RFC 7265.

Parameters:: jcal_property (list) – The jCal property to parse.
Raises:: JCalParsingError – If the provided jCal is invalid.
Return type:: Self

classmethod from_xcal(xml)[source]#

Parse xCal from RFC 6321.

Parameters:: xml (XCalParser | ElementAdapter | Element) – The XML to parse or a parser.
Raises:: XCalParsingError – If the provided xCal is invalid.
Return type:: VProp

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

params: Parameters#

classmethod parse_type(key, values)[source]#

to_ical()[source]#

to_jcal(name)[source]#

The jCal representation of this property according to RFC 7265.

Return type:: list

to_xcal(element)[source]#

Add the xCal representation of this property according to RFC 6321.

Return type:: None

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

property wkst: vWeekday | None#

The WKST part of the recurrence rule.

This defines the day on which the workweek starts. It is significant when a weekly rule has an interval greater than one and when a yearly rule uses BYWEEKNO (RFC 5545 Section 3.3.10). The value is one of MO, TU, WE, TH, FR, SA, or SU. When omitted, RFC 5545 defines the default as MO; this accessor returns None so callers can distinguish an omitted value from an explicit one.

Because only one value is expected according to RFC 5545, if multiple values are present, the first one is returned. If the value is missing or an empty sequence, None is returned.

Setting this to None deletes the value, as does del.

Raises:

InvalidCalendar – if a value cannot be read or set as a weekday.
TypeError – when setting a value that is not a weekday string or vWeekday.

Example

>>> from icalendar.prop import vRecur
>>> vRecur("FREQ=WEEKLY;WKST=SU").wkst
'SU'
>>> vRecur("FREQ=WEEKLY").wkst is None
True

Setter accepts:: str | vWeekday | None