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

[tobixen]

Ref https://github.com/python-caldav/caldav/issues/35#issuecomment-2125631113 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.