How-To Guides

Editing Calendar Data

Calendar objects (events, todos, journals) can be accessed and modified using the icalendar or vobject libraries.

Reading Data

For read-only access, use methods that return copies:

# Get raw iCalendar string
data = event.get_data()

# Get icalendar object (a copy - safe to inspect)
ical = event.get_icalendar_instance()
for comp in ical.subcomponents:
    print(comp.get("SUMMARY"))

# Get vobject object (a copy)
vobj = event.get_vobject_instance()

Modifying Data

To edit an object, use context managers that “borrow” the object:

# Edit using icalendar
with event.edit_icalendar_instance() as cal:
    for comp in cal.subcomponents:
        if comp.name == "VEVENT":
            comp["SUMMARY"] = "New summary"
event.save()

# Edit using vobject
with event.edit_vobject_instance() as vobj:
    vobj.vevent.summary.value = "New summary"
event.save()

While inside the with block, the object is exclusively borrowed. Attempting to borrow a different representation will raise RuntimeError.

Quick Access

For simple read access, use the component property:

# Read properties
summary = event.component["SUMMARY"]
start = event.component.start

Backing Up a Calendar

Use caldav.get_calendar() (available since v2.0) to fetch all objects from a specific calendar and write them to disk:

import pathlib
from caldav import get_calendar

backup_dir = pathlib.Path("backup")
backup_dir.mkdir(exist_ok=True)

with get_calendar(calendar_name="Work") as cal:
    for obj in cal.search():
        uid = obj.icalendar_instance.subcomponents[0]["UID"]
        (backup_dir / f"{uid}.ics").write_text(obj.data)

To restore, iterate over the saved .ics files and call cal.add_event() (or add_todo()/add_journal() as appropriate).

For more on server-specific connection details and known incompatibilities, see Compatibility and Some notes on CalDAV URLs.