Usage

This chapter describes how to use icalendar.

Note

To avoid repetition, the code examples in this chapter use the following imports.

>>> from icalendar import Calendar, Event

Components

Components are case-insensitive Python dicts. The Calendar object is a component. The following example shows how to set two properties for it, then display them.

>>> cal = Calendar()
>>> cal["dtstart"] = "20050404T080000"
>>> cal["summary"] = "Python meeting about calendaring"
>>> for k,v in cal.items():
...     k,v
('DTSTART', '20050404T080000')
('SUMMARY', 'Python meeting about calendaring')

Note

To add components to the calendar, create the subcomponent, then add it via icalendar.Component.add(). The example above adds a string, but not a vText component.

You can generate a string for a file with the icalendar.Component.to_ical() method.

>>> cal.to_ical()
b'BEGIN:VCALENDAR\r\nDTSTART:20050404T080000\r\nSUMMARY:Python meeting about calendaring\r\nEND:VCALENDAR\r\n'

The rendered view is easier to read.

BEGIN:VCALENDAR
DTSTART:20050404T080000
SUMMARY:Python meeting about calendaring
END:VCALENDAR

You can define a function to display to_ical() output, as shown in the following example.

>>> def display(cal):
...    return cal.to_ical().decode("utf-8").replace("\r\n", "\n").strip()

You can set multiple properties, as shown in the following example.

>>> cal = Calendar()
>>> cal["attendee"] = ["MAILTO:maxm@mxm.dk","MAILTO:test@example.com"]
>>> print(display(cal))
BEGIN:VCALENDAR
ATTENDEE:MAILTO:maxm@mxm.dk
ATTENDEE:MAILTO:test@example.com
END:VCALENDAR

If you don’t want to care about whether a property value is a list or a single value, use the icalendar.Component.add() method. It will automatically convert the property to a list of values if more than one value is added. Here is an example.

>>> cal = Calendar()
>>> cal.add("attendee", "MAILTO:maxm@mxm.dk")
>>> cal.add("attendee", "MAILTO:test@example.com")
>>> print(display(cal))
BEGIN:VCALENDAR
ATTENDEE:MAILTO:maxm@mxm.dk
ATTENDEE:MAILTO:test@example.com
END:VCALENDAR

Note

This example doesn’t check for compliance, so you should look in the RFC 5545 specification for legal properties for each component. You can also look in the icalendar/cal/calendar.py file, where it is at least defined for each component.

Note

icalendar automatically handles custom components (X-components and IANA-components) without special configuration. See Custom components for details on working with vendor-specific or non-standard components.

Subcomponents

Any component can have subcomponents. For example, inside a calendar, there can be events. They can be arbitrarily nested.

To demonstrate, first, make a new component.

>>> event = Event()
>>> event["uid"] = "42"
>>> event["dtstart"] = "20050404T080000"

Then append it to a parent.

>>> cal.add_component(event)
>>> print(display(cal))
BEGIN:VCALENDAR
ATTENDEE:MAILTO:maxm@mxm.dk
ATTENDEE:MAILTO:test@example.com
BEGIN:VEVENT
DTSTART:20050404T080000
UID:42
END:VEVENT
END:VCALENDAR

Subcomponents are appended to the subcomponents property on the component.

>>> cal.subcomponents
[VEVENT({'UID': '42', 'DTSTART': '20050404T080000'})]

Value types

Property values are UTF-8 encoded strings.

This is impractical if you want to use the data for further computation. The datetime format, for example, looks like 20050404T080000. icalendar can parse and generate iCalendar formatted strings.

You can either use the add() method to do the work, or you can do it manually.

To add a datetime value, you can use Python’s built in datetime types, and the set the encode parameter to True, and it will convert to the type defined in the specification.

>>> from datetime import datetime
>>> cal.add("dtstart", datetime(2005,4,4,8,0,0))
>>> cal["dtstart"].to_ical()
b'20050404T080000'

If that doesn’t work satisfactorily for some reason, you can also do it manually.

In icalendar/prop.py, all the iCalendar data types are defined. Each type has a class that can parse and encode the type.

Thus, to parse it manually, you would do the following.

>>> from icalendar import vDatetime
>>> now = datetime(2005,4,4,8,0,0)
>>> vDatetime(now).to_ical()
b'20050404T080000'

To summarize, initialize the object with a Python built in type, then call the to_ical() method on the object. That will return an iCal-encoded string.

You can do it the other way around, too. To parse an encoded string, call the from_ical() method, and it will return an instance of the corresponding Python type.

>>> vDatetime.from_ical("20050404T080000")
datetime.datetime(2005, 4, 4, 8, 0)

>>> vDatetime.from_ical("20050404T080000Z")
datetime.datetime(2005, 4, 4, 8, 0, tzinfo=ZoneInfo(key='UTC'))

You can also choose to use the icalendar.Component.decoded() method, which will return a decoded value directly.

>>> cal = Calendar()
>>> cal.add("dtstart", datetime(2005,4,4,8,0,0))
>>> cal["dtstart"].to_ical()
b'20050404T080000'
>>> cal.decoded("dtstart")
datetime.datetime(2005, 4, 4, 8, 0)

Property parameters

Property parameters are automatically added, depending on the input value. For example, for date or time related properties, the value type and timezone identifier, if applicable, are automatically added.

>>> import zoneinfo
>>> event = Event()
>>> event.add("dtstart", datetime(2010, 10, 10, 10, 0, 0,
...                               tzinfo=zoneinfo.ZoneInfo("Europe/Vienna")))

>>> lines = event.to_ical().splitlines()
>>> assert (
...     b'DTSTART;TZID=Europe/Vienna:20101010T100000'
...     in lines)

You can also add arbitrary property parameters by passing a parameters dictionary to the add() method as shown.

>>> event = Event()
>>> event.add("X-TEST-PROP", "tryout.",
...           parameters={"prop1":"val1", "prop2":"val2"})
>>> lines = event.to_ical().splitlines()
>>> assert b'X-TEST-PROP;PROP1=val1;PROP2=val2:tryout.' in lines

Examples

This section describes how to use icalendar’s essential features.

Inspect files

Open an .ics file and view its events.

>>> import icalendar
>>> from pathlib import Path
>>> ics_path = Path("src/icalendar/tests/calendars/example.ics")
>>> calendar = icalendar.Calendar.from_ical(ics_path.read_bytes())
>>> for event in calendar.events:
...     print(event.get("SUMMARY"))
New Year's Day
Orthodox Christmas
International Women's Day

Modify content

After loading the example file, edit and save it.

>>> calendar.calendar_name = "My Modified Calendar"  # modify
>>> print(calendar.to_ical()[:121])  # save modification
BEGIN:VCALENDAR
VERSION:2.0
PRODID:collective/icalendar
CALSCALE:GREGORIAN
METHOD:PUBLISH
NAME:My Modified Calendar

iCalendar objects

icalendar supports the creation and parsing of all kinds of objects in the RFC 5545 iCalendar standard.

See also

For a complete list of all supported objects, see the icalendar API reference guide.

Events

Show events.

>>> icalendar.Event()
VEVENT({})

Free/busy times

Show free/busy times.

>>> icalendar.FreeBusy()
VFREEBUSY({})

To-do items

Show to-do items.

>>> icalendar.Todo()
VTODO({})

Alarms

Show alarms.

>>> icalendar.Alarm()
VALARM({})

Journal entries

Show journal entries.

>>> icalendar.Journal()
VJOURNAL({})

timezone implementations

You can localize your events to take place in different timezones.

icalendar supports multiple timezone implementations, including zoneinfo, dateutil.tz, and pytz. To demonstrate icalendar’s flexibility, the following example creates an event that uses all of the timezone implementations with the same result.

>>> import pytz, zoneinfo, dateutil.tz  # timezone libraries
>>> import datetime, icalendar
>>> e = icalendar.Event()
>>> tz = dateutil.tz.tzstr("Europe/London")
>>> e["X-DT-DATEUTIL"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
>>> tz = pytz.timezone("Europe/London")
>>> e["X-DT-USE-PYTZ"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
>>> tz = zoneinfo.ZoneInfo("Europe/London")
>>> e["X-DT-ZONEINFO"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
>>> print(e.to_ical())  # the libraries yield the same result
BEGIN:VEVENT
X-DT-DATEUTIL;TZID=Europe/London:20240619T100100
X-DT-USE-PYTZ;TZID=Europe/London:20240619T100100
X-DT-ZONEINFO;TZID=Europe/London:20240619T100100
END:VEVENT

zoneinfo default implementation

Changed in version 6.0.0.

Version 6 of icalendar switches the default timezone implementation from pytz to zoneinfo. This only affects you if you parse icalendar objects with from_ical. The functionality is extended and tested since 6.0.0 with both timezone implementations pytz and zoneinfo.

Since 6.0.0 by default, zoneinfo timezones are created.

>>> dt = icalendar.Calendar.example("timezoned").events[0].start
>>> dt.tzinfo
ZoneInfo(key='Europe/Vienna')

To continue to receive pytz timezones in parsed results, you can receive all the latest updates, and switch back to earlier behavior.

>>> icalendar.use_pytz()
>>> dt = icalendar.Calendar.example("timezoned").events[0].start
>>> dt.tzinfo
<DstTzInfo 'Europe/Vienna' CET+1:00:00 STD>

Complete recurring meeting

This section shows how create a complete and typical iCalendar file of a recurring meeting event, then add some properties to it, including a location, organizer, attendees, alarms, recurrence, and other properties. This file can be loaded into any application that supports iCalendar files.

Initialize the calendar.

>>> cal = Calendar()
>>> from datetime import datetime
>>> import zoneinfo

Add some properties to be compliant with RFC 5545.

>>> cal.add("prodid", "-//My calendar product//mxm.dk//")
>>> cal.add("version", "2.0")

At least one subcomponent is required for a calendar to be compliant.

>>> event = Event()
>>> event.add("summary", "Python meeting about calendaring")
>>> event.add("dtstart", datetime(2005,4,4,8,0,0,tzinfo=zoneinfo.ZoneInfo("UTC")))
>>> event.add("dtend", datetime(2005,4,4,10,0,0,tzinfo=zoneinfo.ZoneInfo("UTC")))
>>> event.add("dtstamp", datetime(2005,4,4,0,10,0,tzinfo=zoneinfo.ZoneInfo("UTC")))

Create a property with parameters. Notice that they are an attribute on the value.

>>> from icalendar import vCalAddress, vText
>>> organizer = vCalAddress("MAILTO:noone@example.com")

Automatic encoding is not yet implemented for parameter values, so you must use the v* types which you can import from the icalendar icalendar.prop module.

>>> organizer.params["cn"] = vText("Max Rasmussen")
>>> organizer.params["role"] = vText("CHAIR")
>>> event["organizer"] = organizer
>>> event["location"] = vText("Odense, Denmark")

>>> event["uid"] = "20050115T101010/27346262376@mxm.dk"
>>> event.add("priority", 5)

>>> attendee = vCalAddress("MAILTO:maxm@example.com")
>>> attendee.params["cn"] = vText("Max Rasmussen")
>>> attendee.params["ROLE"] = vText("REQ-PARTICIPANT")
>>> event.add("attendee", attendee, encode=0)

>>> attendee = vCalAddress("MAILTO:the-dude@example.com")
>>> attendee.params["cn"] = vText("The Dude")
>>> attendee.params["ROLE"] = vText("REQ-PARTICIPANT")
>>> event.add("attendee", attendee, encode=0)

Add the event to the calendar.

>>> cal.add_component(event)

By extending the event with subcomponents, you can create multiple alarms.

>>> from icalendar import Alarm
>>> from datetime import timedelta
>>> alarm_1h_before = Alarm()
>>> alarm_1h_before.add("action", "DISPLAY")
>>> alarm_1h_before.add("trigger", timedelta(hours=-1))
>>> alarm_1h_before.add("description", "Reminder: Event in 1 hour")
>>> event.add_component(alarm_1h_before)

>>> alarm_24h_before = Alarm()
>>> alarm_24h_before.add("action", "DISPLAY")
>>> alarm_24h_before.add("trigger", timedelta(hours=-24))
>>> alarm_24h_before.add("description", "Reminder: Event in 24 hours")
>>> event.add_component(alarm_24h_before)

You can even add a recurrence, either from a dictionary or a string. Note that if you want to add the recurrence rule from a string, you must use the icalendar.prop.vRecur property. Otherwise the rule will be escaped, making it invalid.

>>> event.add("rrule", {"freq": "daily"})

Write to disk.

>>> import tempfile, os
>>> directory = tempfile.mkdtemp()
>>> f = open(os.path.join(directory, "example.ics"), "wb")
>>> f.write(cal.to_ical())
733
>>> f.close()

Print out the calendar.

>>> print(cal.to_ical().decode("utf-8"))
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//My calendar product//mxm.dk//
BEGIN:VEVENT
SUMMARY:Python meeting about calendaring
DTSTART:20050404T080000Z
DTEND:20050404T100000Z
DTSTAMP:20050404T001000Z
UID:20050115T101010/27346262376@mxm.dk
RRULE:FREQ=DAILY
ATTENDEE;CN="Max Rasmussen";ROLE=REQ-PARTICIPANT:MAILTO:maxm@example.com
ATTENDEE;CN="The Dude";ROLE=REQ-PARTICIPANT:MAILTO:the-dude@example.com
LOCATION:Odense\, Denmark
ORGANIZER;CN="Max Rasmussen";ROLE=CHAIR:MAILTO:noone@example.com
PRIORITY:5
BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:Reminder: Event in 1 hour
TRIGGER:-PT1H
END:VALARM
BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:Reminder: Event in 24 hours
TRIGGER:-P1D
END:VALARM
END:VEVENT
END:VCALENDAR

More examples

The docstrings in the icalendar package API documentation provide other usage examples.

The tests of icalendar also have more examples.