==========================================================
Internet Calendaring and Scheduling (iCalendar) for Python
The icalendar
_ package is a RFC 5545
_ compatible parser/generator for iCalendar
files.
:Homepage: https://icalendar.readthedocs.io
:Code: https://github.com/collective/icalendar
:Mailing list: https://github.com/collective/icalendar/issues
:Dependencies: python-dateutil
_ and pytz
.
:License: BSD
.. image:: https://badge.fury.io/py/icalendar.svg
:target: https://pypi.org/project/icalendar/
:alt: Python Package Version on PyPI
.. image:: https://img.shields.io/pypi/pyversions/icalendar
:target: https://pypi.org/project/icalendar/
:alt: PyPI - Python Version
.. image:: https://img.shields.io/pypi/dm/icalendar.svg
:target: https://pypi.org/project/icalendar/#files
:alt: Downloads from PyPI
.. image:: https://img.shields.io/github/actions/workflow/status/collective/icalendar/tests.yml?branch=main&label=main&logo=github
:target: https://github.com/collective/icalendar/actions/workflows/tests.yml?query=branch%3Amain
:alt: GitHub Actions build status for main
.. image:: https://readthedocs.org/projects/icalendar/badge/?version=latest
:target: https://icalendar.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://coveralls.io/repos/github/collective/icalendar/badge.svg
:target: https://coveralls.io/github/collective/icalendar
:alt: Test Coverage
.. _icalendar
: https://pypi.org/project/icalendar/
.. _RFC 5545
: https://www.ietf.org/rfc/rfc5545.txt
.. _python-dateutil
: https://github.com/dateutil/dateutil/
.. _pytz
: https://pypi.org/project/pytz/
.. _BSD
: https://github.com/collective/icalendar/issues/2
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:
.. code:: python
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.
.. code:: python
>>> 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.
.. code:: python
>>> 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 <https://icalendar.readthedocs.io/en/latest/usage.html>
_.
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:
.. code:: python
>>> 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.
.. code:: python
>>> 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:
.. code:: python
>>> 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 <https://github.com/collective/icalendar/>
_.
It is compatible with Python versions 3.8 - 3.12, and PyPy3.
We expect the main
branch with versions 6+
to receive the latest updates and features.
Related projects
icalevents <https://github.com/irgangla/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 <https://pypi.org/project/recurring-ical-events/>
_. Library to query an ICalendar
object for events happening at a certain date or within a certain time.x-wr-timezone <https://pypi.org/project/x-wr-timezone/>
_. Library to make ICalendar
objects and files using the non-standard X-WR-TIMEZONE
compliant with the standard (RFC 5545).
Further Reading
You can find out more about this project:
Contributing
_Changelog
_License
_
.. _Contributing
: https://icalendar.readthedocs.io/en/latest/contributing.html
.. _Changelog
: https://icalendar.readthedocs.io/en/latest/changelog.html
.. _License
: https://icalendar.readthedocs.io/en/latest/license.html