icalendar.cal.alarm module#

RFC 5545 VALARM component.

class icalendar.cal.alarm.Alarm(*args, **kwargs)[source]#

Bases: Component

A "VALARM" calendar component is a grouping of component properties that defines an alarm or reminder for an event or a to-do. For example, it may be used to define a reminder for a pending event or an overdue to-do.

Example

The following example creates an alarm which uses an audio file from an FTP server.

>>> from icalendar import Alarm
>>> alarm = Alarm.example()
>>> print(alarm.to_ical().decode())
BEGIN:VALARM
ACTION:AUDIO
ATTACH;FMTTYPE=audio/basic:ftp://example.com/pub/sounds/bell-01.aud
DURATION:PT15M
REPEAT:4
TRIGGER;VALUE=DATE-TIME:19970317T133000Z
END:VALARM

Set keys to upper for initial dict.

property ACKNOWLEDGED: datetime | None#

The ACKNOWLEDGED property with all values converted to a datetime in UTC.

This property is the UTC datetime at which this alarm was last sent or acknowledged as defined in RFC 9074.

Setting this property allows calendar clients to dismiss or suppress an alarm across multiple devices. Once set to a value greater than or equal to the alarm's computed trigger time, conforming clients will not refire the alarm.

Returns None when no acknowledgment has been recorded.

Example

Mark an alarm as acknowledged. Note that the example uses an arbitrary time for the purpose of passing doctests. In actual practice, clients should use the current time in UTC, such as datetime.now(UTC).

>>> from datetime import timezone, datetime
>>> from icalendar import Alarm
>>> UTC = timezone.utc
>>> alarm = Alarm()
>>> alarm.ACKNOWLEDGED = datetime(2024, 1, 15, 10, 0, tzinfo=UTC)
>>> alarm.ACKNOWLEDGED
datetime.datetime(2024, 1, 15, 10, 0, tzinfo=ZoneInfo(key='UTC'))

See also

TRIGGER, the time at which the alarm fires.

property ACTION: str#

The action invoked when the alarm triggers.

Typical values defined by RFC 5545 Section 3.8.6.1 are AUDIO, DISPLAY, and EMAIL. The empty string is returned when no ACTION property is present.

property DURATION: timedelta | None#

The delay between repeated triggers of a repeating alarm.

Returns a datetime.timedelta or None when the alarm has no DURATION set. Setting this attribute accepts a timedelta; deleting it removes the property from the component.

DURATION is meaningful only for repeating alarms and must be paired with REPEAT. The two together produce REPEAT additional triggers, each spaced by DURATION after the initial trigger.

Conforming with RFC 5545 Section 3.8.2.5, the DURATION property can appear once in an Alarm component.

Example

Pair DURATION with REPEAT to produce three triggers spaced ten minutes apart.

>>> from datetime import timedelta
>>> from icalendar import Alarm
>>> alarm = Alarm()
>>> alarm.TRIGGER = timedelta(minutes=-30)
>>> alarm.DURATION = timedelta(minutes=10)
>>> alarm.REPEAT = 2
>>> alarm.DURATION
datetime.timedelta(seconds=600)
property REPEAT: int#

The number of additional times the alarm is triggered after the initial trigger.

Defaults to 0, meaning the alarm fires once. To repeat the alarm, set both REPEAT and DURATION. The DURATION sets the gap between repetitions. REPEAT is the count of additional triggers, so a REPEAT of 2 produces three alarms in total (the initial trigger plus two repeats).

Conforming with RFC 5545 Section 3.8.6.2, this property can appear once in an Alarm component and must be paired with DURATION.

Example

Build an alarm that fires once and then repeats twice at five-minute intervals.

>>> from datetime import timedelta
>>> from icalendar import Alarm
>>> alarm = Alarm()
>>> alarm.TRIGGER = timedelta(minutes=-15)
>>> alarm.DURATION = timedelta(minutes=5)
>>> alarm.REPEAT = 2
>>> alarm.REPEAT
2
Raises:

  • TypeError – If the value is not an int. Booleans are rejected, too, even though bool subclasses int.

  • InvalidCalendar – If the value is negative.

Changed in version 7.3.0: Negative values are no longer accepted.

property TRIGGER: timedelta | datetime | None#

The TRIGGER property.

The time at which this alarm fires, per RFC 5545 Section 3.8.6.3.

The value is either a timedelta (relative trigger) or a UTC datetime (absolute trigger).

A negative timedelta fires before the related component boundary (start or end); a positive one fires after it. Use TRIGGER_RELATED to choose whether the offset is measured from the start or the end of the parent event or to-do. An absolute trigger fires at an exact UTC point in time regardless of the parent component's dates.

Examples

Set an alarm to fire 15 minutes before the start of an event.

>>> from datetime import datetime, timedelta, timezone
>>> from icalendar import Alarm, Event
>>> UTC = timezone.utc
>>> event = Event()
>>> event.start = datetime(2024, 1, 15, 10, 0, tzinfo=UTC)
>>> alarm = Alarm()
>>> alarm.TRIGGER = timedelta(minutes=-15)
>>> event.add_component(alarm)
>>> event.alarms.times[0].trigger
datetime.datetime(2024, 1, 15, 9, 45, tzinfo=datetime.timezone.utc)

Set an absolute trigger to fire at a specific UTC time.

>>> absolute_alarm = Alarm()
>>> absolute_alarm.TRIGGER = datetime(2024, 1, 15, 9, 45, tzinfo=UTC)
>>> absolute_alarm.TRIGGER
datetime.datetime(2024, 1, 15, 9, 45, tzinfo=datetime.timezone.utc)

See also

TRIGGER_RELATED, DURATION, REPEAT

To delete the value, either use del or set it to None.

Raises:

InvalidCalendar – if the attribute has invalid values.

The RELATED parameter of the TRIGGER property.

Values are either "START" (default) or "END".

A value of START will set the alarm to trigger off the start of the associated event or to-do. A value of END will set the alarm to trigger off the end of the associated event or to-do.

In this example, we create an alarm that triggers two hours after the end of its parent component.

>>> from icalendar import Alarm
>>> from datetime import timedelta
>>> alarm = Alarm()
>>> alarm.TRIGGER = timedelta(hours=2)
>>> alarm.TRIGGER_RELATED = "END"
class Triggers(start: tuple[timedelta], end: tuple[timedelta], absolute: tuple[datetime])[source]#

Bases: NamedTuple

The computed times of alarm triggers.

start - triggers relative to the start of the Event or Todo (timedelta)

end - triggers relative to the end of the Event or Todo (timedelta)

absolute - triggers at a datetime in UTC

Create new instance of Triggers(start, end, absolute)

absolute: tuple[datetime]#

Alias for field number 2

end: tuple[timedelta]#

Alias for field number 1

start: tuple[timedelta]#

Alias for field number 0

property attachments: list[vUri | vBinary]#

This property defines the attachments for a component.

Setting this property replaces all existing attachments. A str is converted to vUri, and bytes is converted to vBinary. Values that are already vUri or vBinary are stored unchanged, so their parameters are preserved. Setting None or an empty list removes all attachments, as does deleting the property.

Parameters:

attachments (str | bytes | vUri | vBinary | list | None) – A single attachment, or a list of attachments to set. Accepts str, bytes, vUri, and vBinary, individually or mixed together in a list.

Example

Attach a URI to an event, then replace it with a URI and inline binary data together:

>>> from icalendar import Event, vUri, vBinary
>>> event = Event()
>>> event.attachments
[]
>>> event.attachments = ["https://example.com/agenda.pdf"]
>>> print(event.to_ical().decode())
BEGIN:VEVENT
ATTACH:https://example.com/agenda.pdf
END:VEVENT
>>> event.attachments = [
...     vUri(
...         "https://example.com/agenda.pdf",
...         params={"FMTTYPE": "application/pdf"},
...     ),
...     vBinary(b"image-data", params={"FMTTYPE": "image/png"},),
... ]
>>> len(event.attachments)
2

Note

An alarm as an audio action must not contain more than one attachment.

List modifications do not modify the component. Methods such as append(), extend(), and remove(), as well as item assignment, act on a copy. Assign the list back to the property, or use Component.add with a typed value instead.

See also

RFC 5545 Section 3.8.1.1 for the definition of the ATTACH property.

property attendees: list[vCalAddress]#

ATTENDEE defines one or more "Attendees" within a calendar component.

Conformance:

This property MUST be specified in an iCalendar object that specifies a group-scheduled calendar entity. This property MUST NOT be specified in an iCalendar object when publishing the calendar information (e.g., NOT in an iCalendar object that specifies the publication of a calendar user's busy time, event, to-do, or journal). This property is not specified in an iCalendar object that specifies only a time zone definition or that defines calendar components that are not group-scheduled components, but are components only on a single user's calendar.

Description:

This property MUST only be specified within calendar components to specify participants, non-participants, and the chair of a group-scheduled calendar entity. The property is specified within an "EMAIL" category of the "VALARM" calendar component to specify an email address that is to receive the email type of iCalendar alarm.

Examples

Assign one or more attendee email addresses directly. Strings are converted to vCalAddress objects and receive a mailto: prefix when needed.

>>> from icalendar import Event
>>> event = Event()
>>> event.attendees = [
...     "me@my-domain.com",
...     "mailto:you@my-domain.com",
... ]
>>> event.attendees[0]
vCalAddress('mailto:me@my-domain.com')
>>> event.attendees[1]
vCalAddress('mailto:you@my-domain.com')
>>> print(event.to_ical())
BEGIN:VEVENT
ATTENDEE:mailto:me@my-domain.com
ATTENDEE:mailto:you@my-domain.com
END:VEVENT

Use vCalAddress.new when an attendee needs parameters such as CN, ROLE, or RSVP.

>>> from icalendar import vCalAddress
>>> event.attendees = [
...     vCalAddress.new(
...         "chair@example.com",
...         cn="Meeting Chair",
...         role="CHAIR",
...         rsvp=True,
...     )
... ]
property description: str | None#

DESCRIPTION provides a more complete description of the calendar component than that provided by the "SUMMARY" property.

Property Parameters:

IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.

Conformance:

The property can be specified in the "VEVENT", "VTODO", "VJOURNAL", or "VALARM" calendar components. The property can be specified multiple times only within a "VJOURNAL" calendar component.

Description:

This property is used in the "VEVENT" and "VTODO" to capture lengthy textual descriptions associated with the activity.

This property is used in the "VALARM" calendar component to capture the display text for a DISPLAY category of alarm, and to capture the body text for an EMAIL category of alarm.

Examples

The following is an example of this property with formatted line breaks in the property value:

DESCRIPTION:Meeting to provide technical review for "Phoenix"
 design.\nHappy Face Conference Room. Phoenix design team
 MUST attend this meeting.\nRSVP to team leader.
classmethod example(name='example')[source]#

Return the alarm example with the given name.

Return type:

Alarm

inclusive: ClassVar[tuple[str] | tuple[tuple[str, str]]] = (('DURATION', 'REPEAT'), ('SUMMARY', 'ATTENDEE'))#

These properties are inclusive.

In other words, if the first property in the tuple occurs, then the second one must also occur.

Example

('duration', 'repeat')
multiple: ClassVar[tuple[()]] = ('ATTENDEE', 'ATTACH', 'RELATED-TO')#

These properties may occur more than once.

name: ClassVar[str | None] = 'VALARM'#

The name of the component.

This is defined in each component class.

Example

>>> from icalendar import Calendar
>>> cal = Calendar.new()
>>> cal.name
'VCALENDAR'
classmethod new(action=None, attachments=None, attendees=None, concepts=None, description=None, links=None, refids=None, related_to=None, summary=None, uid=None)[source]#

Create a new alarm with all required properties.

This creates a new Alarm in accordance with RFC 5545.

Parameters:
Return type:

None

Returns:

Alarm

Raises:

InvalidCalendar – If the content is not valid according to RFC 5545.

Warning

As time progresses, we will be stricter with the validation.

classmethod new_audio(trigger, attachments=None, duration=None, repeat=None, uid=None, links=None, related_to=None, refids=None, concepts=None)[source]#

Create a new AUDIO alarm that plays a sound.

An AUDIO alarm plays a sound at the trigger time. An optional attachments URI points to the audio file to play; when omitted, the client uses its default alert sound.

Conforms to RFC 5545 Section 3.6.6.

Parameters:
Return type:

Alarm

Returns:

Alarm with ACTION:AUDIO set.

Raises:

InvalidCalendar – If required fields are missing or duration and repeat are not both provided together.

Example

Create an audio alarm using a custom sound file:

>>> from datetime import timedelta
>>> from icalendar import Alarm
>>> alarm = Alarm.new_audio(
...     trigger=timedelta(minutes=-5),
...     attachments="ftp://example.com/pub/sounds/bell-01.aud",
... )
>>> print(alarm.to_ical().decode())
BEGIN:VALARM
ACTION:AUDIO
ATTACH:ftp://example.com/pub/sounds/bell-01.aud
TRIGGER:-PT5M
END:VALARM
classmethod new_display(description, trigger, duration=None, repeat=None, uid=None, links=None, related_to=None, refids=None, concepts=None)[source]#

Create a new DISPLAY alarm that shows a text reminder.

A DISPLAY alarm pops up a text notification at the trigger time. This is the most common alarm type used by calendar clients.

Conforms to RFC 5545 Section 3.6.6.

Parameters:
Return type:

Alarm

Returns:

Alarm with ACTION:DISPLAY set.

Raises:

InvalidCalendar – If required fields are missing or duration and repeat are not both provided together.

Example

Create a display alarm that fires 15 minutes before the event:

>>> from datetime import timedelta
>>> from icalendar import Alarm
>>> alarm = Alarm.new_display(
...     description="Team meeting in 15 minutes",
...     trigger=timedelta(minutes=-15),
... )
>>> print(alarm.to_ical().decode())
BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:Team meeting in 15 minutes
TRIGGER:-PT15M
END:VALARM

Attach the alarm to an event:

from datetime import datetime, timedelta, timezone
from icalendar import Alarm, Event

event = Event.new(
    summary="Team meeting",
    start=datetime(2025, 6, 1, 10, 0, tzinfo=timezone.utc),
    end=datetime(2025, 6, 1, 11, 0, tzinfo=timezone.utc),
)
event.add_component(Alarm.new_display(
    description="Team meeting in 15 minutes",
    trigger=timedelta(minutes=-15),
))
classmethod new_email(summary, description, trigger, attendees, attachments=None, duration=None, repeat=None, uid=None, links=None, related_to=None, refids=None, concepts=None)[source]#

Create a new EMAIL alarm that sends an email notification.

An EMAIL alarm sends an email to each address in attendees when the alarm fires.

Conforms to RFC 5545 Section 3.6.6.

Parameters:
Return type:

Alarm

Returns:

Alarm with ACTION:EMAIL set.

Raises:

InvalidCalendar – If required fields are missing, attendees is empty, or duration and repeat are not both provided together.

Example

Create an email alarm sent to two recipients. Plain email strings and mailto:-prefixed strings are both accepted and normalized to vCalAddress:

>>> from datetime import timedelta
>>> from icalendar import Alarm
>>> alarm = Alarm.new_email(
...     summary="Meeting reminder",
...     description="Your meeting starts in 30 minutes.",
...     trigger=timedelta(minutes=-30),
...     attendees=["user@example.com", "mailto:boss@example.com"],
... )
>>> print(alarm.to_ical().decode())
BEGIN:VALARM
ACTION:EMAIL
ATTENDEE:mailto:user@example.com
ATTENDEE:mailto:boss@example.com
DESCRIPTION:Your meeting starts in 30 minutes.
SUMMARY:Meeting reminder
TRIGGER:-PT30M
END:VALARM
property repeat#

The number of additional times the alarm is triggered after the initial trigger.

Defaults to 0, meaning the alarm fires once. Must be paired with DURATION. Conforms with RFC 5545 Section 3.8.6.2. The value is capped at icalendar.config.MAX_ALARM_REPEAT on read.

Raises:

  • TypeError – If the value is not an int. Booleans are rejected, too, even though bool subclasses int.

  • InvalidCalendar – If the value is negative.

Changed in version 7.3.0: Negative values are no longer accepted.

required: ClassVar[tuple[()]] = ('ACTION', 'TRIGGER')#

These properties are required.

singletons: ClassVar[tuple[()]] = ('ACTION', 'DESCRIPTION', 'SUMMARY', 'TRIGGER', 'DURATION', 'REPEAT', 'UID', 'PROXIMITY', 'ACKNOWLEDGED')#

These properties must appear only once.

property summary: str | None#

SUMMARY defines a short summary or subject for the calendar component.

Property Parameters:

IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.

Conformance:

The property can be specified in "VEVENT", "VTODO", "VJOURNAL", or "VALARM" calendar components.

Description:

This property is used in the "VEVENT", "VTODO", and "VJOURNAL" calendar components to capture a short, one-line summary about the activity or journal entry.

This property is used in the "VALARM" calendar component to capture the subject of an EMAIL category of alarm.

Examples

The following is an example of this property:

SUMMARY:Department Party
property triggers#

The computed triggers of an Alarm.

This takes the TRIGGER, DURATION and REPEAT properties into account.

Here, we create an alarm that triggers 3 times before the start of the parent component.

>>> from icalendar import Alarm
>>> from datetime import timedelta
>>> alarm = Alarm()
>>> alarm.TRIGGER = timedelta(hours=-4)  # trigger 4 hours before START
>>> alarm.DURATION = timedelta(hours=1)  # after 1 hour trigger again
>>> alarm.REPEAT = 2  # trigger 2 more times
>>> alarm.triggers.start == (timedelta(hours=-4),  timedelta(hours=-3),  timedelta(hours=-2))
True
>>> alarm.triggers.end
()
>>> alarm.triggers.absolute
()
property uid: str#

UID specifies the persistent, globally unique identifier for a component.

We recommend using uuid.uuid4() to generate new values.

Returns:

The value of the UID property as a string or "" if no value is set.

Description:

The "UID" itself MUST be a globally unique identifier. The generator of the identifier MUST guarantee that the identifier is unique.

This is the method for correlating scheduling messages with the referenced "VEVENT", "VTODO", or "VJOURNAL" calendar component. The full range of calendar components specified by a recurrence set is referenced by referring to just the "UID" property value corresponding to the calendar component. The "RECURRENCE-ID" property allows the reference to an individual instance within the recurrence set.

This property is an important method for group-scheduling applications to match requests with later replies, modifications, or deletion requests. Calendaring and scheduling applications MUST generate this property in "VEVENT", "VTODO", and "VJOURNAL" calendar components to assure interoperability with other group- scheduling applications. This identifier is created by the calendar system that generates an iCalendar object.

Implementations MUST be able to receive and persist values of at least 255 octets for this property, but they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence.

RFC 7986 states that UID can be used, for example, to identify duplicate calendar streams that a client may have been given access to. It can be used in conjunction with the "LAST-MODIFIED" property also specified on the "VCALENDAR" object to identify the most recent version of a calendar.

Conformance:

RFC 5545 states that the "UID" property can be specified on "VEVENT", "VTODO", and "VJOURNAL" calendar components. RFC 7986 modifies the definition of the "UID" property to allow it to be defined in an iCalendar object. RFC 9074 adds a "UID" property to "VALARM" components to allow a unique identifier to be specified. The value of this property can then be used to refer uniquely to the "VALARM" component.

This property can be specified once only.

Security:

RFC 7986 states that UID values MUST NOT include any data that might identify a user, host, domain, or any other security- or privacy-sensitive information. It is RECOMMENDED that calendar user agents now generate "UID" values that are hex-encoded random Universally Unique Identifier (UUID) values as defined in Sections 4.4 and 4.5 of RFC 4122. You can use the uuid module to generate new UUIDs.

Compatibility:

For Alarms, X-ALARMUID is also considered.

Examples

The following is an example of such a property value: 5FC53010-1267-4F8E-BC28-1D7AE55A7C99.

Set the UID of a calendar:

>>> from icalendar import Calendar
>>> from uuid import uuid4
>>> calendar = Calendar()
>>> calendar.uid = uuid4()
>>> print(calendar.to_ical())
BEGIN:VCALENDAR
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VCALENDAR