[tobixen]

Disclaimer: Code and the text below the line are AI-generated, by Claude Opus 5.5.

---

Implements roadmap item 2.2, a backend for local iCalendar files.

• Layouts. Backend.open(path) picks the layout from the path:

  • a single .ics file;
  • a directory of collection directories, as vdirsyncer lays out a vdir;
  • one collection directory, as khal's path = names it.

  khal, todoman and vdirsyncer can share the same vdir. A path that cannot be a calendar is a ConfigurationError.

• Writes.

  • Every write goes through a temporary file, keeping the file's mode and any symlink.
  • A vdir create never overwrites another object, and does not store a UID twice when two writers race.
  • A single file is locked (filelock, a new dependency) around each write.
  • The etags of API_DESIGN §7 catch a file edited behind the backend's back.

• Async. In the async mode, file I/O runs in worker threads, through a new ato_thread helper whose sync twin is a plain call.

• Capabilities.

  • A collection made for fewer than all components records them in a hidden .calendaring-components file, since the vdir spec has no place for it.
  • time-log is unsupported in a collection holding no events.

• Tests. The conformance suite passes in all three layouts and both modes.

• A separate commit records the decision that occurrence edits and recurring-task completion go to edit-icalendar, superseding Proposal: helpers for completing one occurrence of a recurring VTODO (and editing one occurrence) niccokunzmann/python-recurring-ical-events#292. Until edit-icalendar has them, every backend declares them UNSUPPORTED. The capability notes for them, and for time-log without events, are now public constants in calendaring.capabilities.

Left for later:

• A UID index for large vdirs (each create scans the collection), watching the directory for changes, and a read-only mode over several .ics files.
• Windows: os.replace while a reader holds the file open is untested, since CI runs on Linux.

🤖 Generated with Claude Code