Skip to main content

iCalendar parser/generator

Project description

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


Homepage:

https://icalendar.readthedocs.io

Community Discussions:

https://github.com/collective/icalendar/discussions

Issue Tracker:

https://github.com/collective/icalendar/issues

Code:

https://github.com/collective/icalendar

Dependencies:

python-dateutil and tzdata.

License:

BSD


Python Package Version on PyPI PyPI - Python Version Downloads from PyPI GitHub Actions build status for main Documentation Status Test Coverage

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")
>>> 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.

Further Reading

You can find out more about this project:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

icalendar-6.3.1.tar.gz (177.2 kB view details)

Uploaded Source

Built Distribution

icalendar-6.3.1-py3-none-any.whl (242.3 kB view details)

Uploaded Python 3

File details

Details for the file icalendar-6.3.1.tar.gz.

File metadata

  • Download URL: icalendar-6.3.1.tar.gz
  • Upload date:
  • Size: 177.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.3

File hashes

Hashes for icalendar-6.3.1.tar.gz
Algorithm Hash digest
SHA256 a697ce7b678072941e519f2745704fc29d78ef92a2dc53d9108ba6a04aeba466
MD5 85dcf09c4da0e95ea152ede497d1694f
BLAKE2b-256 0813e5899c916dcf1343ea65823eb7278d3e1a1d679f383f6409380594b5f322

See more details on using hashes here.

File details

Details for the file icalendar-6.3.1-py3-none-any.whl.

File metadata

  • Download URL: icalendar-6.3.1-py3-none-any.whl
  • Upload date:
  • Size: 242.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.3

File hashes

Hashes for icalendar-6.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 7ea1d1b212df685353f74cdc6ec9646bf42fa557d1746ea645ce8779fdfbecdd
MD5 af93823c3895fbb99bfb74fae8fa6567
BLAKE2b-256 6c25b5fc00e85d2dfaf5c806ac8b5f1de072fa11630c5b15b4ae5bbc228abd51

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page