{"id":5536,"library":"types-icalendar","title":"Typing Stubs for icalendar","description":"The `types-icalendar` package provides type annotations (stubs) for the `icalendar` library, which is an RFC 5545 compliant Python parser and generator for iCalendar files. This package is part of the `typeshed` project and specifically targets `icalendar` versions prior to 7.0.0. From `icalendar` version 7.0.0 onwards, type annotations are included directly within the `icalendar` package, making `types-icalendar` redundant for newer versions. It currently requires Python >=3.10 and is updated regularly based on typeshed contributions.","status":"active","version":"6.3.2.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed/tree/main/stubs/icalendar","tags":["typing","stubs","icalendar","calendar","typeshed","rfc5545","datetime"],"install":[{"cmd":"pip install types-icalendar","lang":"bash","label":"Install types-icalendar"},{"cmd":"pip install icalendar==6.3.2","lang":"bash","label":"Install compatible icalendar runtime library"}],"dependencies":[{"reason":"This package provides type stubs for the `icalendar` library, which is required at runtime.","package":"icalendar","optional":false},{"reason":"Transitive dependency of `icalendar` for date/time parsing and manipulation.","package":"python-dateutil","optional":false},{"reason":"Transitive dependency of `icalendar` for timezone information, especially when using Python's `zoneinfo` module.","package":"tzdata","optional":false}],"imports":[{"symbol":"Calendar","correct":"from icalendar import Calendar"},{"symbol":"Event","correct":"from icalendar import Event"},{"note":"Type stubs are not meant for direct import at runtime; import symbols from the runtime library (`icalendar`).","wrong":"from types_icalendar import vDatetime","symbol":"vDatetime","correct":"from icalendar import vDatetime"}],"quickstart":{"code":"from icalendar import Calendar, Event, vText\nfrom datetime import datetime\nimport zoneinfo\n\n# Create a new Calendar object\ncal = Calendar()\ncal.add('prodid', '-//My Company//My Calendar App//EN')\ncal.add('version', '2.0')\ncal.add('summary', 'My Awesome Calendar')\n\n# Create an Event\nevent = Event()\nevent.add('summary', 'Meeting with Client X')\nevent.add('dtstart', datetime(2026, 4, 15, 10, 0, 0, tzinfo=zoneinfo.ZoneInfo('America/New_York')))\nevent.add('dtend', datetime(2026, 4, 15, 11, 0, 0, tzinfo=zoneinfo.ZoneInfo('America/New_York')))\nevent.add('description', 'Discuss Q2 strategy and project roadmap.')\nevent.add('location', vText('Conference Room A'))\nevent['uid'] = '20260415T100000-abcd-1234@example.com'\n\n# Add the event to the calendar\ncal.add_component(event)\n\n# Serialize the calendar to iCalendar format\nical_string = cal.to_ical().decode('utf-8')\nprint(ical_string)\n\n# Example of parsing an iCalendar string\n# parsed_cal = Calendar.from_ical(ical_string)\n# for component in parsed_cal.walk():\n#    if component.name == 'VEVENT':\n#        print(component.get('summary'))","lang":"python","description":"This quickstart demonstrates how to create a basic iCalendar file with an event using the `icalendar` library, for which `types-icalendar` provides type hints. It covers initializing a calendar, adding essential properties, creating and populating an event, and then serializing the calendar to a string. Note the use of `zoneinfo` for timezone-aware datetimes, which is crucial for iCalendar compatibility."},"warnings":[{"fix":"Uninstall `types-icalendar`: `pip uninstall types-icalendar`. Ensure `icalendar` is up to date: `pip install --upgrade icalendar`.","message":"If using `icalendar` version 7.0.0 or newer, `types-icalendar` should be uninstalled. `icalendar` now includes its own type annotations, which can cause conflicts or redundancy with `types-icalendar`.","severity":"breaking","affected_versions":"icalendar >= 7.0.0"},{"fix":"Upgrade to Python 3.10 or newer. Ensure your `icalendar` version matches the `types-icalendar` target (e.g., `icalendar==6.3.2` for `types-icalendar==6.3.2.20260408`).","message":"The `icalendar` runtime library, for which `types-icalendar` provides stubs, dropped support for Python 3.8 and 3.9 in `icalendar` version 7.0.3. The `types-icalendar` package itself requires Python >=3.10, aligning with the current `icalendar` branch it supports (e.g., `icalendar==6.3.2`).","severity":"breaking","affected_versions":"icalendar < 7.0.3 and Python < 3.10"},{"fix":"Update code to expect a string return type from `Component.decoded()` for text properties. If supporting both old and new `icalendar` versions, check `isinstance()` for compatibility.","message":"In `icalendar` versions prior to 7.0.3, the `Component.decoded()` method for text properties returned bytes. From version 7.0.3 onwards, it returns a string. Code relying on the byte return type will break if `icalendar` is updated.","severity":"gotcha","affected_versions":"icalendar < 7.0.3"},{"fix":"Always add `cal.add('prodid', '...')` and `cal.add('version', '2.0')` when creating a new `Calendar` object.","message":"According to RFC 5545, `Calendar` objects in `icalendar` require `PRODID` and `VERSION` properties. Forgetting to add these can lead to invalid iCalendar files, even if the code type-checks. Newer `icalendar` versions (e.g., 7.0.0+) may provide enhanced methods for automatic `PRODID` generation.","severity":"gotcha","affected_versions":"All versions of icalendar"},{"fix":"Always use timezone-aware `datetime` objects (e.g., `datetime(..., tzinfo=zoneinfo.ZoneInfo('Europe/Berlin'))`) for event start/end times to ensure correct iCalendar output and parsing.","message":"Incorrect handling of timezones with `datetime` objects can lead to silently corrupted or invalid iCalendar data. `icalendar` supports multiple timezone implementations (e.g., `zoneinfo`, `dateutil.tz`, `pytz`). Using naive `datetime` objects for `dtstart` or `dtend` without proper timezone information is a common mistake.","severity":"gotcha","affected_versions":"All versions of icalendar"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}