Internet Calendaring and Scheduling (iCalendar) for Python¶
The icalendar package is a RFC 5545 compatible parser/generator for iCalendar files.
- Homepage:
- Code:
- Mailing list:
- Dependencies:
python-dateutil and tzdata.
- License:
Quick start guide¶
icalendar
enables you to create, inspect and modify
calendaring information with Python.
To install the package, run:
pip install icalendar
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")
>>> with ics_path.open() as f:
... calendar = icalendar.Calendar.from_ical(f.read())
>>> for event in calendar.walk('VEVENT'):
... 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["X-WR-CALNAME"] = "My Modified Calendar" # modify
>>> print(calendar.to_ical()[:129]) # save modification
BEGIN:VCALENDAR
VERSION:2.0
PRODID:collective/icalendar
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME: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").walk("VEVENT")[0]["DTSTART"].dt
>>> 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").walk("VEVENT")[0]["DTSTART"].dt
>>> 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.
Further Reading¶
You can find out more about this project:
Contents¶
- About
- Installing iCalendar
- iCalendar package
- More documentation
- API Reference
- iCalendar utility
- icalendar contributors
- Maintenance
- License
- Changelog
- 6.0.2 (unreleased)
- 6.0.1 (2024-10-13)
- 6.0.0 (2024-09-28)
- 6.0.0a0 (2024-07-03)
- 5.0.13 (2024-06-20)
- 5.0.12 (2024-03-19)
- 5.0.11 (2023-11-03)
- 5.0.10 (2023-09-26)
- 5.0.9 (2023-09-24)
- 5.0.8 (2023-09-18)
- 5.0.7 (2023-05-29)
- 5.0.6 (2023-05-26)
- 5.0.5 (2023-04-13)
- 5.0.4 (2022-12-29)
- 5.0.3 (2022-11-23)
- 5.0.2 (2022-11-03)
- 5.0.1 (2022-10-22)
- 5.0.0 (2022-10-17)
- 5.0.0a1 (2022-07-11)
- 4.1.0 (2022-07-11)
- 4.0.9 (2021-10-16)
- 4.0.8 (2021-10-07)
- 4.0.7 (2020-09-07)
- 4.0.6 (2020-05-06)
- 4.0.5 (2020-03-21)
- 4.0.4 (2019-11-25)
- 4.0.3 (2018-10-10)
- 4.0.2 (2018-06-20)
- 4.0.1 (2018-02-11)
- 4.0.0 (2017-11-08)
- 3.12 (2017-11-07)
- 3.11.7 (2017-08-27)
- 3.11.6 (2017-08-04)
- 3.11.5 (2017-07-03)
- 3.11.4 (2017-05-10)
- 3.11.3 (2017-02-15)
- 3.11.2 (2017-01-12)
- 3.11.1 (2016-12-19)
- 3.11 (2016-11-18)
- 3.10 (2016-05-26)
- 3.9.2 (2016-02-05)
- 3.9.1 (2015-09-08)
- 3.9.0 (2015-03-24)
- 3.8.4 (2014-11-01)
- 3.8.3 (2014-08-26)
- 3.8.2 (2014-07-22)
- 3.8.1 (2014-07-17)
- 3.8 (2014-07-17)
- 3.7 (2014-06-02)
- 3.6.2 (2014-04-05)
- 3.6.1 (2014-01-13)
- 3.6 (2014-01-06)
- 3.5 (2013-07-03)
- 3.4 (2013-04-24)
- 3.3 (2013-02-08)
- 3.2 (2012-11-27)
- 3.1 (2012-09-05)
- 3.0.1b2 (2012-03-01)
- 3.0.1b1 (2012-02-24)
- 3.0
- 2.2 (2011-08-24)
- 2.1 (2009-12-14)
- 2.0.1 (2008-07-11)
- 2.0 (2008-07-11)
- 1.2 (2006-11-25)
- 1.1 (2006-11-23)
- 1.0 (2006-08-03)
- 0.11 (2005-11-08)
- 0.10 (2005-04-28)