icalendar.cal.calendar module#

RFC 5545 iCalendar component.

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

Bases: Component

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

Examples

Create a new Calendar:

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

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

Add all missing VTIMEZONE components.

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

Note

Timezones that are not known will not be added.

Parameters:

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

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

property availabilities: list[Availability]#

All Availability components in the calendar.

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

property calendar_name: str | None#

This property specifies the name of the calendar.

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

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

Example

Below, we set the name of the calendar.

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

property calscale: str#

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

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

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

property categories: list[str]#

This property defines the categories for a component.

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

Example

Below, we add the categories to an event:

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

Note

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

property color: str#

This property specifies a color used for displaying the calendar.

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

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

Example

"turquoise", "#ffffff"

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

property description: str | None#

This property specifies the description of the calendar.

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

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

Example

Below, we add a description to a calendar.

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

property events: list[Event]#

All event components in the calendar.

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

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

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

property freebusy: list[FreeBusy]#

All FreeBusy components in the calendar.

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

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

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

The set of missing timezone component tzids.

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

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

The set of TZIDs in use.

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

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

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

property images: list[Image]#

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

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

Note

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

property method: str#

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

Description:

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

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

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

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

name = 'VCALENDAR'#

Create a new Calendar with all required properties.

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

Parameters:

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

Returns:

Calendar

Raises:

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

Warning

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

property prodid: str#

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

Conformance:

The property MUST be specified once in an iCalendar object.

Description:

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

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

Example

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

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

property refresh_interval: timedelta | None#

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

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

Raises:: ValueError – When setting a negative duration.

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

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

property source: str#

A URI from where calendar data can be refreshed.

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

Example

The following is an example of this property:

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

subcomponents: list[Component]#

property timezones: list[Timezone]#

Return the timezones components in this calendar.

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

Note

This is a read-only property.

property todos: list[Todo]#

All todo components in the calendar.

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

property uid: str#

UID specifies the persistent, globally unique identifier for a component.

We recommend using uuid.uuid4() to generate new values.

Returns:: The value of the UID property as a string or "" if no value is set.

Description:

The “UID” itself MUST be a globally unique identifier. The generator of the identifier MUST guarantee that the identifier is unique.

This is the method for correlating scheduling messages with the referenced “VEVENT”, “VTODO”, or “VJOURNAL” calendar component. The full range of calendar components specified by a recurrence set is referenced by referring to just the “UID” property value corresponding to the calendar component. The “RECURRENCE-ID” property allows the reference to an individual instance within the recurrence set.

This property is an important method for group-scheduling applications to match requests with later replies, modifications, or deletion requests. Calendaring and scheduling applications MUST generate this property in “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to assure interoperability with other group- scheduling applications. This identifier is created by the calendar system that generates an iCalendar object.

Implementations MUST be able to receive and persist values of at least 255 octets for this property, but they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence.

RFC 7986 states that UID can be used, for example, to identify duplicate calendar streams that a client may have been given access to. It can be used in conjunction with the “LAST-MODIFIED” property also specified on the “VCALENDAR” object to identify the most recent version of a calendar.

Conformance:

RFC 5545 states that the “UID” property can be specified on “VEVENT”, “VTODO”, and “VJOURNAL” calendar components. RFC 7986 modifies the definition of the “UID” property to allow it to be defined in an iCalendar object. RFC 9074 adds a “UID” property to “VALARM” components to allow a unique identifier to be specified. The value of this property can then be used to refer uniquely to the “VALARM” component.

This property can be specified once only.

Security:

RFC 7986 states that UID values MUST NOT include any data that might identify a user, host, domain, or any other security- or privacy-sensitive information. It is RECOMMENDED that calendar user agents now generate “UID” values that are hex-encoded random Universally Unique Identifier (UUID) values as defined in Sections 4.4 and 4.5 of RFC 4122. You can use the uuid module to generate new UUIDs.

Compatibility:

For Alarms, X-ALARMUID is also considered.

Examples

The following is an example of such a property value: 5FC53010-1267-4F8E-BC28-1D7AE55A7C99.

Set the UID of a calendar:

>>> from icalendar import Calendar
>>> from uuid import uuid4
>>> calendar = Calendar()
>>> calendar.uid = uuid4()
>>> print(calendar.to_ical())
BEGIN:VCALENDAR
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VCALENDAR

property url: str#

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

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

Example

The following is an example of this property:

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

validate()[source]#

Validate that the calendar has required properties and components.

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

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

property version: str#

VERSION of the calendar specification.

The default is "2.0" for RFC 5545.

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

icalendar.cal.calendar module#

This Page