RFC 9074

CHANGES.rst

@@ -14,7 +14,7 @@ Breaking changes:
 
 New features:
 
-- ...
+- Add ``VALARM`` properties for :rfc:`9074`, see `Issue 657 <https://github.com/collective/icalendar/issues/657>`_
 
 Bug fixes:
 

README.rst

@@ -2,15 +2,15 @@
 Internet Calendaring and Scheduling (iCalendar) for Python
 ==========================================================
 
-The `icalendar`_ package is a `RFC 5545`_ compatible parser/generator for iCalendar
+The `icalendar`_ package is a :rfc:`5545` compatible parser/generator for iCalendar
 files.
 
 ----
 
 :Homepage: https://icalendar.readthedocs.io
 :Code: https://github.com/collective/icalendar
 :Mailing list: https://github.com/collective/icalendar/issues
-:Dependencies: `python-dateutil`_ and `pytz`_.
+:Dependencies: `python-dateutil`_ and `tzdata`_.
 :License: `BSD`_
 
 ----
@@ -41,9 +41,8 @@ files.
 
 
 .. _`icalendar`: https://pypi.org/project/icalendar/
-.. _`RFC 5545`: https://www.ietf.org/rfc/rfc5545.txt
 .. _`python-dateutil`: https://github.com/dateutil/dateutil/
-.. _`pytz`: https://pypi.org/project/pytz/
+.. _`tzdata`: https://pypi.org/project/tzdata/
 .. _`BSD`: https://github.com/collective/icalendar/issues/2
 
 Quick start guide
@@ -96,7 +95,7 @@ Create Events, TODOs, Journals, Alarms, ...
 -------------------------------------------
 
 ``icalendar`` supports the creation and parsing of all kinds of objects
-in the iCalendar (RFC 5545) standard.
+in the iCalendar (:rfc:`5545`) standard.
 
 .. code:: python
 
@@ -177,7 +176,7 @@ Related projects
 
 * `icalevents <https://github.com/irgangla/icalevents>`_. It is built on top of icalendar and allows you to query iCal files and get the events happening on specific dates. It manages recurrent events as well.
 * `recurring-ical-events <https://pypi.org/project/recurring-ical-events/>`_. Library to query an ``ICalendar`` object for events happening at a certain date or within a certain time.
-* `x-wr-timezone <https://pypi.org/project/x-wr-timezone/>`_. Library to make ``ICalendar`` objects and files using the non-standard ``X-WR-TIMEZONE`` compliant with the standard (RFC 5545).
+* `x-wr-timezone <https://pypi.org/project/x-wr-timezone/>`_. Library to make ``ICalendar`` objects and files using the non-standard ``X-WR-TIMEZONE`` compliant with the standard (:rfc:`5545`).
 
 Further Reading
 ===============

docs/usage.rst

@@ -12,18 +12,18 @@ Compatibility
 
 This package is compatible with the following standards:
 
-- :rfc:`5545`
-- :rfc:`7529`
-
-We do not claim compatibility to:
-
-- :rfc:`2445` - which is obsoleted by :rfc:`5545`
-- :rfc:`6886`
-- :rfc:`7953`
-- :rfc:`7986`
-- :rfc:`9073`
-- :rfc:`9074`
-- :rfc:`9253`
+- :rfc:`5545` - Internet Calendaring and Scheduling Core Object Specification (iCalendar)
+- :rfc:`7529` - Non-Gregorian Recurrence Rules in the Internet Calendaring and Scheduling Core Object Specification (iCalendar)
+- :rfc:`9074` - "VALARM" Extensions for iCalendar
+
+We do not claim compatibility to the following RFCs. They might work though.
+
+- :rfc:`2445` - obsoleted by :rfc:`5545`
+- :rfc:`6868` - Parameter Value Encoding in iCalendar and vCard
+- :rfc:`7953` - Calendar Availability
+- :rfc:`7986` - New Properties for iCalendar
+- :rfc:`9073` - Event Publishing Extensions to iCalendar
+- :rfc:`9253` - Support for iCalendar Relationships
 
 File structure
 --------------

src/icalendar/cal.py

@@ -959,10 +959,10 @@ class Alarm(Component):
     required = ('ACTION', 'TRIGGER',)
     singletons = (
             'ATTACH', 'ACTION', 'DESCRIPTION', 'SUMMARY', 'TRIGGER',
-            'DURATION', 'REPEAT',
+            'DURATION', 'REPEAT', 'UID', 'PROXIMITY', 'ACKNOWLEDGED'
             )
     inclusive = (('DURATION', 'REPEAT',), ('SUMMARY', 'ATTENDEE',))
-    multiple = ('ATTENDEE', 'ATTACH')
+    multiple = ('ATTENDEE', 'ATTACH', 'RELATED-TO')
 
 
 class Calendar(Component):

src/icalendar/prop.py

@@ -1073,6 +1073,7 @@ def __init__(self, *args, **kwargs):
         'action': 'text',
         'repeat': 'integer',
         'trigger': 'duration',
+        'acknowledged': 'date-time',
         # Change Management Component Properties
         'created': 'date-time',
         'dtstamp': 'date-time',

src/icalendar/tests/events/rfc_9074_example_1.ics

@@ -0,0 +1,16 @@
+BEGIN:VEVENT
+CREATED:20210302T151004Z
+UID:AC67C078-CED3-4BF5-9726-832C3749F627
+DTSTAMP:20210302T151004Z
+DTSTART;TZID=America/New_York:20210302T103000
+DTEND;TZID=America/New_York:20210302T113000
+SUMMARY:Meeting
+
+BEGIN:VALARM
+UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
+TRIGGER:-PT15M
+DESCRIPTION:Event reminder
+ACTION:DISPLAY
+END:VALARM
+
+END:VEVENT

src/icalendar/tests/events/rfc_9074_example_2.ics

@@ -0,0 +1,25 @@
+BEGIN:VEVENT
+CREATED:20210302T151004Z
+UID:AC67C078-CED3-4BF5-9726-832C3749F627
+DTSTAMP:20210302T151516Z
+DTSTART;TZID=America/New_York:20210302T103000
+DTEND;TZID=America/New_York:20210302T113000
+SUMMARY:Meeting
+
+BEGIN:VALARM
+UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
+TRIGGER:-PT15M
+DESCRIPTION:Event reminder
+ACTION:DISPLAY
+ACKNOWLEDGED:20210302T151514Z
+END:VALARM
+
+BEGIN:VALARM
+UID:DE7B5C34-83FF-47FE-BE9E-FF41AE6DD097
+TRIGGER;VALUE=DATE-TIME:20210302T152000Z
+RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
+DESCRIPTION:Event reminder
+ACTION:DISPLAY
+END:VALARM
+
+END:VEVENT

src/icalendar/tests/events/rfc_9074_example_3.ics

@@ -0,0 +1,25 @@
+BEGIN:VEVENT
+CREATED:20210302T151004Z
+UID:AC67C078-CED3-4BF5-9726-832C3749F627
+DTSTAMP:20210302T152026Z
+DTSTART;TZID=America/New_York:20210302T103000
+DTEND;TZID=America/New_York:20210302T113000
+SUMMARY:Meeting
+
+BEGIN:VALARM
+UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
+TRIGGER:-PT15M
+DESCRIPTION:Event reminder
+ACTION:DISPLAY
+ACKNOWLEDGED:20210302T152024Z
+END:VALARM
+
+BEGIN:VALARM
+UID:87D690A7-B5E8-4EB4-8500-491F50AFE394
+TRIGGER;VALUE=DATE-TIME:20210302T152500Z
+RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
+DESCRIPTION:Event reminder
+ACTION:DISPLAY
+END:VALARM
+
+END:VEVENT

src/icalendar/tests/events/rfc_9074_example_4.ics

@@ -0,0 +1,26 @@
+BEGIN:VEVENT
+CREATED:20210302T151004Z
+UID:AC67C078-CED3-4BF5-9726-832C3749F627
+DTSTAMP:20210302T152508Z
+DTSTART;TZID=America/New_York:20210302T103000
+DTEND;TZID=America/New_York:20210302T113000
+SUMMARY:Meeting
+
+BEGIN:VALARM
+UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
+TRIGGER:-PT15M
+DESCRIPTION:Event reminder
+ACTION:DISPLAY
+ACKNOWLEDGED:20210302T152507Z
+END:VALARM
+
+BEGIN:VALARM
+UID:87D690A7-B5E8-4EB4-8500-491F50AFE394
+TRIGGER;VALUE=DATE-TIME:20210302T152500Z
+RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
+DESCRIPTION:Event reminder
+ACTION:DISPLAY
+ACKNOWLEDGED:20210302T152507Z
+END:VALARM
+
+END:VEVENT

src/icalendar/tests/events/rfc_9074_example_proximity.ics

@@ -0,0 +1,14 @@
+BEGIN:VEVENT
+BEGIN:VALARM
+UID:77D80D14-906B-4257-963F-85B1E734DBB6
+ACTION:DISPLAY
+TRIGGER;VALUE=DATE-TIME:19760401T005545Z
+DESCRIPTION:Remember to buy milk
+PROXIMITY:DEPART
+BEGIN:VLOCATION
+UID:123456-abcdef-98765432
+NAME:Office
+URL:geo:40.443,-79.945;u=10
+END:VLOCATION
+END:VALARM
+END:VEVENT

src/icalendar/tests/test_rfc_9074.py

@@ -0,0 +1,43 @@
+"""Test the VALARM compatibility of RFC 9074.
+
+See https://www.rfc-editor.org/rfc/rfc9074.html
+and also https://github.com/collective/icalendar/issues/657
+"""
+import pytest
+
+from icalendar.prop import vDDDTypes, vText
+
+
+@pytest.mark.parametrize(
+    ("prop", "cls", "file", "alarm_index"),
+    [
+        ("UID", vText, "rfc_9074_example_1", 0),
+        ("RELATED-TO", vText, "rfc_9074_example_2", 1),
+        ("ACKNOWLEDGED", vDDDTypes, "rfc_9074_example_3", 0),
+        ("PROXIMITY", vText, "rfc_9074_example_proximity", 0),
+    ]
+)
+def test_calendar_types(events, prop, cls, file, alarm_index):
+    """Check the types of the properties."""
+    event = events[file]
+    alarm = event.subcomponents[alarm_index]
+    value = alarm[prop]
+    assert isinstance(value, cls)
+
+
+def test_snooze(events):
+    """Check values of the alarms."""
+    alarm_1 = events.rfc_9074_example_3.subcomponents[0]
+    assert alarm_1["ACKNOWLEDGED"].dt == vDDDTypes.from_ical("20210302T152024Z")
+    alarm_2 = events.rfc_9074_example_3.subcomponents[1]
+    assert alarm_2["RELATED-TO"] == "8297C37D-BA2D-4476-91AE-C1EAA364F8E1"
+    assert alarm_2["RELATED-TO"].params["RELTYPE"] == "SNOOZE"
+
+
+def test_proximity(events):
+    """Check the proximity values."""
+    alarm = events.rfc_9074_example_proximity.subcomponents[0]
+    assert alarm["PROXIMITY"] == "DEPART"
+    assert len(alarm.subcomponents) == 1
+    location = alarm.subcomponents[0]
+    assert location["UID"] == "123456-abcdef-98765432"