Code Monkey home page Code Monkey logo

ical-library's Introduction

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

ical-library's People

Contributors

jorricks avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar

ical-library's Issues

Expansion of events fails when expanding event starts exactly at max_datetime

Error;

Traceback (most recent call last):
  File "/home/bigdata/venv/lib64/python3.9/site-packages/duty_board/worker_loop.py", line 112, in update_all_outdated_calendars
    calendar = plugin.sync_calendar(calendar=calendar, session=session)
  File "/home/bigdata/venv/lib64/python3.9/site-packages/duty_board/plugin/ical_plugin_mixin.py", line 88, in sync_calendar
    for event in self._get_events_for_upcoming_month(calendar.icalendar_url, calendar.event_prefix or ""):
  File "/home/bigdata/venv/lib64/python3.9/site-packages/duty_board/plugin/ical_plugin_mixin.py", line 39, in _get_events_for_upcoming_month
    return [
  File "/home/bigdata/venv/lib64/python3.9/site-packages/duty_board/plugin/ical_plugin_mixin.py", line 39, in <listcomp>
    return [
  File "/home/bigdata/venv/lib64/python3.9/site-packages/ical_library/timeline.py", line 136, in overlapping
    for timespan, event in self.iterate():
  File "/home/bigdata/venv/lib64/python3.9/site-packages/ical_library/timeline.py", line 120, in iterate
    heap: List[TimespanWithParent] = self.__explode_recurring_components()
  File "/home/bigdata/venv/lib64/python3.9/site-packages/ical_library/timeline.py", line 101, in __explode_recurring_components
    list_of_timestamps_with_parents.extend(
  File "/home/bigdata/venv/lib64/python3.9/site-packages/ical_library/ical_components/v_event.py", line 216, in expand_component_in_range
    for event_start_time, event_end_time in iterator:
  File "/home/bigdata/venv/lib64/python3.9/site-packages/ical_library/help_modules/property_utils.py", line 252, in expand_component_in_range
    for rrule_time in iterator:
  File "/home/bigdata/venv/lib64/python3.9/site-packages/ical_library/help_modules/property_utils.py", line 129, in _yield_rrule_list
    for rrule_time in iterator:
  File "/home/bigdata/venv/lib64/python3.9/site-packages/ical_library/ical_properties/rrule.py", line 275, in sequence_iterator
    raise ValueError(f"This should not be the case: {starting_datetime=} >= {max_datetime=} .")
ValueError: This should not be the case: starting_datetime=Date(2023, 3, 8) >= max_datetime=Date(2023, 3, 8) .

Corresponding VEvent:

BEGIN:VEVENT
DTSTART;VALUE=DATE:20230308
DTEND;VALUE=DATE:20230315
DTSTAMP:20230208T071445Z
UID:[email protected]
ATTENDEE;CUTYPE=INDIVIDUAL;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;[email protected];X-NUM-GUESTS=0:mailto:[email protected]
RECURRENCE-ID;VALUE=DATE:20230308
CREATED:20220223T123118Z
DESCRIPTION:
LAST-MODIFIED:20230118T224003Z
LOCATION:
SEQUENCE:3
STATUS:CONFIRMED
SUMMARY:Data Duty 24/7:  @abc
TRANSP:TRANSPARENT
END:VEVENT
BEGIN:VEVENT
DTSTART;VALUE=DATE:20230308
DTEND;VALUE=DATE:20230315
RRULE:FREQ=WEEKLY;WKST=MO;COUNT=4;INTERVAL=12;BYDAY=WE
DTSTAMP:20230208T071445Z
UID:[email protected]
ATTENDEE;CUTYPE=INDIVIDUAL;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;[email protected];X-NUM-GUESTS=0:mailto:[email protected]
CREATED:20220223T123118Z
DESCRIPTION:
LAST-MODIFIED:20230118T224003Z
LOCATION:
SEQUENCE:3
STATUS:CONFIRMED
SUMMARY:Data Duty 24/7:  @abc
TRANSP:TRANSPARENT
X-APPLE-TRAVEL-ADVISORY-BEHAVIOR:AUTOMATIC
BEGIN:VALARM
ACTION:AUDIO
TRIGGER:-PT15H
X-WR-ALARMUID:9C6E4D2C-0153-4CE9-8121-FCB2933FF375
UID:9C6E4D2C-0153-4CE9-8121-FCB2933FF375
ATTACH;VALUE=URI:Chord
X-APPLE-DEFAULT-ALARM:TRUE
ACKNOWLEDGED:20221011T075815Z
END:VALARM
END:VEVENT

Recurring events keep their offset, even though timezone offset changed over time

A minimal example where it goes wrong. The iCalendar shows below yields the following recurrence;

  • 2022-10-18 12:00:00 +02:00
  • 2022-10-25 12:00:00 +02:00
  • 2022-11-01 12:00:00 +02:00 -> which equals 2022-11-01 11:00:00 in Amsterdam
  • 2022-11-08 12:00:00 +02:00 -> which equals 2022-11-01 11:00:00 in Amsterdam

The last two did not change their offset, which they should. Thereby the event appear an hour to early.

BEGIN:VCALENDAR
PRODID:-//Google Inc//Google Calendar 70.9054//EN
VERSION:2.0
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:Test iCal-library
X-WR-TIMEZONE:Europe/Amsterdam
X-WR-CALDESC:Calendar to test iCal-library
BEGIN:VTIMEZONE
TZID:Europe/Amsterdam
X-LIC-LOCATION:Europe/Amsterdam
BEGIN:DAYLIGHT
TZOFFSETFROM:+0100
TZOFFSETTO:+0200
TZNAME:CEST
DTSTART:19700329T020000
RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU
END:DAYLIGHT
BEGIN:STANDARD
TZOFFSETFROM:+0200
TZOFFSETTO:+0100
TZNAME:CET
DTSTART:19701025T030000
RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
DTSTART;TZID=Europe/Amsterdam:20221020T120000
DTEND;TZID=Europe/Amsterdam:20221020T170000
RRULE:FREQ=WEEKLY;BYDAY=TU
DTSTAMP:20221230T184331Z
UID:[email protected]
CREATED:20221020T074107Z
DESCRIPTION:
LAST-MODIFIED:20221023T072955Z
LOCATION:
SEQUENCE:1
STATUS:CONFIRMED
SUMMARY:No meetings please <3?
TRANSP:OPAQUE
END:VEVENT
END:VCALENDAR

Pendulum 3.0.0 breaks package

Hey there, first of all thank you so much for an amazing package. I've spent so long looking for something that handles recurring events well.

When installing via pip install iCal-library v3.0.0 of Pendulum gets installed. When attempting to use the package the following error is thrown:

ImportError: cannot import name 'Period' from 'pendulum' (/Users/dsalib/Developer/oasis/venv/lib/python3.9/site-packages/pendulum/__init__.py)

I resolved this by pinning to v2.1.1 of Pendulum. You may want to do the same, or upgrade to support Pendulum v3.

Cheers!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.