Internet Calendaring and Scheduling (iCalendar) for Python — icalendar 6.3.1 documentation (original) (raw)

The icalendar package is a RFC 5545 compatible parser/generator for iCalendar files.

Homepage:

https://icalendar.readthedocs.io

Community Discussions:

collective/icalendar#discussions

Issue Tracker:

collective/icalendar#issues

Code:

collective/icalendar

Dependencies:

python-dateutil and tzdata.

License:

BSD

Quick start guide#

icalendar enables you to create, inspect and modifycalendaring information with Python.

To install the package, run:

Inspect Files#

You can open an .ics file and see all the 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#

Such a calendar can then be edited and saved again.

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

Create Events, TODOs, Journals, Alarms, …#

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

icalendar.Event() # events VEVENT({}) icalendar.FreeBusy() # free/busy times VFREEBUSY({}) icalendar.Todo() # Todo list entries VTODO({}) icalendar.Alarm() # Alarms e.g. for events VALARM({}) icalendar.Journal() # Journal entries VJOURNAL({})

Have a look at more examples.

Use timezones of your choice#

With icalendar, you can localize your events to take place in different timezones.zoneinfo, dateutil.tz and pytz are compatible with icalendar. This 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

Version 6 with zoneinfo#

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

By default and since 6.0.0, zoneinfo timezones are created.

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

If you would like to continue to receive pytz timezones in parse 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>

Version 6 is on branch main. It is compatible with Python versions 3.8 - 3.13, and PyPy3. We expect the main branch with versions 6+ to receive the latest updates and features.