iCalendar

Warnings

• breaking In v7.0.0, the `from_ical` method on `Calendar`, `Event`, and other components now expects a string (`str`) or bytes (`bytes`) object directly, instead of a file-like object.
  Fix: If you were reading from a file, explicitly read the content into a string or bytes first: `ical_data = file.read(); cal = Calendar.from_ical(ical_data)`.
• breaking Version 7.0.0 introduced significant changes to how datetime objects are handled, aligning more strictly with Python's standard `datetime` module. Floating datetimes (without `tzinfo`) are now treated as UTC by default if no `TZID` is specified.
  Fix: Always use timezone-aware `datetime` objects, preferably `datetime.timezone.utc`, when adding event times to avoid ambiguity and ensure correct RFC 5545 compliance.
• gotcha Incorrect timezone handling is a common source of errors. If datetimes are not timezone-aware, `icalendar` might make assumptions (e.g., UTC) that don't match your intended local time.
  Fix: Explicitly provide `tzinfo` for all `datetime` objects, e.g., using `datetime.datetime.now(datetime.timezone.utc)` or `datetime.datetime(..., tzinfo=zoneinfo.ZoneInfo('America/New_York'))` (Python >=3.9). For older Python, `pytz` is commonly used.
• breaking In v5.0.0, `vDDDTypes` (used for date/datetime/duration properties) is no longer directly callable. Instead, you must use its static methods `vDDDTypes.from_str()` for parsing and `vDDDTypes.to_ical()` for serialization.
  Fix: Update calls from `vDDDTypes(value)` to `vDDDTypes.from_str(value)` or directly use `component.add('property', value)` for common cases where `icalendar` handles the type conversion automatically.

Install

• pip install icalendar Install stable version

Imports

• Calendar

  from icalendar import Calendar

• Event

  from icalendar import Event

• vRecur

  from icalendar import vRecur

  Used for defining recurrence rules for events.
• vDDDTypes

  from icalendar import vDDDTypes

  A class for handling iCalendar datetime/date/duration types, especially for advanced parsing/serialization.

Quickstart

This quickstart demonstrates how to create an iCalendar object with an event and a recurrence rule, serialize it to an iCalendar string, and then parse that string back into a Python object to extract event details.

import datetime
from icalendar import Calendar, Event, vRecur

# --- Create an iCalendar ---
cal = Calendar()
cal.add('prodid', '-//My Organisation//Example Calendar App//EN')
cal.add('version', '2.0')

event = Event()
event.add('summary', 'Team Standup')
# Always use timezone-aware datetimes for iCalendar
event.add('dtstart', datetime.datetime(2024, 7, 10, 9, 0, 0, tzinfo=datetime.timezone.utc))
event.add('dtend', datetime.datetime(2024, 7, 10, 9, 15, 0, tzinfo=datetime.timezone.utc))
event.add('dtstamp', datetime.datetime.now(datetime.timezone.utc))
event['uid'] = 'event_20240710_standup@example.com'
event.add('location', 'Online Meeting Room')

# Add a recurrence rule (e.g., daily for 5 occurrences)
rrule = vRecur({'freq': ['DAILY'], 'count': [5]})
event.add('rrule', rrule)

cal.add_component(event)

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

# --- Parse an iCalendar ---
print("\n--- Parsed iCalendar ---")
parsed_cal = Calendar.from_ical(ical_string)
for component in parsed_cal.walk():
    if component.name == 'VEVENT':
        print(f"Summary: {component.get('summary')}")
        print(f"Start: {component.get('dtstart').dt}")
        print(f"End: {component.get('dtend').dt}")
        if 'rrule' in component:
            print(f"Recurrence Rule: {component.get('rrule')}")