Typing Stubs for icalendar

Warnings

• breaking 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`.
  Fix: Uninstall `types-icalendar`: `pip uninstall types-icalendar`. Ensure `icalendar` is up to date: `pip install --upgrade icalendar`.
• breaking 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`).
  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`).
• gotcha 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.
  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.
• gotcha 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.
  Fix: Always add `cal.add('prodid', '...')` and `cal.add('version', '2.0')` when creating a new `Calendar` object.
• gotcha 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.
  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.

Install

• pip install types-icalendar Install types-icalendar
• pip install icalendar==6.3.2 Install compatible icalendar runtime library

Imports

• Calendar

  from icalendar import Calendar

• Event

  from icalendar import Event

• vDatetime

  from icalendar import vDatetime

  Type stubs are not meant for direct import at runtime; import symbols from the runtime library (`icalendar`).

Quickstart

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.

from icalendar import Calendar, Event, vText
from datetime import datetime
import zoneinfo

# Create a new Calendar object
cal = Calendar()
cal.add('prodid', '-//My Company//My Calendar App//EN')
cal.add('version', '2.0')
cal.add('summary', 'My Awesome Calendar')

# Create an Event
event = Event()
event.add('summary', 'Meeting with Client X')
event.add('dtstart', datetime(2026, 4, 15, 10, 0, 0, tzinfo=zoneinfo.ZoneInfo('America/New_York')))
event.add('dtend', datetime(2026, 4, 15, 11, 0, 0, tzinfo=zoneinfo.ZoneInfo('America/New_York')))
event.add('description', 'Discuss Q2 strategy and project roadmap.')
event.add('location', vText('Conference Room A'))
event['uid'] = '20260415T100000-abcd-1234@example.com'

# Add the event to the calendar
cal.add_component(event)

# Serialize the calendar to iCalendar format
ical_string = cal.to_ical().decode('utf-8')
print(ical_string)

# Example of parsing an iCalendar string
# parsed_cal = Calendar.from_ical(ical_string)
# for component in parsed_cal.walk():
#    if component.name == 'VEVENT':
#        print(component.get('summary'))