iCalEvents

Warnings

• gotcha When fetching events from Apple iCal sources, issues with timezone data are common. Always consider using the `fix_apple=True` parameter in the `events()` function to mitigate these known inconsistencies.
  Fix: Pass `fix_apple=True` to the `events()` or `events_async()` calls.
• breaking iCalEvents relies on the `icalendar` library. `icalendar` version 7.x, released in February 2026, dropped support for Python 3.8 and 3.9. While `icalevents` 0.3.1 requires Python >=3.9, users with older `icalevents` versions or specific dependency setups might encounter `icalendar` compatibility issues if they upgrade `icalendar` to 7.x on Python 3.8/3.9.
  Fix: Ensure your Python environment is 3.10 or newer if using `icalendar` 7.x, or pin `icalendar` to a compatible older version (e.g., `<7.0.0`) if strictly needing Python 3.9 or older.
• gotcha Asynchronous event fetching with `events_async` requires a specific pattern: initiate with `events_async`, then repeatedly check `all_done(key)` until the request finishes, and finally retrieve results with `latest_events(key)`. Failing to follow this sequence can lead to incomplete data or blocking.
  Fix: Implement the full async pattern: `key = events_async(...)`, then `while not all_done(key): time.sleep(polling_interval)`, and finally `result = latest_events(key)`.
• gotcha External iCal calendar services (e.g., Google Calendar, iCloud) may have their own caching or synchronization delays. Changes made in the source calendar might not be immediately reflected when `icalevents` fetches the data, leading to stale information. This is an external service limitation, not a library bug.
  Fix: Account for potential delays by adjusting refresh intervals or informing users that real-time updates may not be guaranteed by the external service. Consider implementing mechanisms to force a refresh on the source calendar if available.

Install

• pip install icalevents Install latest version

Imports

• events

  from icalevents.icalevents import events

  The primary class for synchronous event fetching.
• events_async

  from icalevents.icalevents import events_async, latest_events, all_done

  For asynchronous event fetching, typically used with `all_done` and `latest_events`.

Quickstart

This quickstart demonstrates how to fetch and display iCalendar events from a given URL within a specific date range. It includes a placeholder for an iCal URL, emphasizing the need for a valid source. The `fix_apple=True` parameter is included as a common best practice when dealing with Apple iCal sources.

import os
from datetime import datetime, timedelta
from icalevents.icalevents import events

# Replace with your actual iCal URL, e.g., from Google Calendar or iCloud
ICAL_URL = os.environ.get('ICAL_SOURCE_URL', 'https://example.com/path/to/your/calendar.ics')

if not ICAL_URL or ICAL_URL == 'https://example.com/path/to/your/calendar.ics':
    print("Please set the ICAL_SOURCE_URL environment variable or replace the placeholder in the code.")
else:
    # Define a time range for events (e.g., next 7 days)
    start_date = datetime.now()
    end_date = start_date + timedelta(days=7)

    # Fetch events
    try:
        calendar_events = events(ICAL_URL, start=start_date, end=end_date, fix_apple=True)

        if calendar_events:
            print(f"Found {len(calendar_events)} events between {start_date.date()} and {end_date.date()}:")
            for event in calendar_events:
                print(f"- {event.summary} (Start: {event.start}, End: {event.end})")
        else:
            print("No events found in the specified range.")
    except Exception as e:
        print(f"Error fetching events: {e}")
        print("Ensure the ICAL_SOURCE_URL is correct and accessible.")