icalendar.cal.timezone module

RFC 5545 components for timezone information.

class icalendar.cal.timezone.Timezone(*args, **kwargs)

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.

Set keys to upper for initial dict.

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.

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

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

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, value, parameters=None, encode=True)

Add a property.

Parameters:

• name (string) – Name of the property.

• value (Python native type or icalendar property type.) – Value of the property. Either of a basic Python type of any of the icalendar's own property types.

• parameters (Dictionary) – Property parameter dictionary for the value. Only available, if encode is set to True.

• encode (Boolean) – True, if the value should be encoded to one of icalendar's own property types (Fallback is "vText") or False, if not.

Returns:

None

add_component(component)

Add a subcomponent to this component.

canonical_order = ('TZID',)

clear()

Remove all items from ordered dict.

property comments: list[str]

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

Purpose:

This property specifies non-processing information intended to provide a comment to the calendar user.

Conformance:

In RFC 5545, this property can be specified multiple times in "VEVENT", "VTODO", "VJOURNAL", and "VFREEBUSY" calendar components as well as in the "STANDARD" and "DAYLIGHT" sub-components. In RFC 7953, this property can be specified multiple times in "VAVAILABILITY" and "VAVAILABLE".

Property Parameters:

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

property concepts: list[vUri]

CONCEPT

Purpose:

CONCEPT defines the formal categories for a calendar component.

Conformance:

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

Description:

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

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

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

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

Examples

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

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

See also

Component.categories

content_line(name, value, sorted=True)

Returns property as content line.

content_lines(sorted=True)

Converts the Component and subcomponents into content lines.

copy(recursive=False)

Copy the component.

Parameters:

recursive (bool) – If True, this creates copies of the component, its subcomponents, and all its properties. If False, this only creates a shallow copy of the component.

Return type:

None

Returns:

A copy of the component.

Examples

Create a shallow copy of a component:

>>> from icalendar import Event
>>> event = Event.new(description="Event to be copied")
>>> event_copy = event.copy()
>>> str(event_copy.description)
'Event to be copied'

Shallow copies lose their subcomponents:

>>> from icalendar import Calendar
>>> calendar = Calendar.example()
>>> len(calendar.subcomponents)
3
>>> calendar_copy = calendar.copy()
>>> len(calendar_copy.subcomponents)
0

A recursive copy also copies all the subcomponents:

>>> full_calendar_copy = calendar.copy(recursive=True)
>>> len(full_calendar_copy.subcomponents)
3
>>> full_calendar_copy.events[0] == calendar.events[0]
True
>>> full_calendar_copy.events[0] is calendar.events[0]
False

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.

property daylight: list[TimezoneDaylight]

The DAYLIGHT subcomponents as a list.

These are for the daylight saving time.

decoded(name, default=[])

Returns decoded value of property.

A component maps keys to icalendar property value types. This function returns values compatible to native Python types.

Return type:

Any

classmethod example(name='pacific_fiji')

Return the timezone example with the given name.

Return type:

Calendar

exclusive: ClassVar[tuple[()]] = ()

These properties are mutually exclusive.

classmethod from_ical(st, multiple=False)

Parse iCalendar data into component instances.

Handles standard and custom components (X-*, IANA-registered).

Parameters:

• st (str | bytes) – iCalendar data as bytes or string

• multiple (bool) – If True, returns list. If False, returns single component.

Return type:

Component | list[Component]

Returns:

Component or list of components

See also

Custom components for examples of parsing custom components

classmethod from_jcal(jcal)

Create a component from a jCal list.

Parameters:

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

Raises:

• JCalParsingError – If the jCal provided is invalid.

• JSONDecodeError – If the provided string is not valid JSON.

Return type:

Component

This reverses to_json() and to_jcal().

The following code parses an example from RFC 7265:

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

classmethod from_tzid(tzid, tzp=TZP('zoneinfo'), first_date=datetime.date(1970, 1, 1), last_date=datetime.date(2038, 1, 1))

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

Parameters:

• tzid (str) – the id of the timezone

• tzp (TZP) – the timezone provider

• first_date (date) – a datetime that is earlier than anything that happens in the calendar

• last_date (date) – a datetime that is later than anything that happens in the calendar

Raises:

ValueError – If the tzid is unknown.

Return type:

Timezone

>>> 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, tzid=None, first_date=datetime.date(1970, 1, 1), last_date=datetime.date(2038, 1, 1))

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 (str | None) – the tzid for this timezone. If None, it will be extracted from the tzinfo.

• first_date (date) – a datetime that is earlier than anything that happens in the calendar

• last_date (date) – a datetime that is later than anything that happens in the calendar

Raises:

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

Return type:

Timezone

Note

This can take some time. Please cache the results.

classmethod fromkeys(iterable, value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None)

Get property value with default.

classmethod get_component_class(name)

Return a component with this name.

Parameters:

name (str) – Name of the component, i.e. VCALENDAR

Return type:

type[Component]

get_inline(name, decode=1)

Returns a list of values (split on comma).

get_transitions()

Return a tuple of (transition_times, transition_info)

• transition_times = [datetime, …]

• transition_info = [(TZOFFSETTO, dts_offset, tzname)]

Return type:

tuple[list[datetime], list[tuple[timedelta, timedelta, str]]]

ignore_exceptions: ClassVar[bool] = False

Whether or not to ignore exceptions when parsing.

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

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

These properties are inclusive.

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

Example

('duration', 'repeat')

is_empty()

Returns True if Component has no items or subcomponents, else False.

is_thunderbird()

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

Return type:

bool

items()

Return a set-like object providing a view on the dict's items.

keys()

Return a set-like object providing a view on the dict's keys.

property last_modified: datetime

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

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

property links: list[vUri | vUid | vXmlReference]

LINK properties as a list.

Purpose:

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

Property Parameters:

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

Conformance:

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

Description:

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

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

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

LABEL

This parameter maps to the "title" attribute defined in Section 3.4.1 of RFC 8288. LABEL is used to label the destination of a link such that it can be used as a human-readable identifier (e.g., a menu entry) in the language indicated by the LANGUAGE (if present).

LANGUAGE

This parameter maps to the "hreflang" attribute defined in Section 3.4.1 of RFC 8288. See RFC 5646. Example: en, de-ch.

LINKREL

This parameter maps to the link relation type defined in Section 2.1 of RFC 8288. See Registered Link Relation Types.

FMTTYPE

This parameter maps to the "type" attribute defined in Section 3.4.1 of RFC 8288.

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

Examples

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

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

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

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

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

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

Set a link icalendar.vUri to the event page:

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

move_to_end(key, last=True)

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

Raise KeyError if the element does not exist.

multiple: ClassVar[tuple[()]] = ()

These properties may occur more than once.

name: ClassVar[str | None] = 'VTIMEZONE'

The name of the component.

This should be defined in each component class.

Example: VCALENDAR.

classmethod new(created=None, comments=None, concepts=None, last_modified=None, links=None, refids=None, related_to=None, stamp=None)

Create a new component.

Parameters:

• comments (list[str] | str | None) – The comments of the component.

• concepts (list[vUri | str] | str | vUri | None) – The concepts of the component.

• created (date | None) – The created of the component.

• last_modified (date | None) – The last_modified of the component.

• links (str | vUri | vUid | vXmlReference | None | list[str | vUri | vUid | vXmlReference]) – The links of the component.

• related_to (None | str | vText | vUri | vUid | list[str | vText | vUri | vUid]) – The related_to of the component.

• stamp (date | None) – The DTSTAMP of the component.

Raises:

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

Return type:

Component

Warning

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

property_items(recursive=True, sorted=True)

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

Return type:

list[tuple[str, object]]

property refids: list[str]

REFID

Purpose:

REFID acts as a key for associated iCalendar entities.

Conformance:

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

Description:

The value of this property is free-form text that creates an identifier for associated components. All components that use the same REFID value are associated through that value and can be located or retrieved as a group. For example, all of the events in a travel itinerary would have the same REFID value, so as to be grouped together.

Examples

The following is an example of this property.

REFID:itinerary-2014-11-17

Use a REFID to associate several VTODOs:

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

Note

List modifications do not modify the component.

classmethod register(component_class)

Register a custom component class.

Parameters:

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

Raises:

• ValueError – If component_class has no name attribute.

• ValueError – If a component with this name is already registered.

Return type:

None

Examples

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

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

property related_to: list[vText | vUri | vUid]

RELATED-TO properties as a list.

Purpose:

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

Value Type:

RFC 5545: TEXT RFC 9253: URI, UID

Conformance:

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

Description (RFC 5545):

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

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

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

Description (RFC 9253):

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

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

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

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

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

The FIRST and NEXT define ordering relationships between calendar components.

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

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

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

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

Examples

RFC 5545 examples of this property:

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

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

RFC 9253 examples of this property:

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

See also icalendar.enum.RELTYPE.

required: ClassVar[tuple[()]] = ('TZID',)

These properties are required.

set_inline(name, values, encode=1)

Converts a list of values into comma separated string and sets value to that.

singletons: ClassVar[tuple[()]] = ('TZID', 'LAST-MODIFIED', 'TZURL')

These properties must appear only once.

property stamp: 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 standard: list[TimezoneStandard]

The STANDARD subcomponents as a list.

subcomponents: list[TimezoneStandard | TimezoneDaylight]

All subcomponents of this component.

to_ical(sorted=True)

Parameters:

sorted (bool) – Whether parameters and properties should be lexicographically sorted.

to_jcal()

Convert this component to a jCal object.

Return type:

list

Returns:

jCal object

See also to_json.

In this example, we create a simple VEVENT component and convert it to jCal:

>>> from icalendar import Event
>>> from datetime import date
>>> from pprint import pprint
>>> event = Event.new(summary="My Event", start=date(2025, 11, 22))
>>> pprint(event.to_jcal())
['vevent',
 [['dtstamp', {}, 'date-time', '2025-05-17T08:06:12Z'],
  ['summary', {}, 'text', 'My Event'],
  ['uid', {}, 'text', 'd755cef5-2311-46ed-a0e1-6733c9e15c63'],
  ['dtstart', {}, 'date', '2025-11-22']],
 []]

to_json()

Return this component as a jCal JSON string.

Return type:

str

Returns:

JSON string

See also to_jcal.

to_tz(tzp=TZP('zoneinfo'), lookup_tzid=True)

convert this VTIMEZONE component to a timezone object

Parameters:

• tzp (TZP) – timezone provider to use

• lookup_tzid (bool) – 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.

types_factory: ClassVar[TypesFactory] = {'ADR': <class 'icalendar.prop.adr.vAdr'>, 'BINARY': <class 'icalendar.prop.binary.vBinary'>, 'BOOLEAN': <class 'icalendar.prop.boolean.vBoolean'>, 'CAL-ADDRESS': <class 'icalendar.prop.cal_address.vCalAddress'>, 'CATEGORIES': <class 'icalendar.prop.categories.vCategory'>, 'DATE': <class 'icalendar.prop.dt.types.vDDDTypes'>, 'DATE-TIME': <class 'icalendar.prop.dt.types.vDDDTypes'>, 'DATE-TIME-LIST': <class 'icalendar.prop.dt.list.vDDDLists'>, 'DURATION': <class 'icalendar.prop.dt.types.vDDDTypes'>, 'FLOAT': <class 'icalendar.prop.float.vFloat'>, 'GEO': <class 'icalendar.prop.geo.vGeo'>, 'INLINE': <class 'icalendar.prop.inline.vInline'>, 'INTEGER': <class 'icalendar.prop.integer.vInt'>, 'N': <class 'icalendar.prop.n.vN'>, 'ORG': <class 'icalendar.prop.org.vOrg'>, 'PERIOD': <class 'icalendar.prop.dt.period.vPeriod'>, 'RECUR': <class 'icalendar.prop.recur.recur.vRecur'>, 'TEXT': <class 'icalendar.prop.text.vText'>, 'TIME': <class 'icalendar.prop.dt.time.vTime'>, 'UID': <class 'icalendar.prop.uid.vUid'>, 'UNKNOWN': <class 'icalendar.prop.unknown.vUnknown'>, 'URI': <class 'icalendar.prop.uri.vUri'>, 'UTC-OFFSET': <class 'icalendar.prop.dt.utc_offset.vUTCOffset'>, 'XML-REFERENCE': <class 'icalendar.prop.xml_reference.vXmlReference'>}

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.

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

values()

Return an object providing a view on the dict's values.

walk(name=None, select=<function Component.<lambda>>)

Recursively traverses component and subcomponents. Returns sequence of same. If name is passed, only components with name will be returned.

Parameters:

• name – The name of the component or None such as VEVENT.

• select – A function that takes the component as first argument and returns True/False.

Returns:

A list of components that match.

Return type:

list[Component]

with_uid(uid)

Return a list of components with the given UID.

Parameters:

uid (str) – The UID of the component.

Returns:

List of components with the given UID.

Return type:

list[Component]

class icalendar.cal.timezone.TimezoneDaylight(*args, **kwargs)

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.

Set keys to upper for initial dict.

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 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 LAST_MODIFIED: datetime | None

The LAST-MODIFIED property. datetime in UTC

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

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

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

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

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

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

Add a property.

Parameters:

• name (string) – Name of the property.

• value (Python native type or icalendar property type.) – Value of the property. Either of a basic Python type of any of the icalendar's own property types.

• parameters (Dictionary) – Property parameter dictionary for the value. Only available, if encode is set to True.

• encode (Boolean) – True, if the value should be encoded to one of icalendar's own property types (Fallback is "vText") or False, if not.

Returns:

None

add_component(component)

Add a subcomponent to this component.

clear()

Remove all items from ordered dict.

property comments: list[str]

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

Purpose:

This property specifies non-processing information intended to provide a comment to the calendar user.

Conformance:

In RFC 5545, this property can be specified multiple times in "VEVENT", "VTODO", "VJOURNAL", and "VFREEBUSY" calendar components as well as in the "STANDARD" and "DAYLIGHT" sub-components. In RFC 7953, this property can be specified multiple times in "VAVAILABILITY" and "VAVAILABLE".

Property Parameters:

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

property concepts: list[vUri]

CONCEPT

Purpose:

CONCEPT defines the formal categories for a calendar component.

Conformance:

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

Description:

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

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

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

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

Examples

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

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

See also

Component.categories

content_line(name, value, sorted=True)

Returns property as content line.

content_lines(sorted=True)

Converts the Component and subcomponents into content lines.

copy(recursive=False)

Copy the component.

Parameters:

recursive (bool) – If True, this creates copies of the component, its subcomponents, and all its properties. If False, this only creates a shallow copy of the component.

Return type:

None

Returns:

A copy of the component.

Examples

Create a shallow copy of a component:

>>> from icalendar import Event
>>> event = Event.new(description="Event to be copied")
>>> event_copy = event.copy()
>>> str(event_copy.description)
'Event to be copied'

Shallow copies lose their subcomponents:

>>> from icalendar import Calendar
>>> calendar = Calendar.example()
>>> len(calendar.subcomponents)
3
>>> calendar_copy = calendar.copy()
>>> len(calendar_copy.subcomponents)
0

A recursive copy also copies all the subcomponents:

>>> full_calendar_copy = calendar.copy(recursive=True)
>>> len(full_calendar_copy.subcomponents)
3
>>> full_calendar_copy.events[0] == calendar.events[0]
True
>>> full_calendar_copy.events[0] is calendar.events[0]
False

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=[])

Returns decoded value of property.

A component maps keys to icalendar property value types. This function returns values compatible to native Python types.

Return type:

Any

exclusive: ClassVar[tuple[()]] = ()

These properties are mutually exclusive.

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.

classmethod from_ical(st, multiple=False)

Parse iCalendar data into component instances.

Handles standard and custom components (X-*, IANA-registered).

Parameters:

• st (str | bytes) – iCalendar data as bytes or string

• multiple (bool) – If True, returns list. If False, returns single component.

Return type:

Component | list[Component]

Returns:

Component or list of components

See also

Custom components for examples of parsing custom components

classmethod from_jcal(jcal)

Create a component from a jCal list.

Parameters:

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

Raises:

• JCalParsingError – If the jCal provided is invalid.

• JSONDecodeError – If the provided string is not valid JSON.

Return type:

Component

This reverses to_json() and to_jcal().

The following code parses an example from RFC 7265:

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

classmethod fromkeys(iterable, value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None)

Get property value with default.

classmethod get_component_class(name)

Return a component with this name.

Parameters:

name (str) – Name of the component, i.e. VCALENDAR

Return type:

type[Component]

get_inline(name, decode=1)

Returns a list of values (split on comma).

ignore_exceptions: ClassVar[bool] = False

Whether or not to ignore exceptions when parsing.

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

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

These properties are inclusive.

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

Example

('duration', 'repeat')

is_empty()

Returns True if Component has no items or subcomponents, else False.

is_thunderbird()

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

Return type:

bool

items()

Return a set-like object providing a view on the dict's items.

keys()

Return a set-like object providing a view on the dict's keys.

property last_modified: datetime

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

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

property links: list[vUri | vUid | vXmlReference]

LINK properties as a list.

Purpose:

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

Property Parameters:

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

Conformance:

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

Description:

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

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

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

LABEL

This parameter maps to the "title" attribute defined in Section 3.4.1 of RFC 8288. LABEL is used to label the destination of a link such that it can be used as a human-readable identifier (e.g., a menu entry) in the language indicated by the LANGUAGE (if present).

LANGUAGE

This parameter maps to the "hreflang" attribute defined in Section 3.4.1 of RFC 8288. See RFC 5646. Example: en, de-ch.

LINKREL

This parameter maps to the link relation type defined in Section 2.1 of RFC 8288. See Registered Link Relation Types.

FMTTYPE

This parameter maps to the "type" attribute defined in Section 3.4.1 of RFC 8288.

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

Examples

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

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

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

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

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

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

Set a link icalendar.vUri to the event page:

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

move_to_end(key, last=True)

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

Raise KeyError if the element does not exist.

multiple: ClassVar[tuple[()]] = ('COMMENT', 'RDATE', 'TZNAME', 'RRULE', 'EXDATE')

These properties may occur more than once.

name: ClassVar[str | None] = 'DAYLIGHT'

The name of the component.

This should be defined in each component class.

Example: VCALENDAR.

classmethod new(created=None, comments=None, concepts=None, last_modified=None, links=None, refids=None, related_to=None, stamp=None)

Create a new component.

Parameters:

• comments (list[str] | str | None) – The comments of the component.

• concepts (list[vUri | str] | str | vUri | None) – The concepts of the component.

• created (date | None) – The created of the component.

• last_modified (date | None) – The last_modified of the component.

• links (str | vUri | vUid | vXmlReference | None | list[str | vUri | vUid | vXmlReference]) – The links of the component.

• related_to (None | str | vText | vUri | vUid | list[str | vText | vUri | vUid]) – The related_to of the component.

• stamp (date | None) – The DTSTAMP of the component.

Raises:

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

Return type:

Component

Warning

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

property_items(recursive=True, sorted=True)

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

Return type:

list[tuple[str, object]]

property 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 refids: list[str]

REFID

Purpose:

REFID acts as a key for associated iCalendar entities.

Conformance:

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

Description:

The value of this property is free-form text that creates an identifier for associated components. All components that use the same REFID value are associated through that value and can be located or retrieved as a group. For example, all of the events in a travel itinerary would have the same REFID value, so as to be grouped together.

Examples

The following is an example of this property.

REFID:itinerary-2014-11-17

Use a REFID to associate several VTODOs:

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

Note

List modifications do not modify the component.

classmethod register(component_class)

Register a custom component class.

Parameters:

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

Raises:

• ValueError – If component_class has no name attribute.

• ValueError – If a component with this name is already registered.

Return type:

None

Examples

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

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

property related_to: list[vText | vUri | vUid]

RELATED-TO properties as a list.

Purpose:

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

Value Type:

RFC 5545: TEXT RFC 9253: URI, UID

Conformance:

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

Description (RFC 5545):

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

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

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

Description (RFC 9253):

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

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

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

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

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

The FIRST and NEXT define ordering relationships between calendar components.

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

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

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

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

Examples

RFC 5545 examples of this property:

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

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

RFC 9253 examples of this property:

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

See also icalendar.enum.RELTYPE.

required: ClassVar[tuple[()]] = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')

These properties are required.

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.

set_inline(name, values, encode=1)

Converts a list of values into comma separated string and sets value to that.

singletons: ClassVar[tuple[()]] = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')

These properties must appear only once.

property stamp: 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.

subcomponents: list[Component]

All subcomponents of this component.

to_ical(sorted=True)

Parameters:

sorted (bool) – Whether parameters and properties should be lexicographically sorted.

to_jcal()

Convert this component to a jCal object.

Return type:

list

Returns:

jCal object

See also to_json.

In this example, we create a simple VEVENT component and convert it to jCal:

>>> from icalendar import Event
>>> from datetime import date
>>> from pprint import pprint
>>> event = Event.new(summary="My Event", start=date(2025, 11, 22))
>>> pprint(event.to_jcal())
['vevent',
 [['dtstamp', {}, 'date-time', '2025-05-17T08:06:12Z'],
  ['summary', {}, 'text', 'My Event'],
  ['uid', {}, 'text', 'd755cef5-2311-46ed-a0e1-6733c9e15c63'],
  ['dtstart', {}, 'date', '2025-11-22']],
 []]

to_json()

Return this component as a jCal JSON string.

Return type:

str

Returns:

JSON string

See also to_jcal.

types_factory: ClassVar[TypesFactory] = {'ADR': <class 'icalendar.prop.adr.vAdr'>, 'BINARY': <class 'icalendar.prop.binary.vBinary'>, 'BOOLEAN': <class 'icalendar.prop.boolean.vBoolean'>, 'CAL-ADDRESS': <class 'icalendar.prop.cal_address.vCalAddress'>, 'CATEGORIES': <class 'icalendar.prop.categories.vCategory'>, 'DATE': <class 'icalendar.prop.dt.types.vDDDTypes'>, 'DATE-TIME': <class 'icalendar.prop.dt.types.vDDDTypes'>, 'DATE-TIME-LIST': <class 'icalendar.prop.dt.list.vDDDLists'>, 'DURATION': <class 'icalendar.prop.dt.types.vDDDTypes'>, 'FLOAT': <class 'icalendar.prop.float.vFloat'>, 'GEO': <class 'icalendar.prop.geo.vGeo'>, 'INLINE': <class 'icalendar.prop.inline.vInline'>, 'INTEGER': <class 'icalendar.prop.integer.vInt'>, 'N': <class 'icalendar.prop.n.vN'>, 'ORG': <class 'icalendar.prop.org.vOrg'>, 'PERIOD': <class 'icalendar.prop.dt.period.vPeriod'>, 'RECUR': <class 'icalendar.prop.recur.recur.vRecur'>, 'TEXT': <class 'icalendar.prop.text.vText'>, 'TIME': <class 'icalendar.prop.dt.time.vTime'>, 'UID': <class 'icalendar.prop.uid.vUid'>, 'UNKNOWN': <class 'icalendar.prop.unknown.vUnknown'>, 'URI': <class 'icalendar.prop.uri.vUri'>, 'UTC-OFFSET': <class 'icalendar.prop.dt.utc_offset.vUTCOffset'>, 'XML-REFERENCE': <class 'icalendar.prop.xml_reference.vXmlReference'>}

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

values()

Return an object providing a view on the dict's values.

walk(name=None, select=<function Component.<lambda>>)

Recursively traverses component and subcomponents. Returns sequence of same. If name is passed, only components with name will be returned.

Parameters:

• name – The name of the component or None such as VEVENT.

• select – A function that takes the component as first argument and returns True/False.

Returns:

A list of components that match.

Return type:

list[Component]

with_uid(uid)

Return a list of components with the given UID.

Parameters:

uid (str) – The UID of the component.

Returns:

List of components with the given UID.

Return type:

list[Component]

class icalendar.cal.timezone.TimezoneStandard(*args, **kwargs)

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.

Set keys to upper for initial dict.

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 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 LAST_MODIFIED: datetime | None

The LAST-MODIFIED property. datetime in UTC

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

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

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

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

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

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

Add a property.

Parameters:

• name (string) – Name of the property.

• value (Python native type or icalendar property type.) – Value of the property. Either of a basic Python type of any of the icalendar's own property types.

• parameters (Dictionary) – Property parameter dictionary for the value. Only available, if encode is set to True.

• encode (Boolean) – True, if the value should be encoded to one of icalendar's own property types (Fallback is "vText") or False, if not.

Returns:

None

add_component(component)

Add a subcomponent to this component.

clear()

Remove all items from ordered dict.

property comments: list[str]

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

Purpose:

This property specifies non-processing information intended to provide a comment to the calendar user.

Conformance:

In RFC 5545, this property can be specified multiple times in "VEVENT", "VTODO", "VJOURNAL", and "VFREEBUSY" calendar components as well as in the "STANDARD" and "DAYLIGHT" sub-components. In RFC 7953, this property can be specified multiple times in "VAVAILABILITY" and "VAVAILABLE".

Property Parameters:

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

property concepts: list[vUri]

CONCEPT

Purpose:

CONCEPT defines the formal categories for a calendar component.

Conformance:

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

Description:

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

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

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

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

Examples

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

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

See also

Component.categories

content_line(name, value, sorted=True)

Returns property as content line.

content_lines(sorted=True)

Converts the Component and subcomponents into content lines.

copy(recursive=False)

Copy the component.

Parameters:

recursive (bool) – If True, this creates copies of the component, its subcomponents, and all its properties. If False, this only creates a shallow copy of the component.

Return type:

None

Returns:

A copy of the component.

Examples

Create a shallow copy of a component:

>>> from icalendar import Event
>>> event = Event.new(description="Event to be copied")
>>> event_copy = event.copy()
>>> str(event_copy.description)
'Event to be copied'

Shallow copies lose their subcomponents:

>>> from icalendar import Calendar
>>> calendar = Calendar.example()
>>> len(calendar.subcomponents)
3
>>> calendar_copy = calendar.copy()
>>> len(calendar_copy.subcomponents)
0

A recursive copy also copies all the subcomponents:

>>> full_calendar_copy = calendar.copy(recursive=True)
>>> len(full_calendar_copy.subcomponents)
3
>>> full_calendar_copy.events[0] == calendar.events[0]
True
>>> full_calendar_copy.events[0] is calendar.events[0]
False

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=[])

Returns decoded value of property.

A component maps keys to icalendar property value types. This function returns values compatible to native Python types.

Return type:

Any

exclusive: ClassVar[tuple[()]] = ()

These properties are mutually exclusive.

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.

classmethod from_ical(st, multiple=False)

Parse iCalendar data into component instances.

Handles standard and custom components (X-*, IANA-registered).

Parameters:

• st (str | bytes) – iCalendar data as bytes or string

• multiple (bool) – If True, returns list. If False, returns single component.

Return type:

Component | list[Component]

Returns:

Component or list of components

See also

Custom components for examples of parsing custom components

classmethod from_jcal(jcal)

Create a component from a jCal list.

Parameters:

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

Raises:

• JCalParsingError – If the jCal provided is invalid.

• JSONDecodeError – If the provided string is not valid JSON.

Return type:

Component

This reverses to_json() and to_jcal().

The following code parses an example from RFC 7265:

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

classmethod fromkeys(iterable, value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None)

Get property value with default.

classmethod get_component_class(name)

Return a component with this name.

Parameters:

name (str) – Name of the component, i.e. VCALENDAR

Return type:

type[Component]

get_inline(name, decode=1)

Returns a list of values (split on comma).

ignore_exceptions: ClassVar[bool] = False

Whether or not to ignore exceptions when parsing.

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

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

These properties are inclusive.

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

Example

('duration', 'repeat')

is_empty()

Returns True if Component has no items or subcomponents, else False.

is_thunderbird()

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

Return type:

bool

items()

Return a set-like object providing a view on the dict's items.

keys()

Return a set-like object providing a view on the dict's keys.

property last_modified: datetime

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

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

property links: list[vUri | vUid | vXmlReference]

LINK properties as a list.

Purpose:

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

Property Parameters:

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

Conformance:

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

Description:

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

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

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

LABEL

This parameter maps to the "title" attribute defined in Section 3.4.1 of RFC 8288. LABEL is used to label the destination of a link such that it can be used as a human-readable identifier (e.g., a menu entry) in the language indicated by the LANGUAGE (if present).

LANGUAGE

This parameter maps to the "hreflang" attribute defined in Section 3.4.1 of RFC 8288. See RFC 5646. Example: en, de-ch.

LINKREL

This parameter maps to the link relation type defined in Section 2.1 of RFC 8288. See Registered Link Relation Types.

FMTTYPE

This parameter maps to the "type" attribute defined in Section 3.4.1 of RFC 8288.

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

Examples

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

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

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

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

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

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

Set a link icalendar.vUri to the event page:

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

move_to_end(key, last=True)

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

Raise KeyError if the element does not exist.

multiple: ClassVar[tuple[()]] = ('COMMENT', 'RDATE', 'TZNAME', 'RRULE', 'EXDATE')

These properties may occur more than once.

name: ClassVar[str | None] = 'STANDARD'

The name of the component.

This should be defined in each component class.

Example: VCALENDAR.

classmethod new(created=None, comments=None, concepts=None, last_modified=None, links=None, refids=None, related_to=None, stamp=None)

Create a new component.

Parameters:

• comments (list[str] | str | None) – The comments of the component.

• concepts (list[vUri | str] | str | vUri | None) – The concepts of the component.

• created (date | None) – The created of the component.

• last_modified (date | None) – The last_modified of the component.

• links (str | vUri | vUid | vXmlReference | None | list[str | vUri | vUid | vXmlReference]) – The links of the component.

• related_to (None | str | vText | vUri | vUid | list[str | vText | vUri | vUid]) – The related_to of the component.

• stamp (date | None) – The DTSTAMP of the component.

Raises:

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

Return type:

Component

Warning

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

property_items(recursive=True, sorted=True)

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

Return type:

list[tuple[str, object]]

property 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 refids: list[str]

REFID

Purpose:

REFID acts as a key for associated iCalendar entities.

Conformance:

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

Description:

The value of this property is free-form text that creates an identifier for associated components. All components that use the same REFID value are associated through that value and can be located or retrieved as a group. For example, all of the events in a travel itinerary would have the same REFID value, so as to be grouped together.

Examples

The following is an example of this property.

REFID:itinerary-2014-11-17

Use a REFID to associate several VTODOs:

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

Note

List modifications do not modify the component.

classmethod register(component_class)

Register a custom component class.

Parameters:

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

Raises:

• ValueError – If component_class has no name attribute.

• ValueError – If a component with this name is already registered.

Return type:

None

Examples

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

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

property related_to: list[vText | vUri | vUid]

RELATED-TO properties as a list.

Purpose:

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

Value Type:

RFC 5545: TEXT RFC 9253: URI, UID

Conformance:

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

Description (RFC 5545):

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

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

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

Description (RFC 9253):

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

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

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

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

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

The FIRST and NEXT define ordering relationships between calendar components.

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

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

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

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

Examples

RFC 5545 examples of this property:

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

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

RFC 9253 examples of this property:

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

See also icalendar.enum.RELTYPE.

required: ClassVar[tuple[()]] = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')

These properties are required.

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.

set_inline(name, values, encode=1)

Converts a list of values into comma separated string and sets value to that.

singletons: ClassVar[tuple[()]] = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')

These properties must appear only once.

property stamp: 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.

subcomponents: list[Component]

All subcomponents of this component.

to_ical(sorted=True)

Parameters:

sorted (bool) – Whether parameters and properties should be lexicographically sorted.

to_jcal()

Convert this component to a jCal object.

Return type:

list

Returns:

jCal object

See also to_json.

In this example, we create a simple VEVENT component and convert it to jCal:

>>> from icalendar import Event
>>> from datetime import date
>>> from pprint import pprint
>>> event = Event.new(summary="My Event", start=date(2025, 11, 22))
>>> pprint(event.to_jcal())
['vevent',
 [['dtstamp', {}, 'date-time', '2025-05-17T08:06:12Z'],
  ['summary', {}, 'text', 'My Event'],
  ['uid', {}, 'text', 'd755cef5-2311-46ed-a0e1-6733c9e15c63'],
  ['dtstart', {}, 'date', '2025-11-22']],
 []]

to_json()

Return this component as a jCal JSON string.

Return type:

str

Returns:

JSON string

See also to_jcal.

types_factory: ClassVar[TypesFactory] = {'ADR': <class 'icalendar.prop.adr.vAdr'>, 'BINARY': <class 'icalendar.prop.binary.vBinary'>, 'BOOLEAN': <class 'icalendar.prop.boolean.vBoolean'>, 'CAL-ADDRESS': <class 'icalendar.prop.cal_address.vCalAddress'>, 'CATEGORIES': <class 'icalendar.prop.categories.vCategory'>, 'DATE': <class 'icalendar.prop.dt.types.vDDDTypes'>, 'DATE-TIME': <class 'icalendar.prop.dt.types.vDDDTypes'>, 'DATE-TIME-LIST': <class 'icalendar.prop.dt.list.vDDDLists'>, 'DURATION': <class 'icalendar.prop.dt.types.vDDDTypes'>, 'FLOAT': <class 'icalendar.prop.float.vFloat'>, 'GEO': <class 'icalendar.prop.geo.vGeo'>, 'INLINE': <class 'icalendar.prop.inline.vInline'>, 'INTEGER': <class 'icalendar.prop.integer.vInt'>, 'N': <class 'icalendar.prop.n.vN'>, 'ORG': <class 'icalendar.prop.org.vOrg'>, 'PERIOD': <class 'icalendar.prop.dt.period.vPeriod'>, 'RECUR': <class 'icalendar.prop.recur.recur.vRecur'>, 'TEXT': <class 'icalendar.prop.text.vText'>, 'TIME': <class 'icalendar.prop.dt.time.vTime'>, 'UID': <class 'icalendar.prop.uid.vUid'>, 'UNKNOWN': <class 'icalendar.prop.unknown.vUnknown'>, 'URI': <class 'icalendar.prop.uri.vUri'>, 'UTC-OFFSET': <class 'icalendar.prop.dt.utc_offset.vUTCOffset'>, 'XML-REFERENCE': <class 'icalendar.prop.xml_reference.vXmlReference'>}

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

values()

Return an object providing a view on the dict's values.

walk(name=None, select=<function Component.<lambda>>)

Recursively traverses component and subcomponents. Returns sequence of same. If name is passed, only components with name will be returned.

Parameters:

• name – The name of the component or None such as VEVENT.

• select – A function that takes the component as first argument and returns True/False.

Returns:

A list of components that match.

Return type:

list[Component]

with_uid(uid)

Return a list of components with the given UID.

Parameters:

uid (str) – The UID of the component.

Returns:

List of components with the given UID.

Return type:

list[Component]