/iCal-library

ICalLibrary - Fast, yet simple, iCalendar reader with excellent recurrence support in Python

Primary LanguagePythonMIT LicenseMIT

iCal-library

Fast, yet simple, iCalendar reader with excellent recurrence support. RFC 5545 compliant.

Coverage Package version Supported Python versions

Documentation: https://jorricks.github.io/iCal-library/

Source Code: https://github.com/Jorricks/iCal-library

Features

  • 🚀 Easy python interface. It's as simple as 'client.load_ics_file("<my_file>").timeline' to show all your events of that week.
  • 📈 Timeline support. Show exactly what is planned for a specific week.
  • ✨ Fully functional support for recurring iCal components. E.g. Any recurring event will show up as intended within the timeline interface. This includes:
    1. Recurring components/events based on RRule.
    2. Recurring components/events based on RDate.
    3. Excluding components/events based on EXDate.
    4. Any combination of the above three.
    5. Redefined/changed components/events correctly show the latest version.
  • ⏩ Very fast parsing due to lazy evaluation of iCal properties.
  • ⁉️ Debugger supported. Any issues? Open up a debugger and inspect all values.
  • 🔅 Minimal dependencies. Only python-dateutil and pendulum.
  • 🆎 Fully typed code base.

Requirements

Python 3.8+

iCal-library uses two major libraries for their date and time utilities:

Installation

To use iCal-library, first install it using pip:

pip install iCal-library

Example

A simple example. Please look in the docs for more examples.

from ical_library import client

calendar = client.parse_icalendar_file("/home/user/my_icalendar.ics")
print(calendar.events)
print(calendar.todos)
print(calendar.journals)
print(calendar.free_busy_list)
print(calendar.time_zones)

Note: iCal-library is fully Debugger compliant, meaning it is very easy to use a debugger with this project. It will be much faster to see all the different attributes and functions from inside a Python debugger. If you are unsure whether your IDE supports it, take a look here under the sections 'IDEs with Debug Capabilities'.

Limitations

  • Currently, it is not supported to write ICS files. If this is a deal-breaker for you, it should be relatively straight forward to add it, so please consider submitting a PR for this :). However, this will be added shortly!

Why yet another iCalendar library?

I first tried several libraries for iCalendar events. However, none of them supported recurring events as well as they should be. For some libraries my calendar loaded but then didn't show my recurring events, while others simply threw stacktraces trying to load it. Furthermore, I noticed that my calendar (with over 2000 events) took ages to load. After traversing the code of the other libraries I decided I wanted to build my own. With some key principles:

  • Recurring components should be the main priority to get working.
  • No strict evaluation that could lead to errors while parsing the file.
  • Lazy evaluation for iCalendar properties to speed up the process.

Ideas for additional features

  • Support quoted property parameters containing special characters.
  • Support the new Properties for iCalendar (RFC 7986).
  • Support CalDev (RFC 4791).