icalendar.cal.component module#

The base for RFC 5545 components.

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

Bases: CaselessDict

Base class for calendar components.

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

name#

The name of the component. Example: VCALENDAR.

required#

These properties are required.

singletons#

These properties must only appear once.

multiple#

These properties may occur more than once.

exclusive#

These properties are mutually exclusive.

inclusive#

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

Type:

tuple[str] | tuple[tuple[str, str]]

ignore_exceptions#

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

types_factory#

Factory for property types

property CREATED: datetime | None#

The CREATED property. datetime in UTC

All values will be converted to a datetime in UTC.

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

Conformance:

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

property DTSTAMP: datetime | None#

The DTSTAMP property. datetime in UTC

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

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

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

The value MUST be specified in the UTC time format.

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

property LAST_MODIFIED: datetime | None#

The LAST-MODIFIED property. datetime in UTC

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

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

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

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

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

Add a property.

Parameters:

  • name (string) – Name of the property.

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

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

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

Returns:

None

add_component(component: Component)[source]#

Add a subcomponent to this component.

property comments: list[str]#

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

Purpose:

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

Conformance:

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

Property Parameters:

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

property concepts: list[vUri]#

CONCEPT

Purpose:

CONCEPT defines the formal categories for a calendar component.

Conformance:

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

Description:

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

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

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

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

Examples

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

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

See also

Compnent.categories

content_line(name, value, sorted: bool = True)[source]#

Returns property as content line.

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

Converts the Component and subcomponents into content lines.

property created: datetime#

Datetime when the information associated with the component was created.

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

decoded(name, default=[])[source]#

Returns decoded value of property.

exclusive = ()#
classmethod from_ical(st, multiple: bool = False) → Self | list[Self][source]#

Populates the component recursively from a string.

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

Return a component with this name.

Parameters:

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

get_inline(name, decode=1)[source]#

Returns a list of values (split on comma).

ignore_exceptions = False#
inclusive: tuple[str] | tuple[tuple[str, str]] = ()#
is_empty()[source]#

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

is_thunderbird() → bool[source]#

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

property last_modified: datetime#

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

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

LINK properties as a list.

Purpose:

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

Property Parameters:

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

Conformance:

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

Description:

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

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

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

  • LABEL

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

  • LANGUAGE

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

  • LINKREL

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

  • FMTTYPE:

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

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

Examples

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

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

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

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

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

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

Set a link icalendar.vUri to the event page:

>>> from icalendar import Event, vUri
>>> from datetime import datetime
>>> link = vUri(
...     "http://example.com/event-page",
...     params={"LINKREL":"SOURCE"}
... )
>>> event = Event.new(
...     start=datetime(2025, 9, 17, 12, 0),
...     summary="An Example Event with a page"
... )
>>> event.links = [link]
>>> print(event.to_ical())
BEGIN:VEVENT
SUMMARY:An Example Event with a page
DTSTART:20250917T120000
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
LINK;LINKREL="SOURCE":http://example.com/event-page
END:VEVENT
multiple = ()#
name = None#
classmethod new(created: date | None = None, comments: list[str] | str | None = None, concepts: list[str | vUri] | str | vUri | None = None, last_modified: date | None = None, links: list[str | vXmlReference | vUri | vUid] | None = None, refids: list[str] | str | None = None, related_to: None | str | vText | vUri | vUid | List[str | vText | vUri | vUid] = None, stamp: date | None = None) → Component[source]#

Create a new component.

Parameters:

  • comments – The comments of the component.

  • concepts – The concepts of the component.

  • created – The created of the component.

  • last_modified – The last_modified of the component.

  • links – The links of the component.

  • related_to – The related_to of the component.

  • stamp – The DTSTAMP of the component.

Raises:

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

Warning

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

property_items(recursive=True, sorted: bool = True) → list[tuple[str, object]][source]#

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

property refids: list[str]#

REFID

Purpose:

REFID acts as a key for associated iCalendar entities.

Conformance:

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

Description:

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

Examples

The following is an example of this property.

REFID:itinerary-2014-11-17

Use a REFID to associate several VTODOs:

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

Note

List modifications do not modify the component.

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

RELATED-TO properties as a list.

Purpose:

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

Value Type:

RFC 5545: TEXT RFC 9253: URI, UID

Conformance:

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

Description (RFC 5545):

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

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

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

Description (RFC 9253):

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

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

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

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

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

The FIRST and NEXT define ordering relationships between calendar components.

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

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

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

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

Examples

RFC 5545 examples of this property:

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

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

RFC 9253 examples of this property:

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

See also icalendar.enum.RELTYPE.

required = ()#
set_inline(name, values, encode=1)[source]#

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

singletons = ()#
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]#
to_ical(sorted: bool = True)[source]#
Parameters:

sorted – Whether parameters and properties should be lexicographically sorted.

types_factory = {'BINARY': <class 'icalendar.prop.vBinary'>, 'BOOLEAN': <class 'icalendar.prop.vBoolean'>, 'CAL-ADDRESS': <class 'icalendar.prop.vCalAddress'>, 'CATEGORIES': <class 'icalendar.prop.vCategory'>, 'DATE': <class 'icalendar.prop.vDDDTypes'>, 'DATE-TIME': <class 'icalendar.prop.vDDDTypes'>, 'DATE-TIME-LIST': <class 'icalendar.prop.vDDDLists'>, 'DURATION': <class 'icalendar.prop.vDDDTypes'>, 'FLOAT': <class 'icalendar.prop.vFloat'>, 'GEO': <class 'icalendar.prop.vGeo'>, 'INLINE': <class 'icalendar.prop.vInline'>, 'INTEGER': <class 'icalendar.prop.vInt'>, 'PERIOD': <class 'icalendar.prop.vPeriod'>, 'RECUR': <class 'icalendar.prop.vRecur'>, 'TEXT': <class 'icalendar.prop.vText'>, 'TIME': <class 'icalendar.prop.vTime'>, 'UID': <class 'icalendar.prop.vUid'>, 'URI': <class 'icalendar.prop.vUri'>, 'UTC-OFFSET': <class 'icalendar.prop.vUTCOffset'>, 'XML-REFERENCE': <class 'icalendar.prop.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
walk(name=None, select=<function Component.<lambda>>) → list[Component][source]#

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]