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.

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.

multiple = ()#
name = None#
classmethod new(created: date | None = None, comments: list[str] | str | None = None, last_modified: date | None = None, stamp: date | None = None) Component[source]#

Create a new component.

Parameters:
  • comments – The comments of the component.

  • created – The created of the component.

  • last_modified – The last_modified 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), …]

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'>, 'URI': <class 'icalendar.prop.vUri'>, 'UTC-OFFSET': <class 'icalendar.prop.vUTCOffset'>}#
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]