From 0dc16a67c2f279e83beac9c4b5b60dbb7cdefbf8 Mon Sep 17 00:00:00 2001 From: Jannis Date: Sat, 21 Dec 2024 22:40:53 +0100 Subject: [PATCH 1/9] docs: add vRecur example --- docs/usage.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index ddbb3faa..95bb3af7 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -387,11 +387,16 @@ 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 - >>> event.add('rrule', {'freq': 'daily'}) + >>> from icalendar import vRecur + + >>> event.add('rrule', {'freq': 'daily', 'interval': 10}) + + >>> event.add('rrule', vRecur.from_ical('FREQ=DAILY;INTERVAL=10')) Write to disk. From 6f81b19171dd5d2631e6fd5ba4f149dc3b9f2bb7 Mon Sep 17 00:00:00 2001 From: Jannis Date: Sat, 21 Dec 2024 22:46:09 +0100 Subject: [PATCH 2/9] Update changelog --- CHANGES.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGES.rst b/CHANGES.rst index d50a55c7..d74a45eb 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -7,6 +7,7 @@ Changelog Minor changes: - Add a ``weekday`` attribute to ``vWeekday`` components. See `Issue 749 `_. +- Add ``vRecur`` example to usage documentation. See `Issue 758 `_. Breaking changes: @@ -36,7 +37,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: From 3c0dc1b11be6031a01580f691e1612cd29ab1f57 Mon Sep 17 00:00:00 2001 From: Jannis Date: Sun, 22 Dec 2024 00:29:15 +0100 Subject: [PATCH 3/9] Improve class docstring --- src/icalendar/prop.py | 62 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/src/icalendar/prop.py b/src/icalendar/prop.py index 63fda819..f040f4b1 100644 --- a/src/icalendar/prop.py +++ b/src/icalendar/prop.py @@ -1100,6 +1100,68 @@ 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 + {'FREQ': ['DAILY'], 'COUNT': [10]} """ frequencies = ["SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", From e2a6aa10bf4203101e9bcc565c49eab6ce11e7c0 Mon Sep 17 00:00:00 2001 From: Jannis Date: Sun, 22 Dec 2024 00:32:25 +0100 Subject: [PATCH 4/9] Remove duplicate example --- docs/usage.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 95bb3af7..55a4444d 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -396,8 +396,6 @@ Note that if you want to add the reccurence rule from a string, you must use the >>> event.add('rrule', {'freq': 'daily', 'interval': 10}) - >>> event.add('rrule', vRecur.from_ical('FREQ=DAILY;INTERVAL=10')) - Write to disk. .. code-block:: pycon From bda6224a3199789f1030cfe9e37ae94a1499f347 Mon Sep 17 00:00:00 2001 From: Jannis <55352293+fluxxcode@users.noreply.github.com> Date: Sun, 22 Dec 2024 00:36:03 +0100 Subject: [PATCH 5/9] Update docs/usage.rst Co-authored-by: Steve Piercy --- docs/usage.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/usage.rst b/docs/usage.rst index 55a4444d..58c9611f 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -388,7 +388,8 @@ By extending the event with subcomponents, you can create multiple alarms. >>> event.add_component(alarm_24h_before) 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. +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 From b4eea5aaa5b5e35db2be66d307567f4d2f163bc4 Mon Sep 17 00:00:00 2001 From: Jannis Date: Sun, 22 Dec 2024 00:37:47 +0100 Subject: [PATCH 6/9] Revert usage example --- docs/usage.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 58c9611f..fc474d4f 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -393,9 +393,7 @@ Otherwise the rule will be escaped, making it invalid. .. code-block:: pycon - >>> from icalendar import vRecur - - >>> event.add('rrule', {'freq': 'daily', 'interval': 10}) + >>> event.add('rrule', {'freq': 'daily'}) Write to disk. From f1018c110ef8b6859d289ef58acbd30623cf5e71 Mon Sep 17 00:00:00 2001 From: Jannis Date: Sun, 22 Dec 2024 00:42:58 +0100 Subject: [PATCH 7/9] Fix example --- src/icalendar/prop.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/src/icalendar/prop.py b/src/icalendar/prop.py index f040f4b1..b6ae9125 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 @@ -1161,7 +1161,7 @@ class vRecur(CaselessDict): >>> from icalendar.prop import vRecur >>> rrule = vRecur.from_ical('FREQ=DAILY;COUNT=10') >>> rrule - {'FREQ': ['DAILY'], 'COUNT': [10]} + vRecur({'FREQ': ['DAILY'], 'COUNT': [10]}) """ frequencies = ["SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", From d55f6784b3d4f5402b4da038ebf6ad9afe255827 Mon Sep 17 00:00:00 2001 From: Jannis Date: Sun, 22 Dec 2024 00:51:18 +0100 Subject: [PATCH 8/9] Update changelog --- CHANGES.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGES.rst b/CHANGES.rst index d74a45eb..7724b581 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -7,7 +7,7 @@ Changelog Minor changes: - Add a ``weekday`` attribute to ``vWeekday`` components. See `Issue 749 `_. -- Add ``vRecur`` example to usage documentation. See `Issue 758 `_. +- Document ``vRecur`` property. See `Issue 758 `_. Breaking changes: From 5856a7fe98a27a05b729fbb79f1ce096348310b3 Mon Sep 17 00:00:00 2001 From: Jannis Date: Sun, 22 Dec 2024 01:00:36 +0100 Subject: [PATCH 9/9] Fix formatting --- src/icalendar/prop.py | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/icalendar/prop.py b/src/icalendar/prop.py index b6ae9125..c826584c 100644 --- a/src/icalendar/prop.py +++ b/src/icalendar/prop.py @@ -1101,22 +1101,27 @@ def __reduce_ex__(self, _p): class vRecur(CaselessDict): """Recurrence definition. - Property Name: RRULE + Property Name: + RRULE - Purpose: This property defines a rule or repeating pattern for recurring events, to-dos, + Purpose: + This property defines a rule or repeating pattern for recurring events, to-dos, journal entries, or time zone definitions. - Value Type: RECUR + Value Type: + RECUR - Property Parameters: IANA and non-standard property parameters can be specified on - this property. + 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" + 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. + 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