icalendar.cal.event module#

RFC 5545 VEVENT component.

class icalendar.cal.event.Event(*args, **kwargs)[source]#

Bases: Component

A grouping of component properties that describe an event.

Description:

A “VEVENT” calendar component is a grouping of component properties, possibly including “VALARM” calendar components, that represents a scheduled amount of time on a calendar. For example, it can be an activity; such as a one-hour long, department meeting from 8:00 AM to 9:00 AM, tomorrow. Generally, an event will take up time on an individual calendar. Hence, the event will appear as an opaque interval in a search for busy time. Alternately, the event can have its Time Transparency set to “TRANSPARENT” in order to prevent blocking of the event in searches for busy time.

The “VEVENT” is also the calendar component used to specify an anniversary or daily reminder within a calendar. These events have a DATE value type for the “DTSTART” property instead of the default value type of DATE-TIME. If such a “VEVENT” has a “DTEND” property, it MUST be specified as a DATE value also. The anniversary type of “VEVENT” can span more than one date (i.e., “DTEND” property value is set to a calendar date after the “DTSTART” property value). If such a “VEVENT” has a “DURATION” property, it MUST be specified as a “dur-day” or “dur-week” value.

The “DTSTART” property for a “VEVENT” specifies the inclusive start of the event. For recurring events, it also specifies the very first instance in the recurrence set. The “DTEND” property for a “VEVENT” calendar component specifies the non-inclusive end of the event. For cases where a “VEVENT” calendar component specifies a “DTSTART” property with a DATE value type but no “DTEND” nor “DURATION” property, the event’s duration is taken to be one day. For cases where a “VEVENT” calendar component specifies a “DTSTART” property with a DATE-TIME value type but no “DTEND” property, the event ends on the same calendar date and time of day specified by the “DTSTART” property.

The “VEVENT” calendar component cannot be nested within another calendar component. However, “VEVENT” calendar components can be related to each other or to a “VTODO” or to a “VJOURNAL” calendar component with the “RELATED-TO” property.

Examples

The following is an example of the “VEVENT” calendar component used to represent a meeting that will also be opaque to searches for busy time:

BEGIN:VEVENT
UID:19970901T130000Z-123401@example.com
DTSTAMP:19970901T130000Z
DTSTART:19970903T163000Z
DTEND:19970903T190000Z
SUMMARY:Annual Employee Review
CLASS:PRIVATE
CATEGORIES:BUSINESS,HUMAN RESOURCES
END:VEVENT

The following is an example of the “VEVENT” calendar component used to represent a reminder that will not be opaque, but rather transparent, to searches for busy time:

BEGIN:VEVENT
UID:19970901T130000Z-123402@example.com
DTSTAMP:19970901T130000Z
DTSTART:19970401T163000Z
DTEND:19970402T010000Z
SUMMARY:Laurel is in sensitivity awareness class.
CLASS:PUBLIC
CATEGORIES:BUSINESS,HUMAN RESOURCES
TRANSP:TRANSPARENT
END:VEVENT

The following is an example of the “VEVENT” calendar component used to represent an anniversary that will occur annually:

BEGIN:VEVENT
UID:19970901T130000Z-123403@example.com
DTSTAMP:19970901T130000Z
DTSTART;VALUE=DATE:19971102
SUMMARY:Our Blissful Anniversary
TRANSP:TRANSPARENT
CLASS:CONFIDENTIAL
CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION
RRULE:FREQ=YEARLY
END:VEVENT

The following is an example of the “VEVENT” calendar component used to represent a multi-day event scheduled from June 28th, 2007 to July 8th, 2007 inclusively. Note that the “DTEND” property is set to July 9th, 2007, since the “DTEND” property specifies the non-inclusive end of the event.

BEGIN:VEVENT
UID:20070423T123432Z-541111@example.com
DTSTAMP:20070423T123432Z
DTSTART;VALUE=DATE:20070628
DTEND;VALUE=DATE:20070709
SUMMARY:Festival International de Jazz de Montreal
TRANSP:TRANSPARENT
END:VEVENT

Create a new Event:

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event.new(start=datetime(2021, 1, 1, 12, 30, 0))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART:20210101T123000
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VEVENT

property DTEND: date | None#

The DTEND property.

The “DTEND” property for a “VEVENT” calendar component specifies the non-inclusive end of the event.

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 DTSTART: date | None#

The DTSTART property.

The “DTSTART” property for a “VEVENT” specifies the inclusive start of the event.

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 “VEVENT” specifies the inclusive start of the VEVENT. The “DURATION” property in conjunction with the DTSTART property for a “VEVENT” calendar component specifies the non-inclusive end of the event.

If you would like to calculate the duration of a VEVENT, 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 icalendar import Event
>>> event = Event.example("rfc_9074_example_1")
>>> len(event.alarms.times)
1
>>> alarm_time = event.alarms.times[0]
>>> alarm_time.trigger  # The time when the alarm pops up
datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='America/New_York'))
>>> alarm_time.is_active()  # This alarm has not been acknowledged
True

Note that this only uses DTSTART and DTEND, 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

canonical_order = ('SUMMARY', 'DTSTART', 'DTEND', 'DURATION', 'DTSTAMP', 'UID', 'RECURRENCE-ID', 'SEQUENCE', 'RRULE', 'RDATE', 'EXDATE')#

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.

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:t
 el:+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.
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.
location – The location of the event.
organizer – The organizer of the event.
priority – The priority 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.

subcomponents: list[Component]#

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

icalendar.cal.event module#

This Page