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. datetime in UTC

All values will be converted to a datetime in UTC. This is defined in RFC 9074:

Purpose: This property specifies the UTC date and time at which the corresponding alarm was last sent or acknowledged.

This property is used to specify when an alarm was last sent or acknowledged. This allows clients to determine when a pending alarm has been acknowledged by a calendar user so that any alerts can be dismissed across multiple devices. It also allows clients to track repeating alarms or alarms on recurring events or to-dos to ensure that the right number of missed alarms can be tracked.

Clients SHOULD set this property to the current date-time value in UTC when a calendar user acknowledges a pending alarm. Certain kinds of alarms, such as email-based alerts, might not provide feedback as to when the calendar user sees them. For those kinds of alarms, the client SHOULD set this property when the alarm is triggered and the action is successfully carried out.

When an alarm is triggered on a client, clients can check to see if an "ACKNOWLEDGED" property is present. If it is, and the value of that property is greater than or equal to the computed trigger time for the alarm, then the client SHOULD NOT trigger the alarm. Similarly, if an alarm has been triggered and an "alert" has been presented to a calendar user, clients can monitor the iCalendar data to determine whether an "ACKNOWLEDGED" property is added or changed in the alarm component. If the value of any "ACKNOWLEDGED" property in the alarm changes and is greater than or equal to the trigger time of the alarm, then clients SHOULD dismiss or cancel any "alert" presented to the calendar user.

property CREATED: datetime | None#

The CREATED property. datetime in UTC

All values will be converted to a datetime in UTC.

CREATED specifies the date and time that the calendar information was created by the calendar user agent in the calendar store.

Conformance:
The property can be specified once in "VEVENT", "VTODO", or "VJOURNAL" calendar components. The value MUST be specified as a date with UTC time.

property DTSTAMP: datetime | None#

The DTSTAMP property. datetime in UTC

All values will be converted to a datetime in UTC. RFC 5545:

Conformance: This property MUST be included in the "VEVENT", "VTODO", "VJOURNAL", or "VFREEBUSY" calendar components.

Description: In the case of an iCalendar object that specifies a "METHOD" property, this property specifies the date and time that the instance of the iCalendar object was created. In the case of an iCalendar object that doesn't specify a "METHOD" property, this property specifies the date and time that the information associated with the calendar component was last revised in the calendar store.

The value MUST be specified in the UTC time format.

In the case of an iCalendar object that doesn't specify a "METHOD" property, this property is equivalent to the "LAST-MODIFIED" property.

property DURATION: timedelta | None#

The DURATION property of an alarm component.

The alarm can be defined such that it triggers repeatedly. A definition of an alarm with a repeating trigger MUST include both the "DURATION" and "REPEAT" properties. The "DURATION" property specifies the delay period, after which the alarm will repeat.

property LAST_MODIFIED: datetime | None#

The LAST-MODIFIED property. datetime in UTC

All values will be converted to a datetime in UTC. RFC 5545:

Purpose: This property specifies the date and time that the information associated with the calendar component was last revised in the calendar store.

Note: This is analogous to the modification date and time for a file in the file system.

Conformance: This property can be specified in the "VEVENT", "VTODO", "VJOURNAL", or "VTIMEZONE" calendar components.

property REPEAT: int#

The REPEAT property of an alarm component.

The alarm can be defined such that it triggers repeatedly. A definition of an alarm with a repeating trigger MUST include both the "DURATION" and "REPEAT" properties. The "DURATION" property specifies the delay period, after which the alarm will repeat. The "REPEAT" property specifies the number of additional repetitions that the alarm will be triggered. This repetition count is in addition to the initial triggering of the alarm.

property TRIGGER: timedelta | datetime | None#

The TRIGGER property.

Purpose: This property specifies when an alarm will trigger.

Value Type: The default value type is DURATION. The value type can be set to a DATE-TIME value type, in which case the value MUST specify a UTC-formatted DATE-TIME value.

Either a positive or negative duration may be specified for the "TRIGGER" property. An alarm with a positive duration is triggered after the associated start or end of the event or to-do. An alarm with a negative duration is triggered before the associated start or end of the event or to-do.

Accepted values: datetime, timedelta. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

property TRIGGER_RELATED: str#

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

count(value, /)#: Return number of occurrences of value.

end: tuple[timedelta]#: Alias for field number 1

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

start: tuple[timedelta]#: Alias for field number 0

add(name, value, parameters=None, encode=True)#

Add a property.

Parameters:

name (string) – Name of the property.
value (Python native type or icalendar property type.) – Value of the property. Either of a basic Python type of any of the icalendar's own property types.
parameters (Dictionary) – Property parameter dictionary for the value. Only available, if encode is set to True.
encode (Boolean) – True, if the value should be encoded to one of icalendar's own property types (Fallback is "vText") or False, if not.

Returns:

None

add_component(component)#: Add a subcomponent to this component.

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

Add a new attendee to an existing event.

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

Create an email alarm with several attendees:

>>> from icalendar import Alarm, vCalAddress
>>> alarm = Alarm.new(attendees = [
...     vCalAddress("mailto:me@my-domain.com"),
...     vCalAddress("mailto:you@my-domain.com"),
... ], summary = "Email alarm")
>>> print(alarm.to_ical())
BEGIN:VALARM
ATTENDEE:mailto:me@my-domain.com
ATTENDEE:mailto:you@my-domain.com
SUMMARY:Email alarm
END:VALARM

clear()#: Remove all items from ordered dict.

property comments: list[str]#

COMMENT is used to specify a comment to the calendar user.

Purpose:: This property specifies non-processing information intended to provide a comment to the calendar user.
Conformance:: In RFC 5545, this property can be specified multiple times in "VEVENT", "VTODO", "VJOURNAL", and "VFREEBUSY" calendar components as well as in the "STANDARD" and "DAYLIGHT" sub-components. In RFC 7953, this property can be specified multiple times in "VAVAILABILITY" and "VAVAILABLE".
Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.

property concepts: list[vUri]#

CONCEPT

Purpose:

CONCEPT defines the formal categories for a calendar component.

Conformance:

Since RFC 9253, this property can be specified zero or more times in any iCalendar component.

Description:

This property is used to specify formal categories or classifications of the calendar component. The values are useful in searching for a calendar component of a particular type and category.

This categorization is distinct from the more informal "tagging" of components provided by the existing CATEGORIES property. It is expected that the value of the CONCEPT property will reference an external resource that provides information about the categorization.

In addition, a structured URI value allows for hierarchical categorization of events.

Possible category resources are the various proprietary systems, for example, the Library of Congress, or an open source of categorization data.

Examples

The following is an example of this property. It points to a server acting as the source for the calendar object.

CONCEPT:https://example.com/event-types/arts/music

See also

Custom components for examples of parsing custom components

classmethod from_jcal(jcal)#

Create a component from a jCal list.

Parameters:

jcal (str | list) – jCal list or JSON string according to RFC 7265.

Raises:

JCalParsingError – If the jCal provided is invalid.
JSONDecodeError – If the provided string is not valid JSON.

Return type:

Component

This reverses to_json() and to_jcal().

The following code parses an example from RFC 7265:

>>> from icalendar import Component
>>> jcal = ["vcalendar",
...   [
...     ["calscale", {}, "text", "GREGORIAN"],
...     ["prodid", {}, "text", "-//Example Inc.//Example Calendar//EN"],
...     ["version", {}, "text", "2.0"]
...   ],
...   [
...     ["vevent",
...       [
...         ["dtstamp", {}, "date-time", "2008-02-05T19:12:24Z"],
...         ["dtstart", {}, "date", "2008-10-06"],
...         ["summary", {}, "text", "Planning meeting"],
...         ["uid", {}, "text", "4088E990AD89CB3DBB484909"]
...       ],
...       []
...     ]
...   ]
... ]
>>> calendar = Component.from_jcal(jcal)
>>> print(calendar.name)
VCALENDAR
>>> print(calendar.prodid)
-//Example Inc.//Example Calendar//EN
>>> event = calendar.events[0]
>>> print(event.summary)
Planning meeting

classmethod fromkeys(iterable, value=None)#: Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None)#: Get property value with default.

classmethod get_component_class(name)#

Return a component with this name.

Parameters:: name (str) – Name of the component, i.e. VCALENDAR
Return type:: type[Component]

get_inline(name, decode=1)#: Returns a list of values (split on comma).

ignore_exceptions: ClassVar[bool] = False#

Whether or not to ignore exceptions when parsing.

If True, and this component can't be parsed, then it will silently ignore it, rather than let the exception propagate upwards.

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')

is_empty()#: Returns True if Component has no items or subcomponents, else False.

is_thunderbird()#

Whether this component has attributes that indicate that Mozilla Thunderbird created it.

Return type:: bool

items()#: Return a set-like object providing a view on the dict's items.

keys()#: Return a set-like object providing a view on the dict's keys.

property last_modified: datetime#

Datetime when the information associated with the component was last revised.

Since LAST_MODIFIED is an optional property, this returns DTSTAMP if LAST_MODIFIED is not set.

property links: list[vUri | vUid | vXmlReference]#

LINK properties as a list.

Purpose:

LINK provides a reference to external information related to a component.

Property Parameters:

The VALUE parameter is required. Non-standard, link relation type, format type, label, and language parameters can also be specified on this property. The LABEL parameter is defined in RFC 7986.

Conformance:

This property can be specified zero or more times in any iCalendar component. LINK is specified in RFC 9253. The LINKREL parameter is required.

Description:

When used in a component, the value of this property points to additional information related to the component. For example, it may reference the originating web server.

This property is a serialization of the model in RFC 8288, where the link target is carried in the property value, the link context is the containing calendar entity, and the link relation type and any target attributes are carried in iCalendar property parameters.

The LINK property parameters map to RFC 8288 attributes as follows:

LABEL: This parameter maps to the "title" attribute defined in Section 3.4.1 of RFC 8288. LABEL is used to label the destination of a link such that it can be used as a human-readable identifier (e.g., a menu entry) in the language indicated by the LANGUAGE (if present).
LANGUAGE: This parameter maps to the "hreflang" attribute defined in Section 3.4.1 of RFC 8288. See RFC 5646. Example: en, de-ch.
LINKREL: This parameter maps to the link relation type defined in Section 2.1 of RFC 8288. See Registered Link Relation Types.
FMTTYPE: This parameter maps to the "type" attribute defined in Section 3.4.1 of RFC 8288.

There is no mapping for "title*", "anchor", "rev", or "media" RFC 8288.

Examples

The following is an example of this property, which provides a reference to the source for the calendar object.

LINK;LINKREL=SOURCE;LABEL=Venue;VALUE=URI:
 https://example.com/events

The following is an example of this property, which provides a reference to an entity from which this one was derived. The link relation is a vendor-defined value.

LINK;LINKREL="https://example.com/linkrel/derivedFrom";
 VALUE=URI:
 https://example.com/tasks/01234567-abcd1234.ics

The following is an example of this property, which provides a reference to a fragment of an XML document. The link relation is a vendor-defined value.

LINK;LINKREL="https://example.com/linkrel/costStructure";
 VALUE=XML-REFERENCE:
 https://example.com/xmlDocs/bidFramework.xml
 #xpointer(descendant::CostStruc/range-to(
 following::CostStrucEND[1]))

Set a link icalendar.vUri to the event page:

>>> from icalendar import Event, vUri
>>> from datetime import datetime
>>> link = vUri(
...     "http://example.com/event-page",
...     params={"LINKREL":"SOURCE"}
... )
>>> event = Event.new(
...     start=datetime(2025, 9, 17, 12, 0),
...     summary="An Example Event with a page"
... )
>>> event.links = [link]
>>> print(event.to_ical())
BEGIN:VEVENT
SUMMARY:An Example Event with a page
DTSTART:20250917T120000
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
LINK;LINKREL="SOURCE":http://example.com/event-page
END:VEVENT

move_to_end(key, last=True)#

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

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 should be defined in each component class.

Example: VCALENDAR.

classmethod new(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:

attendees (list[vCalAddress] | None) – The attendees of the alarm.
concepts (list[vUri | str] | str | vUri | None) – The concepts of the alarm.
description (str | None) – The description of the alarm.
links (str | vUri | vUid | vXmlReference | None | list[str | vUri | vUid | vXmlReference]) – The links of the alarm.
refids (list[str] | str | None) – refids of the alarm.
related_to (None | str | vText | vUri | vUid | list[str | vText | vUri | vUid]) – related_to of the alarm.
summary (str | None) – The summary of the alarm.
uid (str | UUID | None) – The uid of the alarm.

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.

property_items(recursive=True, sorted=True)#

Returns properties in this component and subcomponents as: [(name, value), …]

Return type:: list[tuple[str, object]]

property refids: list[str]#

REFID

Purpose:: REFID acts as a key for associated iCalendar entities.
Conformance:: Since RFC 9253, this property can be specified zero or more times in any iCalendar component.
Description:: The value of this property is free-form text that creates an identifier for associated components. All components that use the same REFID value are associated through that value and can be located or retrieved as a group. For example, all of the events in a travel itinerary would have the same REFID value, so as to be grouped together.

Examples

The following is an example of this property.

REFID:itinerary-2014-11-17

Use a REFID to associate several VTODOs:

>>> from icalendar import Todo
>>> todo_1 = Todo.new(
...     summary="turn off stove",
...     refids=["travel", "alps"]
... )
>>> todo_2 = Todo.new(
...     summary="pack backpack",
...     refids=["travel", "alps"]
... )
>>> todo_1.refids == todo_2.refids
True

Note

List modifications do not modify the component.

classmethod register(component_class)#

Register a custom component class.

Parameters:

component_class (type[Component]) – Component subclass to register. Must have a name attribute.

Raises:

ValueError – If component_class has no name attribute.
ValueError – If a component with this name is already registered.

Return type:

None

Examples

Create a custom icalendar component with the name X-EXAMPLE:

>>> from icalendar import Component
>>> class XExample(Component):
...     name = "X-EXAMPLE"
...     def custom_method(self):
...         return "custom"
>>> Component.register(XExample)

property related_to: list[vText | vUri | vUid]#

RELATED-TO properties as a list.

Purpose:

This property is used to represent a relationship or reference between one calendar component and another. RFC 9523 allows URI or UID values and a GAP parameter.

Value Type:

RFC 5545: TEXT RFC 9253: URI, UID

Conformance:

Since RFC 5545. this property can be specified in the "VEVENT", "VTODO", and "VJOURNAL" calendar components. Since RFC 9523, this property MAY be specified in any iCalendar component.

Description (RFC 5545):

The property value consists of the persistent, globally unique identifier of another calendar component. This value would be represented in a calendar component by the "UID" property.

By default, the property value points to another calendar component that has a PARENT relationship to the referencing object. The "RELTYPE" property parameter is used to either explicitly state the default PARENT relationship type to the referenced calendar component or to override the default PARENT relationship type and specify either a CHILD or SIBLING relationship. The PARENT relationship indicates that the calendar component is a subordinate of the referenced calendar component. The CHILD relationship indicates that the calendar component is a superior of the referenced calendar component. The SIBLING relationship indicates that the calendar component is a peer of the referenced calendar component.

Changes to a calendar component referenced by this property can have an implicit impact on the related calendar component. For example, if a group event changes its start or end date or time, then the related, dependent events will need to have their start and end dates changed in a corresponding way. Similarly, if a PARENT calendar component is cancelled or deleted, then there is an implied impact to the related CHILD calendar components. This property is intended only to provide information on the relationship of calendar components. It is up to the target calendar system to maintain any property implications of this relationship.

Description (RFC 9253):

By default or when VALUE=UID is specified, the property value consists of the persistent, globally unique identifier of another calendar component. This value would be represented in a calendar component by the UID property.

By default, the property value points to another calendar component that has a PARENT relationship to the referencing object. The RELTYPE property parameter is used to either explicitly state the default PARENT relationship type to the referenced calendar component or to override the default PARENT relationship type and specify either a CHILD or SIBLING relationship or a temporal relationship.

The PARENT relationship indicates that the calendar component is a subordinate of the referenced calendar component. The CHILD relationship indicates that the calendar component is a superior of the referenced calendar component. The SIBLING relationship indicates that the calendar component is a peer of the referenced calendar component.

To preserve backwards compatibility, the value type MUST be UID when the PARENT, SIBLING, or CHILD relationships are specified.

The FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH, or STARTTOSTART relationships define temporal relationships, as specified in the RELTYPE parameter definition.

The FIRST and NEXT define ordering relationships between calendar components.

The DEPENDS-ON relationship indicates that the current calendar component depends on the referenced calendar component in some manner. For example, a task may be blocked waiting on the other, referenced, task.

The REFID and CONCEPT relationships establish a reference from the current component to the referenced component. Changes to a calendar component referenced by this property can have an implicit impact on the related calendar component. For example, if a group event changes its start or end date or time, then the related, dependent events will need to have their start and end dates and times changed in a corresponding way. Similarly, if a PARENT calendar component is canceled or deleted, then there is an implied impact to the related CHILD calendar components. This property is intended only to provide information on the relationship of calendar components.

Deletion of the target component, for example, the target of a FIRST, NEXT, or temporal relationship, can result in broken links.

It is up to the target calendar system to maintain any property implications of these relationships.

Examples

RFC 5545 examples of this property:

RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com

RELATED-TO:19960401-080045-4000F192713-0052@example.com

RFC 9253 examples of this property:

RELATED-TO;VALUE=URI;RELTYPE=STARTTOFINISH:
 https://example.com/caldav/user/jb/cal/
 19960401-080045-4000F192713.ics

icalendar.cal.alarm module#

This Page