Enhancing icalendar through attributes

[niccokunzmann]

The icalendar standard has clarity about which attributes can be expected in components.

Attribtues can

• (S1) occur mandatory
• (S2) occur optionally

They can also

• (S3) occur at most once
• (S4) occur several times

Several issues exist that hint at a better API that we can provide.

(P1) Proposal for (S1) mandatory properties

The UID attribute of VEVENT is an example of this.

It is mandatory and also occurs once.

Add mandatory attributes to the constructor as well as a make_valid=True argument.
In case that argument is set, mandatory attributes receive a valid value.

Event() # sets UID, DTSTART to now.
Event(make_valid=False) # sets nothing
Event(uid="{aaaa-aaaa-aaaa-aaaa}") # sets the UID to the value and DTSTART, too.

We need make_valid=False in order to create the components from_ical()

Proposal for S1 & S2 - accessing properties

Attributes that are defined in the standard can be added as properties in Pythonic form.
The setter allows setting values that are supported as argument to the wrapping icalendar property.

class MandatoryPropertyNotSet(ValueError):
    """A mandatory property was not set on a component."""


class Event:

    @property
    def dtstart(self) -> vDatetime:  # all supported types
        """The DTSTART property (mandatory)

        See `RFC 5545 ...<link to rfc>`

        If DTSTART is not set, this raises and MandatoryPropertyNotSet error.
        """

    @dtstart.setter
    def dtstart(self, value: Union[vDatetime, datetime, date]):
        # ...

(P2) Proposal for S3 & S1 - properties that occur once

When attributes can occur only once, we can set them and access them in that way.
See above for the dtstart example.

(P3) Proposal for S3 & S2 - properties that occur several times

An attribute that can occur once at most and is optional, should look like this:

@property
def summary(self) -> Optional[vText]:
    """The SUMMARY (optional)

    See `RFC 5545 ...<link to rfc>`
    """

@dtstart.setter
def summary(self, value: Union[vText, str, bytes, None]):
    # ...

(P3) Proposal for S4 - attributes occur more than once

Issues: #224
It creates edge cases that are rarely caught if we allow attributes to be

• a list like vDDDLists
• a value like vDDDTypes at the same time.

Proposal to access those attributes all as a list:

@property
def rrules(self) -> vList[vRRule]: # plural
    """The RRULE

    See `RFC 5545 ...<link to rfc>`
    """

@rrules.setter
def rrules(self, value: vList[vRRule]]):
    # ...

Here, it can be confusing if one beliefs that this can be modified.
The project ObservableList handles this use-case by creating a list that
can be observed for changes. These can be then copied into the component.

event = Event()
event.rrules.append(str | bytes | vRRule | dateutil.rrule.rrule)

Requirements

I would like the following to happen:

• properties are types
• properties are set+get
• properties validate the input and convert it to a useful one
• properties refer to the RFC

Related

• Mandatory properties are neither enforced nor set to a default #596
• unique identifier must be included in VEVENT, VTODO, and VJOURNAL #315
• Use valid names for custom components / properties #431

Discussion

I wonder what you think about this, especially:

• What would be really good behavior?
• What would you expect to be in there?
• What edge cases come up for you?