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: PoolManager | None = None)

Bases: object

Downloads or reads and decodes iCal sources.

data_from_file(file: str | Path, apple_fix: bool = False) → str

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: bytes | str, apple_fix: bool = False) → str

data_from_url(url: str, apple_fix: bool = False) → str

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

static decode(content: bytes | str, encoding: str = 'utf-8', apple_fix: bool = False) → str

Decode content using the set charset.

Parameters:

• content – content do decode

• encoding – the used charset for decoding the content

• apple_fix – fix Apple txdata bug

Returns:

decoded (and fixed) content

icalevents.icaldownload.apple_data_fix(content: str) → str

Fix Apple tzdata bug.

Parameters:

content – content to fix

Returns:

fixed content

icalevents.icaldownload.apple_url_fix(url: str) → str

Fix Apple URL.

Parameters:

url – URL to fix

Returns:

fixed URL

icalevents.icalevents module

icalevents.icalevents.all_done(key: str) → bool

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: str | None = None, file: str | Path | None = None, string_content: bytes | str | None = None, start: datetime | None = None, end: datetime | None = None, fix_apple: bool = False, http: PoolManager | None = None, tzinfo: tzinfo | None = None, sort: bool = False, strict: bool = 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: str, url: str | None = None, file: str | Path | None = None, start: datetime | None = None, string_content: bytes | str | None = None, end: datetime | None = None, fix_apple: bool = False) → None

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: str) → list[Event]

Get the latest downloaded events for the given key.

Returns:

events for key

icalevents.icalevents.request_data(key: str, url: str | None, file: str | Path | None, string_content: bytes | str | None, start: datetime | None, end: datetime | None, fix_apple: bool) → None

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: str) → None

Remove finished Thread from queue.

Parameters:

key – data source key

icalevents.icalevents.update_events(key: str, data: list[Event]) → None

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: str)

Bases: str

property params

class icalevents.icalparser.Event

Bases: object

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

astimezone(tzinfo: tzinfo) → Event

copy_to(new_start: datetime | None = None, uid: str | None = None) → Event

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: datetime | None = None) → timedelta

timedelta form now to event.

Returns:

timedelta from now

icalevents.icalparser.create_event(component: Component, strict: bool) → Event

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: Component) → list[datetime]

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: str) → tzinfo | None

icalevents.icalparser.now() → datetime

Get current time.

Returns:

now as datetime with timezone

icalevents.icalparser.parse_events(content: str, start: datetime | None = None, end: datetime | None = None, default_span: timedelta = datetime.timedelta(days=7), tzinfo: tzinfo | None = None, sort: bool = False, strict: bool = 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: 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