diff --git a/CHANGES.rst b/CHANGES.rst index 5f0d38bf..237ea54f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -7,6 +7,7 @@ Changelog Minor changes: - Add a ``weekday`` attribute to ``vWeekday`` components. See `Issue 749 `_. +- Document ``vRecur`` property. See `Issue 758 `_. - Print failure of doctest to aid debugging. Breaking changes: @@ -37,7 +38,7 @@ Minor changes: - Merge "File Structure" and "Overview" sections in the docs. See `Issue 626 `_. - Update code blocks in ``usage.rst`` with the correct lexer. - Tidy up the docstring for ``icalendar.prop.vPeriod``. -- Improve typing and fix typing issues +- Improve typing and fix typing issues New features: diff --git a/docs/usage.rst b/docs/usage.rst index ddbb3faa..fc474d4f 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -387,7 +387,9 @@ By extending the event with subcomponents, you can create multiple alarms. >>> alarm_24h_before.add('description', 'Reminder: Event in 24 hours') >>> event.add_component(alarm_24h_before) -Or even recurrence. +Or even recurrence, either from a dictionary or a string. +Note that if you want to add the reccurence rule from a string, you must use the ``vRecur`` property. +Otherwise the rule will be escaped, making it invalid. .. code-block:: pycon diff --git a/src/icalendar/prop.py b/src/icalendar/prop.py index 63fda819..c826584c 100644 --- a/src/icalendar/prop.py +++ b/src/icalendar/prop.py @@ -203,7 +203,7 @@ class vCalAddress(str): .. code-block:: text mailto:jane_doe@example.com - + .. code-block:: pycon >>> from icalendar.prop import vCalAddress @@ -211,7 +211,7 @@ class vCalAddress(str): >>> cal_address vCalAddress('mailto:jane_doe@example.com') - + """ def __new__(cls, value, encoding=DEFAULT_ENCODING): @@ -259,7 +259,7 @@ class vFloat(float): 1000000.0000001 1.333 -3.14 - + .. code-block:: pycon >>> from icalendar.prop import vFloat @@ -505,11 +505,11 @@ class vDate(TimeBase): Value Name: DATE - + Purpose: This value type is used to identify values that contain a calendar date. - + Format Definition: This value type is defined by the following notation: @@ -531,7 +531,7 @@ class vDate(TimeBase): format specifies a four-digit year, two-digit month, and two-digit day of the month. There are no separator characters between the year, month, and day component text. - + Example: The following represents July 14, 1997: @@ -696,7 +696,7 @@ class vDuration(TimeBase): components MUST be added first, that is, the number of days MUST be added first, followed by the number of hours, number of minutes, and number of seconds. - + Example: A duration of 15 days, 5 hours, and 20 seconds would be: @@ -709,7 +709,7 @@ class vDuration(TimeBase): .. code-block:: text P7W - + .. code-block:: pycon >>> from icalendar.prop import vDuration @@ -805,7 +805,7 @@ class vPeriod(TimeBase): ; [ISO.8601.2004] complete representation basic format for a ; period of time consisting of a start and positive duration ; of time. - + Description: If the property permits, multiple "period" values are specified by a COMMA-separated list of values. There are two @@ -835,7 +835,7 @@ class vPeriod(TimeBase): .. code-block:: text 19970101T180000Z/PT5H30M - + .. code-block:: pycon >>> from icalendar.prop import vPeriod @@ -1100,6 +1100,73 @@ def __reduce_ex__(self, _p): class vRecur(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. + + Example: + The following RRULE specifies daily events for 10 occurrences. + + .. code-block:: text + + RRULE:FREQ=DAILY;COUNT=10 + + .. code-block:: pycon + + >>> from icalendar.prop import vRecur + >>> rrule = vRecur.from_ical('FREQ=DAILY;COUNT=10') + >>> rrule + vRecur({'FREQ': ['DAILY'], 'COUNT': [10]}) """ frequencies = ["SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY",