{"id":5962,"library":"icalevents","title":"iCalEvents","description":"iCalEvents is a simple Python 3 library designed to download, parse, and query iCalendar (iCal) sources. It provides functionalities for extracting event data, especially within specified time ranges, and handles recurring events. Maintained by Jazzband, its latest version (0.3.1) was released on September 26, 2025.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/jazzband/icalevents","tags":["ical","calendar","events","parser","sync","ics"],"install":[{"cmd":"pip install icalevents","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"icalevents is built on top of the icalendar library for iCal parsing.","package":"icalendar"}],"imports":[{"note":"The primary class for synchronous event fetching.","symbol":"events","correct":"from icalevents.icalevents import events"},{"note":"For asynchronous event fetching, typically used with `all_done` and `latest_events`.","symbol":"events_async","correct":"from icalevents.icalevents import events_async, latest_events, all_done"}],"quickstart":{"code":"import os\nfrom datetime import datetime, timedelta\nfrom icalevents.icalevents import events\n\n# Replace with your actual iCal URL, e.g., from Google Calendar or iCloud\nICAL_URL = os.environ.get('ICAL_SOURCE_URL', 'https://example.com/path/to/your/calendar.ics')\n\nif not ICAL_URL or ICAL_URL == 'https://example.com/path/to/your/calendar.ics':\n    print(\"Please set the ICAL_SOURCE_URL environment variable or replace the placeholder in the code.\")\nelse:\n    # Define a time range for events (e.g., next 7 days)\n    start_date = datetime.now()\n    end_date = start_date + timedelta(days=7)\n\n    # Fetch events\n    try:\n        calendar_events = events(ICAL_URL, start=start_date, end=end_date, fix_apple=True)\n\n        if calendar_events:\n            print(f\"Found {len(calendar_events)} events between {start_date.date()} and {end_date.date()}:\")\n            for event in calendar_events:\n                print(f\"- {event.summary} (Start: {event.start}, End: {event.end})\")\n        else:\n            print(\"No events found in the specified range.\")\n    except Exception as e:\n        print(f\"Error fetching events: {e}\")\n        print(\"Ensure the ICAL_SOURCE_URL is correct and accessible.\")","lang":"python","description":"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."},"warnings":[{"fix":"Pass `fix_apple=True` to the `events()` or `events_async()` calls.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"icalendar 7.x and above (indirectly affecting icalevents on Python <3.10)"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions with asynchronous features"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (due to external service behavior)"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}