How to handle deletion of a recurrence?

[embie27]

How to delete only a single occurrence of a recurring event? The delete()-method deletes every occurrence.

[tobixen]

Sorry the slow response.

Deleting a single instance of a recurring event is slightly nontrivial, see https://blog.jonudell.net/2008/08/28/specifying-exceptions-to-recurring-calendar-events/amp/ for details.

It is within the scope of the caldav library to support this somehow, but I will not have capacity to look into it anytime soon.

[tobixen]

It's probably several years still until I get time to deal with this.

The problem is as such: when running a .delete() on a recurrence instance (that is defined as a calendar event or todo having a recurrence-id set), then a DELETE-command is sent to the server on the URL. The problem is that the URL for the recurrence instance is the same as the URL for the recurring instance (and all other recurrence instance), hence everything will be deleted, and that's probably not what one wanted.

But what does one actually want to do when running DELETE on a recurrence instance?

• Does one want to cancel the instance? Then it's probably best and easiest to switch STATUS to CANCELLED.
• However, the proper thing to do is probably tu use the EXRULE property. "delete" and "cancel" are two slightly different things, "delete" means that he recurrence instance was never going to happen in the first place, cancel means that it was planned but got cancelled.
• A recurring instance is an exception to the general rule. Maybe a DELETE actually means that the exception should be deleted?
• Since the client library can't guess what the caller actually wants, perhaps the right thing to do is to throw an error?

Probably it's needed to specify with a separate optional parameter how to deal with recurrence instances - probably with the default being "raise an error".

And yes, this is a bit related to #379, because maybe it's needed to load the full recurrence set and put it back to the server to get things done correctly on all servers.

[julien4215]

I don't really know the subject but when I looked the references I saw that EXRULE is deprecated (https://icalendar.org/iCalendar-RFC-5545/a-3-deprecated-features.html). I guess that can be useful for the issue.

[ptrba]

Commenting on:

But what does one actually want to do when running DELETE on a recurrence instance?

I have a recurrent series of events but attendees are assigned only on specific instances of the series. The use case is, that I want to remove the assignment of the attendee(s). I came across the issue because I wanted to delete the event in this case. However, this is not needed, I can simply remove the attendee(s) an leave the event without attendees in the calendar.

[ptrba]

There seems to be a deeper issue here. On a related discussion from sabre dav https://groups.google.com/g/sabredav-discuss/c/M82DQRJTr4A?pli=1 they suggest to work on the level of 'calendar' rather than 'event' objects. Rather than fetching single events, icalendar.Calendar object can be fetched and modified.

This solves the problem of deleting single events from a recurrent series of events. Simply get the calendar object which contains the recurrent series and all possible modifications of single events. Then add/remove/update the corresponding items, then put the calendar object back.

Important, there are 2 concepts of calendars.

1. The calendar used by python-caldav as caldav.DAVClient(...).principal().calendar(). I call it parent here. This is not the calendar we are referring to.
2. There is an icalendar.Calendar object which is a container for multiple subcomponents. It is basically what you get if you fetch an .ics from a url. This is what we mean by calendar object in what follows.

python-caldav does not seem to support working with calendar objects directly, but it is easy to work around this. Here is a working example. Create a series where just one item has an attendee. In this example we first create the 2 corresponding events wrapped by a calendar object. Notice their identical uid. Tested with SOGo. The will be located at <base_url>/6B-664A5280-F-5B831280.ics.

data = """
BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
SUMMARY:recurrence with attendee one single item
DTSTART;TZID=Europe/Zurich:20240101T090000
DTEND;TZID=Europe/Zurich:20240101T180000
UID:6B-664A5280-F-5B831280
DESCRIPTION:this is the recurrent series
TRANSP:OPAQUE
RRULE:FREQ=WEEKLY;BYDAY=TU,WE,TH
END:VEVENT
BEGIN:VEVENT
SUMMARY:single item
DTSTART;TZID=Europe/Zurich:20240605T090000
DTEND;TZID=Europe/Zurich:20240605T170000
UID:6B-664A5280-F-5B831280
DESCRIPTION:this is the single item assigning a attendee to just one event
ATTENDEE:foo.bar@corge.baz
RECURRENCE-ID:20240605T070000Z
END:VEVENT
END:VCALENDAR
"""

parent = caldav.DAVClient(...).principal().calendar() 

ical_calendar = icalendar.Calendar.from_ical(data)

events = [event for event in ical_calendar.subcomponents if isinstance(event,icalendar.Event)]

assert len(events) == 2
assert events[0].get('RECURRENCE-ID') is None
assert events[1].get('RECURRENCE-ID').dt == datetime.datetime(2024,6,5,7,0,tzinfo=datetime.timezone.utc)

caldav.CalendarObjectResource(
    client=parent.client,
    data=ical_calendar.to_ical().decode('utf-8'),
    parent=parent
).save()

# Important, do not provide a comp_class here. If we put comp_class='Event' we will only receive
# one of the original 2 events
object_by_id = calendar_.calendar.object_by_uid('6B-664A5280-F-5B831280',comp_class=None)

# object_by_id is an event rather than a Calendar,
# but no problem, the desired calendar is present in the underlying data
ical_calendar_ = icalendar.Calendar.from_ical(object_by_id.data)

events = [event for event in ical_calendar_.subcomponents if isinstance(event,icalendar.Event)]
assert len(events) == 2
assert events[0].get('RECURRENCE-ID') is None
assert events[1].get('RECURRENCE-ID').dt == datetime.datetime(2024, 6, 5, 7, 0, tzinfo=datetime.timezone.utc)

ical_calendar__ = icalendar.Calendar()
ical_calendar__.add_component(events[0])

caldav.CalendarObjectResource(
    client=parent.client,
    data=ical_calendar__.to_ical().decode('utf-8'),
    parent=parent
).save()

object_by_id = calendar_.calendar.object_by_uid('6B-664A5280-F-5B831280', comp_class=None)
ical_calendar_ = icalendar.Calendar.from_ical(object_by_id.data)

events = [event for event in ical_calendar_.subcomponents if isinstance(event, icalendar.Event)]
assert len(events) == 1

python-caldav would definitely benefit from a better support for icalendar.calendar objects, but this is another issue.

[tobixen]

A "calendar" is a collection of events/tasks/journals. In the CalDAV specifications, it's defined to have a CalDAV URL and it supports operations like search, hence the caldav.Calendar class mirrors the CalDAV specification. In the icalendar definition it's possible to bundle together independent events/tasks/journals in a VCALENDAR-object, however the CalDAV protocol will return each event/task/journal as separate VCALENDAR-objects. The exception is with recurring tasks, there a VCALENDAR-object containing the base definition and the instances are returned.

What is probably poorly documented is that a caldav.Event-object in some cases may be a recurrent event with all the recurrence instance data included (and sometimes with the recurrence instance data autogenerated, either at the server side or client side), other times such an object may contain only a recurrence instance, and yet in other cases it may contain only the definition of the recurring event.

The Calendar.search-method has two relevant options, expand will autogenerate instances, and split_expanded will split each of those into separate Event-objects rather than including all the recurrence-instances in one Event-object. The latter is set to true by default.

# Important, do not provide a comp_class here. If we put comp_class='Event' we will only receive
# one of the original 2 events
object_by_id = calendar_.calendar.object_by_uid('6B-664A5280-F-5B831280',comp_class=None)

This sounds like a bug. I should look into it when I'm more awake.

ical_calendar_ = icalendar.Calendar.from_ical(object_by_id.data)

This should be equivalent to:

ical_calendar_ = object_by_id.icalendar_instance

I'm recommending to do this in the documentation:

ical_calendar_ = object_by_id.icalendar_component

Which will give the icalendar component object (event/task/journal) rather than the icalendar calendar object. and hence throw away all the recurrence-data fra object_by_id if there exist any. The documentation is probably a bit weak at this point.

python-caldav would definitely benefit from a better support for icalendar.calendar objects, but this is another issue

I disagree on that one - but the possibility to edit overridden recurrence instances (and handling them at all) is probably not very well thought-through in the python-caldav library.

[ptrba]

Great explanation. So it all boils down to the following:

VCALENDAR objects can be used to fully control recurring events with multiple single instances. Add, modify or delete all or some of the individual instances.

I can confirm the issue with object_by_id for accessing the VCALENDAR object:

# Important, do not provide a comp_class here. If we put comp_class='Event' we will only receive
# one of the original 2 events
object_by_id = calendar_.calendar.object_by_uid('6B-664A5280-F-5B831280',comp_class=caldav.Event)

# object_by_id is an event rather than a Calendar,
# but no problem, the desired calendar is present in the underlying data
ical_calendar_ = object_by_id.icalendar_instance

events = [event for event in ical_calendar_.subcomponents if isinstance(event,icalendar.Event)]
assert len(events) == 1 # expecting 2

[tobixen]

Great explanation. So it all boils down to the following:

VCALENDAR objects can be used to fully control recurring events with multiple single instances. Add, modify or delete all or some of the individual instances.

Yes. By fetching it through object_by_id, or using calendar.search(..., split_expanded=False) and then accessing the icalendar data either through the raw event.data, event.vobject_instance or (recommended) event.icalendar_instance, followed by an event.save() , it should be possible to make any changes on recurrence instances. If it doesn't, it's a bug.

There also exists higher-level methods for editing participants in the caldav library - though, it's very poorly tested as it was done as part of a project that lost traction at some point.

I can confirm the issue with object_by_id for accessing the VCALENDAR object:

I will fork it out as a separate issue.

[tobixen]

@ptrba - could you please have a look at #398? First of all - I haven't slept much over the last two nights, perhaps the text there make sense only in my own head, I'd like a peer-review on weather the text is readable at all :-) The other thing is weather my suggestions make sense at all or not.