Internet Calendaring and Scheduling (iCalendar) for Python

The icalendar package is a 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

------------------------------------------------------------------------

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 (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.

Related projects

-   icalevents. It is built on top of icalendar and allows you to query
    iCal files and get the events happening on specific dates. It
    manages recurrent events as well.
-   recurring-ical-events. Library to query an icalendar.Calendar object
    for events and other components happening at a certain date or
    within a certain time.
-   x-wr-timezone. Library and command line tool to make
    icalendar.Calendar objects and files from Google Calendar (using the
    non-standard X-WR-TIMEZONE property) compliant with the standard
    (5545).
-   ics-query. Command line tool to query iCalendar files for
    occurrences of events and other components.
-   icalendar-compatibility - access to event data compatible with
    RFC5545 and different implementations

Further Reading

You can find out more about this project:

-   Contributing
-   Changelog
-   License
