VALARM support

[niccokunzmann]

Events and TODOs can contain alarms.
These alarms can be acknowledged.

For niccokunzmann/python-recurring-ical-events#186, in order to calculate which alarms hit within a time span, I would like to get a list from the VEVENTs and VTODOs of the corresponding alarms and whether they are snoozed.

My proposal

from icalendar import Event

event = Event()

# create alarms

event.alarms.acknowledged : list[Alarm]
event.alarms.not_acknowledged : list[Alarm]
event.alarms.all : list[Alarm]

According to RFC 9074, we can snooze or acknowledge an alarm.

@property
Alarm.acknowledged : datetime.datetime # UTC

The problem as pointed out by RFC 9074 is that the VALARM component in conjunction with RFC5545 only had no defined way to acknowledge an alarm. Thus, the attributes of event.alarms and todo.alarms will take care of compatibility issues. E.g. Thunderbird saves the dates of the acknowledged alarm time in the VEVENT. Thus this cannot just be a property of VALARM but must reside in the VEVENT.

See also

• RFC 9074 - Alarm Extension #657

I will open a PR.

[niccokunzmann]

A problem that I see with this approach is that icalendar works more on the specification level than the semantic level: An event can have an RRULE and RDATE and this will not work with these.
However, this is a good start. Whoever likes, can set DTSTART of the event to another time and then check the alarms - they will only be calculated on the first, core instance of events and TODOs.
I wonder, how we would like to handle these things in general - I like the interface of the dict to access the specified properties and subcomponents. Any special 'read' functionality can be put in such properties.

[niccokunzmann]

It seems to be nicer to have another interface. The problem is this:

• we have relative alarms and we want to be able to compute them for different event starts

What is required to compute an alarm fully:

• an event or component that displays this alarm - so we know what to say
• times at which alarms were acknowledged
• alarm relationships that say if the alarm is snoozed and moved
• either absolute times of the alarm or a start+end of a component relative to which the alarm is computed

The result is:

• a time of the alarm
• a component that the user should be notified about
• a state of the alarm of whether it is active or acknowledged

[niccokunzmann]

#737 creates an interface with a functionality that is requested.