icalendar.alarms module

Compute the times and states of alarms.

This takes different calendar software into account and the RFC 9074 (Alarm Extension).

• RFC 9074 defines an ACKNOWLEDGED property in the VALARM.

• Outlook does not export VALARM information.

• Google Calendar uses the DTSTAMP to acknowledge the alarms.

• Thunderbird snoozes the alarms with a X-MOZ-SNOOZE-TIME attribute in the event.

• Thunderbird acknowledges the alarms with a X-MOZ-LASTACK attribute in the event.

• Etar deletes alarms that are acknowledged.

• Nextcloud’s Webinterface does not do anything with the alarms when the time passes.

class icalendar.alarms.AlarmTime(alarm: Alarm, trigger: datetime, acknowledged_until: datetime | None = None, snoozed_until: datetime | None = None, parent: Parent | None = None)

Bases: object

An alarm time with all the information.

property acknowledged: datetime | None

The time in UTC at which this alarm was last acknowledged.

If the alarm was not acknowledged (dismissed), then this is None.

property alarm: Alarm

The alarm component.

is_active() → bool

Whether this alarm is active (True) or acknowledged (False).

For example, in some calendar software, this is True until the user looks at the alarm message and clicked the dismiss button.

Alarms can be in local time (without a timezone). To calculate if the alarm really happened, we need it to be in a timezone. If a timezone is required but not given, we throw an IncompleteAlarmInformation.

property parent: Event | Todo | None

This is the component that contains the alarm.

This is None if you did not use Alarms.set_component().

property trigger: date

This is the time to trigger the alarm.

If the alarm has been snoozed, this can differ from the TRIGGER property.

class icalendar.alarms.Alarms(component: Alarm | Event | Todo | None = None)

Bases: object

Compute the times and states of alarms.

This is an example using RFC 9074. One alarm is 30 minutes before the event and acknowledged. Another alarm is 15 minutes before the event and still active.

>>> from icalendar import Event, Alarms
>>> event = Event.from_ical(
... '''BEGIN:VEVENT
... CREATED:20210301T151004Z
... UID:AC67C078-CED3-4BF5-9726-832C3749F627
... DTSTAMP:20210301T151004Z
... DTSTART;TZID=America/New_York:20210302T103000
... DTEND;TZID=America/New_York:20210302T113000
... SUMMARY:Meeting
... BEGIN:VALARM
... UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
... TRIGGER:-PT30M
... ACKNOWLEDGED:20210302T150004Z
... DESCRIPTION:Event reminder
... ACTION:DISPLAY
... END:VALARM
... BEGIN:VALARM
... UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
... TRIGGER:-PT15M
... DESCRIPTION:Event reminder
... ACTION:DISPLAY
... END:VALARM
... END:VEVENT
... ''')
>>> alarms = Alarms(event)
>>> len(alarms.times)   # all alarms including those acknowledged
2
>>> len(alarms.active)  # the alarms that are not acknowledged, yet
1
>>> alarms.active[0].trigger  # this alarm triggers 15 minutes before 10:30
datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='America/New_York'))

RFC 9074 specifies that alarms can also be triggered by proximity. This is not implemented yet.

acknowledge_until(dt: date | None) → None

This is the time in UTC when all the alarms of this component were acknowledged.

Only the last call counts.

Since RFC 9074 (Alarm Extension) was created later, calendar implementations differ in how they acknowledge alarms. For example, Thunderbird and Google Calendar store the last time an event has been acknowledged because of an alarm. All alarms that happen before this time count as acknowledged.

property active: list[AlarmTime]

The alarm times that are still active and not acknowledged.

This considers snoozed alarms.

Alarms can be in local time (without a timezone). To calculate if the alarm really happened, we need it to be in a timezone. If a timezone is required but not given, we throw an IncompleteAlarmInformation.

add_alarm(alarm: Alarm) → None

Optional: Add an alarm component.

add_component(component: Alarm | Parent)

Add a component.

If this is an alarm, it is added. Events and Todos are added as a parent and all their alarms are added, too.

set_end(dt: date | None)

Set the end of the component.

If you have only absolute alarms, this is not required. If you have alarms relative to the end of a compoment, set the end here.

set_local_timezone(tzinfo: tzinfo | str | None)

Set the local timezone.

Events are sometimes in local time. In order to compute the exact time of the alarm, some alarms without timezone are considered local.

Some computations work without setting this, others don’t. If they need this information, expect a LocalTimezoneMissing exception somewhere down the line.

set_parent(parent: Event | Todo)

Set the parent of all the alarms.

If you would like to collect alarms from a component, use add_component

set_start(dt: date | None)

Set the start of the component.

If you have only absolute alarms, this is not required. If you have alarms relative to the start of a compoment, set the start here.

snooze_until(dt: date | None) → None

This is the time in UTC when all the alarms of this component were snoozed.

Only the last call counts.

The alarms are supposed to turn up again at dt when they are not acknowledged but snoozed.

property times: list[AlarmTime]

Compute and return the times of the alarms given.

If the information for calculation is incomplete, this will raise a IncompleteAlarmInformation exception.

Please make sure to set all the required parameters before calculating. If you forget to set the acknowledged times, that is not problem.

exception icalendar.alarms.ComponentEndMissing

Bases: IncompleteAlarmInformation

We are missing the end of a component that the alarm is for.

Use Alarms.set_end().

exception icalendar.alarms.ComponentStartMissing

Bases: IncompleteAlarmInformation

We are missing the start of a component that the alarm is for.

Use Alarms.set_start().

exception icalendar.alarms.IncompleteAlarmInformation

Bases: ValueError

The alarms cannot be calculated yet because information is missing.