Improvements, test code and documentation needed for editing and selecting recurrence instances

[tobixen]

Ref #35 (comment) and below

[tobixen]

Some thoughts ...

Below, those definitions apply:

• All instances of the word Event below may be substituted with any subclass of CalendarObjectResource, such as Todo. (Event is easy to type and easy to understand, very few cares about Journal, most users should not need to know what a CalendarObjectResource is, etc). Some goes with VEVENT, can be substituted with VTODO.
• A "recurring event" may be the daily lunch eaten in the local canteen in the office every Monday-Friday. It is an event with RRULE set in the icalendar data, while RECURRENCE-ID is not set. It's the basis (template) for all recurrence instances. (We can immediately see a problem here - every country has certain dates that are defined as "banking holidays". Like, if I've understood things correct, in the UK the King/Queen always happens to have birthday on a Monday, and on that Monday nobody eats lunch in the canteen).
• A "recurrence instance" is a single instance of a recurring event, such as a lunch on a specific day (the VEVENT contains no RRULE, but does contain a RECURRENCE-ID)..
• An "auto-generated recurrence instance" is a completely ordinary lunch on a specific date, and it exists only on the client side (unless it's saved back to the server). It is generated by setting the expand-flag to True in the search-method. Currently the expanding will by default take place on the server side if the server supports it, otherwise on the client side (this will at some point be carefully changed to always happen on the client side).
• A "special recurrence instance" represents a variation of the regular instance, i.e. an external customer added to the invitee list on a specific date, or something is to be celebrated and the lunch is being held on an external resturant on another date.

An Event-object can contain quite some different things (binary number representing suggested new check-methods below):

• No data at all (the object was not loaded or could not be loaded) = 000
• A completely ordinary, non-recurring event = 100
• A recurring event, not including any recurrence instances (there are no specials, and the event is not expanded) = 110
• A recurring event, with specials included (I suppose this named a "recurrence-set" in some RFCs). = 011
• A singe recurrence instance (special or auto-generated) = 101
• A set of recurrence instances for some specific time range, including all recurrence instances for the time range, but not including the recurring event itself = 001

There needs to be methods on the Event to easily check what kind of data the Event contains (perhaps is_single, contains_recurring, contains_recurrence_instance. That's three booleans, represented by the binary in the list above. Note that 111 and 010 are an invalid combinations.

When encountering recurring events, the search-method will act differently depending on weather the flags split_expanded and expanded are set. Both are True by default (if a date range is given in the search). In the "split expand"-mode, recurrence instances are yielded as separate Event-objects (a list will be returned containing 100 and 101 type of Events). When expand is set, but split_expanded is not set, a set of recurrence instances may be yielded (001 - with 101 and 100 also being valid dependent on what kind of data exists on the server).

What if split_expanded is set and expand is not set? It still ought to return every recurrence instance in separate Event-objects, but I don't think I had it on the radar while the code was written, so we need test code for this case. Does the current expand-code support special recurrence instances? I believe it's needed to write test code for this.

split_expanded is specific for the search-method, but all methods returning Events should have this functionality built-in. The flag should be renamed, split_recurrences seems like a good idea - and of course, search should still support the deprecated split_expanded-flag until 3.0 is released.

A library client that wants to edit a recurrence instance should be able to do it regardless on weather the Event-object is of type 101 or 011. For sure 011 works today, 101 needs to be tested (it may be that different servers behaves differently, then it would probably be appropriate to have client logic converting the 101 into an 011.

Same goes when a library client wants to create a new special recurrence instance. It should be doable by editing an autogenerated 101 and saving it, or by adding it to the icalendar data of a 011.

Deleting a recurrence instance (see #35) is not very well defined, if running Event.delete on a 101, it should possibly raise an error rather than doing something potentially harmful. (Today I think it will delete the whole recurrence-set, that's definitively not what one wants). At the other hand, a traceback is likely to blow up on some end-user sooner or later, probably setting the status to CANCELLED would be the better idea.

Today we have a property icalendar_component which is very useful for the 1xx-cases, but will do the completely wrong thing for 0xx.. The usage of icalendar_component is recommended in the documentation. I'm not sure what to do with this. Possibly to let a list of 1xx be the default return type of any methods returning an Event and to be very clear in the documentation about the issues with icalendar_component. This change may possibly be introduced carefully from version 2.0 by deprecating the current API and writing a new API.

[tobixen]

Related to #379 and possibly #397

[tobixen]

Here are some "thoughts" from Claude. I think it glosses over some of the complexity wrg of "deleting a recurrence". I also believe it's important to create the helper methods before starting with the more complex issues.

Issue #398 Analysis: CalDAV Recurrence Instance Management

Date: 2025-12-03
Issue URL: #398
Status: Open (Milestone 3.0)

Issue Summary

This task addresses improvements needed for handling recurring calendar events in the python-caldav library, specifically for editing and selecting recurrence instances. The core problem involves inconsistent handling of recurrence instances—individual occurrences of repeating events—across different scenarios and server implementations.

---

Is it still relevant?

YES - This is a significant issue that affects core functionality and user safety when working with recurring events.

---

Current State

What exists:

1. ✅ Basic recurrence support - save/load recurring events with RRULE
2. ✅ Search with expansion - expand=True and split_expanded=True parameters
3. ✅ Some editing of single recurrence instances - testEditSingleRecurrence exists in test_caldav.py
4. ✅ CheckRecurrenceSearch in caldav-server-tester tests recurrence search features
5. ✅ RECURRENCE-ID handling in save() method with only_this_recurrence parameter

What's missing or problematic:

1. ❌ No helper methods to identify Event object types (is_single, contains_recurring, contains_recurrence_instance)
2. ❌ Dangerous delete() behavior - deleting a single recurrence instance may delete the entire series
3. ❌ Incomplete testing for split_expanded combinations
4. ❌ No server compatibility features for recurrence instance editing/deletion
5. ❌ No tests in caldav-server-tester for editing or deleting recurrence instances
6. ❌ Poor documentation about Event object states and appropriate usage patterns

---

Key Problems Identified in Issue

1. Event Type Classification System

The library doesn't clearly distinguish between different Event object types. The issue proposes binary classifications:

• "No data" (000)
• "Non-recurring event" (100)
• "Recurring event without instances" (110)
• "Recurring event with special instances" (011)
• "Single recurrence instance" (101)
• "Set of instances for time range" (001)

Suggested methods: is_single, contains_recurring, contains_recurrence_instance

2. Incomplete Search Method Functionality

The search() method's handling of split_expanded and expand flags needs comprehensive testing:

• Cases where split_expanded=True but expand=False lack test coverage
• Support for "special recurrence instances" (variations like external attendees or location changes) requires validation

3. Recurrence Instance Editing Limitations

• Editing type 101 (single instance) objects needs testing across different servers
• Creating new special instances from auto-generated instances lacks proper implementation
• May require client-side logic converting single instances into recurrence-sets

4. Deletion Safety Concerns

CRITICAL: Calling Event.delete() on a single recurrence instance currently risks deleting the entire recurring event series instead of just that instance.

Proposed solution: Set status to CANCELLED rather than full deletion.

5. Documentation and API Clarity

The icalendar_component property behaves incorrectly for certain data states. Documentation needs clarification about appropriate usage patterns and API deprecation strategy.

---

Proposed Actions

Priority 1: Safety - Fix delete() behavior

CRITICAL for data safety

1. Add feature save-load.event.recurrence-instance.delete to compatibility_hints.py to track server support
2. Modify delete() method in davobject.py to check for RECURRENCE-ID and handle it safely:
   • Option A: Set STATUS to CANCELLED instead of deleting (safest)
   • Option B: Add EXDATE to parent event
   • Option C: Raise error and require explicit parameter like delete_entire_series=True
3. Add tests in caldav-server-tester to detect how different servers handle recurrence instance deletion

Estimated effort: Medium (2-3 days)

Priority 2: Discoverability - Add helper methods

Improves developer experience

1. Add to CalendarObjectResource class in calendarobjectresource.py:

   def is_single_event(self) -> bool:
       """Returns True if this is a non-recurring event"""
   
   def is_recurring_event(self) -> bool:
       """Returns True if this event has an RRULE"""
   
   def is_recurrence_instance(self) -> bool:
       """Returns True if this is a single instance with RECURRENCE-ID"""
   
   def has_recurrence_exceptions(self) -> bool:
       """Returns True if this recurring event has EXDATE or special instances"""

2. Add comprehensive docstrings explaining Event object states

3. Add property to get RECURRENCE-ID value easily

Estimated effort: Small (1 day)

Priority 3: Testing - Expand test coverage

Validates functionality across servers

1. Add tests for split_expanded=True, expand=False combinations
2. Add caldav-server-tester checks:
   • save-load.event.recurrence-instance.edit - Can edit single instance?
   • save-load.event.recurrence-instance.delete - Can delete single instance safely?
   • save-load.event.recurrence-instance.create - Can create exception from scratch?
3. Test across multiple server implementations to identify compatibility issues

Estimated effort: Medium (2-3 days)

Priority 4: Documentation

Essential for users to understand the complexity

1. Add comprehensive guide to docs/ explaining recurring event types
2. Document split_expanded vs expand behavior clearly with examples
3. Add cookbook examples for common recurrence patterns:
   • Editing a single instance
   • Cancelling a single instance
   • Creating an exception with different time/location
   • Updating all future instances
4. Add migration guide if API changes are needed

Estimated effort: Medium (2 days)

---

Recommended Implementation Order

1. First (Safety): Add the delete() safety check and basic feature detection

   • Prevents data loss
   • Can be done incrementally without breaking changes

2. Second (Foundation): Add helper methods for event type detection

   • Makes the API more discoverable
   • Helps users write safer code

3. Third (Validation): Add caldav-server-tester checks for recurrence instance operations

   • Identifies server compatibility issues
   • Informs which workarounds are needed

4. Fourth (Polish): Improve documentation and add more comprehensive tests

   • Educates users on best practices
   • Reduces support burden

---

Server Compatibility Considerations

Different CalDAV servers handle recurrence instances differently:

• Some servers automatically handle EXDATE when deleting an instance
• Some require explicit CANCELLED status
• Some don't support editing instances at all
• Some have bugs with RECURRENCE-ID matching

The caldav-server-tester framework should detect these differences and set appropriate compatibility flags.

---

Risk Assessment

High Risk (Must Address):

• delete() data loss - Users could accidentally delete entire event series

Medium Risk:

• Inconsistent behavior across servers - Users get unpredictable results
• Poor error messages - Users don't understand what went wrong

Low Risk:

• Documentation gaps - Users can figure it out with trial and error
• Missing helper methods - Users can check properties directly

---

Conclusion

This issue is definitely still relevant and should be addressed, particularly the delete() safety concern which could cause data loss. The recommended approach is to:

1. Start with safety fixes (Priority 1)
2. Add developer-friendly helper methods (Priority 2)
3. Expand test coverage to validate behavior (Priority 3)
4. Improve documentation (Priority 4)

This phased approach allows incremental progress while addressing the most critical issues first.

[tobixen]

This is a quite complex issue, I think it will probably slip the 3.0 milestone