Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jorricks/ical-library
ICalLibrary - Fast, yet simple, iCalendar reader with excellent recurrence support in Python
https://github.com/jorricks/ical-library
calendar client events ical ical-parser icalendar icalendar-parsing icalendar-rfc mkdocs-material pendulum python python-dateutil python-types recurring recurring-events rfc rfc5545
Last synced: about 1 month ago
JSON representation
ICalLibrary - Fast, yet simple, iCalendar reader with excellent recurrence support in Python
- Host: GitHub
- URL: https://github.com/jorricks/ical-library
- Owner: Jorricks
- License: mit
- Created: 2022-06-28T05:11:33.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-04T14:49:12.000Z (11 months ago)
- Last Synced: 2024-11-21T17:47:18.726Z (about 1 month ago)
- Topics: calendar, client, events, ical, ical-parser, icalendar, icalendar-parsing, icalendar-rfc, mkdocs-material, pendulum, python, python-dateutil, python-types, recurring, recurring-events, rfc, rfc5545
- Language: Python
- Homepage: https://jorricks.github.io/iCal-library/
- Size: 960 KB
- Stars: 12
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Fast, yet simple, iCalendar reader with excellent recurrence support. RFC 5545 compliant.
---
**Documentation**: [https://jorricks.github.io/iCal-library/](https://jorricks.github.io/iCal-library/)
**Source Code**: [https://github.com/Jorricks/iCal-library](https://github.com/Jorricks/iCal-library)
## Features
- 🚀 Easy python interface. It's as simple as '`client.load_ics_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:
- [Pendulum](https://github.com/sdispater/pendulum) for its extensions on datetime objects and parsing of durations.
- [Python-Dateutil](https://github.com/dateutil/dateutil) for its RRule support.
## Installation
To use iCal-library, first install it using pip:
pip install iCal-library
## Example
A simple example. Please look [in the docs](https://jorricks.github.io/iCal-library/) for more examples.
```python3
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](https://wiki.python.org/moin/PythonDebuggingTools) 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).