icalendar package#

class icalendar.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.

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

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

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.

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

multiple = ('ATTENDEE', 'ATTACH', 'RELATED-TO')#

name = 'VALARM'#

Create a new alarm with all required properties.

This creates a new Alarm in accordance with RFC 5545.

Parameters:

attendees – The attendees of the alarm.
concepts – The Component.concepts of the alarm.
description – The description of the alarm.
links – The Component.links of the alarm.
refids – Component.refids of the alarm.
related_to – Component.related_to of the alarm.
summary – The summary of the alarm.
uid – 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.

required = ('ACTION', 'TRIGGER')#

singletons = ('ATTACH', 'ACTION', 'DESCRIPTION', 'SUMMARY', 'TRIGGER', 'DURATION', 'REPEAT', 'UID', 'PROXIMITY', 'ACKNOWLEDGED')#

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

class icalendar.AlarmTime(alarm: Alarm, trigger: datetime, acknowledged_until: datetime | None = None, snoozed_until: datetime | None = None, parent: Parent | None = None)[source]#

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[source]#

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(component: Alarm | Event | Todo | None = None)[source]#

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[source]#

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[source]#: Optional: Add an alarm component.

add_component(component: Alarm | Parent)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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[source]#

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.

class icalendar.Availability(*args, **kwargs)[source]#

Bases: Component

VAVAILABILITY component from RFC 7953.

This provides a grouping of component properties and subcomponents that describe the availability associated with a calendar user.

Description:

A “VAVAILABILITY” component indicates a period of time within which availability information is provided. A “VAVAILABILITY” component can specify a start time and an end time or duration. If “DTSTART” is not present, then the start time is unbounded. If “DTEND” or “DURATION” are not present, then the end time is unbounded. Within the specified time period, availability defaults to a free-busy type of “BUSY-UNAVAILABLE” (see Section 3.2), except for any time periods corresponding to “AVAILABLE” subcomponents.

“AVAILABLE” subcomponents are used to indicate periods of free time within the time range of the enclosing “VAVAILABILITY” component. “AVAILABLE” subcomponents MAY include recurrence properties to specify recurring periods of time, which can be overridden using normal iCalendar recurrence behavior (i.e., use of the “RECURRENCE-ID” property).

If specified, the “DTSTART” and “DTEND” properties in “VAVAILABILITY” components and “AVAILABLE” subcomponents MUST be “DATE-TIME” values specified as either the date with UTC time or the date with local time and a time zone reference.

The iCalendar object containing the “VAVAILABILITY” component MUST contain appropriate “VTIMEZONE” components corresponding to each unique “TZID” parameter value used in any DATE-TIME properties in all components, unless [RFC7809] is in effect.

When used to publish available time, the “ORGANIZER” property specifies the calendar user associated with the published available time.

If the “PRIORITY” property is specified in “VAVAILABILITY” components, it is used to determine how that component is combined with other “VAVAILABILITY” components. See Section 4.

Other calendar properties MAY be specified in “VAVAILABILITY” or “AVAILABLE” components and are considered attributes of the marked block of time. Their usage is application specific. For example, the “LOCATION” property might be used to indicate that a person is available in one location for part of the week and a different location for another part of the week (but see Section 9 for when it is appropriate to add additional data like this).

Example

The following is an example of a “VAVAILABILITY” calendar component used to represent the availability of a user, always available Monday through Friday, 9:00 am to 5:00 pm in the America/Montreal time zone:

BEGIN:VAVAILABILITY
ORGANIZER:mailto:bernard@example.com
UID:0428C7D2-688E-4D2E-AC52-CD112E2469DF
DTSTAMP:20111005T133225Z
BEGIN:AVAILABLE
UID:34EDA59B-6BB1-4E94-A66C-64999089C0AF
SUMMARY:Monday to Friday from 9:00 to 17:00
DTSTART;TZID=America/Montreal:20111002T090000
DTEND;TZID=America/Montreal:20111002T170000
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR
END:AVAILABLE
END:VAVAILABILITY

You can get the same example from example():

The following is an example of a “VAVAILABILITY” calendar component used to represent the availability of a user available Monday through Thursday, 9:00 am to 5:00 pm, at the main office, and Friday, 9:00 am to 12:00 pm, in the branch office in the America/Montreal time zone between October 2nd and December 2nd 2011:

BEGIN:VAVAILABILITY
ORGANIZER:mailto:bernard@example.com
UID:84D0F948-7FC6-4C1D-BBF3-BA9827B424B5
DTSTAMP:20111005T133225Z
DTSTART;TZID=America/Montreal:20111002T000000
DTEND;TZID=America/Montreal:20111202T000000
BEGIN:AVAILABLE
UID:7B33093A-7F98-4EED-B381-A5652530F04D
SUMMARY:Monday to Thursday from 9:00 to 17:00
DTSTART;TZID=America/Montreal:20111002T090000
DTEND;TZID=America/Montreal:20111002T170000
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH
LOCATION:Main Office
END:AVAILABLE
BEGIN:AVAILABLE
UID:DF39DC9E-D8C3-492F-9101-0434E8FC1896
SUMMARY:Friday from 9:00 to 12:00
DTSTART;TZID=America/Montreal:20111006T090000
DTEND;TZID=America/Montreal:20111006T120000
RRULE:FREQ=WEEKLY
LOCATION:Branch Office
END:AVAILABLE
END:VAVAILABILITY

For more examples, have a look at RFC 5545.

property DTEND: datetime | None#

The DTEND property. datetime in UTC

All values will be converted to a datetime in UTC. Start of the component.

This is almost the same as Event.DTEND with one exception: The values MUST have a timezone and DATE is not allowed.

Description:: RFC 7953: If specified, the “DTSTART” and “DTEND” properties in “VAVAILABILITY” components and “AVAILABLE” subcomponents MUST be “DATE-TIME” values specified as either the date with UTC time or the date with local time and a time zone reference.

property DTSTART: datetime | None#

The DTSTART property. datetime in UTC

All values will be converted to a datetime in UTC. Start of the component.

This is almost the same as Event.DTSTART with one exception: The values MUST have a timezone and DATE is not allowed.

Description:: RFC 7953: If specified, the “DTSTART” and “DTEND” properties in “VAVAILABILITY” components and “AVAILABLE” subcomponents MUST be “DATE-TIME” values specified as either the date with UTC time or the date with local time and a time zone reference.

property DURATION: timedelta | None#

The DURATION property.

The “DTSTART” property for a “Availability” specifies the inclusive start of the Availability. The “DURATION” property in conjunction with the DTSTART property for a “Availability” calendar component specifies the non-inclusive end of the event.

If you would like to calculate the duration of a Availability, do not use this. Instead use the duration property (lower case).

property available: list[Available]#

All VAVAILABLE sub-components.

This is a shortcut to get all VAVAILABLE sub-components. Modifications do not change the calendar. Use Component.add_component().

property busy_type: StrEnum#

BUSYTYPE specifies the default busy time type.

Returns:: icalendar.enums.BUSYTYPE

Description:: This property is used to specify the default busy time type. The values correspond to those used by the FBTYPE” parameter used on a “FREEBUSY” property, with the exception that the “FREE” value is not used in this property. If not specified on a component that allows this property, the default is “BUSY- UNAVAILABLE”.

canonical_order = ('DTSTART', 'DTEND', 'DURATION', 'DTSTAMP', 'UID', 'SEQUENCE', 'SUMMARY', 'DESCRIPTION', 'ORGANIZER')#

property categories: list[str]#

This property defines the categories for a component.

Property Parameters:: IANA, non-standard, and language property parameters can be specified on this property.
Conformance:: The property can be specified within “VEVENT”, “VTODO”, or “VJOURNAL” calendar components. Since RFC 7986 it can also be defined on a “VCALENDAR” component.
Description:: This property is used to specify categories or subtypes of the calendar component. The categories are useful in searching for a calendar component of a particular type and category. Within the “VEVENT”, “VTODO”, or “VJOURNAL” calendar components, more than one category can be specified as a COMMA-separated list of categories.

Example

Below, we add the categories to an event:

>>> from icalendar import Event
>>> event = Event()
>>> event.categories = ["Work", "Meeting"]
>>> print(event.to_ical())
BEGIN:VEVENT
CATEGORIES:Work,Meeting
END:VEVENT
>>> event.categories.append("Lecture")
>>> event.categories == ["Work", "Meeting", "Lecture"]
True

Note

At present, we do not take the LANGUAGE parameter into account.

See also

Component.concepts

property classification: StrEnum#

CLASS specifies the class of the calendar component.

Returns:: icalendar.enums.CLASS

Description:: An access classification is only one component of the general security system within a calendar application. It provides a method of capturing the scope of the access the calendar owner intends for information within an individual calendar entry. The access classification of an individual iCalendar component is useful when measured along with the other security components of a calendar system (e.g., calendar user authentication, authorization, access rights, access role, etc.). Hence, the semantics of the individual access classifications cannot be completely defined by this memo alone. Additionally, due to the “blind” nature of most exchange processes using this memo, these access classifications cannot serve as an enforcement statement for a system receiving an iCalendar object. Rather, they provide a method for capturing the intention of the calendar owner for the access to the calendar component. If not specified in a component that allows this property, the default value is PUBLIC. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the PRIVATE value.

property contacts: list[str]#

Contact information associated with the calendar component.

Purpose:: This property is used to represent contact information or alternately a reference to contact information associated with the calendar component.
Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: In RFC 5545, this property can be specified in a “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar component. In RFC 7953, this property can be specified in a “VAVAILABILITY” amd “VAVAILABLE” calendar component.
Description:: The property value consists of textual contact information. An alternative representation for the property value can also be specified that refers to a URI pointing to an alternate form, such as a vCard RFC 2426, for the contact information.

Example

The following is an example of this property referencing textual contact information:

CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property with an alternate representation of an LDAP URI to a directory entry containing the contact information:

CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\,
c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\,
+1-919-555-1234

The following is an example of this property with an alternate representation of a MIME body part containing the contact information, such as a vCard RFC 2426 embedded in a text/ directory media type RFC 2425:

CONTACT;ALTREP="CID:part3.msg970930T083000SILVER@example.com":
 Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property referencing a network resource, such as a vCard RFC 2426 object containing the contact information:

CONTACT;ALTREP="http://example.com/pdi/jdoe.vcf":Jim
 Dolittle\, ABC Industries\, +1-919-555-1234

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.

property duration: timedelta | None#

Compute the duration of this component.

If there is no DTEND or DURATION set, this is None. Otherwise, the duration is calculated from DTSTART and DTEND/DURATION.

This is in accordance with RFC 7953: If “DTEND” or “DURATION” are not present, then the end time is unbounded.

property end: timedelta | None#

Compute the duration of this component.

If there is no DTEND or DURATION set, this is None. Otherwise, the duration is calculated from DTSTART and DTEND/DURATION.

This is in accordance with RFC 7953: If “DTEND” or “DURATION” are not present, then the end time is unbounded.

classmethod example(name: str = 'rfc_7953_1') → Availability[source]#: Return the calendar example with the given name.

exclusive = ('DTEND', 'DURATION')#

property location: str | None#

The intended venue for the activity defined by a calendar component.

Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: Since RFC 5545, this property can be specified in “VEVENT” or “VTODO” calendar component. RFC 7953 adds this property to “VAVAILABILITY” and “VAVAILABLE”.
Description:: Specific venues such as conference or meeting rooms may be explicitly specified using this property. An alternate representation may be specified that is a URI that points to directory information with more structured specification of the location. For example, the alternate representation may specify either an LDAP URL RFC 4516 pointing to an LDAP server entry or a CID URL RFC 2392 pointing to a MIME body part containing a Virtual-Information Card (vCard) RFC 2426 for the location.

name = 'VAVAILABILITY'#

Create a new event with all required properties.

This creates a new Availability in accordance with RFC 7953.

Parameters:

busy_type – The busy_type of the availability.
categories – The categories of the availability.
classification – The classification of the availability.
comments – The Component.comments of the availability.
concepts – The Component.concepts of the availability.
contacts – The contacts of the availability.
created – The Component.created of the availability.
description – The description of the availability.
end – The end of the availability.
last_modified – The Component.last_modified of the availability.
links – The Component.links of the availability.
location – The location of the availability.
organizer – The organizer of the availability.
refids – Component.refids of the availability.
related_to – Component.related_to of the availability.
sequence – The sequence of the availability.
stamp – The Component.stamp of the availability. If None, this is set to the current time.
start – The start of the availability.
summary – The summary of the availability.
uid – The uid of the availability. If None, this is set to a new uuid.uuid4().
url – The url of the availability.

Returns:

Availability

Raises:

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

Warning

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

property organizer: vCalAddress | None#

ORGANIZER defines the organizer for a calendar component.

Property Parameters:

IANA, non-standard, language, common name, directory entry reference, and sent-by property parameters can be specified on this property.

Conformance:

This property MUST be specified in an iCalendar object that specifies a group-scheduled calendar entity. This property MUST be specified in an iCalendar object that specifies the publication of a calendar user’s busy time. This property MUST NOT be 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 is specified within the “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to specify the organizer of a group-scheduled calendar entity. The property is specified within the “VFREEBUSY” calendar component to specify the calendar user requesting the free or busy time. When publishing a “VFREEBUSY” calendar component, the property is used to specify the calendar that the published busy time came from.

The property has the property parameters “CN”, for specifying the common or display name associated with the “Organizer”, “DIR”, for specifying a pointer to the directory information associated with the “Organizer”, “SENT-BY”, for specifying another calendar user that is acting on behalf of the “Organizer”. The non-standard parameters may also be specified on this property. If the “LANGUAGE” property parameter is specified, the identified language applies to the “CN” parameter value.

property priority: int#

Conformance:

This property can be specified in “VEVENT” and “VTODO” calendar components according to RFC 5545. RFC 7953 adds this property to “VAVAILABILITY”.

Description:

This priority is specified as an integer in the range 0 to 9. A value of 0 specifies an undefined priority. A value of 1 is the highest priority. A value of 2 is the second highest priority. Subsequent numbers specify a decreasing ordinal priority. A value of 9 is the lowest priority.

A CUA with a three-level priority scheme of “HIGH”, “MEDIUM”, and “LOW” is mapped into this property such that a property value in the range of 1 to 4 specifies “HIGH” priority. A value of 5 is the normal or “MEDIUM” priority. A value in the range of 6 to 9 is “LOW” priority.

A CUA with a priority schema of “A1”, “A2”, “A3”, “B1”, “B2”, …, “C3” is mapped into this property such that a property value of 1 specifies “A1”, a property value of 2 specifies “A2”, a property value of 3 specifies “A3”, and so forth up to a property value of 9 specifies “C3”.

Other integer values are reserved for future use.

Within a “VEVENT” calendar component, this property specifies a priority for the event. This property may be useful when more than one event is scheduled for a given time period.

Within a “VTODO” calendar component, this property specified a priority for the to-do. This property is useful in prioritizing multiple action items for a given time period.

required = ('DTSTART', 'DTSTAMP', 'UID')#

property sequence: int#

This property defines the revision sequence number of the calendar component within a sequence of revisions.

Value Type:

INTEGER

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

The property can be specified in “VEVENT”, “VTODO”, or “VJOURNAL” calendar component.

Description:

When a calendar component is created, its sequence number is 0. It is monotonically incremented by the “Organizer’s” CUA each time the “Organizer” makes a significant revision to the calendar component.

The “Organizer” includes this property in an iCalendar object that it sends to an “Attendee” to specify the current version of the calendar component.

The “Attendee” includes this property in an iCalendar object that it sends to the “Organizer” to specify the version of the calendar component to which the “Attendee” is referring.

A change to the sequence number is not the mechanism that an “Organizer” uses to request a response from the “Attendees”. The “RSVP” parameter on the “ATTENDEE” property is used by the “Organizer” to indicate that a response from the “Attendees” is requested.

Recurrence instances of a recurring component MAY have different sequence numbers.

Examples

The following is an example of this property for a calendar component that was just created by the “Organizer”:

>>> from icalendar import Event
>>> event = Event()
>>> event.sequence
0

The following is an example of this property for a calendar component that has been revised 10 different times by the “Organizer”:

>>> from icalendar import Calendar
>>> calendar = Calendar.example("issue_156_RDATE_with_PERIOD_TZID_khal")
>>> event = calendar.events[0]
>>> event.sequence
10

singletons = ('DTSTAMP', 'UID', 'BUSYTYPE', 'CLASS', 'CREATED', 'DESCRIPTION', 'DTSTART', 'LAST-MODIFIED', 'LOCATION', 'ORGANIZER', 'PRIORITY', 'SEQUENCE', 'SUMMARY', 'URL', 'DTEND', 'DURATION')#

property start: datetime | None#

The DTSTART property. datetime in UTC

All values will be converted to a datetime in UTC. Start of the component.

This is almost the same as Event.DTSTART with one exception: The values MUST have a timezone and DATE is not allowed.

Description:: RFC 7953: If specified, the “DTSTART” and “DTEND” properties in “VAVAILABILITY” components and “AVAILABLE” subcomponents MUST be “DATE-TIME” values specified as either the date with UTC time or the date with local time and a time zone reference.

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 url: str#

A Uniform Resource Locator (URL) associated with the iCalendar object.

Description:: This property may be used in a calendar component to convey a location where a more dynamic rendition of the calendar information associated with the calendar component can be found. This memo does not attempt to standardize the form of the URI, nor the format of the resource pointed to by the property value. If the URL property and Content-Location MIME header are both specified, they MUST point to the same resource.
Conformance:: This property can be specified once in the “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar components. Since RFC 7986, this property can also be defined on a “VCALENDAR”.

Example

The following is an example of this property:

URL:http://example.com/pub/calendars/jsmith/mytime.ics

class icalendar.Available(*args, **kwargs)[source]#

Bases: Component

Sub-component of “VAVAILABILITY from RFC 7953.

Description:: “AVAILABLE” subcomponents are used to indicate periods of free time within the time range of the enclosing “VAVAILABILITY” component. “AVAILABLE” subcomponents MAY include recurrence properties to specify recurring periods of time, which can be overridden using normal iCalendar recurrence behavior (i.e., use of the “RECURRENCE-ID” property).

Examples

This is a recurring “AVAILABLE” subcomponent:

BEGIN:AVAILABLE
UID:57DD4AAF-3835-46B5-8A39-B3B253157F01
SUMMARY:Monday to Friday from 9:00 to 17:00
DTSTART;TZID=America/Denver:20111023T090000
DTEND;TZID=America/Denver:20111023T170000
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR
LOCATION:Denver
END:AVAILABLE

You can get the same example from example():

property DTEND: datetime | None#

The DTEND property. datetime in UTC

All values will be converted to a datetime in UTC. Start of the component.

This is almost the same as Event.DTEND with one exception: The values MUST have a timezone and DATE is not allowed.

Description:: RFC 7953: If specified, the “DTSTART” and “DTEND” properties in “VAVAILABILITY” components and “AVAILABLE” subcomponents MUST be “DATE-TIME” values specified as either the date with UTC time or the date with local time and a time zone reference.

property DTSTART: datetime | None#

The DTSTART property. datetime in UTC

All values will be converted to a datetime in UTC. Start of the component.

This is almost the same as Event.DTSTART with one exception: The values MUST have a timezone and DATE is not allowed.

Description:: RFC 7953: If specified, the “DTSTART” and “DTEND” properties in “VAVAILABILITY” components and “AVAILABLE” subcomponents MUST be “DATE-TIME” values specified as either the date with UTC time or the date with local time and a time zone reference.

property DURATION: timedelta | None#

The DURATION property.

The “DTSTART” property for a “Available” specifies the inclusive start of the Available. The “DURATION” property in conjunction with the DTSTART property for a “Available” calendar component specifies the non-inclusive end of the event.

If you would like to calculate the duration of a Available, do not use this. Instead use the duration property (lower case).

property categories: list[str]#

This property defines the categories for a component.

Property Parameters:: IANA, non-standard, and language property parameters can be specified on this property.
Conformance:: The property can be specified within “VEVENT”, “VTODO”, or “VJOURNAL” calendar components. Since RFC 7986 it can also be defined on a “VCALENDAR” component.
Description:: This property is used to specify categories or subtypes of the calendar component. The categories are useful in searching for a calendar component of a particular type and category. Within the “VEVENT”, “VTODO”, or “VJOURNAL” calendar components, more than one category can be specified as a COMMA-separated list of categories.

Example

Below, we add the categories to an event:

>>> from icalendar import Event
>>> event = Event()
>>> event.categories = ["Work", "Meeting"]
>>> print(event.to_ical())
BEGIN:VEVENT
CATEGORIES:Work,Meeting
END:VEVENT
>>> event.categories.append("Lecture")
>>> event.categories == ["Work", "Meeting", "Lecture"]
True

Note

At present, we do not take the LANGUAGE parameter into account.

See also

Component.concepts

property contacts: list[str]#

Contact information associated with the calendar component.

Purpose:: This property is used to represent contact information or alternately a reference to contact information associated with the calendar component.
Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: In RFC 5545, this property can be specified in a “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar component. In RFC 7953, this property can be specified in a “VAVAILABILITY” amd “VAVAILABLE” calendar component.
Description:: The property value consists of textual contact information. An alternative representation for the property value can also be specified that refers to a URI pointing to an alternate form, such as a vCard RFC 2426, for the contact information.

Example

The following is an example of this property referencing textual contact information:

CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property with an alternate representation of an LDAP URI to a directory entry containing the contact information:

CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\,
c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\,
+1-919-555-1234

The following is an example of this property with an alternate representation of a MIME body part containing the contact information, such as a vCard RFC 2426 embedded in a text/ directory media type RFC 2425:

CONTACT;ALTREP="CID:part3.msg970930T083000SILVER@example.com":
 Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property referencing a network resource, such as a vCard RFC 2426 object containing the contact information:

CONTACT;ALTREP="http://example.com/pdi/jdoe.vcf":Jim
 Dolittle\, ABC Industries\, +1-919-555-1234

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.

property duration: timedelta | None#

Compute the duration of this component.

If there is no DTEND or DURATION set, this is None. Otherwise, the duration is calculated from DTSTART and DTEND/DURATION.

This is in accordance with RFC 7953: If “DTEND” or “DURATION” are not present, then the end time is unbounded.

property end: timedelta | None#

Compute the duration of this component.

If there is no DTEND or DURATION set, this is None. Otherwise, the duration is calculated from DTSTART and DTEND/DURATION.

This is in accordance with RFC 7953: If “DTEND” or “DURATION” are not present, then the end time is unbounded.

classmethod example(name: str = 'rfc_7953_1') → Available[source]#: Return the calendar example with the given name.

property exdates: list[date | datetime]#

EXDATE defines the list of DATE-TIME exceptions for recurring components.

EXDATE is defined in RFC 5545.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

Example

Below, we add an exdate in a list and get the resulting list of exdates.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of excluded dates
>>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.exdates
[datetime.datetime(2025, 4, 28, 16, 5)]

Note

You cannot modify the EXDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

property location: str | None#

The intended venue for the activity defined by a calendar component.

Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: Since RFC 5545, this property can be specified in “VEVENT” or “VTODO” calendar component. RFC 7953 adds this property to “VAVAILABILITY” and “VAVAILABLE”.
Description:: Specific venues such as conference or meeting rooms may be explicitly specified using this property. An alternate representation may be specified that is a URI that points to directory information with more structured specification of the location. For example, the alternate representation may specify either an LDAP URL RFC 4516 pointing to an LDAP server entry or a CID URL RFC 2392 pointing to a MIME body part containing a Virtual-Information Card (vCard) RFC 2426 for the location.

name = 'VAVAILABLE'#

Create a new Available component with all required properties.

This creates a new Available component in accordance with RFC 7953.

Parameters:

categories – The categories of the Available component.
comments – The Component.comments of the Available component.
concepts – The Component.concepts of the Available component.
contacts – The contacts of the Available component.
created – The Component.created of the Available component.
description – The description of the Available component.
end – The end of the Available component.
last_modified – The Component.last_modified of the Available component.
links – The Component.links of the Available component.
location – The location of the Available component.
refids – Component.refids of the Available component.
related_to – Component.related_to of the Available component.
sequence – The sequence of the Available component.
stamp – The Component.stamp of the Available component. If None, this is set to the current time.
start – The start of the Available component.
summary – The summary of the Available component.
uid – The uid of the Available component. If None, this is set to a new uuid.uuid4().

Returns:

Available

Raises:

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

Warning

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

property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]#

The RDATE property defines the list of DATE-TIME values for recurring components.

RDATE is defined in RFC 5545. The return value is a list of tuples (start, end).

start can be a datetime.date or a datetime.datetime, with and without timezone.

end is None if the end is not specified and a datetime.datetime if the end is specified.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

Example

Below, we set one RDATE in a list and get the resulting tuple of start and end.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of recurrence dates
>>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.rdates
[(datetime.datetime(2025, 4, 28, 16, 5), None)]

Note

You cannot modify the RDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

property rrules: list[vRecur]#

RRULE defines a rule or repeating pattern for recurring components.

RRULE is defined in RFC 5545. RFC 7529 adds the SKIP parameter icalendar.prop.vSkip.

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

Description:

The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

Examples

Daily for 10 occurrences:

>>> from icalendar import Event
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;COUNT=10
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

Daily until December 24, 1997:

>>> from icalendar import Event, vRecur
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

Note

You cannot modify the RRULE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

property sequence: int#

This property defines the revision sequence number of the calendar component within a sequence of revisions.

Value Type:

INTEGER

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

The property can be specified in “VEVENT”, “VTODO”, or “VJOURNAL” calendar component.

Description:

When a calendar component is created, its sequence number is 0. It is monotonically incremented by the “Organizer’s” CUA each time the “Organizer” makes a significant revision to the calendar component.

The “Organizer” includes this property in an iCalendar object that it sends to an “Attendee” to specify the current version of the calendar component.

The “Attendee” includes this property in an iCalendar object that it sends to the “Organizer” to specify the version of the calendar component to which the “Attendee” is referring.

A change to the sequence number is not the mechanism that an “Organizer” uses to request a response from the “Attendees”. The “RSVP” parameter on the “ATTENDEE” property is used by the “Organizer” to indicate that a response from the “Attendees” is requested.

Recurrence instances of a recurring component MAY have different sequence numbers.

Examples

The following is an example of this property for a calendar component that was just created by the “Organizer”:

>>> from icalendar import Event
>>> event = Event()
>>> event.sequence
0

The following is an example of this property for a calendar component that has been revised 10 different times by the “Organizer”:

>>> from icalendar import Calendar
>>> calendar = Calendar.example("issue_156_RDATE_with_PERIOD_TZID_khal")
>>> event = calendar.events[0]
>>> event.sequence
10

property start: datetime | None#

The DTSTART property. datetime in UTC

All values will be converted to a datetime in UTC. Start of the component.

This is almost the same as Event.DTSTART with one exception: The values MUST have a timezone and DATE is not allowed.

Description:: RFC 7953: If specified, the “DTSTART” and “DTEND” properties in “VAVAILABILITY” components and “AVAILABLE” subcomponents MUST be “DATE-TIME” values specified as either the date with UTC time or the date with local time and a time zone reference.

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

class icalendar.BUSYTYPE(*values)[source]#

Bases: StrEnum

Enum for BUSYTYPE from RFC 7953.

Values:: BUSY, BUSY_UNAVAILABLE, BUSY_TENTATIVE
Description:: This property is used to specify the default busy time type. The values correspond to those used by the FBTYPE parameter used on a “FREEBUSY” property, with the exception that the “FREE” value is not used in this property. If not specified on a component that allows this property, the default is “BUSY- UNAVAILABLE”.

Example

The following is an example of this property:

BUSYTYPE:BUSY

BUSY = 'BUSY'#

BUSY_TENTATIVE = 'BUSY-TENTATIVE'#

BUSY_UNAVAILABLE = 'BUSY-UNAVAILABLE'#

class icalendar.CLASS(*values)[source]#

Bases: StrEnum

Enum for CLASS from RFC 5545.

Values:: PUBLIC, PRIVATE, CONFIDENTIAL
Description:: An access classification is only one component of the general security system within a calendar application. It provides a method of capturing the scope of the access the calendar owner intends for information within an individual calendar entry. The access classification of an individual iCalendar component is useful when measured along with the other security components of a calendar system (e.g., calendar user authentication, authorization, access rights, access role, etc.). Hence, the semantics of the individual access classifications cannot be completely defined by this memo alone. Additionally, due to the “blind” nature of most exchange processes using this memo, these access classifications cannot serve as an enforcement statement for a system receiving an iCalendar object. Rather, they provide a method for capturing the intention of the calendar owner for the access to the calendar component. If not specified in a component that allows this property, the default value is PUBLIC. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the PRIVATE value.

CONFIDENTIAL = 'CONFIDENTIAL'#

PRIVATE = 'PRIVATE'#

PUBLIC = 'PUBLIC'#

class icalendar.CUTYPE(*values)[source]#

Bases: StrEnum

Enum for CTYPE from RFC 5545.

Values:: INDIVIDUAL, GROUP, RESOURCE, ROOM, UNKNOWN
Purpose:: To identify the type of calendar user specified by the property.
Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the type of calendar user specified by the property. If not specified on a property that allows this parameter, the default is INDIVIDUAL. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the UNKNOWN value.

GROUP = 'GROUP'#

INDIVIDUAL = 'INDIVIDUAL'#

RESOURCE = 'RESOURCE'#

ROOM = 'ROOM'#

UNKNOWN = 'UNKNOWN'#

class icalendar.Calendar(*args, **kwargs)[source]#

Bases: Component

The “VCALENDAR” object is a collection of calendar information. This information can include a variety of components, such as “VEVENT”, “VTODO”, “VJOURNAL”, “VFREEBUSY”, “VTIMEZONE”, or any other type of calendar component.

Examples

Create a new Calendar:

>>> from icalendar import Calendar
>>> calendar = Calendar.new(name="My Calendar")
>>> print(calendar.calendar_name)
My Calendar

add_missing_timezones(first_date: date = datetime.date(1970, 1, 1), last_date: date = datetime.date(2038, 1, 1))[source]#

Add all missing VTIMEZONE components.

This adds all the timezone components that are required. VTIMEZONE components are inserted at the beginning of the calendar to ensure they appear before other components that reference them.

Note

Timezones that are not known will not be added.

Parameters:

first_date – earlier than anything that happens in the calendar
last_date – later than anything happening in the calendar

>>> from icalendar import Calendar, Event
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> calendar = Calendar()
>>> event = Event()
>>> calendar.add_component(event)
>>> event.start = datetime(1990, 10, 11, 12, tzinfo=ZoneInfo("Europe/Berlin"))
>>> calendar.timezones
[]
>>> calendar.add_missing_timezones()
>>> calendar.timezones[0].tz_name
'Europe/Berlin'
>>> calendar.get_missing_tzids()  # check that all are added
set()

property availabilities: list[Availability]#

All Availability components in the calendar.

This is a shortcut to get all availabilities. Modifications do not change the calendar. Use Component.add_component().

property calendar_name: str | None#

This property specifies the name of the calendar.

This implements RFC 7986 NAME and X-WR-CALNAME.

Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: This property can be specified multiple times in an iCalendar object. However, each property MUST represent the name of the calendar in a different language.
Description:: This property is used to specify a name of the iCalendar object that can be used by calendar user agents when presenting the calendar data to a user. Whilst a calendar only has a single name, multiple language variants can be specified by including this property multiple times with different “LANGUAGE” parameter values on each.

Example

Below, we set the name of the calendar.

>>> from icalendar import Calendar
>>> calendar = Calendar()
>>> calendar.calendar_name = "My Calendar"
>>> print(calendar.to_ical())
BEGIN:VCALENDAR
NAME:My Calendar
END:VCALENDAR

property calscale: str#

CALSCALE defines the calendar scale used for the calendar information specified in the iCalendar object.

Compatibility:: RFC 7529 makes the case that GREGORIAN stays the default and other calendar scales are implemented on the RRULE.
Conformance:: This property can be specified once in an iCalendar object. The default value is “GREGORIAN”.
Description:: This memo is based on the Gregorian calendar scale. The Gregorian calendar scale is assumed if this property is not specified in the iCalendar object. It is expected that other calendar scales will be defined in other specifications or by future versions of this memo.

canonical_order = ('VERSION', 'PRODID', 'CALSCALE', 'METHOD', 'DESCRIPTION', 'X-WR-CALDESC', 'NAME', 'X-WR-CALNAME')#

property categories: list[str]#

This property defines the categories for a component.

Property Parameters:: IANA, non-standard, and language property parameters can be specified on this property.
Conformance:: The property can be specified within “VEVENT”, “VTODO”, or “VJOURNAL” calendar components. Since RFC 7986 it can also be defined on a “VCALENDAR” component.
Description:: This property is used to specify categories or subtypes of the calendar component. The categories are useful in searching for a calendar component of a particular type and category. Within the “VEVENT”, “VTODO”, or “VJOURNAL” calendar components, more than one category can be specified as a COMMA-separated list of categories.

Example

Below, we add the categories to an event:

>>> from icalendar import Event
>>> event = Event()
>>> event.categories = ["Work", "Meeting"]
>>> print(event.to_ical())
BEGIN:VEVENT
CATEGORIES:Work,Meeting
END:VEVENT
>>> event.categories.append("Lecture")
>>> event.categories == ["Work", "Meeting", "Lecture"]
True

Note

At present, we do not take the LANGUAGE parameter into account.

See also

Component.concepts

property color: str#

This property specifies a color used for displaying the calendar.

This implements RFC 7986 COLOR and X-APPLE-CALENDAR-COLOR. Please note that since RFC 7986, subcomponents can have their own color.

Property Parameters:: IANA and non-standard property parameters can be specified on this property.
Conformance:: This property can be specified once in an iCalendar object or in VEVENT, VTODO, or VJOURNAL calendar components.
Description:: This property specifies a color that clients MAY use when presenting the relevant data to a user. Typically, this would appear as the “background” color of events or tasks. The value is a case-insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of W3C.REC-css3-color-20110607.

Example

"turquoise", "#ffffff"

>>> from icalendar import Calendar
>>> calendar = Calendar()
>>> calendar.color = "black"
>>> print(calendar.to_ical())
BEGIN:VCALENDAR
COLOR:black
END:VCALENDAR

property description: str | None#

This property specifies the description of the calendar.

This implements RFC 7986 DESCRIPTION and X-WR-CALDESC.

Conformance:: This property can be specified multiple times in an iCalendar object. However, each property MUST represent the description of the calendar in a different language.
Description:: This property is used to specify a lengthy textual description of the iCalendar object that can be used by calendar user agents when describing the nature of the calendar data to a user. Whilst a calendar only has a single description, multiple language variants can be specified by including this property multiple times with different “LANGUAGE” parameter values on each.

Example

Below, we add a description to a calendar.

>>> from icalendar import Calendar
>>> calendar = Calendar()
>>> calendar.description = "This is a calendar"
>>> print(calendar.to_ical())
BEGIN:VCALENDAR
DESCRIPTION:This is a calendar
END:VCALENDAR

property events: list[Event]#

All event components in the calendar.

This is a shortcut to get all events. Modifications do not change the calendar. Use Component.add_component().

>>> from icalendar import Calendar
>>> calendar = Calendar.example()
>>> event = calendar.events[0]
>>> event.start
datetime.date(2022, 1, 1)
>>> print(event["SUMMARY"])
New Year's Day

classmethod example(name: str = 'example') → Calendar[source]#: Return the calendar example with the given name.

property freebusy: list[FreeBusy]#

All FreeBusy components in the calendar.

This is a shortcut to get all FreeBusy. Modifications do not change the calendar. Use Component.add_component().

classmethod from_ical(st, multiple=False)[source]#: Populates the component recursively from a string.

get_missing_tzids() → set[str][source]#

The set of missing timezone component tzids.

To create a RFC 5545 compatible calendar, all of these timezones should be added.

get_used_tzids() → set[str][source]#

The set of TZIDs in use.

This goes through the whole calendar to find all occurrences of timezone information like the TZID parameter in all attributes.

>>> from icalendar import Calendar
>>> calendar = Calendar.example("timezone_rdate")
>>> calendar.get_used_tzids()
{'posix/Europe/Vaduz'}

Even if you use UTC, this will not show up.

property images: list[Image]#

IMAGE specifies an image associated with the calendar or a calendar component.

Description:: This property specifies an image for an iCalendar object or a calendar component via a URI or directly with inline data that can be used by calendar user agents when presenting the calendar data to a user. Multiple properties MAY be used to specify alternative sets of images with, for example, varying media subtypes, resolutions, or sizes. When multiple properties are present, calendar user agents SHOULD display only one of them, picking one that provides the most appropriate image quality, or display none. The “DISPLAY” parameter is used to indicate the intended display mode for the image. The “ALTREP” parameter, defined in RFC 5545, can be used to provide a “clickable” image where the URI in the parameter value can be “launched” by a click on the image in the calendar user agent.
Conformance:: This property can be specified multiple times in an iCalendar object or in “VEVENT”, “VTODO”, or “VJOURNAL” calendar components.

Note

At the present moment, this property is read-only. If you require a setter, please open an issue or a pull request.

property method: str#

METHOD defines the iCalendar object method associated with the calendar object.

Description:

When used in a MIME message entity, the value of this property MUST be the same as the Content-Type “method” parameter value. If either the “METHOD” property or the Content-Type “method” parameter is specified, then the other MUST also be specified.

No methods are defined by this specification. This is the subject of other specifications, such as the iCalendar Transport- independent Interoperability Protocol (iTIP) defined by RFC 5546.

If this property is not present in the iCalendar object, then a scheduling transaction MUST NOT be assumed. In such cases, the iCalendar object is merely being used to transport a snapshot of some calendar information; without the intention of conveying a scheduling semantic.

multiple = ('CATEGORIES', 'DESCRIPTION', 'NAME')#

name = 'VCALENDAR'#

Create a new Calendar with all required properties.

This creates a new Calendar in accordance with RFC 5545 and RFC 7986.

Parameters:

calscale – The calscale of the calendar.
categories – The categories of the calendar.
color – The color of the calendar.
concepts – The Component.concepts of the calendar.
description – The description of the calendar.
language – The language for the calendar. Used to generate localized prodid.
last_modified – The Component.last_modified of the calendar.
links – The Component.links of the calendar.
method – The method of the calendar.
name – The calendar_name of the calendar.
organization – The organization name. Used to generate prodid if not provided.
prodid – The prodid of the component. If None and organization is provided, generates a prodid in format “-//organization//name//language”.
refresh_interval – The refresh_interval of the calendar.
refids – Component.refids of the calendar.
related_to – Component.related_to of the calendar.
source – The source of the calendar.
uid – The uid of the calendar. If None, this is set to a new uuid.uuid4().
url – The url of the calendar.
version – The version of the calendar.

Returns:

Calendar

Raises:

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

Warning

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

property prodid: str#

PRODID specifies the identifier for the product that created the iCalendar object.

Conformance:

The property MUST be specified once in an iCalendar object.

Description:

The vendor of the implementation SHOULD assure that this is a globally unique identifier; using some technique such as an FPI value, as defined in [ISO.9070.1991].

This property SHOULD NOT be used to alter the interpretation of an iCalendar object beyond the semantics specified in this memo. For example, it is not to be used to further the understanding of non- standard properties.

Example

The following is an example of this property. It does not imply that English is the default language.

-//ABC Corporation//NONSGML My Product//EN

property refresh_interval: timedelta | None#

REFRESH-INTERVAL specifies a suggested minimum interval for polling for changes of the calendar data from the original source of that data.

Conformance:: This property can be specified once in an iCalendar object, consisting of a positive duration of time.
Description:: This property specifies a positive duration that gives a suggested minimum polling interval for checking for updates to the calendar data. The value of this property SHOULD be used by calendar user agents to limit the polling interval for calendar data updates to the minimum interval specified.

Raises:: ValueError – When setting a negative duration.

required = ('PRODID', 'VERSION')#

singletons = ('PRODID', 'VERSION', 'CALSCALE', 'METHOD', 'COLOR')#

property source: str#

A URI from where calendar data can be refreshed.

Description:: This property identifies a location where a client can retrieve updated data for the calendar. Clients SHOULD honor any specified “REFRESH-INTERVAL” value when periodically retrieving data. Note that this property differs from the “URL” property in that “URL” is meant to provide an alternative representation of the calendar data rather than the original location of the data.
Conformance:: This property can be specified once in an iCalendar object.

Example

The following is an example of this property:

SOURCE;VALUE=URI:https://example.com/holidays.ics

property timezones: list[Timezone]#

Return the timezones components in this calendar.

>>> from icalendar import Calendar
>>> calendar = Calendar.example("pacific_fiji")
>>> [timezone.tz_name for timezone in calendar.timezones]
['custom_Pacific/Fiji']

Note

This is a read-only property.

property todos: list[Todo]#

All todo components in the calendar.

This is a shortcut to get all todos. Modifications do not change the calendar. Use Component.add_component().

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

property url: str#

A Uniform Resource Locator (URL) associated with the iCalendar object.

Description:: This property may be used in a calendar component to convey a location where a more dynamic rendition of the calendar information associated with the calendar component can be found. This memo does not attempt to standardize the form of the URI, nor the format of the resource pointed to by the property value. If the URL property and Content-Location MIME header are both specified, they MUST point to the same resource.
Conformance:: This property can be specified once in the “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar components. Since RFC 7986, this property can also be defined on a “VCALENDAR”.

Example

The following is an example of this property:

URL:http://example.com/pub/calendars/jsmith/mytime.ics

validate()[source]#

Validate that the calendar has required properties and components.

This method can be called explicitly to validate a calendar before output.

Raises:: IncompleteComponent – If the calendar lacks required properties or components.

property version: str#

VERSION of the calendar specification.

The default is "2.0" for RFC 5545.

Purpose:: This property specifies the identifier corresponding to the highest version number or the minimum and maximum range of the iCalendar specification that is required in order to interpret the iCalendar object.

class icalendar.Component(*args, **kwargs)[source]#

Bases: CaselessDict

Base class for calendar components.

Component is the base object for calendar, Event and the other components defined in RFC 5545. Normally you will not use this class directly, but rather one of the subclasses.

name#: The name of the component. Example: VCALENDAR.

required#: These properties are required.

singletons#: These properties must only appear once.

multiple#: These properties may occur more than once.

exclusive#: These properties are mutually exclusive.

inclusive#

If the first in a tuple occurs, the second one must also occur.

Type:: tuple[str] | tuple[tuple[str, str]]

ignore_exceptions#: If True, and we cannot parse this component, we will silently ignore it, rather than let the exception propagate upwards.

types_factory#: Factory for property types

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 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.

add(name: str, value, parameters: dict[str, str] | Parameters = None, encode: bool = True)[source]#

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: Component)[source]#: Add a subcomponent to this component.

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

Compnent.categories

content_line(name, value, sorted: bool = True)[source]#: Returns property as content line.

content_lines(sorted: bool = True)[source]#: Converts the Component and subcomponents into content lines.

property created: datetime#

Datetime when the information associated with the component was created.

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

decoded(name, default=[])[source]#: Returns decoded value of property.

exclusive = ()#

classmethod from_ical(st, multiple: bool = False) → Self | list[Self][source]#: Populates the component recursively from a string.

classmethod get_component_class(name: str) → type[Component][source]#

Return a component with this name.

Parameters:: name – Name of the component, i.e. VCALENDAR

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

ignore_exceptions = False#

inclusive: tuple[str] | tuple[tuple[str, str]] = ()#

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

is_thunderbird() → bool[source]#: Whether this component has attributes that indicate that Mozilla Thunderbird created it.

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

multiple = ()#

name = None#

Create a new component.

Parameters:

comments – The comments of the component.
concepts – The concepts of the component.
created – The created of the component.
last_modified – The last_modified of the component.
links – The links of the component.
related_to – The related_to of the component.
stamp – The DTSTAMP of the component.

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: bool = True) → list[tuple[str, object]][source]#: Returns properties in this component and subcomponents as: [(name, value), …]

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.

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

See also

Component.concepts

property classification: StrEnum#

CLASS specifies the class of the calendar component.

Returns:: icalendar.enums.CLASS

Description:: An access classification is only one component of the general security system within a calendar application. It provides a method of capturing the scope of the access the calendar owner intends for information within an individual calendar entry. The access classification of an individual iCalendar component is useful when measured along with the other security components of a calendar system (e.g., calendar user authentication, authorization, access rights, access role, etc.). Hence, the semantics of the individual access classifications cannot be completely defined by this memo alone. Additionally, due to the “blind” nature of most exchange processes using this memo, these access classifications cannot serve as an enforcement statement for a system receiving an iCalendar object. Rather, they provide a method for capturing the intention of the calendar owner for the access to the calendar component. If not specified in a component that allows this property, the default value is PUBLIC. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the PRIVATE value.

property color: str#

This property specifies a color used for displaying the component.

This implements RFC 7986 COLOR property.

Property Parameters:: IANA and non-standard property parameters can be specified on this property.
Conformance:: This property can be specified once in an iCalendar object or in VEVENT, VTODO, or VJOURNAL calendar components.
Description:: This property specifies a color that clients MAY use when presenting the relevant data to a user. Typically, this would appear as the “background” color of events or tasks. The value is a case-insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of W3C.REC-css3-color-20110607.

Example

"turquoise", "#ffffff"

>>> from icalendar import Todo
>>> todo = Todo()
>>> todo.color = "green"
>>> print(todo.to_ical())
BEGIN:VTODO
COLOR:green
END:VTODO

property conferences: list[Conference]#

Return the CONFERENCE properties as a list.

Purpose:

This property specifies information for accessing a conferencing system.

Conformance:

This property can be specified multiple times in a “VEVENT” or “VTODO” calendar component.

Description:

This property specifies information for accessing a conferencing system for attendees of a meeting or task. This might be for a telephone-based conference number dial-in with access codes included (such as a tel: URI RFC 3966 or a sip: or sips: URI RFC 3261), for a web-based video chat (such as an http: or https: URI RFC 7230), or for an instant messaging group chat room (such as an xmpp: URI RFC 5122). If a specific URI for a conferencing system is not available, a data: URI RFC 2397 containing a text description can be used.

A conference system can be a bidirectional communication channel or a uni-directional “broadcast feed”.

The “FEATURE” property parameter is used to describe the key capabilities of the conference system to allow a client to choose the ones that give the required level of interaction from a set of multiple properties.

The “LABEL” property parameter is used to convey additional details on the use of the URI. For example, the URIs or access codes for the moderator and attendee of a teleconference system could be different, and the “LABEL” property parameter could be used to “tag” each “CONFERENCE” property to indicate which is which.

The “LANGUAGE” property parameter can be used to specify the language used for text values used with this property (as per Section 3.2.10 of RFC 5545).

Example

The following are examples of this property:

CONFERENCE;VALUE=URI;FEATURE=PHONE,MODERATOR;
 LABEL=Moderator dial-in:tel:+1-412-555-0123,,,654321
CONFERENCE;VALUE=URI;FEATURE=PHONE;
 LABEL=Attendee dial-in:tel:+1-412-555-0123,,,555123
CONFERENCE;VALUE=URI;FEATURE=PHONE;
 LABEL=Attendee dial-in:tel:+1-888-555-0456,,,555123
CONFERENCE;VALUE=URI;FEATURE=CHAT;
 LABEL=Chat room:xmpp:chat-123@conference.example.com
CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO;
 LABEL=Attendee dial-in:https://chat.example.com/audio?id=123456

Get all conferences:

>>> from icalendar import Event
>>> event = Event()
>>> event.conferences
[]

Set a conference:

>>> from icalendar import Event, Conference
>>> event = Event()
>>> event.conferences = [
...     Conference(
...         "tel:+1-412-555-0123,,,654321",
...         feature="PHONE,MODERATOR",
...         label="Moderator dial-in",
...         language="EN",
...     )
... ]
>>> print(event.to_ical())
BEGIN:VEVENT
CONFERENCE;FEATURE="PHONE,MODERATOR";LABEL=Moderator dial-in;LANGUAGE=EN;V
 ALUE=URI:tel:+1-412-555-0123,,,654321
END:VEVENT

property contacts: list[str]#

Contact information associated with the calendar component.

Purpose:: This property is used to represent contact information or alternately a reference to contact information associated with the calendar component.
Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: In RFC 5545, this property can be specified in a “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar component. In RFC 7953, this property can be specified in a “VAVAILABILITY” amd “VAVAILABLE” calendar component.
Description:: The property value consists of textual contact information. An alternative representation for the property value can also be specified that refers to a URI pointing to an alternate form, such as a vCard RFC 2426, for the contact information.

Example

The following is an example of this property referencing textual contact information:

CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property with an alternate representation of an LDAP URI to a directory entry containing the contact information:

CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\,
c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\,
+1-919-555-1234

The following is an example of this property with an alternate representation of a MIME body part containing the contact information, such as a vCard RFC 2426 embedded in a text/ directory media type RFC 2425:

CONTACT;ALTREP="CID:part3.msg970930T083000SILVER@example.com":
 Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property referencing a network resource, such as a vCard RFC 2426 object containing the contact information:

CONTACT;ALTREP="http://example.com/pdi/jdoe.vcf":Jim
 Dolittle\, ABC Industries\, +1-919-555-1234

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.

property duration: timedelta#

The duration of the VEVENT.

Returns the DURATION property if set, otherwise calculated from start and end. When setting duration, the end time is automatically calculated from start + duration. You can set the duration to automatically adjust the end time while keeping start locked.

Setting the duration will: 1. Keep the start time locked (unchanged) 2. Adjust the end time to start + duration 3. Remove any existing DTEND property 4. Set the DURATION property

property end: date | datetime#

The end of the event.

Invalid values raise an InvalidCalendar error. If there is no end, we also raise an IncompleteComponent error.

classmethod example(name: str = 'rfc_9074_example_3') → Event[source]#: Return the calendar example with the given name.

exclusive = ('DTEND', 'DURATION')#

property exdates: list[date | datetime]#

EXDATE defines the list of DATE-TIME exceptions for recurring components.

EXDATE is defined in RFC 5545.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

Example

Below, we add an exdate in a list and get the resulting list of exdates.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of excluded dates
>>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.exdates
[datetime.datetime(2025, 4, 28, 16, 5)]

Note

You cannot modify the EXDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

ignore_exceptions = True#

property images: list[Image]#

IMAGE specifies an image associated with the calendar or a calendar component.

Description:: This property specifies an image for an iCalendar object or a calendar component via a URI or directly with inline data that can be used by calendar user agents when presenting the calendar data to a user. Multiple properties MAY be used to specify alternative sets of images with, for example, varying media subtypes, resolutions, or sizes. When multiple properties are present, calendar user agents SHOULD display only one of them, picking one that provides the most appropriate image quality, or display none. The “DISPLAY” parameter is used to indicate the intended display mode for the image. The “ALTREP” parameter, defined in RFC 5545, can be used to provide a “clickable” image where the URI in the parameter value can be “launched” by a click on the image in the calendar user agent.
Conformance:: This property can be specified multiple times in an iCalendar object or in “VEVENT”, “VTODO”, or “VJOURNAL” calendar components.

Note

At the present moment, this property is read-only. If you require a setter, please open an issue or a pull request.

property location: str | None#

The intended venue for the activity defined by a calendar component.

Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: Since RFC 5545, this property can be specified in “VEVENT” or “VTODO” calendar component. RFC 7953 adds this property to “VAVAILABILITY” and “VAVAILABLE”.
Description:: Specific venues such as conference or meeting rooms may be explicitly specified using this property. An alternate representation may be specified that is a URI that points to directory information with more structured specification of the location. For example, the alternate representation may specify either an LDAP URL RFC 4516 pointing to an LDAP server entry or a CID URL RFC 2392 pointing to a MIME body part containing a Virtual-Information Card (vCard) RFC 2426 for the location.

multiple = ('ATTACH', 'ATTENDEE', 'CATEGORIES', 'COMMENT', 'CONTACT', 'EXDATE', 'RSTATUS', 'RELATED', 'RESOURCES', 'RDATE', 'RRULE')#

name = 'VEVENT'#

Create a new event with all required properties.

This creates a new Event in accordance with RFC 5545.

Parameters:

attendees – The attendees of the event.
categories – The categories of the event.
classification – The classification of the event.
color – The color of the event.
comments – The Component.comments of the event.
concepts – The Component.concepts of the event.
conferences – The conferences of the event.
created – The Component.created of the event.
description – The description of the event.
end – The end of the event.
last_modified – The Component.last_modified of the event.
links – The Component.links of the event.
location – The location of the event.
organizer – The organizer of the event.
priority – The priority of the event.
refids – Component.refids of the event.
related_to – Component.related_to of the event.
sequence – The sequence of the event.
stamp – The Component.stamp of the event. If None, this is set to the current time.
start – The start of the event.
status – The status of the event.
summary – The summary of the event.
transparency – The transparency of the event.
uid – The uid of the event. If None, this is set to a new uuid.uuid4().
url – The url of the event.

Returns:

Event

Raises:

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

Warning

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

property organizer: vCalAddress | None#

ORGANIZER defines the organizer for a calendar component.

Property Parameters:

IANA, non-standard, language, common name, directory entry reference, and sent-by property parameters can be specified on this property.

Conformance:

This property MUST be specified in an iCalendar object that specifies a group-scheduled calendar entity. This property MUST be specified in an iCalendar object that specifies the publication of a calendar user’s busy time. This property MUST NOT be 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 is specified within the “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to specify the organizer of a group-scheduled calendar entity. The property is specified within the “VFREEBUSY” calendar component to specify the calendar user requesting the free or busy time. When publishing a “VFREEBUSY” calendar component, the property is used to specify the calendar that the published busy time came from.

The property has the property parameters “CN”, for specifying the common or display name associated with the “Organizer”, “DIR”, for specifying a pointer to the directory information associated with the “Organizer”, “SENT-BY”, for specifying another calendar user that is acting on behalf of the “Organizer”. The non-standard parameters may also be specified on this property. If the “LANGUAGE” property parameter is specified, the identified language applies to the “CN” parameter value.

property priority: int#

Conformance:

This property can be specified in “VEVENT” and “VTODO” calendar components according to RFC 5545. RFC 7953 adds this property to “VAVAILABILITY”.

Description:

This priority is specified as an integer in the range 0 to 9. A value of 0 specifies an undefined priority. A value of 1 is the highest priority. A value of 2 is the second highest priority. Subsequent numbers specify a decreasing ordinal priority. A value of 9 is the lowest priority.

A CUA with a three-level priority scheme of “HIGH”, “MEDIUM”, and “LOW” is mapped into this property such that a property value in the range of 1 to 4 specifies “HIGH” priority. A value of 5 is the normal or “MEDIUM” priority. A value in the range of 6 to 9 is “LOW” priority.

A CUA with a priority schema of “A1”, “A2”, “A3”, “B1”, “B2”, …, “C3” is mapped into this property such that a property value of 1 specifies “A1”, a property value of 2 specifies “A2”, a property value of 3 specifies “A3”, and so forth up to a property value of 9 specifies “C3”.

Other integer values are reserved for future use.

Within a “VEVENT” calendar component, this property specifies a priority for the event. This property may be useful when more than one event is scheduled for a given time period.

Within a “VTODO” calendar component, this property specified a priority for the to-do. This property is useful in prioritizing multiple action items for a given time period.

property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]#

The RDATE property defines the list of DATE-TIME values for recurring components.

RDATE is defined in RFC 5545. The return value is a list of tuples (start, end).

start can be a datetime.date or a datetime.datetime, with and without timezone.

end is None if the end is not specified and a datetime.datetime if the end is specified.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

Example

Below, we set one RDATE in a list and get the resulting tuple of start and end.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of recurrence dates
>>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.rdates
[(datetime.datetime(2025, 4, 28, 16, 5), None)]

Note

You cannot modify the RDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

required = ('UID', 'DTSTAMP')#

property rrules: list[vRecur]#

RRULE defines a rule or repeating pattern for recurring components.

RRULE is defined in RFC 5545. RFC 7529 adds the SKIP parameter icalendar.prop.vSkip.

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

Description:

The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

Examples

Daily for 10 occurrences:

>>> from icalendar import Event
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;COUNT=10
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

Daily until December 24, 1997:

>>> from icalendar import Event, vRecur
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

Note

You cannot modify the RRULE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

property sequence: int#

This property defines the revision sequence number of the calendar component within a sequence of revisions.

Value Type:

INTEGER

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

The property can be specified in “VEVENT”, “VTODO”, or “VJOURNAL” calendar component.

Description:

When a calendar component is created, its sequence number is 0. It is monotonically incremented by the “Organizer’s” CUA each time the “Organizer” makes a significant revision to the calendar component.

The “Organizer” includes this property in an iCalendar object that it sends to an “Attendee” to specify the current version of the calendar component.

The “Attendee” includes this property in an iCalendar object that it sends to the “Organizer” to specify the version of the calendar component to which the “Attendee” is referring.

A change to the sequence number is not the mechanism that an “Organizer” uses to request a response from the “Attendees”. The “RSVP” parameter on the “ATTENDEE” property is used by the “Organizer” to indicate that a response from the “Attendees” is requested.

Recurrence instances of a recurring component MAY have different sequence numbers.

Examples

The following is an example of this property for a calendar component that was just created by the “Organizer”:

>>> from icalendar import Event
>>> event = Event()
>>> event.sequence
0

The following is an example of this property for a calendar component that has been revised 10 different times by the “Organizer”:

>>> from icalendar import Calendar
>>> calendar = Calendar.example("issue_156_RDATE_with_PERIOD_TZID_khal")
>>> event = calendar.events[0]
>>> event.sequence
10

set_duration(duration: timedelta | None, locked: Literal['start', 'end'] = 'start')[source]#

Set the duration of the event relative to either start or end.

Parameters:

duration – The duration to set, or None to convert to DURATION property
locked – Which property to keep unchanged (‘start’ or ‘end’)

set_end(end: date | datetime, locked: Literal['start', 'duration'] = 'start')[source]#

Set the end of the component, keeping either the start or the duration same.

Parameters:

end – The end time to set
locked – Which property to keep unchanged (‘start’ or ‘duration’)

set_start(start: date | datetime, locked: Literal['duration', 'end'] | None = None)[source]#

Set the start and keep the duration or end of the event.

Parameters:

start – The start time to set
locked – Which property to keep unchanged (‘duration’, ‘end’, or None for auto-detect)

singletons = ('CLASS', 'CREATED', 'COLOR', 'DESCRIPTION', 'DTSTART', 'GEO', 'LAST-MODIFIED', 'LOCATION', 'ORGANIZER', 'PRIORITY', 'DTSTAMP', 'SEQUENCE', 'STATUS', 'SUMMARY', 'TRANSP', 'URL', 'RECURRENCE-ID', 'DTEND', 'DURATION', 'UID')#

property start: date | datetime#

The start of the event.

Invalid values raise an InvalidCalendar. If there is no start, we also raise an IncompleteComponent error.

You can get the start, end and duration of an event as follows:

>>> from datetime import datetime
>>> from icalendar import Event
>>> event = Event()
>>> event.start = datetime(2021, 1, 1, 12)
>>> event.end = datetime(2021, 1, 1, 12, 30) # 30 minutes
>>> event.duration  # 1800 seconds == 30 minutes
datetime.timedelta(seconds=1800)
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART:20210101T120000
DTEND:20210101T123000
END:VEVENT

property status: StrEnum#

STATUS defines the overall status or confirmation for the calendar component.

Returns:: icalendar.enums.STATUS

The default value is "".

Description:: In a group-scheduled calendar component, the property is used by the “Organizer” to provide a confirmation of the event to the “Attendees”. For example in a “VEVENT” calendar component, the “Organizer” can indicate that a meeting is tentative, confirmed, or cancelled. In a “VTODO” calendar component, the “Organizer” can indicate that an action item needs action, is completed, is in process or being worked on, or has been cancelled. In a “VJOURNAL” calendar component, the “Organizer” can indicate that a journal entry is draft, final, or has been cancelled or removed.

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 transparency: StrEnum#

TRANSP defines whether or not an event is transparent to busy time searches.

Returns:: icalendar.enums.TRANSP

Description:: Time Transparency is the characteristic of an event that determines whether it appears to consume time on a calendar. Events that consume actual time for the individual or resource associated with the calendar SHOULD be recorded as OPAQUE, allowing them to be detected by free/busy time searches. Other events, which do not take up the individual’s (or resource’s) time SHOULD be recorded as TRANSPARENT, making them invisible to free/ busy time searches.

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

property url: str#

A Uniform Resource Locator (URL) associated with the iCalendar object.

Description:: This property may be used in a calendar component to convey a location where a more dynamic rendition of the calendar information associated with the calendar component can be found. This memo does not attempt to standardize the form of the URI, nor the format of the resource pointed to by the property value. If the URL property and Content-Location MIME header are both specified, they MUST point to the same resource.
Conformance:: This property can be specified once in the “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar components. Since RFC 7986, this property can also be defined on a “VCALENDAR”.

Example

The following is an example of this property:

URL:http://example.com/pub/calendars/jsmith/mytime.ics

class icalendar.FBTYPE(*values)[source]#

Bases: StrEnum

Enum for FBTYPE from RFC 5545.

Values:: FREE, BUSY, BUSY_UNAVAILABLE, BUSY_TENTATIVE

See also

Component.concepts

property classification: StrEnum#

CLASS specifies the class of the calendar component.

Returns:: icalendar.enums.CLASS

Description:: An access classification is only one component of the general security system within a calendar application. It provides a method of capturing the scope of the access the calendar owner intends for information within an individual calendar entry. The access classification of an individual iCalendar component is useful when measured along with the other security components of a calendar system (e.g., calendar user authentication, authorization, access rights, access role, etc.). Hence, the semantics of the individual access classifications cannot be completely defined by this memo alone. Additionally, due to the “blind” nature of most exchange processes using this memo, these access classifications cannot serve as an enforcement statement for a system receiving an iCalendar object. Rather, they provide a method for capturing the intention of the calendar owner for the access to the calendar component. If not specified in a component that allows this property, the default value is PUBLIC. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the PRIVATE value.

property color: str#

This property specifies a color used for displaying the component.

This implements RFC 7986 COLOR property.

Property Parameters:: IANA and non-standard property parameters can be specified on this property.
Conformance:: This property can be specified once in an iCalendar object or in VEVENT, VTODO, or VJOURNAL calendar components.
Description:: This property specifies a color that clients MAY use when presenting the relevant data to a user. Typically, this would appear as the “background” color of events or tasks. The value is a case-insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of W3C.REC-css3-color-20110607.

Example

"turquoise", "#ffffff"

>>> from icalendar import Todo
>>> todo = Todo()
>>> todo.color = "green"
>>> print(todo.to_ical())
BEGIN:VTODO
COLOR:green
END:VTODO

property contacts: list[str]#

Contact information associated with the calendar component.

Purpose:: This property is used to represent contact information or alternately a reference to contact information associated with the calendar component.
Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: In RFC 5545, this property can be specified in a “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar component. In RFC 7953, this property can be specified in a “VAVAILABILITY” amd “VAVAILABLE” calendar component.
Description:: The property value consists of textual contact information. An alternative representation for the property value can also be specified that refers to a URI pointing to an alternate form, such as a vCard RFC 2426, for the contact information.

Example

The following is an example of this property referencing textual contact information:

CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property with an alternate representation of an LDAP URI to a directory entry containing the contact information:

CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\,
c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\,
+1-919-555-1234

The following is an example of this property with an alternate representation of a MIME body part containing the contact information, such as a vCard RFC 2426 embedded in a text/ directory media type RFC 2425:

CONTACT;ALTREP="CID:part3.msg970930T083000SILVER@example.com":
 Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property referencing a network resource, such as a vCard RFC 2426 object containing the contact information:

CONTACT;ALTREP="http://example.com/pdi/jdoe.vcf":Jim
 Dolittle\, ABC Industries\, +1-919-555-1234

property description: str#

The concatenated descriptions of the journal.

A Journal can have several descriptions. This is a compatibility method.

property descriptions: list[str]#

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 multiple times only within a “VJOURNAL” calendar component.
Description:: This property is used in the “VJOURNAL” calendar component to capture one or more textual journal entries.

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.

property duration: timedelta#

timedelta(0).

Type:: The journal has no duration

property end: date#

The start of the Journal.

The “DTSTART” property is used to specify the calendar date with which the journal entry is associated.

property exdates: list[date | datetime]#

EXDATE defines the list of DATE-TIME exceptions for recurring components.

EXDATE is defined in RFC 5545.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

Example

Below, we add an exdate in a list and get the resulting list of exdates.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of excluded dates
>>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.exdates
[datetime.datetime(2025, 4, 28, 16, 5)]

Note

You cannot modify the EXDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

property images: list[Image]#

IMAGE specifies an image associated with the calendar or a calendar component.

Description:: This property specifies an image for an iCalendar object or a calendar component via a URI or directly with inline data that can be used by calendar user agents when presenting the calendar data to a user. Multiple properties MAY be used to specify alternative sets of images with, for example, varying media subtypes, resolutions, or sizes. When multiple properties are present, calendar user agents SHOULD display only one of them, picking one that provides the most appropriate image quality, or display none. The “DISPLAY” parameter is used to indicate the intended display mode for the image. The “ALTREP” parameter, defined in RFC 5545, can be used to provide a “clickable” image where the URI in the parameter value can be “launched” by a click on the image in the calendar user agent.
Conformance:: This property can be specified multiple times in an iCalendar object or in “VEVENT”, “VTODO”, or “VJOURNAL” calendar components.

Note

At the present moment, this property is read-only. If you require a setter, please open an issue or a pull request.

multiple = ('ATTACH', 'ATTENDEE', 'CATEGORIES', 'COMMENT', 'CONTACT', 'EXDATE', 'RELATED', 'RDATE', 'RRULE', 'RSTATUS', 'DESCRIPTION')#

name = 'VJOURNAL'#

Create a new journal entry with all required properties.

This creates a new Journal in accordance with RFC 5545.

Parameters:

attendees – The attendees of the journal.
categories – The categories of the journal.
classification – The classification of the journal.
color – The color of the journal.
comments – The Component.comments of the journal.
concepts – The Component.concepts of the journal.
contacts – The contacts of the journal.
created – The Component.created of the journal.
description – The description of the journal.
end – The end of the journal.
last_modified – The Component.last_modified of the journal.
links – The Component.links of the journal.
organizer – The organizer of the journal.
refids – Component.refids of the journal.
related_to – Component.related_to of the journal.
sequence – The sequence of the journal.
stamp – The Component.stamp of the journal. If None, this is set to the current time.
start – The start of the journal.
status – The status of the journal.
summary – The summary of the journal.
uid – The uid of the journal. If None, this is set to a new uuid.uuid4().
url – The url of the journal.

Returns:

Journal

Raises:

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

Warning

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

property organizer: vCalAddress | None#

ORGANIZER defines the organizer for a calendar component.

Property Parameters:

IANA, non-standard, language, common name, directory entry reference, and sent-by property parameters can be specified on this property.

Conformance:

This property MUST be specified in an iCalendar object that specifies a group-scheduled calendar entity. This property MUST be specified in an iCalendar object that specifies the publication of a calendar user’s busy time. This property MUST NOT be 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 is specified within the “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to specify the organizer of a group-scheduled calendar entity. The property is specified within the “VFREEBUSY” calendar component to specify the calendar user requesting the free or busy time. When publishing a “VFREEBUSY” calendar component, the property is used to specify the calendar that the published busy time came from.

The property has the property parameters “CN”, for specifying the common or display name associated with the “Organizer”, “DIR”, for specifying a pointer to the directory information associated with the “Organizer”, “SENT-BY”, for specifying another calendar user that is acting on behalf of the “Organizer”. The non-standard parameters may also be specified on this property. If the “LANGUAGE” property parameter is specified, the identified language applies to the “CN” parameter value.

property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]#

The RDATE property defines the list of DATE-TIME values for recurring components.

RDATE is defined in RFC 5545. The return value is a list of tuples (start, end).

start can be a datetime.date or a datetime.datetime, with and without timezone.

end is None if the end is not specified and a datetime.datetime if the end is specified.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

Example

Below, we set one RDATE in a list and get the resulting tuple of start and end.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of recurrence dates
>>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.rdates
[(datetime.datetime(2025, 4, 28, 16, 5), None)]

Note

You cannot modify the RDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

required = ('UID', 'DTSTAMP')#

property rrules: list[vRecur]#

RRULE defines a rule or repeating pattern for recurring components.

RRULE is defined in RFC 5545. RFC 7529 adds the SKIP parameter icalendar.prop.vSkip.

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

Description:

The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

Examples

Daily for 10 occurrences:

>>> from icalendar import Event
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;COUNT=10
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

Daily until December 24, 1997:

>>> from icalendar import Event, vRecur
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

Note

You cannot modify the RRULE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

property sequence: int#

This property defines the revision sequence number of the calendar component within a sequence of revisions.

Value Type:

INTEGER

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

The property can be specified in “VEVENT”, “VTODO”, or “VJOURNAL” calendar component.

Description:

When a calendar component is created, its sequence number is 0. It is monotonically incremented by the “Organizer’s” CUA each time the “Organizer” makes a significant revision to the calendar component.

The “Organizer” includes this property in an iCalendar object that it sends to an “Attendee” to specify the current version of the calendar component.

The “Attendee” includes this property in an iCalendar object that it sends to the “Organizer” to specify the version of the calendar component to which the “Attendee” is referring.

A change to the sequence number is not the mechanism that an “Organizer” uses to request a response from the “Attendees”. The “RSVP” parameter on the “ATTENDEE” property is used by the “Organizer” to indicate that a response from the “Attendees” is requested.

Recurrence instances of a recurring component MAY have different sequence numbers.

Examples

The following is an example of this property for a calendar component that was just created by the “Organizer”:

>>> from icalendar import Event
>>> event = Event()
>>> event.sequence
0

The following is an example of this property for a calendar component that has been revised 10 different times by the “Organizer”:

>>> from icalendar import Calendar
>>> calendar = Calendar.example("issue_156_RDATE_with_PERIOD_TZID_khal")
>>> event = calendar.events[0]
>>> event.sequence
10

singletons = ('CLASS', 'COLOR', 'CREATED', 'DTSTART', 'DTSTAMP', 'LAST-MODIFIED', 'ORGANIZER', 'RECURRENCE-ID', 'SEQUENCE', 'STATUS', 'SUMMARY', 'UID', 'URL')#

property start: date#

The start of the Journal.

The “DTSTART” property is used to specify the calendar date with which the journal entry is associated.

property status: StrEnum#

STATUS defines the overall status or confirmation for the calendar component.

Returns:: icalendar.enums.STATUS

The default value is "".

Description:: In a group-scheduled calendar component, the property is used by the “Organizer” to provide a confirmation of the event to the “Attendees”. For example in a “VEVENT” calendar component, the “Organizer” can indicate that a meeting is tentative, confirmed, or cancelled. In a “VTODO” calendar component, the “Organizer” can indicate that an action item needs action, is completed, is in process or being worked on, or has been cancelled. In a “VJOURNAL” calendar component, the “Organizer” can indicate that a journal entry is draft, final, or has been cancelled or removed.

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

property url: str#

A Uniform Resource Locator (URL) associated with the iCalendar object.

Description:: This property may be used in a calendar component to convey a location where a more dynamic rendition of the calendar information associated with the calendar component can be found. This memo does not attempt to standardize the form of the URI, nor the format of the resource pointed to by the property value. If the URL property and Content-Location MIME header are both specified, they MUST point to the same resource.
Conformance:: This property can be specified once in the “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar components. Since RFC 7986, this property can also be defined on a “VCALENDAR”.

Example

The following is an example of this property:

URL:http://example.com/pub/calendars/jsmith/mytime.ics

exception icalendar.LocalTimezoneMissing[source]#

Bases: IncompleteAlarmInformation

We are missing the local timezone to compute the value.

Use Alarms.set_local_timezone().

class icalendar.PARTSTAT(*values)[source]#

Bases: StrEnum

Enum for PARTSTAT from RFC 5545.

Values:: NEEDS_ACTION, ACCEPTED, DECLINED, TENTATIVE, DELEGATED, COMPLETED, IN_PROCESS
Purpose:: To specify the participation status for the calendar user specified by the property.
Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the participation status for the calendar user specified by the property value. The parameter values differ depending on whether they are associated with a group-scheduled “VEVENT”, “VTODO”, or “VJOURNAL”. The values MUST match one of the values allowed for the given calendar component. If not specified on a property that allows this parameter, the default value is NEEDS-ACTION. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the NEEDS-ACTION value.

ACCEPTED = 'ACCEPTED'#

COMPLETED = 'COMPLETED'#

DECLINED = 'DECLINED'#

DELEGATED = 'DELEGATED'#

IN_PROCESS = 'IN-PROCESS'#

NEEDS_ACTION = 'NEEDS-ACTION'#

TENTATIVE = 'TENTATIVE'#

class icalendar.Parameters(*args, **kwargs)[source]#

Bases: CaselessDict

Parser and generator of Property parameter strings.

It knows nothing of datatypes. Its main concern is textual structure.

Examples

Modify parameters:

>>> from icalendar import Parameters
>>> params = Parameters()
>>> params['VALUE'] = 'TEXT'
>>> params.value
'TEXT'
>>> params
Parameters({'VALUE': 'TEXT'})

Create new parameters:

>>> params = Parameters(value="BINARY")
>>> params.value
'BINARY'

Set a default:

>>> params = Parameters(value="BINARY", default_value="TEXT")
>>> params
Parameters({'VALUE': 'BINARY'})

always_quoted = ('ALTREP', 'DELEGATED-FROM', 'DELEGATED-TO', 'DIR', 'MEMBER', 'SENT-BY', 'X-ADDRESS', 'X-TITLE', 'LINKREL')#

classmethod from_ical(st, strict=False)[source]#: Parses the parameter format from ical text format.

params()[source]#: In RFC 5545 keys are called parameters, so this is to be consitent with the naming conventions.

quote_also = {'CN': " '"}#

to_ical(sorted: bool = True)[source]#

property value: VALUE | str | None#

The VALUE parameter from RFC 5545.

Description:

This parameter specifies the value type and format of the property value. The property values MUST be of a single value type. For example, a “RDATE” property cannot have a combination of DATE-TIME and TIME value types.

If the property’s value is the default value type, then this parameter need not be specified. However, if the property’s default value type is overridden by some other allowable value type, then this parameter MUST be specified.

Applications MUST preserve the value data for x-name and iana- token values that they don’t recognize without attempting to interpret or parse the value data.

class icalendar.RANGE(*values)[source]#

Bases: StrEnum

Enum for RANGE from RFC 5545.

Values:: THISANDFUTURE, THISANDPRIOR (deprecated)
Purpose:: To specify the effective range of recurrence instances from the instance specified by the recurrence identifier specified by the property.
Description:: This parameter can be specified on a property that specifies a recurrence identifier. The parameter specifies the effective range of recurrence instances that is specified by the property. The effective range is from the recurrence identifier specified by the property. If this parameter is not specified on an allowed property, then the default range is the single instance specified by the recurrence identifier value of the property. The parameter value can only be “THISANDFUTURE” to indicate a range defined by the recurrence identifier and all subsequent instances. The value “THISANDPRIOR” is deprecated by this revision of iCalendar and MUST NOT be generated by applications.

THISANDFUTURE = 'THISANDFUTURE'#

THISANDPRIOR = 'THISANDPRIOR'#

class icalendar.RELATED(*values)[source]#

Bases: StrEnum

Enum for RELATED from RFC 5545.

Values:: START, END
Purpose:: To specify the relationship of the alarm trigger with respect to the start or end of the calendar component.
Description:: This parameter can be specified on properties that specify an alarm trigger with a “DURATION” value type. The parameter specifies whether the alarm will trigger relative to the start or end of the calendar component. The parameter value START will set the alarm to trigger off the start of the calendar component; the parameter value END will set the alarm to trigger off the end of the calendar component. If the parameter is not specified on an allowable property, then the default is START.

END = 'END'#

START = 'START'#

class icalendar.RELTYPE(*values)[source]#

Bases: StrEnum

Enum for RELTYPE from RFC 5545.

Values:

PARENT, CHILD, SIBLING, FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH, STARTTOSTART, FIRST, NEXT, DEPENDS-ON, REFID, CONCEPT

Purpose:

To specify the type of hierarchical relationship associated with the calendar component specified by the property.

Description:

This parameter can be specified on a property that references another related calendar. The parameter specifies the hierarchical relationship type of the calendar component referenced by the property. The parameter value can be PARENT, to indicate that the referenced calendar component is a superior of calendar component; CHILD to indicate that the referenced calendar component is a subordinate of the calendar component; or SIBLING to indicate that the referenced calendar component is a peer of the calendar component. If this parameter is not specified on an allowable property, the default relationship type is PARENT. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the PARENT value.

New Temporal RELTYPE Parameter Values (RFC 9253):

RELTYPE=FINISHTOSTART
Task-B cannot start until Task-A finishes. For example, when painting is complete, carpet laying can begin.
RELTYPE=FINISHTOFINISH
Task-B can only be completed after Task-A is finished. The related tasks may run in parallel before completion.
RELTYPE=STARTTOFINISH
The start of Task-A (which occurs after Task-B) controls the finish of Task-B. For example, ticket sales (Task-B) end after the game starts (Task-A).
RELTYPE=STARTTOSTART
The start of Task-A triggers the start of Task-B, that is, Task-B can start anytime after Task-A starts.

Additional New RELTYPE Parameter Values (RFC 9253):

RELTYPE=FIRST
This indicates that the referenced calendar component is the first in a series the referencing calendar component is part of.
RELTYPE=NEXT
This indicates that the referenced calendar component is the next in a series the referencing calendar component is part of.
RELTYPE=DEPENDS-ON
This 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.
RELTYPE=REFID
This establishes a reference from the current component to components with a REFID property that matches the value given in the associated RELATED-TO property.
RELTYPE=CONCEPT
This establishes a reference from the current component to components with a CONCEPT property that matches the value given in the associated RELATED-TO property.

Note that the relationship types of PARENT, CHILD, and SIBLING establish a hierarchical relationship. The new types of FIRST and NEXT are an ordering relationship.

Examples

The following is an example from RFC 5545:

RELATED-TO;RELTYPE=SIBLING:19960401-080045-4000F192713@
 example.com

Usage inside of RELATED-TO according to RFC 9253:

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

CHILD = 'CHILD'#

CONCEPT = 'CONCEPT'#

DEPENDS_ON = 'DEPENDS-ON'#

FINISHTOFINISH = 'FINISHTOFINISH'#

FINISHTOSTART = 'FINISHTOSTART'#

FIRST = 'FIRST'#

NEXT = 'NEXT'#

PARENT = 'PARENT'#

REFID = 'REFID'#

SIBLING = 'SIBLING'#

STARTTOFINISH = 'STARTTOFINISH'#

STARTTOSTART = 'STARTTOSTART'#

class icalendar.ROLE(*values)[source]#

Bases: StrEnum

Enum for ROLE from RFC 5545.

Values:: CHAIR, REQ_PARTICIPANT, OPT_PARTICIPANT, NON_PARTICIPANT
Purpose:: To specify the participation role for the calendar user specified by the property.
Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the participation role for the calendar user specified by the property in the group schedule calendar component. If not specified on a property that allows this parameter, the default value is REQ-PARTICIPANT. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the REQ-PARTICIPANT value.

CHAIR = 'CHAIR'#

NON_PARTICIPANT = 'NON-PARTICIPANT'#

OPT_PARTICIPANT = 'OPT-PARTICIPANT'#

REQ_PARTICIPANT = 'REQ-PARTICIPANT'#

class icalendar.STATUS(*values)[source]#

Bases: StrEnum

Enum for STATUS from RFC 5545.

Values for icalendar.cal.event.Event:: CONFIRMED, TENTATIVE, CANCELLED
Values for icalendar.cal.todo.Todo:: NEEDS_ACTION, COMPLETED, IN_PROCESS, CANCELLED
Values for icalendar.cal.journal.Journal:: DRAFT, FINAL, CANCELLED
Description:: In a group-scheduled calendar component, the property is used by the “Organizer” to provide a confirmation of the event to the “Attendees”. For example in a “VEVENT” calendar component, the “Organizer” can indicate that a meeting is tentative, confirmed, or cancelled. In a “VTODO” calendar component, the “Organizer” can indicate that an action item needs action, is completed, is in process or being worked on, or has been cancelled. In a “VJOURNAL” calendar component, the “Organizer” can indicate that a journal entry is draft, final, or has been cancelled or removed.

CANCELLED = 'CANCELLED'#

COMPLETED = 'COMPLETED'#

CONFIRMED = 'CONFIRMED'#

DRAFT = 'DRAFT'#

FINAL = 'FINAL'#

IN_PROCESS = 'IN-PROCESS'#

NEEDS_ACTION = 'NEEDS-ACTION'#

TENTATIVE = 'TENTATIVE'#

class icalendar.TRANSP(*values)[source]#

Bases: StrEnum

Enum for TRANSP from RFC 5545.

Values:: OPAQUE, TRANSPARENT
Description:: Time Transparency is the characteristic of an event that determines whether it appears to consume time on a calendar. Events that consume actual time for the individual or resource associated with the calendar SHOULD be recorded as OPAQUE, allowing them to be detected by free/busy time searches. Other events, which do not take up the individual’s (or resource’s) time SHOULD be recorded as TRANSPARENT, making them invisible to free/ busy time searches.

OPAQUE = 'OPAQUE'#

TRANSPARENT = 'TRANSPARENT'#

class icalendar.Timezone(*args, **kwargs)[source]#

Bases: Component

A “VTIMEZONE” calendar component is a grouping of component properties that defines a time zone. It is used to describe the way in which a time zone changes its offset from UTC over time.

DEFAULT_FIRST_DATE = datetime.date(1970, 1, 1)#

DEFAULT_LAST_DATE = datetime.date(2038, 1, 1)#

canonical_order = ('TZID',)#

property daylight: list[TimezoneDaylight]#

The DAYLIGHT subcomponents as a list.

These are for the daylight saving time.

classmethod example(name: str = 'pacific_fiji') → Calendar[source]#: Return the timezone example with the given name.

classmethod from_tzid(tzid: str, tzp: TZP = TZP('zoneinfo'), first_date: date = datetime.date(1970, 1, 1), last_date: date = datetime.date(2038, 1, 1)) → Timezone[source]#

Create a VTIMEZONE from a tzid like "Europe/Berlin".

Parameters:

tzid – the id of the timezone
tzp – the timezone provider
first_date – a datetime that is earlier than anything that happens in the calendar
last_date – a datetime that is later than anything that happens in the calendar

Raises:

ValueError – If the tzid is unknown.

>>> from icalendar import Timezone
>>> tz = Timezone.from_tzid("Europe/Berlin")
>>> print(tz.to_ical()[:36])
BEGIN:VTIMEZONE
TZID:Europe/Berlin

Note

This can take some time. Please cache the results.

classmethod from_tzinfo(timezone: tzinfo, tzid: str | None = None, first_date: date = datetime.date(1970, 1, 1), last_date: date = datetime.date(2038, 1, 1)) → Timezone[source]#

Return a VTIMEZONE component from a timezone object.

This works with pytz and zoneinfo and any other timezone. The offsets are calculated from the tzinfo object.

Parameters:

Parameters:

tzinfo – the timezone object
tzid – the tzid for this timezone. If None, it will be extracted from the tzinfo.
first_date – a datetime that is earlier than anything that happens in the calendar
last_date – a datetime that is later than anything that happens in the calendar

Raises:

ValueError – If we have no tzid and cannot extract one.

Note

This can take some time. Please cache the results.

get_transitions() → tuple[list[datetime], list[tuple[timedelta, timedelta, str]]][source]#

Return a tuple of (transition_times, transition_info)

transition_times = [datetime, …]
transition_info = [(TZOFFSETTO, dts_offset, tzname)]

name = 'VTIMEZONE'#

required = ('TZID',)#

singletons = ('TZID', 'LAST-MODIFIED', 'TZURL')#

property standard: list[TimezoneStandard]#: The STANDARD subcomponents as a list.

subcomponents: list[TimezoneStandard | TimezoneDaylight]#

to_tz(tzp: TZP = TZP('zoneinfo'), lookup_tzid: bool = True)[source]#

convert this VTIMEZONE component to a timezone object

Parameters:

tzp – timezone provider to use
lookup_tzid – whether to use the TZID property to look up existing timezone definitions with tzp. If it is False, a new timezone will be created. If it is True, the existing timezone will be used if it exists, otherwise a new timezone will be created.

property tz_name: str#

Return the name of the timezone component.

Please note that the names of the timezone are different from this name and may change with winter/summer time.

class icalendar.TimezoneDaylight(*args, **kwargs)[source]#

Bases: Component

The “DAYLIGHT” sub-component of “VTIMEZONE” defines the daylight saving time offset from UTC for a time zone. It represents a time zone’s daylight saving time, typically used during summer months in locations that observe Daylight Saving Time.

property DTSTART: datetime | None#

The DTSTART property.

The mandatory “DTSTART” property gives the effective onset date: and local time for the time zone sub-component definition. “DTSTART” in this usage MUST be specified as a date with a local time value.

Accepted values: datetime. 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 TZOFFSETFROM: timedelta | None#

The TZOFFSETFROM property.

The mandatory “TZOFFSETFROM” property gives the UTC offset that is: in use when the onset of this time zone observance begins. “TZOFFSETFROM” is combined with “DTSTART” to define the effective onset for the time zone sub-component definition. For example, the following represents the time at which the observance of Standard Time took effect in Fall 1967 for New York City:

DTSTART:19671029T020000 TZOFFSETFROM:-0400

Accepted values: 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 TZOFFSETTO: timedelta | None#

The TZOFFSETTO property.

The mandatory “TZOFFSETTO” property gives the UTC offset for the: time zone sub-component (Standard Time or Daylight Saving Time) when this observance is in use.

Accepted values: 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 exdates: list[date | datetime]#

EXDATE defines the list of DATE-TIME exceptions for recurring components.

EXDATE is defined in RFC 5545.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

Example

Below, we add an exdate in a list and get the resulting list of exdates.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of excluded dates
>>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.exdates
[datetime.datetime(2025, 4, 28, 16, 5)]

Note

You cannot modify the EXDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

multiple = ('COMMENT', 'RDATE', 'TZNAME', 'RRULE', 'EXDATE')#

name = 'DAYLIGHT'#

property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]#

The RDATE property defines the list of DATE-TIME values for recurring components.

RDATE is defined in RFC 5545. The return value is a list of tuples (start, end).

start can be a datetime.date or a datetime.datetime, with and without timezone.

end is None if the end is not specified and a datetime.datetime if the end is specified.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

Example

Below, we set one RDATE in a list and get the resulting tuple of start and end.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of recurrence dates
>>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.rdates
[(datetime.datetime(2025, 4, 28, 16, 5), None)]

Note

You cannot modify the RDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

required = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')#

property rrules: list[vRecur]#

RRULE defines a rule or repeating pattern for recurring components.

RRULE is defined in RFC 5545. RFC 7529 adds the SKIP parameter icalendar.prop.vSkip.

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

Description:

The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

Examples

Daily for 10 occurrences:

>>> from icalendar import Event
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;COUNT=10
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

Daily until December 24, 1997:

>>> from icalendar import Event, vRecur
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

Note

You cannot modify the RRULE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

singletons = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')#

class icalendar.TimezoneStandard(*args, **kwargs)[source]#

Bases: Component

The “STANDARD” sub-component of “VTIMEZONE” defines the standard time offset from UTC for a time zone. It represents a time zone’s standard time, typically used during winter months in locations that observe Daylight Saving Time.

property DTSTART: datetime | None#

The DTSTART property.

The mandatory “DTSTART” property gives the effective onset date: and local time for the time zone sub-component definition. “DTSTART” in this usage MUST be specified as a date with a local time value.

Accepted values: datetime. 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 TZOFFSETFROM: timedelta | None#

The TZOFFSETFROM property.

The mandatory “TZOFFSETFROM” property gives the UTC offset that is: in use when the onset of this time zone observance begins. “TZOFFSETFROM” is combined with “DTSTART” to define the effective onset for the time zone sub-component definition. For example, the following represents the time at which the observance of Standard Time took effect in Fall 1967 for New York City:

DTSTART:19671029T020000 TZOFFSETFROM:-0400

Accepted values: 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 TZOFFSETTO: timedelta | None#

The TZOFFSETTO property.

The mandatory “TZOFFSETTO” property gives the UTC offset for the: time zone sub-component (Standard Time or Daylight Saving Time) when this observance is in use.

Accepted values: 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 exdates: list[date | datetime]#

EXDATE defines the list of DATE-TIME exceptions for recurring components.

EXDATE is defined in RFC 5545.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

Example

Below, we add an exdate in a list and get the resulting list of exdates.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of excluded dates
>>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.exdates
[datetime.datetime(2025, 4, 28, 16, 5)]

Note

You cannot modify the EXDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

multiple = ('COMMENT', 'RDATE', 'TZNAME', 'RRULE', 'EXDATE')#

name = 'STANDARD'#

property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]#

The RDATE property defines the list of DATE-TIME values for recurring components.

RDATE is defined in RFC 5545. The return value is a list of tuples (start, end).

start can be a datetime.date or a datetime.datetime, with and without timezone.

end is None if the end is not specified and a datetime.datetime if the end is specified.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

Example

Below, we set one RDATE in a list and get the resulting tuple of start and end.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of recurrence dates
>>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.rdates
[(datetime.datetime(2025, 4, 28, 16, 5), None)]

Note

You cannot modify the RDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

required = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')#

property rrules: list[vRecur]#

RRULE defines a rule or repeating pattern for recurring components.

RRULE is defined in RFC 5545. RFC 7529 adds the SKIP parameter icalendar.prop.vSkip.

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

Description:

The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

Examples

Daily for 10 occurrences:

>>> from icalendar import Event
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;COUNT=10
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

Daily until December 24, 1997:

>>> from icalendar import Event, vRecur
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

Note

You cannot modify the RRULE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

singletons = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')#

class icalendar.Todo(*args, **kwargs)[source]#

Bases: Component

A “VTODO” calendar component is a grouping of component properties that represents an action item or assignment. For example, it can be used to represent an item of work assigned to an individual, such as “Prepare for the upcoming conference seminar on Internet Calendaring”.

Examples

Create a new Todo:

>>> from icalendar import Todo
>>> todo = Todo.new()
>>> print(todo.to_ical())
BEGIN:VTODO
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VTODO

property DTSTART: date | None#

The DTSTART property.

The “DTSTART” property for a “VTODO” specifies the inclusive start of the Todo.

Accepted values: datetime, date. 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 DUE: date | None#

The DUE property.

The “DUE” property for a “VTODO” calendar component specifies the non-inclusive end of the Todo.

Accepted values: datetime, date. 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 DURATION: timedelta | None#

The DURATION property.

The “DTSTART” property for a “VTODO” specifies the inclusive start of the VTODO. The “DURATION” property in conjunction with the DTSTART property for a “VTODO” calendar component specifies the non-inclusive end of the event.

If you would like to calculate the duration of a VTODO, do not use this. Instead use the duration property (lower case).

property X_MOZ_LASTACK: datetime | None#

The X-MOZ-LASTACK property. datetime in UTC

All values will be converted to a datetime in UTC. Thunderbird: Alarms before this time are acknowledged.

property X_MOZ_SNOOZE_TIME: datetime | None#

The X-MOZ-SNOOZE-TIME property. datetime in UTC

All values will be converted to a datetime in UTC. Thunderbird: Alarms before this time are snoozed.

property alarms: Alarms#

Compute the alarm times for this component.

>>> from datetime import datetime
>>> from icalendar import Todo
>>> todo = Todo()  # empty without alarms
>>> todo.start = datetime(2024, 10, 26, 10, 21)
>>> len(todo.alarms.times)
0

Note that this only uses DTSTART and DUE, but ignores RDATE, EXDATE, and RRULE properties.

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

property categories: list[str]#

This property defines the categories for a component.

Property Parameters:: IANA, non-standard, and language property parameters can be specified on this property.
Conformance:: The property can be specified within “VEVENT”, “VTODO”, or “VJOURNAL” calendar components. Since RFC 7986 it can also be defined on a “VCALENDAR” component.
Description:: This property is used to specify categories or subtypes of the calendar component. The categories are useful in searching for a calendar component of a particular type and category. Within the “VEVENT”, “VTODO”, or “VJOURNAL” calendar components, more than one category can be specified as a COMMA-separated list of categories.

Example

Below, we add the categories to an event:

>>> from icalendar import Event
>>> event = Event()
>>> event.categories = ["Work", "Meeting"]
>>> print(event.to_ical())
BEGIN:VEVENT
CATEGORIES:Work,Meeting
END:VEVENT
>>> event.categories.append("Lecture")
>>> event.categories == ["Work", "Meeting", "Lecture"]
True

Note

At present, we do not take the LANGUAGE parameter into account.

See also

Component.concepts

property classification: StrEnum#

CLASS specifies the class of the calendar component.

Returns:: icalendar.enums.CLASS

Description:: An access classification is only one component of the general security system within a calendar application. It provides a method of capturing the scope of the access the calendar owner intends for information within an individual calendar entry. The access classification of an individual iCalendar component is useful when measured along with the other security components of a calendar system (e.g., calendar user authentication, authorization, access rights, access role, etc.). Hence, the semantics of the individual access classifications cannot be completely defined by this memo alone. Additionally, due to the “blind” nature of most exchange processes using this memo, these access classifications cannot serve as an enforcement statement for a system receiving an iCalendar object. Rather, they provide a method for capturing the intention of the calendar owner for the access to the calendar component. If not specified in a component that allows this property, the default value is PUBLIC. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the PRIVATE value.

property color: str#

This property specifies a color used for displaying the component.

This implements RFC 7986 COLOR property.

Property Parameters:: IANA and non-standard property parameters can be specified on this property.
Conformance:: This property can be specified once in an iCalendar object or in VEVENT, VTODO, or VJOURNAL calendar components.
Description:: This property specifies a color that clients MAY use when presenting the relevant data to a user. Typically, this would appear as the “background” color of events or tasks. The value is a case-insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of W3C.REC-css3-color-20110607.

Example

"turquoise", "#ffffff"

>>> from icalendar import Todo
>>> todo = Todo()
>>> todo.color = "green"
>>> print(todo.to_ical())
BEGIN:VTODO
COLOR:green
END:VTODO

property conferences: list[Conference]#

Return the CONFERENCE properties as a list.

Purpose:

This property specifies information for accessing a conferencing system.

Conformance:

This property can be specified multiple times in a “VEVENT” or “VTODO” calendar component.

Description:

This property specifies information for accessing a conferencing system for attendees of a meeting or task. This might be for a telephone-based conference number dial-in with access codes included (such as a tel: URI RFC 3966 or a sip: or sips: URI RFC 3261), for a web-based video chat (such as an http: or https: URI RFC 7230), or for an instant messaging group chat room (such as an xmpp: URI RFC 5122). If a specific URI for a conferencing system is not available, a data: URI RFC 2397 containing a text description can be used.

A conference system can be a bidirectional communication channel or a uni-directional “broadcast feed”.

The “FEATURE” property parameter is used to describe the key capabilities of the conference system to allow a client to choose the ones that give the required level of interaction from a set of multiple properties.

The “LABEL” property parameter is used to convey additional details on the use of the URI. For example, the URIs or access codes for the moderator and attendee of a teleconference system could be different, and the “LABEL” property parameter could be used to “tag” each “CONFERENCE” property to indicate which is which.

The “LANGUAGE” property parameter can be used to specify the language used for text values used with this property (as per Section 3.2.10 of RFC 5545).

Example

The following are examples of this property:

CONFERENCE;VALUE=URI;FEATURE=PHONE,MODERATOR;
 LABEL=Moderator dial-in:tel:+1-412-555-0123,,,654321
CONFERENCE;VALUE=URI;FEATURE=PHONE;
 LABEL=Attendee dial-in:tel:+1-412-555-0123,,,555123
CONFERENCE;VALUE=URI;FEATURE=PHONE;
 LABEL=Attendee dial-in:tel:+1-888-555-0456,,,555123
CONFERENCE;VALUE=URI;FEATURE=CHAT;
 LABEL=Chat room:xmpp:chat-123@conference.example.com
CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO;
 LABEL=Attendee dial-in:https://chat.example.com/audio?id=123456

Get all conferences:

>>> from icalendar import Event
>>> event = Event()
>>> event.conferences
[]

Set a conference:

>>> from icalendar import Event, Conference
>>> event = Event()
>>> event.conferences = [
...     Conference(
...         "tel:+1-412-555-0123,,,654321",
...         feature="PHONE,MODERATOR",
...         label="Moderator dial-in",
...         language="EN",
...     )
... ]
>>> print(event.to_ical())
BEGIN:VEVENT
CONFERENCE;FEATURE="PHONE,MODERATOR";LABEL=Moderator dial-in;LANGUAGE=EN;V
 ALUE=URI:tel:+1-412-555-0123,,,654321
END:VEVENT

property contacts: list[str]#

Contact information associated with the calendar component.

Purpose:: This property is used to represent contact information or alternately a reference to contact information associated with the calendar component.
Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: In RFC 5545, this property can be specified in a “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar component. In RFC 7953, this property can be specified in a “VAVAILABILITY” amd “VAVAILABLE” calendar component.
Description:: The property value consists of textual contact information. An alternative representation for the property value can also be specified that refers to a URI pointing to an alternate form, such as a vCard RFC 2426, for the contact information.

Example

The following is an example of this property referencing textual contact information:

CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property with an alternate representation of an LDAP URI to a directory entry containing the contact information:

CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\,
c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\,
+1-919-555-1234

The following is an example of this property with an alternate representation of a MIME body part containing the contact information, such as a vCard RFC 2426 embedded in a text/ directory media type RFC 2425:

CONTACT;ALTREP="CID:part3.msg970930T083000SILVER@example.com":
 Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property referencing a network resource, such as a vCard RFC 2426 object containing the contact information:

CONTACT;ALTREP="http://example.com/pdi/jdoe.vcf":Jim
 Dolittle\, ABC Industries\, +1-919-555-1234

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.

property duration: timedelta#

The duration of the VTODO.

Returns the DURATION property if set, otherwise calculated from start and end. You can set the duration to automatically adjust the end time while keeping start locked.

Setting the duration will: 1. Keep the start time locked (unchanged) 2. Adjust the end time to start + duration 3. Remove any existing DUE property 4. Set the DURATION property

property end: date | datetime#

The end of the todo.

Invalid values raise an InvalidCalendar error. If there is no end, we also raise an IncompleteComponent error.

exclusive = ('DUE', 'DURATION')#

property exdates: list[date | datetime]#

EXDATE defines the list of DATE-TIME exceptions for recurring components.

EXDATE is defined in RFC 5545.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

Example

Below, we add an exdate in a list and get the resulting list of exdates.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of excluded dates
>>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.exdates
[datetime.datetime(2025, 4, 28, 16, 5)]

Note

You cannot modify the EXDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

property images: list[Image]#

IMAGE specifies an image associated with the calendar or a calendar component.

Description:: This property specifies an image for an iCalendar object or a calendar component via a URI or directly with inline data that can be used by calendar user agents when presenting the calendar data to a user. Multiple properties MAY be used to specify alternative sets of images with, for example, varying media subtypes, resolutions, or sizes. When multiple properties are present, calendar user agents SHOULD display only one of them, picking one that provides the most appropriate image quality, or display none. The “DISPLAY” parameter is used to indicate the intended display mode for the image. The “ALTREP” parameter, defined in RFC 5545, can be used to provide a “clickable” image where the URI in the parameter value can be “launched” by a click on the image in the calendar user agent.
Conformance:: This property can be specified multiple times in an iCalendar object or in “VEVENT”, “VTODO”, or “VJOURNAL” calendar components.

Note

At the present moment, this property is read-only. If you require a setter, please open an issue or a pull request.

property location: str | None#

The intended venue for the activity defined by a calendar component.

Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: Since RFC 5545, this property can be specified in “VEVENT” or “VTODO” calendar component. RFC 7953 adds this property to “VAVAILABILITY” and “VAVAILABLE”.
Description:: Specific venues such as conference or meeting rooms may be explicitly specified using this property. An alternate representation may be specified that is a URI that points to directory information with more structured specification of the location. For example, the alternate representation may specify either an LDAP URL RFC 4516 pointing to an LDAP server entry or a CID URL RFC 2392 pointing to a MIME body part containing a Virtual-Information Card (vCard) RFC 2426 for the location.

multiple = ('ATTACH', 'ATTENDEE', 'CATEGORIES', 'COMMENT', 'CONTACT', 'EXDATE', 'RSTATUS', 'RELATED', 'RESOURCES', 'RDATE', 'RRULE')#

name = 'VTODO'#

Create a new TODO with all required properties.

This creates a new Todo in accordance with RFC 5545.

Parameters:

attendees – The attendees of the todo.
categories – The categories of the todo.
classification – The classification of the todo.
color – The color of the todo.
comments – The Component.comments of the todo.
concepts – The Component.concepts of the todo.
contacts – The contacts of the todo.
conferences – The conferences of the todo.
created – The Component.created of the todo.
description – The description of the todo.
end – The end of the todo.
last_modified – The Component.last_modified of the todo.
links – The Component.links of the todo.
location – The location of the todo.
organizer – The organizer of the todo.
refids – Component.refids of the todo.
related_to – Component.related_to of the todo.
sequence – The sequence of the todo.
stamp – The Component.DTSTAMP of the todo. If None, this is set to the current time.
start – The start of the todo.
status – The status of the todo.
summary – The summary of the todo.
uid – The uid of the todo. If None, this is set to a new uuid.uuid4().
url – The url of the todo.

Returns:

Todo

Raises:

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

Warning

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

property organizer: vCalAddress | None#

ORGANIZER defines the organizer for a calendar component.

Property Parameters:

IANA, non-standard, language, common name, directory entry reference, and sent-by property parameters can be specified on this property.

Conformance:

This property MUST be specified in an iCalendar object that specifies a group-scheduled calendar entity. This property MUST be specified in an iCalendar object that specifies the publication of a calendar user’s busy time. This property MUST NOT be 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 is specified within the “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to specify the organizer of a group-scheduled calendar entity. The property is specified within the “VFREEBUSY” calendar component to specify the calendar user requesting the free or busy time. When publishing a “VFREEBUSY” calendar component, the property is used to specify the calendar that the published busy time came from.

The property has the property parameters “CN”, for specifying the common or display name associated with the “Organizer”, “DIR”, for specifying a pointer to the directory information associated with the “Organizer”, “SENT-BY”, for specifying another calendar user that is acting on behalf of the “Organizer”. The non-standard parameters may also be specified on this property. If the “LANGUAGE” property parameter is specified, the identified language applies to the “CN” parameter value.

property priority: int#

Conformance:

This property can be specified in “VEVENT” and “VTODO” calendar components according to RFC 5545. RFC 7953 adds this property to “VAVAILABILITY”.

Description:

This priority is specified as an integer in the range 0 to 9. A value of 0 specifies an undefined priority. A value of 1 is the highest priority. A value of 2 is the second highest priority. Subsequent numbers specify a decreasing ordinal priority. A value of 9 is the lowest priority.

A CUA with a three-level priority scheme of “HIGH”, “MEDIUM”, and “LOW” is mapped into this property such that a property value in the range of 1 to 4 specifies “HIGH” priority. A value of 5 is the normal or “MEDIUM” priority. A value in the range of 6 to 9 is “LOW” priority.

A CUA with a priority schema of “A1”, “A2”, “A3”, “B1”, “B2”, …, “C3” is mapped into this property such that a property value of 1 specifies “A1”, a property value of 2 specifies “A2”, a property value of 3 specifies “A3”, and so forth up to a property value of 9 specifies “C3”.

Other integer values are reserved for future use.

Within a “VEVENT” calendar component, this property specifies a priority for the event. This property may be useful when more than one event is scheduled for a given time period.

Within a “VTODO” calendar component, this property specified a priority for the to-do. This property is useful in prioritizing multiple action items for a given time period.

property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]#

The RDATE property defines the list of DATE-TIME values for recurring components.

RDATE is defined in RFC 5545. The return value is a list of tuples (start, end).

start can be a datetime.date or a datetime.datetime, with and without timezone.

end is None if the end is not specified and a datetime.datetime if the end is specified.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

Description:

This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

Example

Below, we set one RDATE in a list and get the resulting tuple of start and end.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of recurrence dates
>>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.rdates
[(datetime.datetime(2025, 4, 28, 16, 5), None)]

Note

You cannot modify the RDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

required = ('UID', 'DTSTAMP')#

property rrules: list[vRecur]#

RRULE defines a rule or repeating pattern for recurring components.

RRULE is defined in RFC 5545. RFC 7529 adds the SKIP parameter icalendar.prop.vSkip.

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

Description:

The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

Examples

Daily for 10 occurrences:

>>> from icalendar import Event
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;COUNT=10
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

Daily until December 24, 1997:

>>> from icalendar import Event, vRecur
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

Note

You cannot modify the RRULE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related Projects.

property sequence: int#

This property defines the revision sequence number of the calendar component within a sequence of revisions.

Value Type:

INTEGER

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

The property can be specified in “VEVENT”, “VTODO”, or “VJOURNAL” calendar component.

Description:

When a calendar component is created, its sequence number is 0. It is monotonically incremented by the “Organizer’s” CUA each time the “Organizer” makes a significant revision to the calendar component.

The “Organizer” includes this property in an iCalendar object that it sends to an “Attendee” to specify the current version of the calendar component.

The “Attendee” includes this property in an iCalendar object that it sends to the “Organizer” to specify the version of the calendar component to which the “Attendee” is referring.

A change to the sequence number is not the mechanism that an “Organizer” uses to request a response from the “Attendees”. The “RSVP” parameter on the “ATTENDEE” property is used by the “Organizer” to indicate that a response from the “Attendees” is requested.

Recurrence instances of a recurring component MAY have different sequence numbers.

Examples

The following is an example of this property for a calendar component that was just created by the “Organizer”:

>>> from icalendar import Event
>>> event = Event()
>>> event.sequence
0

The following is an example of this property for a calendar component that has been revised 10 different times by the “Organizer”:

>>> from icalendar import Calendar
>>> calendar = Calendar.example("issue_156_RDATE_with_PERIOD_TZID_khal")
>>> event = calendar.events[0]
>>> event.sequence
10

set_duration(duration: timedelta | None, locked: Literal['start', 'end'] = 'start')[source]#

Set the duration of the event relative to either start or end.

Parameters:

duration – The duration to set, or None to convert to DURATION property
locked – Which property to keep unchanged (‘start’ or ‘end’)

set_end(end: date | datetime, locked: Literal['start', 'duration'] = 'start')[source]#

Set the end of the component, keeping either the start or the duration same.

Parameters:

end – The end time to set
locked – Which property to keep unchanged (‘start’ or ‘duration’)

set_start(start: date | datetime, locked: Literal['duration', 'end'] | None = None)[source]#

Set the start with explicit locking behavior.

Parameters:

start – The start time to set
locked – Which property to keep unchanged (‘duration’, ‘end’, or None for auto-detect)

singletons = ('CLASS', 'COLOR', 'COMPLETED', 'CREATED', 'DESCRIPTION', 'DTSTAMP', 'DTSTART', 'GEO', 'LAST-MODIFIED', 'LOCATION', 'ORGANIZER', 'PERCENT-COMPLETE', 'PRIORITY', 'RECURRENCE-ID', 'SEQUENCE', 'STATUS', 'SUMMARY', 'UID', 'URL', 'DUE', 'DURATION')#

property start: date | datetime#

The start of the VTODO.

Invalid values raise an InvalidCalendar. If there is no start, we also raise an IncompleteComponent error.

You can get the start, end and duration of a Todo as follows:

>>> from datetime import datetime
>>> from icalendar import Todo
>>> todo = Todo()
>>> todo.start = datetime(2021, 1, 1, 12)
>>> todo.end = datetime(2021, 1, 1, 12, 30) # 30 minutes
>>> todo.duration  # 1800 seconds == 30 minutes
datetime.timedelta(seconds=1800)
>>> print(todo.to_ical())
BEGIN:VTODO
DTSTART:20210101T120000
DUE:20210101T123000
END:VTODO

property status: StrEnum#

STATUS defines the overall status or confirmation for the calendar component.

Returns:: icalendar.enums.STATUS

The default value is "".

Description:: In a group-scheduled calendar component, the property is used by the “Organizer” to provide a confirmation of the event to the “Attendees”. For example in a “VEVENT” calendar component, the “Organizer” can indicate that a meeting is tentative, confirmed, or cancelled. In a “VTODO” calendar component, the “Organizer” can indicate that an action item needs action, is completed, is in process or being worked on, or has been cancelled. In a “VJOURNAL” calendar component, the “Organizer” can indicate that a journal entry is draft, final, or has been cancelled or removed.

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

property url: str#

A Uniform Resource Locator (URL) associated with the iCalendar object.

Description:: This property may be used in a calendar component to convey a location where a more dynamic rendition of the calendar information associated with the calendar component can be found. This memo does not attempt to standardize the form of the URI, nor the format of the resource pointed to by the property value. If the URL property and Content-Location MIME header are both specified, they MUST point to the same resource.
Conformance:: This property can be specified once in the “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar components. Since RFC 7986, this property can also be defined on a “VCALENDAR”.

Example

The following is an example of this property:

URL:http://example.com/pub/calendars/jsmith/mytime.ics

class icalendar.TypesFactory(*args, **kwargs)[source]#

Bases: CaselessDict

All Value types defined in RFC 5545 are registered in this factory class.

The value and parameter names don’t overlap. So one factory is enough for both kinds.

for_property(name, value_param: str | None = None) → type[source]#

Returns the type class for a property or parameter.

Parameters:

name – Property or parameter name
value_param – Optional VALUE parameter, for example,
"DATE"
"DATE-TIME"
string. (or other)

Returns:

The appropriate value type class

from_ical(name, value)[source]#: Decodes a named property or parameter value from an icalendar encoded string to a primitive python type.

to_ical(name, value)[source]#: Encodes a named value from a primitive python type to an icalendar encoded string.

types_map = {'ACKNOWLEDGED': 'date-time', 'ACTION': 'text', 'ALTREP': 'uri', 'ATTACH': 'uri', 'ATTENDEE': 'cal-address', 'CALSCALE': 'text', 'CATEGORIES': 'categories', 'CLASS': 'text', 'CN': 'text', 'COMMENT': 'text', 'COMPLETED': 'date-time', 'CONCEPT': 'uri', 'CONFERENCE': 'uri', 'CONTACT': 'text', 'CREATED': 'date-time', 'CUTYPE': 'text', 'DELEGATED-FROM': 'cal-address', 'DELEGATED-TO': 'cal-address', 'DESCRIPTION': 'text', 'DIR': 'uri', 'DTEND': 'date-time', 'DTSTAMP': 'date-time', 'DTSTART': 'date-time', 'DUE': 'date-time', 'DURATION': 'duration', 'ENCODING': 'text', 'EXDATE': 'date-time-list', 'EXRULE': 'recur', 'FBTYPE': 'text', 'FMTTYPE': 'text', 'FREEBUSY': 'period', 'GAP': 'duration', 'GEO': 'geo', 'LABEL': 'text', 'LANGUAGE': 'text', 'LAST-MODIFIED': 'date-time', 'LINK': 'uri', 'LINKREL': 'text', 'LOCATION': 'text', 'MEMBER': 'cal-address', 'METHOD': 'text', 'ORGANIZER': 'cal-address', 'PARTSTAT': 'text', 'PERCENT-COMPLETE': 'integer', 'PRIORITY': 'integer', 'PRODID': 'text', 'RANGE': 'text', 'RDATE': 'date-time-list', 'RECURRENCE-ID': 'date-time', 'REFID': 'text', 'REFRESH-INTERVAL': 'duration', 'RELATED': 'text', 'RELATED-TO': 'text', 'RELTYPE': 'text', 'REPEAT': 'integer', 'REQUEST-STATUS': 'text', 'RESOURCES': 'text', 'ROLE': 'text', 'RRULE': 'recur', 'RSVP': 'boolean', 'SENT-BY': 'cal-address', 'SEQUENCE': 'integer', 'SOURCE': 'uri', 'STATUS': 'text', 'SUMMARY': 'text', 'TRANSP': 'text', 'TRIGGER': 'duration', 'TZID': 'text', 'TZNAME': 'text', 'TZOFFSETFROM': 'utc-offset', 'TZOFFSETTO': 'utc-offset', 'TZURL': 'uri', 'UID': 'text', 'URL': 'uri', 'VALUE': 'text', 'VERSION': 'text'}#

class icalendar.VALUE(*values)[source]#

Bases: StrEnum

VALUE datatypes as defined in RFC 5545.

Attributes: BOOLEAN, CAL_ADDRESS, DATE, DATE_TIME, DURATION, FLOAT, INTEGER, PERIOD, RECUR, TEXT, TIME, URI, UTC_OFFSET

Description:

This parameter specifies the value type and format of the property value. The property values MUST be of a single value type. For example, a “RDATE” property cannot have a combination of DATE-TIME and TIME value types.

If the property’s value is the default value type, then this parameter need not be specified. However, if the property’s default value type is overridden by some other allowable value type, then this parameter MUST be specified.

Applications MUST preserve the value data for x-name and iana- token values that they don’t recognize without attempting to interpret or parse the value data.

BOOLEAN = 'BOOLEAN'#

CAL_ADDRESS = 'CAL-ADDRESS'#

DATE = 'DATE'#

DATE_TIME = 'DATE-TIME'#

DURATION = 'DURATION'#

FLOAT = 'FLOAT'#

INTEGER = 'INTEGER'#

PERIOD = 'PERIOD'#

RECUR = 'RECUR'#

TEXT = 'TEXT'#

TIME = 'TIME'#

URI = 'URI'#

UTC_OFFSET = 'UTC-OFFSET'#

icalendar.q_join(lst, sep=',', always_quote=False)[source]#: Joins a list on sep, quoting strings with QUOTABLE chars.

icalendar.q_split(st, sep=',', maxsplit=-1)[source]#: Splits a string on char, taking double (q)uotes into considderation.

icalendar.use_pytz()[source]#: Use pytz as the implementation that looks up and creates timezones.

icalendar.use_zoneinfo()[source]#: Use zoneinfo as the implementation that looks up and creates timezones.

class icalendar.vBinary(obj, params: dict[str, str] | None = None)[source]#

Bases: object

Binary property values are base 64 encoded.

static from_ical(ical)[source]#

obj: str#

params: Parameters#

to_ical()[source]#

class icalendar.vBoolean(*args, params: dict[str, Any] | None = None, **kwargs)[source]#

Bases: int

Boolean

Value Name: BOOLEAN

Purpose: This value type is used to identify properties that contain: either a “TRUE” or “FALSE” Boolean value.
Format Definition: This value type is defined by the following: notation:

boolean    = "TRUE" / "FALSE"

Description: These values are case-insensitive text. No additional: content value encoding is defined for this value type.
Example: The following is an example of a hypothetical property that: has a BOOLEAN value type:

TRUE

>>> from icalendar.prop import vBoolean
>>> boolean = vBoolean.from_ical('TRUE')
>>> boolean
True
>>> boolean = vBoolean.from_ical('FALSE')
>>> boolean
False
>>> boolean = vBoolean.from_ical('True')
>>> boolean
True

BOOL_MAP = {'FALSE': False, 'TRUE': True}#

classmethod from_ical(ical)[source]#

params: Parameters#

to_ical()[source]#

class icalendar.vCalAddress(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

Calendar User Address

Value Name:: CAL-ADDRESS
Purpose:: This value type is used to identify properties that contain a calendar user address.
Description:: The value is a URI as defined by [RFC3986] or any other IANA-registered form for a URI. When used to address an Internet email transport address for a calendar user, the value MUST be a mailto URI, as defined by [RFC2368].

Example

mailto: is in front of the address.

mailto:jane_doe@example.com

Parsing:

>>> from icalendar import vCalAddress
>>> cal_address = vCalAddress.from_ical('mailto:jane_doe@example.com')
>>> cal_address
vCalAddress('mailto:jane_doe@example.com')

Encoding:

>>> from icalendar import vCalAddress, Event
>>> event = Event()
>>> jane = vCalAddress("mailto:jane_doe@example.com")
>>> jane.name = "Jane"
>>> event["organizer"] = jane
>>> print(event.to_ical().decode().replace('\\r\\n', '\\n').strip())
BEGIN:VEVENT
ORGANIZER;CN=Jane:mailto:jane_doe@example.com
END:VEVENT

property CN: str#

Specify the common name to be associated with the calendar user specified.

Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the common name to be associated with the calendar user specified by the property. The parameter value is text. The parameter value can be used for display text to be associated with the calendar address specified by the property.

property CUTYPE: CUTYPE | str#

Identify the type of calendar user specified by the property.

Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the type of calendar user specified by the property. If not specified on a property that allows this parameter, the default is INDIVIDUAL. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the UNKNOWN value.

property DELEGATED_FROM: tuple[str]#

Specify the calendar users that have delegated their participation to the calendar user specified by the property.

Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. This parameter specifies those calendar users that have delegated their participation in a group-scheduled event or to-do to the calendar user specified by the property. The individual calendar address parameter values MUST each be specified in a quoted-string.

property DELEGATED_TO: tuple[str]#

Specify the calendar users to whom the calendar user specified by the property has delegated participation.

Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. This parameter specifies those calendar users whom have been delegated participation in a group-scheduled event or to-do by the calendar user specified by the property. The individual calendar address parameter values MUST each be specified in a quoted-string.

property DIR: str | None#

Specify reference to a directory entry associated with the calendar user specified by the property.

Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies a reference to the directory entry associated with the calendar user specified by the property. The parameter value is a URI. The URI parameter value MUST be specified in a quoted-string.

Note

While there is no restriction imposed on the URI schemes allowed for this parameter, CID RFC 2392, DATA RFC 2397, FILE RFC 1738, FTP RFC 1738, HTTP RFC 2616, HTTPS RFC 2818, LDAP RFC 4516, and MID RFC 2392 are the URI schemes most commonly used by current implementations.

property LANGUAGE: str | None#

Specify the language for text values in a property or property parameter.

Description:

This parameter identifies the language of the text in the property value and of all property parameter values of the property. The value of the “LANGUAGE” property parameter is that defined in RFC 5646.

For transport in a MIME entity, the Content-Language header field can be used to set the default language for the entire body part. Otherwise, no default language is assumed.

property PARTSTAT: PARTSTAT | str#

Specify the participation status for the calendar user specified by the property.

Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the participation status for the calendar user specified by the property value. The parameter values differ depending on whether they are associated with a group-scheduled “VEVENT”, “VTODO”, or “VJOURNAL”. The values MUST match one of the values allowed for the given calendar component. If not specified on a property that allows this parameter, the default value is NEEDS-ACTION. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the NEEDS-ACTION value.

property ROLE: ROLE | str#

Specify the participation role for the calendar user specified by the property.

Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the participation role for the calendar user specified by the property in the group schedule calendar component. If not specified on a property that allows this parameter, the default value is REQ-PARTICIPANT. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the REQ-PARTICIPANT value.

property RSVP: bool#

Specify whether there is an expectation of a favor of anreply from the calendar user specified by the property value.

Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the expectation of a reply from the calendar user specified by the property value. This parameter is used by the “Organizer” to request a participation status reply from an “Attendee” of a group-scheduled event or to-do. If not specified on a property that allows this parameter, the default value is False.

property SENT_BY: str | None#

Specify the calendar user that is acting on behalf of the calendar user specified by the property.

Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the calendar user that is acting on behalf of the calendar user specified by the property. The parameter value MUST be a mailto URI as defined in RFC 2368. The individual calendar address parameter values MUST each be specified in a quoted-string.

property email: str#

at the start.

Type:: The email address without mailto

classmethod from_ical(ical)[source]#

property name: str#

Specify the common name to be associated with the calendar user specified.

Description:: This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the common name to be associated with the calendar user specified by the property. The parameter value is text. The parameter value can be used for display text to be associated with the calendar address specified by the property.

Create a new vCalAddress with RFC 5545 parameters.

Creates a vCalAddress instance with automatic mailto: prefix handling and support for all standard RFC 5545 parameters.

Parameters:

email – The email address (mailto: prefix added automatically if missing)
cn – Common Name parameter
cutype – Calendar user type (INDIVIDUAL, GROUP, RESOURCE, ROOM)
delegated_from – Email of the calendar user that delegated
delegated_to – Email of the calendar user that was delegated to
directory – Reference to directory information
language – Language for text values
partstat – Participation status (NEEDS-ACTION, ACCEPTED, DECLINED, etc.)
role – Role (REQ-PARTICIPANT, OPT-PARTICIPANT, NON-PARTICIPANT, CHAIR)
rsvp – Whether RSVP is requested
sent_by – Email of the calendar user acting on behalf of this user

Returns:

A new calendar address with specified parameters

Return type:

vCalAddress

Raises:

TypeError – If email is not a string

Examples

Basic usage:

>>> from icalendar.prop import vCalAddress
>>> addr = vCalAddress.new("test@test.com")
>>> str(addr)
'mailto:test@test.com'

With parameters:

>>> addr = vCalAddress.new("test@test.com", cn="Test User", role="CHAIR")
>>> addr.params["CN"]
'Test User'
>>> addr.params["ROLE"]
'CHAIR'

params: Parameters#

to_ical()[source]#

class icalendar.vDDDLists(dt_list)[source]#

Bases: object

A list of vDDDTypes values.

dts: list#

static from_ical(ical, timezone=None)[source]#

params: Parameters#

to_ical()[source]#

class icalendar.vDDDTypes(dt)[source]#

Bases: TimeBase

A combined Datetime, Date or Duration parser/generator. Their format cannot be confused, and often values can be of either types. So this is practical.

classmethod from_ical(ical, timezone=None)[source]#

params: Parameters#

property td: timedelta#

Compatibility property returning self.dt.

This class is used to replace different time components. Some of them contain a datetime or date (.dt). Some of them contain a timedelta (.td). This property allows interoperability.

to_ical()[source]#

class icalendar.vDate(dt)[source]#

Bases: TimeBase

Date

Value Name:

DATE

Purpose:

This value type is used to identify values that contain a calendar date.

Format Definition:

This value type is defined by the following notation:

date               = date-value

date-value         = date-fullyear date-month date-mday
date-fullyear      = 4DIGIT
date-month         = 2DIGIT        ;01-12
date-mday          = 2DIGIT        ;01-28, 01-29, 01-30, 01-31
                                   ;based on month/year

Description:

If the property permits, multiple “date” values are specified as a COMMA-separated list of values. The format for the value type is based on the [ISO.8601.2004] complete representation, basic format for a calendar date. The textual format specifies a four-digit year, two-digit month, and two-digit day of the month. There are no separator characters between the year, month, and day component text.

Example

The following represents July 14, 1997:

19970714

>>> from icalendar.prop import vDate
>>> date = vDate.from_ical('19970714')
>>> date.year
1997
>>> date.month
7
>>> date.day
14

static from_ical(ical)[source]#

params: Parameters#

to_ical()[source]#

class icalendar.vDatetime(dt, /, params: dict[str, Any] | None = None)[source]#

Bases: TimeBase

Date-Time

Value Name: DATE-TIME

Purpose: This value type is used to identify values that specify a: precise calendar date and time of day. The format is based on the ISO.8601.2004 complete representation.
Format:: YYYYMMDDTHHMMSS
Descripiton: vDatetime is timezone aware and uses a timezone library.: When a vDatetime object is created from an ical string, you can pass a valid timezone identifier. When a vDatetime object is created from a python datetime object, it uses the tzinfo component, if present. Otherwise a timezone-naive object is created. Be aware that there are certain limitations with timezone naive DATE-TIME components in the icalendar standard.

Example 1: The following represents March 2, 2021 at 10:15 with local time:

>>> from icalendar import vDatetime
>>> datetime = vDatetime.from_ical("20210302T101500")
>>> datetime.tzname()
>>> datetime.year
2021
>>> datetime.minute
15

Example 2: The following represents March 2, 2021 at 10:15 in New York:

>>> datetime = vDatetime.from_ical("20210302T101500", 'America/New_York')
>>> datetime.tzname()
'EST'

Example 3: The following represents March 2, 2021 at 10:15 in Berlin:

>>> from zoneinfo import ZoneInfo
>>> timezone = ZoneInfo("Europe/Berlin")
>>> vDatetime.from_ical("20210302T101500", timezone)
datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='Europe/Berlin'))

static from_ical(ical, timezone=None)[source]#: Create a datetime from the RFC string.

params: Parameters#

to_ical()[source]#

class icalendar.vDuration(td: timedelta | str, /, params: dict[str, Any] | None = None)[source]#

Bases: TimeBase

Duration

Value Name:

DURATION

Purpose:

This value type is used to identify properties that contain a duration of time.

Format Definition:

This value type is defined by the following notation:

dur-value  = (["+"] / "-") "P" (dur-date / dur-time / dur-week)

dur-date   = dur-day [dur-time]
dur-time   = "T" (dur-hour / dur-minute / dur-second)
dur-week   = 1*DIGIT "W"
dur-hour   = 1*DIGIT "H" [dur-minute]
dur-minute = 1*DIGIT "M" [dur-second]
dur-second = 1*DIGIT "S"
dur-day    = 1*DIGIT "D"

Description:

If the property permits, multiple “duration” values are specified by a COMMA-separated list of values. The format is based on the [ISO.8601.2004] complete representation basic format with designators for the duration of time. The format can represent nominal durations (weeks and days) and accurate durations (hours, minutes, and seconds). Note that unlike [ISO.8601.2004], this value type doesn’t support the “Y” and “M” designators to specify durations in terms of years and months. The duration of a week or a day depends on its position in the calendar. In the case of discontinuities in the time scale, such as the change from standard time to daylight time and back, the computation of the exact duration requires the subtraction or addition of the change of duration of the discontinuity. Leap seconds MUST NOT be considered when computing an exact duration. When computing an exact duration, the greatest order time components MUST be added first, that is, the number of days MUST be added first, followed by the number of hours, number of minutes, and number of seconds.

Example

A duration of 15 days, 5 hours, and 20 seconds would be:

P15DT5H0M20S

A duration of 7 weeks would be:

P7W

>>> from icalendar.prop import vDuration
>>> duration = vDuration.from_ical('P15DT5H0M20S')
>>> duration
datetime.timedelta(days=15, seconds=18020)
>>> duration = vDuration.from_ical('P7W')
>>> duration
datetime.timedelta(days=49)

property dt: timedelta#: The time delta for compatibility.

static from_ical(ical)[source]#

params: Parameters#

to_ical()[source]#

class icalendar.vFloat(*args, params: dict[str, Any] | None = None, **kwargs)[source]#

Bases: float

Float

Value Name:

FLOAT

Purpose:

This value type is used to identify properties that contain a real-number value.

Format Definition:

This value type is defined by the following notation:

float      = (["+"] / "-") 1*DIGIT ["." 1*DIGIT]

Description:

If the property permits, multiple “float” values are specified by a COMMA-separated list of values.

Example:

1000000.0000001
1.333
-3.14

>>> from icalendar.prop import vFloat
>>> float = vFloat.from_ical('1000000.0000001')
>>> float
1000000.0000001
>>> float = vFloat.from_ical('1.333')
>>> float
1.333
>>> float = vFloat.from_ical('+1.333')
>>> float
1.333
>>> float = vFloat.from_ical('-3.14')
>>> float
-3.14

classmethod from_ical(ical)[source]#

params: Parameters#

to_ical()[source]#

class icalendar.vFrequency(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

A simple class that catches illegal values.

frequencies = {'DAILY': 'DAILY', 'HOURLY': 'HOURLY', 'MINUTELY': 'MINUTELY', 'MONTHLY': 'MONTHLY', 'SECONDLY': 'SECONDLY', 'WEEKLY': 'WEEKLY', 'YEARLY': 'YEARLY'}#

classmethod from_ical(ical)[source]#

params: Parameters#

to_ical()[source]#

Bases: object

Geographic Position

Property Name:

GEO

Purpose:

This property specifies information related to the global position for the activity specified by a calendar component.

Value Type:

FLOAT. The value MUST be two SEMICOLON-separated FLOAT values.

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in “VEVENT” or “VTODO” calendar components.

Description:

This property value specifies latitude and longitude, in that order (i.e., “LAT LON” ordering). The longitude represents the location east or west of the prime meridian as a positive or negative real number, respectively. The longitude and latitude values MAY be specified up to six decimal places, which will allow for accuracy to within one meter of geographical position. Receiving applications MUST accept values of this precision and MAY truncate values of greater precision.

Example:

GEO:37.386013;-122.082932

Parse vGeo:

>>> from icalendar.prop import vGeo
>>> geo = vGeo.from_ical('37.386013;-122.082932')
>>> geo
(37.386013, -122.082932)

Add a geo location to an event:

>>> from icalendar import Event
>>> event = Event()
>>> latitude = 37.386013
>>> longitude = -122.082932
>>> event.add('GEO', (latitude, longitude))
>>> event['GEO']
vGeo((37.386013, -122.082932))

static from_ical(ical)[source]#

params: Parameters#

Create a new vGeo from a tuple of (latitude, longitude).

Raises:: ValueError – if geo is not a tuple of (latitude, longitude)

to_ical()[source]#

class icalendar.vInt(*args, params: dict[str, Any] | None = None, **kwargs)[source]#

Bases: int

Integer

Value Name:

INTEGER

Purpose:

This value type is used to identify properties that contain a signed integer value.

Format Definition:

This value type is defined by the following notation:

integer    = (["+"] / "-") 1*DIGIT

Description:

If the property permits, multiple “integer” values are specified by a COMMA-separated list of values. The valid range for “integer” is -2147483648 to 2147483647. If the sign is not specified, then the value is assumed to be positive.

Example:

1234567890
-1234567890
+1234567890
432109876

>>> from icalendar.prop import vInt
>>> integer = vInt.from_ical('1234567890')
>>> integer
1234567890
>>> integer = vInt.from_ical('-1234567890')
>>> integer
-1234567890
>>> integer = vInt.from_ical('+1234567890')
>>> integer
1234567890
>>> integer = vInt.from_ical('432109876')
>>> integer
432109876

classmethod from_ical(ical: str | bytes)[source]#

params: Parameters#

to_ical() → bytes[source]#

class icalendar.vMonth(month: str | int, /, params: dict[str, Any] | None = None)[source]#

Bases: int

The number of the month for recurrence.

In RFC 5545, this is just an int. In RFC 7529, this can be followed by L to indicate a leap month.

>>> from icalendar import vMonth
>>> vMonth(1) # first month January
vMonth('1')
>>> vMonth("5L") # leap month in Hebrew calendar
vMonth('5L')
>>> vMonth(1).leap
False
>>> vMonth("5L").leap
True

Definition from RFC:

type-bymonth = element bymonth {
   xsd:positiveInteger |
   xsd:string
}

classmethod from_ical(ical: str)[source]#

property leap: bool#: Whether this is a leap month.

params: Parameters#

to_ical() → bytes[source]#: The ical representation.

class icalendar.vPeriod(per: tuple[datetime, datetime | timedelta])[source]#

Bases: TimeBase

Period of Time

Value Name:

PERIOD

Purpose:

This value type is used to identify values that contain a precise period of time.

Format Definition:

This value type is defined by the following notation:

 period     = period-explicit / period-start

period-explicit = date-time "/" date-time
; [ISO.8601.2004] complete representation basic format for a
; period of time consisting of a start and end.  The start MUST
; be before the end.

period-start = date-time "/" dur-value
; [ISO.8601.2004] complete representation basic format for a
; period of time consisting of a start and positive duration
; of time.

Description:

If the property permits, multiple “period” values are specified by a COMMA-separated list of values. There are two forms of a period of time. First, a period of time is identified by its start and its end. This format is based on the [ISO.8601.2004] complete representation, basic format for “DATE- TIME” start of the period, followed by a SOLIDUS character followed by the “DATE-TIME” of the end of the period. The start of the period MUST be before the end of the period. Second, a period of time can also be defined by a start and a positive duration of time. The format is based on the [ISO.8601.2004] complete representation, basic format for the “DATE-TIME” start of the period, followed by a SOLIDUS character, followed by the [ISO.8601.2004] basic format for “DURATION” of the period.

Example

The period starting at 18:00:00 UTC, on January 1, 1997 and ending at 07:00:00 UTC on January 2, 1997 would be:

19970101T180000Z/19970102T070000Z

The period start at 18:00:00 on January 1, 1997 and lasting 5 hours and 30 minutes would be:

19970101T180000Z/PT5H30M

>>> from icalendar.prop import vPeriod
>>> period = vPeriod.from_ical('19970101T180000Z/19970102T070000Z')
>>> period = vPeriod.from_ical('19970101T180000Z/PT5H30M')

property FBTYPE: FBTYPE | str#

Specify the free or busy time type.

Description:: This parameter specifies the free or busy time type. The value FREE indicates that the time interval is free for scheduling. The value BUSY indicates that the time interval is busy because one or more events have been scheduled for that interval. The value BUSY-UNAVAILABLE indicates that the time interval is busy and that the interval can not be scheduled. The value BUSY-TENTATIVE indicates that the time interval is busy because one or more events have been tentatively scheduled for that interval. If not specified on a property that allows this parameter, the default is BUSY. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the BUSY value.

property dt#: Make this cooperate with the other vDDDTypes.

static from_ical(ical, timezone=None)[source]#

overlaps(other)[source]#

params: Parameters#

to_ical()[source]#

class icalendar.vRecur(*args, params: dict[str, Any] | None = None, **kwargs)[source]#

Bases: CaselessDict

Recurrence definition.

Property Name:

RRULE

Purpose:

This property defines a rule or repeating pattern for recurring events, to-dos, journal entries, or time zone definitions.

Value Type:

RECUR

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

Description:

The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

Examples

The following RRULE specifies daily events for 10 occurrences.

RRULE:FREQ=DAILY;COUNT=10

Below, we parse the RRULE ical string.

>>> from icalendar.prop import vRecur
>>> rrule = vRecur.from_ical('FREQ=DAILY;COUNT=10')
>>> rrule
vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})

You can choose to add an rrule to an icalendar.cal.Event or icalendar.cal.Todo.

>>> from icalendar import Event
>>> event = Event()
>>> event.add('RRULE', 'FREQ=DAILY;COUNT=10')
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

canonical_order = ('RSCALE', 'FREQ', 'UNTIL', 'COUNT', 'INTERVAL', 'BYSECOND', 'BYMINUTE', 'BYHOUR', 'BYDAY', 'BYWEEKDAY', 'BYMONTHDAY', 'BYYEARDAY', 'BYWEEKNO', 'BYMONTH', 'BYSETPOS', 'WKST', 'SKIP')#

frequencies = ['SECONDLY', 'MINUTELY', 'HOURLY', 'DAILY', 'WEEKLY', 'MONTHLY', 'YEARLY']#

classmethod from_ical(ical: str)[source]#

params: Parameters#

classmethod parse_type(key, values)[source]#

to_ical()[source]#

types = {'BYDAY': <class 'icalendar.prop.vWeekday'>, 'BYHOUR': <class 'icalendar.prop.vInt'>, 'BYMINUTE': <class 'icalendar.prop.vInt'>, 'BYMONTH': <class 'icalendar.prop.vMonth'>, 'BYMONTHDAY': <class 'icalendar.prop.vInt'>, 'BYSECOND': <class 'icalendar.prop.vInt'>, 'BYSETPOS': <class 'icalendar.prop.vInt'>, 'BYWEEKDAY': <class 'icalendar.prop.vWeekday'>, 'BYWEEKNO': <class 'icalendar.prop.vInt'>, 'BYYEARDAY': <class 'icalendar.prop.vInt'>, 'COUNT': <class 'icalendar.prop.vInt'>, 'FREQ': <class 'icalendar.prop.vFrequency'>, 'INTERVAL': <class 'icalendar.prop.vInt'>, 'SKIP': <enum 'vSkip'>, 'UNTIL': <class 'icalendar.prop.vDDDTypes'>, 'WKST': <class 'icalendar.prop.vWeekday'>}#

class icalendar.vSkip(*values)[source]#

Bases: vText, Enum

Skip values for RRULE.

These are defined in RFC 7529.

OMIT is the default value.

Examples:

>>> from icalendar import vSkip
>>> vSkip.OMIT
vSkip('OMIT')
>>> vSkip.FORWARD
vSkip('FORWARD')
>>> vSkip.BACKWARD
vSkip('BACKWARD')

BACKWARD = vText(b'BACKWARD')#

FORWARD = vText(b'FORWARD')#

OMIT = vText(b'OMIT')#

encoding#

params: Parameters#

class icalendar.vText(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

Simple text.

property ALTREP: str | None#

ALTREP - Specify an alternate text representation for the property value.

Description:: This parameter specifies a URI that points to an alternate representation for a textual property value. A property specifying this parameter MUST also include a value that reflects the default representation of the text value. The URI parameter value MUST be specified in a quoted-string.

Note

While there is no restriction imposed on the URI schemes allowed for this parameter, Content Identifier (CID) RFC 2392, HTTP RFC 2616, and HTTPS RFC 2818 are the URI schemes most commonly used by current implementations.

property GAP: timedelta | None#

Purpose:: GAP pecifies the length of the gap, positive or negative, between two components with a temporal relationship.
Format Definition:: Same as the DURATION value type defined in RFC 5545, Section 3.3.6.
Description:: This parameter MAY be specified on the RELATED-TO property and defines the duration of time between the predecessor and successor in an interval. When positive, it defines the lag time between a task and its logical successor. When negative, it defines the lead time.

Examples

An example of lag time might be if Task-A is “paint the room” and Task-B is “lay the carpets”. Then, Task-A may be related to Task-B with RELTYPE=FINISHTOSTART with a gap of 1 day – long enough for the paint to dry.

====================
|  paint the room  |--+
====================  |
                      |(lag of one day)
                      |
                      |  ===================
                      +->| lay the carpet  |
                         ===================

For an example of lead time, in constructing a two-story building, the electrical work must be done before painting. However, the painter can move in to the first floor as the electricians move upstairs.

=====================
|  electrical work  |--+
=====================  |
         +-------------+
         |(lead of estimated time)
         |  ==================
         +->|    painting    |
            ==================

property LANGUAGE: str | None#

Specify the language for text values in a property or property parameter.

Description:

This parameter identifies the language of the text in the property value and of all property parameter values of the property. The value of the “LANGUAGE” property parameter is that defined in RFC 5646.

For transport in a MIME entity, the Content-Language header field can be used to set the default language for the entire body part. Otherwise, no default language is assumed.

property RELTYPE: RELTYPE#

Specify the type of hierarchical relationship associated with a component.

Conformance:: RFC 5545 introduces the RELTYPE property parameter. RFC 9253 adds new values.
Description:: This parameter can be specified on a property that references another related calendar. The parameter specifies the hierarchical relationship type of the calendar component referenced by the property. The parameter value can be PARENT, to indicate that the referenced calendar component is a superior of calendar component; CHILD to indicate that the referenced calendar component is a subordinate of the calendar component; or SIBLING to indicate that the referenced calendar component is a peer of the calendar component. If this parameter is not specified on an allowable property, the default relationship type is PARENT. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the PARENT value.

property VALUE: str | None#

VALUE explicitly specifies the value type format for a property value.

Conformance:

VALUE is specified in RFC 5545.

Description:

This parameter specifies the value type and format of the property value. The property values MUST be of a single value type. For example, a “RDATE” property cannot have a combination of DATE-TIME and TIME value types.

If the property’s value is the default value type, then this parameter need not be specified. However, if the property’s default value type is overridden by some other allowable value type, then this parameter MUST be specified.

Applications MUST preserve the value data for x-name and iana- token values that they don’t recognize without attempting to interpret or parse the value data.

encoding#

classmethod from_ical(ical: str | bytes)[source]#

property ical_value: str#: The string value of the text.

params: Parameters#

to_ical() → bytes[source]#

class icalendar.vTime(*args)[source]#

Bases: TimeBase

Time

Value Name:

TIME

Purpose:

This value type is used to identify values that contain a time of day.

Format Definition:

This value type is defined by the following notation:

time         = time-hour time-minute time-second [time-utc]

time-hour    = 2DIGIT        ;00-23
time-minute  = 2DIGIT        ;00-59
time-second  = 2DIGIT        ;00-60
;The "60" value is used to account for positive "leap" seconds.

time-utc     = "Z"

Description:

If the property permits, multiple “time” values are specified by a COMMA-separated list of values. No additional content value encoding (i.e., BACKSLASH character encoding, see vText) is defined for this value type.

The “TIME” value type is used to identify values that contain a time of day. The format is based on the [ISO.8601.2004] complete representation, basic format for a time of day. The text format consists of a two-digit, 24-hour of the day (i.e., values 00-23), two-digit minute in the hour (i.e., values 00-59), and two-digit seconds in the minute (i.e., values 00-60). The seconds value of 60 MUST only be used to account for positive “leap” seconds. Fractions of a second are not supported by this format.

In parallel to the “DATE-TIME” definition above, the “TIME” value type expresses time values in three forms:

The form of time with UTC offset MUST NOT be used. For example, the following is not valid for a time value:

230000-0800        ;Invalid time format

FORM #1 LOCAL TIME

The local time form is simply a time value that does not contain the UTC designator nor does it reference a time zone. For example, 11:00 PM:

Time values of this type are said to be “floating” and are not bound to any time zone in particular. They are used to represent the same hour, minute, and second value regardless of which time zone is currently being observed. For example, an event can be defined that indicates that an individual will be busy from 11:00 AM to 1:00 PM every day, no matter which time zone the person is in. In these cases, a local time can be specified. The recipient of an iCalendar object with a property value consisting of a local time, without any relative time zone information, SHOULD interpret the value as being fixed to whatever time zone the “ATTENDEE” is in at any given moment. This means that two “Attendees”, may participate in the same event at different UTC times; floating time SHOULD only be used where that is reasonable behavior.

In most cases, a fixed time is desired. To properly communicate a fixed time in a property value, either UTC time or local time with time zone reference MUST be specified.

The use of local time in a TIME value without the “TZID” property parameter is to be interpreted as floating time, regardless of the existence of “VTIMEZONE” calendar components in the iCalendar object.

FORM #2: UTC TIME

UTC time, or absolute time, is identified by a LATIN CAPITAL LETTER Z suffix character, the UTC designator, appended to the time value. For example, the following represents 07:00 AM UTC:

070000Z

The “TZID” property parameter MUST NOT be applied to TIME properties whose time values are specified in UTC.

FORM #3: LOCAL TIME AND TIME ZONE REFERENCE

The local time with reference to time zone information form is identified by the use the “TZID” property parameter to reference the appropriate time zone definition.

Example:: The following represents 8:30 AM in New York in winter, five hours behind UTC, in each of the three formats:

083000
133000Z
TZID=America/New_York:083000

static from_ical(ical)[source]#

to_ical()[source]#

class icalendar.vUTCOffset(td, /, params: dict[str, Any] | None = None)[source]#

Bases: object

UTC Offset

Value Name:

UTC-OFFSET

Purpose:

This value type is used to identify properties that contain an offset from UTC to local time.

Format Definition:

This value type is defined by the following notation:

utc-offset = time-numzone

time-numzone = ("+" / "-") time-hour time-minute [time-second]

Description:

The PLUS SIGN character MUST be specified for positive UTC offsets (i.e., ahead of UTC). The HYPHEN-MINUS character MUST be specified for negative UTC offsets (i.e., behind of UTC). The value of “-0000” and “-000000” are not allowed. The time-second, if present, MUST NOT be 60; if absent, it defaults to zero.

Example:: The following UTC offsets are given for standard time for New York (five hours behind UTC) and Geneva (one hour ahead of UTC):

-0500

+0100

>>> from icalendar.prop import vUTCOffset
>>> utc_offset = vUTCOffset.from_ical('-0500')
>>> utc_offset
datetime.timedelta(days=-1, seconds=68400)
>>> utc_offset = vUTCOffset.from_ical('+0100')
>>> utc_offset
datetime.timedelta(seconds=3600)

classmethod from_ical(ical)[source]#

ignore_exceptions = False#

params: Parameters#

to_ical()[source]#

class icalendar.vUid(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: vText

A UID of a component.

This is defined in RFC 9253, Section 7.

property FMTTYPE: str | None#

FMTTYPE specfies the content type of a referenced object.

Conformance:: RFC 5545 specifies the FMTTYPE. RFC 9253: adds FMTTYPE to LINK properties. In a LINK, FMTTYPE maps to the “type” attribute defined in Section 3.4.1 of RFC 8288. See RFC 6838.
Description:: This parameter can be specified on properties that are used to reference an object. The parameter specifies the media type RFC 4288 of the referenced object. For example, on the “ATTACH” property, an FTP type URI value does not, by itself, necessarily convey the type of content associated with the resource. The parameter value MUST be the text for either an IANA-registered media type or a non-standard media type.

Example

A Microsoft Word document:

ATTACH;FMTTYPE=application/msword:ftp://example.com/pub/docs/
 agenda.doc

A website:

LINK;FMTTYPE=text/html;LINKREL=SOURCE;LABEL=Venue;VALUE=URI:
 https://example.com/venue

property LABEL: str | None#

LABEL provides a human-readable label.

Conformance:

This property parameter is specified in RFC 7986, iCalendar Property Extensions.

RFC 9253 makes use of this for the LINK property: 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). The LABEL MUST NOT appear more than once in a given link; occurrences after the first MUST be ignored by parsers.

Description:

This property parameter MAY be specified on the “CONFERENCE” property. It is anticipated that other extensions to iCalendar will reuse this property parameter on new properties that they define. As a result, clients MUST expect to find this property parameter present on many different properties. It provides a human-readable label that can be presented to calendar users to allow them to discriminate between properties that might be similar or provide additional information for properties that are not self-describing. The “LANGUAGE” property parameter can be used to specify the language of the text in the parameter value (as per Section 3.2.10 of RFC 5545).

Examples

This is a label of a chat.

property LINKREL: str | None#

Purpose:

LINKREL specifies the relationship of data referenced by a LINK property.

Conformance:

LINKREL is specified in RFC 9253. This parameter maps to the link relation type defined in Section 2.1 of RFC 8288. It is always quoted.

Description:

This parameter MUST be specified on all LINK properties and define the type of reference. This allows programs consuming this data to automatically scan for references they support. There is no default relation type.Any link relation in the link registry established by RFC 8288, or new link relations, may be used. It is expected that link relation types seeing significant usage in calendaring will have the calendaring usage described in an RFC.

In the simplest case, a link relation type identifies the semantics of a link. For example, a link with the relation type “copyright” indicates that the current link context has a copyright resource at the link target.

Link relation types can also be used to indicate that the target resource has particular attributes, or exhibits particular behaviours; for example, a “service” link implies that the link target can be used as part of a defined protocol (in this case, a service description).

Registration:

There are two kinds of relation types: registered and extension. These relation types are registered in RFC 8288.

See also

Registered Link Relation Types.

Examples

This identifies the latest version of the event information.

LINKREL=latest-version

encoding#

property ical_value: str#: The uid of this property.

classmethod new()[source]#

Create a new UID for convenience.

>>> from icalendar import vUid
>>> vUid.new()
vUid('d755cef5-2311-46ed-a0e1-6733c9e15c63')

params: Parameters#

property uid: str#: The uid of this property.

class icalendar.vUri(value: str, encoding: str = 'utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

URI

Value Name:

URI

Purpose:

This value type is used to identify values that contain a uniform resource identifier (URI) type of reference to the property value.

Format Definition:

This value type is defined by the following notation:

uri = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

Description:

This value type might be used to reference binary information, for values that are large, or otherwise undesirable to include directly in the iCalendar object.

Property values with this value type MUST follow the generic URI syntax defined in [RFC3986].

When a property parameter value is a URI value type, the URI MUST be specified as a quoted-string value.

Examples

The following is a URI for a network file:

http://example.com/my-report.txt

>>> from icalendar.prop import vUri
>>> uri = vUri.from_ical('http://example.com/my-report.txt')
>>> uri
vUri('http://example.com/my-report.txt')
>>> uri.uri
'http://example.com/my-report.txt'

property FMTTYPE: str | None#

FMTTYPE specfies the content type of a referenced object.

Conformance:: RFC 5545 specifies the FMTTYPE. RFC 9253: adds FMTTYPE to LINK properties. In a LINK, FMTTYPE maps to the “type” attribute defined in Section 3.4.1 of RFC 8288. See RFC 6838.
Description:: This parameter can be specified on properties that are used to reference an object. The parameter specifies the media type RFC 4288 of the referenced object. For example, on the “ATTACH” property, an FTP type URI value does not, by itself, necessarily convey the type of content associated with the resource. The parameter value MUST be the text for either an IANA-registered media type or a non-standard media type.

Example

A Microsoft Word document:

ATTACH;FMTTYPE=application/msword:ftp://example.com/pub/docs/
 agenda.doc

A website:

LINK;FMTTYPE=text/html;LINKREL=SOURCE;LABEL=Venue;VALUE=URI:
 https://example.com/venue

property GAP: timedelta | None#

Purpose:: GAP pecifies the length of the gap, positive or negative, between two components with a temporal relationship.
Format Definition:: Same as the DURATION value type defined in RFC 5545, Section 3.3.6.
Description:: This parameter MAY be specified on the RELATED-TO property and defines the duration of time between the predecessor and successor in an interval. When positive, it defines the lag time between a task and its logical successor. When negative, it defines the lead time.

Examples

An example of lag time might be if Task-A is “paint the room” and Task-B is “lay the carpets”. Then, Task-A may be related to Task-B with RELTYPE=FINISHTOSTART with a gap of 1 day – long enough for the paint to dry.

====================
|  paint the room  |--+
====================  |
                      |(lag of one day)
                      |
                      |  ===================
                      +->| lay the carpet  |
                         ===================

For an example of lead time, in constructing a two-story building, the electrical work must be done before painting. However, the painter can move in to the first floor as the electricians move upstairs.

=====================
|  electrical work  |--+
=====================  |
         +-------------+
         |(lead of estimated time)
         |  ==================
         +->|    painting    |
            ==================

property LABEL: str | None#

LABEL provides a human-readable label.

Conformance:

This property parameter is specified in RFC 7986, iCalendar Property Extensions.

RFC 9253 makes use of this for the LINK property: 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). The LABEL MUST NOT appear more than once in a given link; occurrences after the first MUST be ignored by parsers.

Description:

This property parameter MAY be specified on the “CONFERENCE” property. It is anticipated that other extensions to iCalendar will reuse this property parameter on new properties that they define. As a result, clients MUST expect to find this property parameter present on many different properties. It provides a human-readable label that can be presented to calendar users to allow them to discriminate between properties that might be similar or provide additional information for properties that are not self-describing. The “LANGUAGE” property parameter can be used to specify the language of the text in the parameter value (as per Section 3.2.10 of RFC 5545).

Examples

This is a label of a chat.

property LANGUAGE: str | None#

Specify the language for text values in a property or property parameter.

Description:

This parameter identifies the language of the text in the property value and of all property parameter values of the property. The value of the “LANGUAGE” property parameter is that defined in RFC 5646.

For transport in a MIME entity, the Content-Language header field can be used to set the default language for the entire body part. Otherwise, no default language is assumed.

property LINKREL: str | None#

Purpose:

LINKREL specifies the relationship of data referenced by a LINK property.

Conformance:

LINKREL is specified in RFC 9253. This parameter maps to the link relation type defined in Section 2.1 of RFC 8288. It is always quoted.

Description:

This parameter MUST be specified on all LINK properties and define the type of reference. This allows programs consuming this data to automatically scan for references they support. There is no default relation type.Any link relation in the link registry established by RFC 8288, or new link relations, may be used. It is expected that link relation types seeing significant usage in calendaring will have the calendaring usage described in an RFC.

In the simplest case, a link relation type identifies the semantics of a link. For example, a link with the relation type “copyright” indicates that the current link context has a copyright resource at the link target.

Link relation types can also be used to indicate that the target resource has particular attributes, or exhibits particular behaviours; for example, a “service” link implies that the link target can be used as part of a defined protocol (in this case, a service description).

Registration:

There are two kinds of relation types: registered and extension. These relation types are registered in RFC 8288.

See also

Registered Link Relation Types.

Examples

This identifies the latest version of the event information.

LINKREL=latest-version

property RELTYPE: RELTYPE#

Specify the type of hierarchical relationship associated with a component.

Conformance:: RFC 5545 introduces the RELTYPE property parameter. RFC 9253 adds new values.
Description:: This parameter can be specified on a property that references another related calendar. The parameter specifies the hierarchical relationship type of the calendar component referenced by the property. The parameter value can be PARENT, to indicate that the referenced calendar component is a superior of calendar component; CHILD to indicate that the referenced calendar component is a subordinate of the calendar component; or SIBLING to indicate that the referenced calendar component is a peer of the calendar component. If this parameter is not specified on an allowable property, the default relationship type is PARENT. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the PARENT value.

property VALUE: str | None#

VALUE explicitly specifies the value type format for a property value.

Conformance:

VALUE is specified in RFC 5545.

Description:

This parameter specifies the value type and format of the property value. The property values MUST be of a single value type. For example, a “RDATE” property cannot have a combination of DATE-TIME and TIME value types.

If the property’s value is the default value type, then this parameter need not be specified. However, if the property’s default value type is overridden by some other allowable value type, then this parameter MUST be specified.

Applications MUST preserve the value data for x-name and iana- token values that they don’t recognize without attempting to interpret or parse the value data.

classmethod from_ical(ical)[source]#

property ical_value: str#: The URI.

params: Parameters#

to_ical()[source]#

property uri: str#: The URI.

class icalendar.vWeekday(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

Either a weekday or a weekdaynum

>>> from icalendar import vWeekday
>>> vWeekday("MO") # Simple weekday
'MO'
>>> vWeekday("2FR").relative # Second friday
2
>>> vWeekday("2FR").weekday
'FR'
>>> vWeekday("-1SU").relative # Last Sunday
-1

Definition from RFC 5545, Section 3.3.10:

weekdaynum = [[plus / minus] ordwk] weekday
plus        = "+"
minus       = "-"
ordwk       = 1*2DIGIT       ;1 to 53
weekday     = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"
;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,
;FRIDAY, and SATURDAY days of the week.

classmethod from_ical(ical)[source]#

params: Parameters#

relative#

to_ical()[source]#

week_days = {'FR': 5, 'MO': 1, 'SA': 6, 'SU': 0, 'TH': 4, 'TU': 2, 'WE': 3}#

weekday#

class icalendar.vXmlReference(value: str, encoding: str = 'utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: vUri

An XML-REFERENCE.

The associated value references an associated XML artifact and is a URI with an XPointer anchor value.

This is defined in RFC 9253, Section 7.

params: Parameters#

property x_pointer: str#

The XPointer of the URI.

The XPointer is defined in W3C.WD-xptr-xpointer-20021219, and its use as an anchor is defined in W3C.REC-xptr-framework-20030325.

property xml_reference: str#: The uid of this property.

icalendar package#

Subpackages#

Submodules#

This Page