Welcome to iCalEvents’s documentation!

Simple Python 3 library to download, parse and query iCal sources.

Usage

iCloud:

from icalevents.icalevents import events

es  = events(<iCloud URL>, fix_apple=True)

Google:

from icalevents.icalevents import events

es  = events(<Google Calendar URL>)

Example

see main.py

from icalevents.icalevents import events_async, latest_events, all_done
from time import sleep

if __name__ == '__main__':
   keys = []

   with open('calendars.txt', mode='r', encoding='utf-8') as f:
      counter = 1

      while True:
            line = f.readline()
            if not line:
               break

            name, url = line.split(maxsplit=1)
            name = name.strip()
            url = url.strip()

            fix_apple = False
            if name == 'icloud':
               fix_apple = True

            key = "req_%d" % counter
            counter += 1
            keys.append(key)
            events_async(key, url, fix_apple=fix_apple)

   while keys:
      print("%d request running." % len(keys))

      for k in keys[:]:
            if all_done(k):
               print("Request %s finished." % k)
               keys.remove(k)

               es = latest_events(k)

               for e in es:
                  print(e)

      sleep(2)

API

Module contents

iCalEvents search all events occurring in a given time frame in an iCal file.

Submodules

icalevents.icaldownload module

Downloads an iCal url or reads an iCal file.

class icalevents.icaldownload.ICalDownload(http=None, encoding='utf-8')

Bases: object

Downloads or reads and decodes iCal sources.

data_from_file(file, apple_fix=False)

Read iCal data from file.

Parameters:

  • file – file to read

  • apple_fix – fix wrong Apple tzdata in iCal

Returns:

decoded (and fixed) iCal data

data_from_string(string_content, apple_fix=False)
data_from_url(url, apple_fix=False)

Download iCal data from URL.

Parameters:

  • url – URL to download

  • apple_fix – fix Apple bugs (protocol type and tzdata in iCal)

Returns:

decoded (and fixed) iCal data

decode(content, apple_fix=False)

Decode content using the set charset.

Parameters:

  • content – content do decode

  • apple_fix – fix Apple txdata bug

Returns:

decoded (and fixed) content

icalevents.icaldownload.apple_data_fix(content)

Fix Apple tzdata bug.

Parameters:

content – content to fix

Returns:

fixed content

icalevents.icaldownload.apple_url_fix(url)

Fix Apple URL.

Parameters:

url – URL to fix

Returns:

fixed URL

icalevents.icalevents module

icalevents.icalevents.all_done(key)

Check if requests for the given key are active.

Parameters:

key – key for requests

Returns:

True if requests are pending or active

icalevents.icalevents.events(url=None, file=None, string_content=None, start=None, end=None, fix_apple=False, http=None, tzinfo=None, sort=None, strict=False) → list[Event]

Get all events form the given iCal URL occurring in the given time range.

Parameters:

  • url – iCal URL

  • file – iCal file path

  • string_content – iCal content as string

  • start – start date (see datetime.date)

  • end – end date (see datetime.date)

  • fix_apple – fix known Apple iCal issues

  • tzinfo – return values in specified tz

  • sort – sort return values

  • strict – return dates, datetimes and datetime with timezones as specified in ical

:sort sorts events by start time

:return events

icalevents.icalevents.events_async(key, url=None, file=None, start=None, string_content=None, end=None, fix_apple=False)

Trigger an asynchronous data request.

Parameters:

  • key – key for data source to get result later

  • url – iCal URL

  • file – iCal file path

  • string_content – iCal content as string

  • start – start date

  • end – end date

  • fix_apple – fix known Apple iCal issues

icalevents.icalevents.latest_events(key)

Get the latest downloaded events for the given key.

Returns:

events for key

icalevents.icalevents.request_data(key, url, file, string_content, start, end, fix_apple)

Request data, update local data cache and remove this Thread from queue.

Parameters:

  • key – key for data source to get result later

  • url – iCal URL

  • file – iCal file path

  • string_content – iCal content as string

  • start – start date

  • end – end date

  • fix_apple – fix known Apple iCal issues

icalevents.icalevents.request_finished(key)

Remove finished Thread from queue.

Parameters:

key – data source key

icalevents.icalevents.update_events(key, data)

Set the latest events for a key.

Parameters:

  • key – key to set

  • data – events for key

icalevents.icalparser module

Parse iCal data to Events.

class icalevents.icalparser.Attendee(address)

Bases: str

property params
class icalevents.icalparser.Event

Bases: object

Represents one event (occurrence in case of reoccurring events).

astimezone(tzinfo)
copy_to(new_start=None, uid=None)

Create a new event equal to this with new start date.

Parameters:

  • new_start – new start date

  • uid – UID of new event

Returns:

new event

time_left(time=None)

timedelta form now to event.

Returns:

timedelta from now

icalevents.icalparser.create_event(component, strict)

Create an event from its iCal representation.

Parameters:

  • component – iCal component

  • strict

Returns:

event

icalevents.icalparser.encode(value: vText | None) → str | None
icalevents.icalparser.extract_exdates(component)

Compile a list of all exception dates stored with a component.

Parameters:

component – icalendar iCal component

Returns:

list of exception dates

icalevents.icalparser.get_timezone(tz_name)
icalevents.icalparser.now()

Get current time.

Returns:

now as datetime with timezone

icalevents.icalparser.parse_events(content, start=None, end=None, default_span=datetime.timedelta(days=7), tzinfo=None, sort=False, strict=False)

Query the events occurring in a given time range.

Parameters:

  • content – iCal URL/file content as String

  • start – start date for search, default today (in UTC format)

  • end – end date for search (in UTC format)

  • default_span – default query length (one week)

Returns:

events as list

icalevents.icalparser.parse_rrule(component)

Extract a dateutil.rrule object from an icalendar component. Also includes the component’s dtstart and exdate properties. The rdate and exrule properties are not yet supported.

Parameters:

component – icalendar component

Returns:

extracted rrule or rruleset or None