Skip to content

Recurring components

These are the components that have the possibility to be recurring. For each of them there is their standard class and their recurring class. The idea is that the original definition is represented by the standard class and any occurrence that is generated based on the recurring properties, is represented by the recurring class.

Given all classes that have recurring options have a major overlap, there are two class abstracting the complexity away from them. This is again in the same concept, where the first one covers the standard class, and the other one covers the recurring class. These two are listed here first before the rest.

AbstractComponentWithRecurringProperties

Bases: Component, ABC

This class helps avoid code repetition with different :class:Component classes that have a duration and have recurring properties.

This class is inherited by VEvent, VToDo and VJournal as these all have recurring properties like :class:RRule, :class:RDate and :class:EXDate. All properties they had in common are part of this class. Note: VJournal is the odd one out as these events don't have a duration.

Parameters:

Name Type Description Default
name str

The actual name of this component instance. E.g. VEVENT, RRULE, VCUSTOMCOMPONENT.

 required
dtstamp Optional[DTStamp]

The DTStamp property. Required and must occur exactly once.

 None
uid Optional[UID]

The UID property. Required and must occur exactly once.

 None
dtstart Optional[DTStart]

The DTStart property. Optional and may occur at most once.

 None
rrule Optional[RRule]

The RRule property. Optional and may occur at most once.

 None
summary Optional[Summary]

The Summary property. Optional and may occur at most once.

 None
exdate Optional[List[EXDate]]

The EXDate property. Optional, but may occur multiple times.

 None
rdate Optional[List[RDate]]

The RDate property. Optional, but may occur multiple times.

 None
comment Optional[List[Comment]]

The Comment property. Optional, but may occur multiple times.

 None
parent Optional[Component]

The Component this item is encapsulated by in the iCalendar data file.

 None
Source code in ical_library/ical_components/abstract_components.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
class AbstractComponentWithRecurringProperties(Component, ABC):
    """
    This class helps avoid code repetition with different :class:`Component` classes that have a duration and have
    recurring properties.

    This class is inherited by VEvent, VToDo and VJournal as these all have recurring properties like :class:`RRule`,
    :class:`RDate` and :class:`EXDate`. All properties they had in common are part of this class.
    Note: VJournal is the odd one out as these events don't have a duration.

    :param name: The actual name of this component instance. E.g. VEVENT, RRULE, VCUSTOMCOMPONENT.
    :param dtstamp: The DTStamp property. Required and must occur exactly once.
    :param uid: The UID property. Required and must occur exactly once.
    :param dtstart: The DTStart property. Optional and may occur at most once.
    :param rrule: The RRule property. Optional and may occur at most once.
    :param summary: The Summary property. Optional and may occur at most once.
    :param exdate: The EXDate property. Optional, but may occur multiple times.
    :param rdate: The RDate property. Optional, but may occur multiple times.
    :param comment: The Comment property. Optional, but may occur multiple times.
    :param parent: The Component this item is encapsulated by in the iCalendar data file.
    """

    def __init__(
        self,
        name: str,
        dtstamp: Optional[DTStamp] = None,
        uid: Optional[UID] = None,
        dtstart: Optional[DTStart] = None,
        rrule: Optional[RRule] = None,
        summary: Optional[Summary] = None,
        recurrence_id: Optional[RecurrenceID] = None,
        exdate: Optional[List[EXDate]] = None,
        rdate: Optional[List[RDate]] = None,
        comment: Optional[List[Comment]] = None,
        parent: Optional[Component] = None,
    ):
        super().__init__(name, parent=parent)

        # Required
        self._dtstamp: Optional[DTStamp] = self.as_parent(dtstamp)
        self._uid: Optional[UID] = self.as_parent(uid)

        # Optional, may only occur once
        self.dtstart: Optional[DTStart] = self.as_parent(dtstart)
        self.rrule: Optional[RRule] = self.as_parent(rrule)
        self.summary: Optional[Summary] = self.as_parent(summary)
        self.recurrence_id: Optional[RecurrenceID] = self.as_parent(recurrence_id)

        # Optional, may occur more than once
        self.exdate: Optional[List[EXDate]] = self.as_parent(exdate)
        self.rdate: Optional[List[RDate]] = self.as_parent(rdate)
        self.comment: Optional[List[Comment]] = self.as_parent(comment)

    @property
    def dtstamp(self) -> DTStamp:
        """A getter to ensure the required property is set."""
        if self._dtstamp is None:
            raise MissingRequiredProperty(self, "dtstamp")
        return self._dtstamp

    @dtstamp.setter
    def dtstamp(self, value: DTStamp):
        """A setter to set the required property."""
        self._dtstamp = value

    @property
    def uid(self) -> UID:
        """A getter to ensure the required property is set."""
        if self._uid is None:
            raise MissingRequiredProperty(self, "uid")
        return self._uid

    @uid.setter
    def uid(self, value: UID):
        """A setter to set the required property."""
        self._uid = value

    @property
    @abstractmethod
    def ending(self) -> _DTBoth:
        """
        As the argument for this is different in each class, we ask this to be implemented.

        :return: The ending of the :class:`Component`, except for :class:`VJournal` which returns the start.
        """
        pass

    @abstractmethod
    def get_duration(self) -> Optional[Duration]:
        """
        As the duration is not present in each of them, we ask this to be implemented by the subclasses.

        :return: The duration of the :class:`Component`.
        """
        pass

    @abstractmethod
    def expand_component_in_range(
        self, return_range: Timespan, starts_to_exclude: Union[List[Date], List[DateTime]]
    ) -> Iterator[TimespanWithParent]:
        """
        Expand this component in range according to its recurring *RDate*, *EXDate* and *RRule* properties.
        :param return_range: The timespan range on which we should return VToDo instances.
        :param starts_to_exclude: List of start Dates or list of start DateTimes of which we already know we should
        exclude them from our recurrence computation (as they have been completely redefined in another element).
        :return: Yield all recurring VToDo instances related to this VToDo in the given *return_range*.
        """
        pass

    def __eq__(
        self: "AbstractComponentWithRecurringProperties", other: "AbstractComponentWithRecurringProperties"
    ) -> bool:
        """Return whether the current instance and the other instance are the same."""
        if type(self) != type(other):
            return False
        return (
            self.dtstart == other.dtstart
            and self.ending == other.ending
            and self.summary == other.summary
            and self.comment == other.comment
        )

    @property
    def timespan(self) -> Optional[TimespanWithParent]:
        """
        Return a timespan as a property representing the start and end of the instance.
        :return: A timespan instance with this class instance as parent.
        """
        if self.start is None:
            return None
        if self.end is None:
            TimespanWithParent(parent=self, begin=self.start, end=self.start)
        return TimespanWithParent(parent=self, begin=self.start, end=self.end)

    @property
    @instance_lru_cache()
    def start(self) -> Optional[Union[Date, DateTime]]:
        """Return the start of this Component as a :class:`Date` or :class:`DateTime` value."""
        return self.dtstart.datetime_or_date_value if self.dtstart else None

    @property
    @instance_lru_cache()
    def end(self) -> Optional[Union[Date, DateTime]]:
        """Return the ending of this Component as a Date or DateTime value."""
        if self.ending:
            return self.ending.datetime_or_date_value
        elif self.start and self.get_duration():
            return self.start + self.get_duration()
        return None

    @property
    @instance_lru_cache()
    def computed_duration(self: "AbstractComponentWithRecurringProperties") -> Optional[Duration]:
        """Return the duration of this Component as a :class:`Date` or :class:`DateTime` value."""
        if a_duration := self.get_duration():
            return a_duration
        elif self.end and self.start:
            result: Period = self.end - self.start
            return result
        return None

    @property
    @instance_lru_cache()
    def max_recurring_timespan(self) -> Optional[Timespan]:
        if not self.start or not self.computed_duration:
            return None
        if not self.rrule and not self.rdate:
            return self.timespan
        max_dt: DateTime = DateTime.min
        if self.rdate:
            max_dt = max(max_dt, max([rdate.compute_max_end_date(self.computed_duration) for rdate in self.rdate]))
        if self.rrule:
            max_dt = max(max_dt, self.rrule.compute_max_end_date(self.start, self.computed_duration))
        if max_dt != DateTime.min:
            return Timespan(self.start, max_dt)
        return None

computed_duration: Optional[Duration] property

Return the duration of this Component as a :class:Date or :class:DateTime value.

dtstamp: DTStamp property writable

A getter to ensure the required property is set.

end: Optional[Union[Date, DateTime]] property

Return the ending of this Component as a Date or DateTime value.

ending: _DTBoth abstractmethod property

As the argument for this is different in each class, we ask this to be implemented.

Returns:

Type Description

The ending of the :class:Component, except for :class:VJournal which returns the start.

start: Optional[Union[Date, DateTime]] property

Return the start of this Component as a :class:Date or :class:DateTime value.

timespan: Optional[TimespanWithParent] property

Return a timespan as a property representing the start and end of the instance.

Returns:

Type Description

A timespan instance with this class instance as parent.

uid: UID property writable

A getter to ensure the required property is set.

expand_component_in_range(return_range, starts_to_exclude) abstractmethod

Expand this component in range according to its recurring RDate, EXDate and RRule properties.

Parameters:

Name Type Description Default
return_range Timespan

The timespan range on which we should return VToDo instances.

 required
starts_to_exclude Union[List[Date], List[DateTime]]

List of start Dates or list of start DateTimes of which we already know we should exclude them from our recurrence computation (as they have been completely redefined in another element).

 required

Returns:

Type Description
Iterator[TimespanWithParent]

Yield all recurring VToDo instances related to this VToDo in the given return_range.
Source code in ical_library/ical_components/abstract_components.py 
111
112
113
114
115
116
117
118
119
120
121
122
@abstractmethod
def expand_component_in_range(
    self, return_range: Timespan, starts_to_exclude: Union[List[Date], List[DateTime]]
) -> Iterator[TimespanWithParent]:
    """
    Expand this component in range according to its recurring *RDate*, *EXDate* and *RRule* properties.
    :param return_range: The timespan range on which we should return VToDo instances.
    :param starts_to_exclude: List of start Dates or list of start DateTimes of which we already know we should
    exclude them from our recurrence computation (as they have been completely redefined in another element).
    :return: Yield all recurring VToDo instances related to this VToDo in the given *return_range*.
    """
    pass

get_duration() abstractmethod

As the duration is not present in each of them, we ask this to be implemented by the subclasses.

Returns:

Type Description
Optional[Duration]

The duration of the :class:Component.
Source code in ical_library/ical_components/abstract_components.py 
102
103
104
105
106
107
108
109
@abstractmethod
def get_duration(self) -> Optional[Duration]:
    """
    As the duration is not present in each of them, we ask this to be implemented by the subclasses.

    :return: The duration of the :class:`Component`.
    """
    pass

AbstractRecurrence

Bases: AbstractComponentWithRecurringProperties, ABC

This class extends :class:AbstractComponentWithRecurringProperties to represent a recurring Component.

This class is inherited by VRecurringEvent, VRecurringToDo and VRecurringJournal. When we compute the recurrence based on the :class:RRule, :class:RDate and :class:EXDate properties, we create new occurrences of that specific component. Instead of copying over all Properties (and using a lot of memory), this class overwrites the getattribute function to act like the original component for most attributes except for start, end, original and parent.

Source code in ical_library/ical_components/abstract_components.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
class AbstractRecurrence(AbstractComponentWithRecurringProperties, ABC):
    """
    This class extends :class:`AbstractComponentWithRecurringProperties` to represent a recurring Component.

    This class is inherited by VRecurringEvent, VRecurringToDo and VRecurringJournal. When we compute the recurrence
    based on the :class:`RRule`, :class:`RDate` and :class:`EXDate` properties, we create new occurrences of that
    specific component. Instead of copying over all Properties (and using a lot of memory), this class overwrites the
    *__getattribute__* function to act like the original component for most attributes except for *start*, *end*,
    *original* and *parent*.
    """

    def __getattribute__(self, var_name: str) -> Any:
        """
        Overwrite this function to return the originals properties except for *start*, *end*, *original* and *parent*.

        Depending on the attributes *name* we are requesting, we either return its own properties or the original
        components properties. This way we don't need to copy over all the variables.
        :param var_name: Name of the attribute we are accessing.
        :return: The value of the attribute we are accessing either from the *original* or from this instance itself.
        """
        if var_name in ("_start", "_end", "_original", "_parent", "start", "end", "original", "parent"):
            return object.__getattribute__(self, var_name)
        if var_name in ("_name", "_extra_child_components", "_extra_properties"):
            return object.__getattribute__(self._original, var_name)
        if var_name in self._original.get_property_ical_names():
            return object.__getattribute__(self._original, var_name)
        return object.__getattribute__(self, var_name)

    def __setattr__(self, key: str, value: Any) -> None:
        """Overwrite the custom __setattr__ from Components to set it back to the standard behavior."""
        object.__setattr__(self, key, value)

    @property
    def start(self) -> DateTime:
        """Return the start of this recurring event."""
        return self._start

    @property
    def end(self) -> DateTime:
        """Return the end of this recurring event."""
        return self._end

    @property
    def original(self) -> AbstractComponentWithRecurringProperties:
        """Return the original component that created this recurring component."""
        return self._original

    @property
    def parent(self) -> Component:
        """Return the parent of the original component."""
        return self._original.parent

end: DateTime property

Return the end of this recurring event.

original: AbstractComponentWithRecurringProperties property

Return the original component that created this recurring component.

parent: Component property

Return the parent of the original component.

start: DateTime property

Return the start of this recurring event.

__getattribute__(var_name)

Overwrite this function to return the originals properties except for start, end, original and parent.

Depending on the attributes name we are requesting, we either return its own properties or the original components properties. This way we don't need to copy over all the variables.

Parameters:

Name Type Description Default
var_name str

Name of the attribute we are accessing.

 required

Returns:

Type Description
Any

The value of the attribute we are accessing either from the original or from this instance itself.
Source code in ical_library/ical_components/abstract_components.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
def __getattribute__(self, var_name: str) -> Any:
    """
    Overwrite this function to return the originals properties except for *start*, *end*, *original* and *parent*.

    Depending on the attributes *name* we are requesting, we either return its own properties or the original
    components properties. This way we don't need to copy over all the variables.
    :param var_name: Name of the attribute we are accessing.
    :return: The value of the attribute we are accessing either from the *original* or from this instance itself.
    """
    if var_name in ("_start", "_end", "_original", "_parent", "start", "end", "original", "parent"):
        return object.__getattribute__(self, var_name)
    if var_name in ("_name", "_extra_child_components", "_extra_properties"):
        return object.__getattribute__(self._original, var_name)
    if var_name in self._original.get_property_ical_names():
        return object.__getattribute__(self._original, var_name)
    return object.__getattribute__(self, var_name)

__setattr__(key, value)

Overwrite the custom setattr from Components to set it back to the standard behavior.

Source code in ical_library/ical_components/abstract_components.py 
221
222
223
def __setattr__(self, key: str, value: Any) -> None:
    """Overwrite the custom __setattr__ from Components to set it back to the standard behavior."""
    object.__setattr__(self, key, value)

VEvent

Bases: AbstractComponentWithRecurringProperties

This class represents the VEVENT component specified in RFC 5545 in '3.6.1. Event Component'.

A "VEVENT" calendar component is a grouping of component properties, possibly including "VALARM" calendar components, that represents a scheduled amount of time on a calendar. For example, it can be an activity; such as a one-hour long, department meeting from 8:00 AM to 9:00 AM, tomorrow. Generally, an event will take up time on an individual calendar. Hence, the event will appear as an opaque interval in a search for busy time. Alternately, the event can have its Time Transparency set to "TRANSPARENT" in order to prevent blocking of the event in searches for busy time.

Parameters:

Name Type Description Default
name

The actual name of this component instance. E.g. VEVENT, RRULE, VCUSTOMCOMPONENT.

 required
parent Optional[Component]

The Component this item is encapsulated by in the iCalendar data file.

 None
dtstamp Optional[DTStamp]

The DTStamp property. Required and must occur exactly once.

 None
uid Optional[UID]

The UID property. Required and must occur exactly once.

 None
dtstart Optional[DTStart]

The DTStart property. Optional and may occur at most once.

 None
rrule Optional[RRule]

The RRule property. Optional and may occur at most once.

 None
summary Optional[Summary]

The Summary property. Optional and may occur at most once.

 None
exdate Optional[List[EXDate]]

The EXDate property. Optional, but may occur multiple times.

 None
rdate Optional[List[RDate]]

The RDate property. Optional, but may occur multiple times.

 None
comment Optional[List[Comment]]

The Comment property. Optional, but may occur multiple times.

 None
ical_class Optional[Class]

Optional Class property. Optional, but may occur at most once.

 None
created Optional[Created]

The Created property. Optional, but may occur at most once.

 None
description Optional[Description]

The Description property. Optional, but may occur at most once.

 None
duration Optional[ICALDuration]

The ICALDuration property. Optional, but may occur at most once.

 None
geo Optional[GEO]

The GEO property. Optional, but may occur at most once.

 None
last_modified Optional[LastModified]

Optional LastModified property. Optional, but may occur at most once.

 None
location Optional[Location]

The Location property. Optional, but may occur at most once.

 None
organizer Optional[Organizer]

The Organizer property. Optional, but may occur at most once.

 None
priority Optional[Priority]

The Priority property. Optional, but may occur at most once.

 None
sequence Optional[Sequence]

The Sequence property. Optional, but may occur at most once.

 None
status Optional[Status]

The Status property. Optional, but may occur at most once.

 None
transp Optional[TimeTransparency]

The TimeTransparency property. Optional, but may occur at most once.

 None
url Optional[URL]

The URL property. Optional, but may occur at most once.

 None
recurrence_id Optional[RecurrenceID]

Optional RecurrenceID property. Optional, but may occur at most once.

 None
dtend Optional[DTEnd]

The DTEnd property. Optional, but may occur at most once.

 None
attach Optional[List[Attach]]

The Attach property. Optional, but may occur multiple times.

 None
attendee Optional[List[Attendee]]

The Attendee property. Optional, but may occur multiple times.

 None
categories Optional[List[Categories]]

The Categories property. Optional, but may occur multiple times.

 None
contact Optional[List[Contact]]

The Contact property. Optional, but may occur multiple times.

 None
rstatus Optional[List[RequestStatus]]

The RequestStatus property. Optional, but may occur multiple times.

 None
related Optional[List[RelatedTo]]

The RelatedTo property. Optional, but may occur multiple times.

 None
resources Optional[List[Resources]]

The Resources property. Optional, but may occur multiple times.

 None
Source code in ical_library/ical_components/v_event.py 
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
class VEvent(AbstractComponentWithRecurringProperties):
    """
    This class represents the VEVENT component specified in RFC 5545 in '3.6.1. Event Component'.

    A "VEVENT" calendar component is a grouping of component properties, possibly including "VALARM" calendar
    components, that represents a scheduled amount of time on a calendar. For example, it can be an activity; such as
    a one-hour long, department meeting from 8:00 AM to 9:00 AM, tomorrow. Generally, an event will take up time on an
    individual calendar. Hence, the event will appear as an opaque interval in a search for busy time. Alternately,
    the event can have its Time Transparency set to "TRANSPARENT" in order to prevent blocking of the event in
    searches for busy time.

    :param name: The actual name of this component instance. E.g. VEVENT, RRULE, VCUSTOMCOMPONENT.
    :param parent: The Component this item is encapsulated by in the iCalendar data file.
    :param dtstamp: The DTStamp property. Required and must occur exactly once.
    :param uid: The UID property. Required and must occur exactly once.
    :param dtstart: The DTStart property. Optional and may occur at most once.
    :param rrule: The RRule property. Optional and may occur at most once.
    :param summary: The Summary property. Optional and may occur at most once.
    :param exdate: The EXDate property. Optional, but may occur multiple times.
    :param rdate: The RDate property. Optional, but may occur multiple times.
    :param comment: The Comment property. Optional, but may occur multiple times.
    :param ical_class: Optional Class property. Optional, but may occur at most once.
    :param created: The Created property. Optional, but may occur at most once.
    :param description: The Description property. Optional, but may occur at most once.
    :param duration: The ICALDuration property. Optional, but may occur at most once.
    :param geo: The GEO property. Optional, but may occur at most once.
    :param last_modified: Optional LastModified property. Optional, but may occur at most once.
    :param location: The Location property. Optional, but may occur at most once.
    :param organizer: The Organizer property. Optional, but may occur at most once.
    :param priority: The Priority property. Optional, but may occur at most once.
    :param sequence: The Sequence property. Optional, but may occur at most once.
    :param status: The Status property. Optional, but may occur at most once.
    :param transp: The TimeTransparency property. Optional, but may occur at most once.
    :param url: The URL property. Optional, but may occur at most once.
    :param recurrence_id: Optional RecurrenceID property. Optional, but may occur at most once.
    :param dtend: The DTEnd property. Optional, but may occur at most once.
    :param attach: The Attach property. Optional, but may occur multiple times.
    :param attendee: The Attendee property. Optional, but may occur multiple times.
    :param categories: The Categories property. Optional, but may occur multiple times.
    :param contact: The Contact property. Optional, but may occur multiple times.
    :param rstatus: The RequestStatus property. Optional, but may occur multiple times.
    :param related: The RelatedTo property. Optional, but may occur multiple times.
    :param resources: The Resources property. Optional, but may occur multiple times.
    """

    def __init__(
        self,
        dtstamp: Optional[DTStamp] = None,
        uid: Optional[UID] = None,
        dtstart: Optional[DTStart] = None,
        rrule: Optional[RRule] = None,
        summary: Optional[Summary] = None,
        exdate: Optional[List[EXDate]] = None,
        rdate: Optional[List[RDate]] = None,
        comment: Optional[List[Comment]] = None,
        ical_class: Optional[Class] = None,
        created: Optional[Created] = None,
        description: Optional[Description] = None,
        duration: Optional[ICALDuration] = None,
        geo: Optional[GEO] = None,
        last_modified: Optional[LastModified] = None,
        location: Optional[Location] = None,
        organizer: Optional[Organizer] = None,
        priority: Optional[Priority] = None,
        sequence: Optional[Sequence] = None,
        status: Optional[Status] = None,
        transp: Optional[TimeTransparency] = None,
        url: Optional[URL] = None,
        recurrence_id: Optional[RecurrenceID] = None,
        dtend: Optional[DTEnd] = None,
        attach: Optional[List[Attach]] = None,
        attendee: Optional[List[Attendee]] = None,
        categories: Optional[List[Categories]] = None,
        contact: Optional[List[Contact]] = None,
        rstatus: Optional[List[RequestStatus]] = None,
        related: Optional[List[RelatedTo]] = None,
        resources: Optional[List[Resources]] = None,
        alarms: Optional[List[VAlarm]] = None,
        parent: Optional[Component] = None,
    ):
        super().__init__(
            name="VEVENT",
            dtstamp=dtstamp,
            uid=uid,
            dtstart=dtstart,
            rrule=rrule,
            summary=summary,
            recurrence_id=recurrence_id,
            exdate=exdate,
            rdate=rdate,
            comment=comment,
            parent=parent,
        )

        # Optional, may only occur once
        # As class is a reserved keyword in python, we prefixed it with `ical_`.
        self.ical_class: Optional[Class] = self.as_parent(ical_class)
        self.created: Optional[Created] = self.as_parent(created)
        self.description: Optional[Description] = self.as_parent(description)
        self.duration: Optional[ICALDuration] = self.as_parent(duration)
        self.geo: Optional[GEO] = self.as_parent(geo)
        self.last_modified: Optional[LastModified] = self.as_parent(last_modified)
        self.location: Optional[Location] = self.as_parent(location)
        self.organizer: Optional[Organizer] = self.as_parent(organizer)
        self.priority: Optional[Priority] = self.as_parent(priority)
        self.sequence: Optional[Sequence] = self.as_parent(sequence)
        self.status: Optional[Status] = self.as_parent(status)
        self.transp: Optional[TimeTransparency] = self.as_parent(transp)
        self.url: Optional[URL] = self.as_parent(url)
        self.dtend: Optional[DTEnd] = self.as_parent(dtend)

        # Optional, may occur more than once
        self.attach: Optional[List[Attach]] = self.as_parent(attach)
        self.attendee: Optional[List[Attendee]] = self.as_parent(attendee)
        self.categories: Optional[List[Categories]] = self.as_parent(categories)
        self.contact: Optional[List[Contact]] = self.as_parent(contact)
        self.rstatus: Optional[List[RequestStatus]] = self.as_parent(rstatus)
        self.related: Optional[List[RelatedTo]] = self.as_parent(related)
        self.resources: Optional[List[Resources]] = self.as_parent(resources)

        # This is a child component
        self.alarms: List[VAlarm] = alarms or []

    def __repr__(self) -> str:
        """Overwrite the repr to create a better representation for the item."""
        if self.dtstart and self.dtend:
            return f"VEvent({self.start} - {self.end}: {self.summary.value if self.summary else ''})"
        else:
            return f"VEvent({self.summary.value if self.summary else ''})"

    @property
    def ending(self) -> Optional[_DTBoth]:
        """
        Return the ending of the event.

        Note: This is an abstract method from :class:`AbstractComponentWithRecurringProperties` we have to implement.
        """
        return self.dtend

    def get_duration(self) -> Optional[Duration]:
        """
        Return the duration of the event.

        Note: This is an abstract method from :class:`AbstractComponentWithRecurringProperties` we have to implement.
        """
        return self.duration.duration if self.duration else None

    def expand_component_in_range(
        self, return_range: Timespan, starts_to_exclude: Union[List[Date], List[DateTime]]
    ) -> Iterator[TimespanWithParent]:
        """
        Expand this VEvent in range according to its recurring *RDate*, *EXDate* and *RRule* properties.
        :param return_range: The timespan range on which we should return VEvent instances.
        :param starts_to_exclude: List of start Dates or list of start DateTimes of which we should exclude as they were
        defined in EXDATE, have already been returned or have been completely redefined in another element.
        :return: Yield all recurring VEvent instances related to this VEvent in the given *return_range*.
        """
        if self.timespan.intersects(return_range):
            yield self.timespan
        starts_to_exclude.append(self.start)

        start = self.start
        duration = self.computed_duration
        if not start or not duration:
            return None

        iterator = property_utils.expand_component_in_range(
            exdate_list=self.exdate or [],
            rdate_list=self.rdate or [],
            rrule=self.rrule,
            first_event_start=start,
            first_event_duration=duration,
            starts_to_exclude=starts_to_exclude,
            return_range=return_range,
            make_tz_aware=None,
        )

        for event_start_time, event_end_time in iterator:
            yield VRecurringEvent(
                original_component_instance=self,
                start=event_start_time,
                end=event_end_time,
            ).timespan

ending: Optional[_DTBoth] property

Return the ending of the event.

Note: This is an abstract method from :class:AbstractComponentWithRecurringProperties we have to implement.

expand_component_in_range(return_range, starts_to_exclude)

Expand this VEvent in range according to its recurring RDate, EXDate and RRule properties.

Parameters:

Name Type Description Default
return_range Timespan

The timespan range on which we should return VEvent instances.

 required
starts_to_exclude Union[List[Date], List[DateTime]]

List of start Dates or list of start DateTimes of which we should exclude as they were defined in EXDATE, have already been returned or have been completely redefined in another element.

 required

Returns:

Type Description
Iterator[TimespanWithParent]

Yield all recurring VEvent instances related to this VEvent in the given return_range.
Source code in ical_library/ical_components/v_event.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
def expand_component_in_range(
    self, return_range: Timespan, starts_to_exclude: Union[List[Date], List[DateTime]]
) -> Iterator[TimespanWithParent]:
    """
    Expand this VEvent in range according to its recurring *RDate*, *EXDate* and *RRule* properties.
    :param return_range: The timespan range on which we should return VEvent instances.
    :param starts_to_exclude: List of start Dates or list of start DateTimes of which we should exclude as they were
    defined in EXDATE, have already been returned or have been completely redefined in another element.
    :return: Yield all recurring VEvent instances related to this VEvent in the given *return_range*.
    """
    if self.timespan.intersects(return_range):
        yield self.timespan
    starts_to_exclude.append(self.start)

    start = self.start
    duration = self.computed_duration
    if not start or not duration:
        return None

    iterator = property_utils.expand_component_in_range(
        exdate_list=self.exdate or [],
        rdate_list=self.rdate or [],
        rrule=self.rrule,
        first_event_start=start,
        first_event_duration=duration,
        starts_to_exclude=starts_to_exclude,
        return_range=return_range,
        make_tz_aware=None,
    )

    for event_start_time, event_end_time in iterator:
        yield VRecurringEvent(
            original_component_instance=self,
            start=event_start_time,
            end=event_end_time,
        ).timespan

get_duration()

Return the duration of the event.

Note: This is an abstract method from :class:AbstractComponentWithRecurringProperties we have to implement.

Source code in ical_library/ical_components/v_event.py 
178
179
180
181
182
183
184
def get_duration(self) -> Optional[Duration]:
    """
    Return the duration of the event.

    Note: This is an abstract method from :class:`AbstractComponentWithRecurringProperties` we have to implement.
    """
    return self.duration.duration if self.duration else None

VRecurringEvent

Bases: AbstractRecurrence, VEvent

This class represents VEvents that are recurring. Inside the AbstractRecurrence class we overwrite specific dunder methods and property methods. This way our end users have a very similar interface to an actual VEvent but without us needing to code the exact same thing twice.

Parameters:

Name Type Description Default
original_component_instance VEvent

The original VEvent instance.

 required
start DateTime

The start of this occurrence.

 required
end DateTime

The end of this occurrence.

 required
Source code in ical_library/ical_components/v_event.py 
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
class VRecurringEvent(AbstractRecurrence, VEvent):
    """
    This class represents VEvents that are recurring.
    Inside the AbstractRecurrence class we overwrite specific dunder methods and property methods.
    This way our end users have a very similar interface to an actual VEvent but without us needing to code the exact
    same thing twice.

    :param original_component_instance: The original VEvent instance.
    :param start: The start of this occurrence.
    :param end: The end of this occurrence.
    """

    def __init__(self, original_component_instance: VEvent, start: DateTime, end: DateTime):
        self._original = original_component_instance
        self._start = start
        self._end = end
        super(VEvent, self).__init__("VEVENT", parent=original_component_instance)

    def __repr__(self) -> str:
        """Overwrite the repr to create a better representation for the item."""
        return f"RVEvent({self._start} - {self._end}: {self.original.summary.value if self.original.summary else ''})"

VToDo

Bases: AbstractComponentWithRecurringProperties

This class represents the VTODO component specified in RFC 5545 in '3.6.2. To-Do Component'.

A "VTODO" calendar component is a grouping of component properties and possibly "VALARM" calendar components that represent an action-item or assignment. For example, it can be used to represent an item of work assigned to an individual; such as "turn in travel expense today".

Parameters:

Name Type Description Default
name

The actual name of this component instance. E.g. VEVENT, RRULE, VCUSTOMCOMPONENT.

 required
parent Optional[Component]

The Component this item is encapsulated by in the iCalendar data file.

 None
dtstamp Optional[DTStamp]

The DTStamp property. Required and must occur exactly once.

 None
uid Optional[UID]

The UID property. Required and must occur exactly once.

 None
dtstart Optional[DTStart]

The DTStart property. Optional and may occur at most once.

 None
rrule Optional[RRule]

The RRule property. Optional and may occur at most once.

 None
summary Optional[Summary]

The Summary property. Optional and may occur at most once.

 None
exdate Optional[List[EXDate]]

The EXDate property. Optional, but may occur multiple times.

 None
rdate Optional[List[RDate]]

The RDate property. Optional, but may occur multiple times.

 None
comment Optional[List[Comment]]

The Comment property. Optional, but may occur multiple times.

 None
ical_class Optional[Class]

Optional Class property. Optional, but may occur at most once.

 None
completed Optional[Completed]

The Completed property. Optional, but may occur at most once.

 None
created Optional[Created]

The Created property. Optional, but may occur at most once.

 None
description Optional[Description]

The Description property. Optional, but may occur at most once.

 None
duration Optional[ICALDuration]

The ICALDuration property. Optional, but may occur at most once.

 None
geo Optional[GEO]

The GEO property. Optional, but may occur at most once.

 None
last_modified Optional[LastModified]

Optional LastModified property. Optional, but may occur at most once.

 None
location Optional[Location]

The Location property. Optional, but may occur at most once.

 None
organizer Optional[Organizer]

The Organizer property. Optional, but may occur at most once.

 None
percent Optional[PercentComplete]

The PercentComplete property. Optional, but may occur at most once.

 None
priority Optional[Priority]

The Priority property. Optional, but may occur at most once.

 None
sequence Optional[Sequence]

The Sequence property. Optional, but may occur at most once.

 None
status Optional[Status]

The Status property. Optional, but may occur at most once.

 None
url Optional[URL]

The URL property. Optional, but may occur at most once.

 None
recurrence_id Optional[RecurrenceID]

Optional RecurrenceID property. Optional, but may occur at most once.

 None
due Optional[Due]

The Due property. Optional, but may occur at most once.

 None
attach Optional[List[Attach]]

The Attach property. Optional, but may occur multiple times.

 None
attendee Optional[List[Attendee]]

The Attendee property. Optional, but may occur multiple times.

 None
categories Optional[List[Categories]]

The Categories property. Optional, but may occur multiple times.

 None
contact Optional[List[Contact]]

The Contact property. Optional, but may occur multiple times.

 None
rstatus Optional[List[RequestStatus]]

The RequestStatus property. Optional, but may occur multiple times.

 None
related Optional[List[RelatedTo]]

The RelatedTo property. Optional, but may occur multiple times.

 None
resources Optional[List[Resources]]

The Resources property. Optional, but may occur multiple times.

 None
Source code in ical_library/ical_components/v_todo.py 
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
class VToDo(AbstractComponentWithRecurringProperties):
    """
    This class represents the VTODO component specified in RFC 5545 in '3.6.2. To-Do Component'.

    A "VTODO" calendar component is a grouping of component properties and possibly "VALARM" calendar components that
    represent an action-item or assignment. For example, it can be used to represent an item of work assigned to an
    individual; such as "turn in travel expense today".

    :param name: The actual name of this component instance. E.g. VEVENT, RRULE, VCUSTOMCOMPONENT.
    :param parent: The Component this item is encapsulated by in the iCalendar data file.
    :param dtstamp: The DTStamp property. Required and must occur exactly once.
    :param uid: The UID property. Required and must occur exactly once.
    :param dtstart: The DTStart property. Optional and may occur at most once.
    :param rrule: The RRule property. Optional and may occur at most once.
    :param summary: The Summary property. Optional and may occur at most once.
    :param exdate: The EXDate property. Optional, but may occur multiple times.
    :param rdate: The RDate property. Optional, but may occur multiple times.
    :param comment: The Comment property. Optional, but may occur multiple times.
    :param ical_class: Optional Class property. Optional, but may occur at most once.
    :param completed: The Completed property. Optional, but may occur at most once.
    :param created: The Created property. Optional, but may occur at most once.
    :param description: The Description property. Optional, but may occur at most once.
    :param duration: The ICALDuration property. Optional, but may occur at most once.
    :param geo: The GEO property. Optional, but may occur at most once.
    :param last_modified: Optional LastModified property. Optional, but may occur at most once.
    :param location: The Location property. Optional, but may occur at most once.
    :param organizer: The Organizer property. Optional, but may occur at most once.
    :param percent: The PercentComplete property. Optional, but may occur at most once.
    :param priority: The Priority property. Optional, but may occur at most once.
    :param sequence: The Sequence property. Optional, but may occur at most once.
    :param status: The Status property. Optional, but may occur at most once.
    :param url: The URL property. Optional, but may occur at most once.
    :param recurrence_id: Optional RecurrenceID property. Optional, but may occur at most once.
    :param due: The Due property. Optional, but may occur at most once.
    :param attach: The Attach property. Optional, but may occur multiple times.
    :param attendee: The Attendee property. Optional, but may occur multiple times.
    :param categories: The Categories property. Optional, but may occur multiple times.
    :param contact: The Contact property. Optional, but may occur multiple times.
    :param rstatus: The RequestStatus property. Optional, but may occur multiple times.
    :param related: The RelatedTo property. Optional, but may occur multiple times.
    :param resources: The Resources property. Optional, but may occur multiple times.
    """

    def __init__(
        self,
        dtstamp: Optional[DTStamp] = None,
        uid: Optional[UID] = None,
        dtstart: Optional[DTStart] = None,
        rrule: Optional[RRule] = None,
        summary: Optional[Summary] = None,
        exdate: Optional[List[EXDate]] = None,
        rdate: Optional[List[RDate]] = None,
        comment: Optional[List[Comment]] = None,
        ical_class: Optional[Class] = None,
        completed: Optional[Completed] = None,
        created: Optional[Created] = None,
        description: Optional[Description] = None,
        duration: Optional[ICALDuration] = None,
        geo: Optional[GEO] = None,
        last_modified: Optional[LastModified] = None,
        location: Optional[Location] = None,
        organizer: Optional[Organizer] = None,
        percent: Optional[PercentComplete] = None,
        priority: Optional[Priority] = None,
        sequence: Optional[Sequence] = None,
        status: Optional[Status] = None,
        url: Optional[URL] = None,
        recurrence_id: Optional[RecurrenceID] = None,
        due: Optional[Due] = None,
        attach: Optional[List[Attach]] = None,
        attendee: Optional[List[Attendee]] = None,
        categories: Optional[List[Categories]] = None,
        contact: Optional[List[Contact]] = None,
        rstatus: Optional[List[RequestStatus]] = None,
        related: Optional[List[RelatedTo]] = None,
        resources: Optional[List[Resources]] = None,
        alarms: Optional[List[VAlarm]] = None,
        parent: Optional[Component] = None,
    ):
        super().__init__(
            name="VTODO",
            dtstamp=dtstamp,
            uid=uid,
            dtstart=dtstart,
            rrule=rrule,
            summary=summary,
            exdate=exdate,
            rdate=rdate,
            comment=comment,
            parent=parent,
        )

        # Optional, may only occur once
        # As class is a reserved keyword in python, we prefixed it with `ical_`.
        self.ical_class: Optional[Class] = self.as_parent(ical_class)
        self.completed: Optional[Completed] = self.as_parent(completed)
        self.created: Optional[Created] = self.as_parent(created)
        self.description: Optional[Description] = self.as_parent(description)
        self.duration: Optional[ICALDuration] = self.as_parent(duration)
        self.geo: Optional[GEO] = self.as_parent(geo)
        self.last_modified: Optional[LastModified] = self.as_parent(last_modified)
        self.location: Optional[Location] = self.as_parent(location)
        self.organizer: Optional[Organizer] = self.as_parent(organizer)
        self.percent: Optional[PercentComplete] = self.as_parent(percent)
        self.priority: Optional[Priority] = self.as_parent(priority)
        self.sequence: Optional[Sequence] = self.as_parent(sequence)
        self.status: Optional[Status] = self.as_parent(status)
        self.url: Optional[URL] = self.as_parent(url)
        self.due: Optional[Due] = self.as_parent(due)

        # Optional, may occur more than once
        self.attach: Optional[List[Attach]] = self.as_parent(attach)
        self.attendee: Optional[List[Attendee]] = self.as_parent(attendee)
        self.categories: Optional[List[Categories]] = self.as_parent(categories)
        self.contact: Optional[List[Contact]] = self.as_parent(contact)
        self.rstatus: Optional[List[RequestStatus]] = self.as_parent(rstatus)
        self.related: Optional[List[RelatedTo]] = self.as_parent(related)
        self.resources: Optional[List[Resources]] = self.as_parent(resources)

        # This is a child component
        self.alarms: List[VAlarm] = alarms or []

    def __repr__(self) -> str:
        """Overwrite the repr to create a better representation for the item."""
        return (
            f"VToDo({self.dtstart.value if self.dtstart else ''} - {self.due.value if self.due else ''}: "
            f"{self.summary.value if self.summary else ''})"
        )

    @property
    def ending(self) -> Optional[_DTBoth]:
        """
        Return the ending of the vtodo.

        Note: This is an abstract method from :class:`AbstractComponentWithRecurringProperties` we have to implement.
        """
        return self.due

    def get_duration(self) -> Optional[Duration]:
        """
        Return the duration of the vtodo.

        Note: This is an abstract method from :class:`AbstractComponentWithRecurringProperties` we have to implement.
        """
        return self.duration.duration if self.duration else None

    def expand_component_in_range(
        self, return_range: Timespan, starts_to_exclude: Union[List[Date], List[DateTime]]
    ) -> Iterator[TimespanWithParent]:
        """
        Expand this VToDo in range according to its recurring *RDate*, *EXDate* and *RRule* properties.
        :param return_range: The timespan range on which we should return VToDo instances.
        :param starts_to_exclude: List of start Dates or list of start DateTimes of which we already know we should
        exclude them from our recurrence computation (as they have been completely redefined in another element).
        :return: Yield all recurring VToDo instances related to this VToDo in the given *return_range*.
        """
        if self.timespan.intersects(return_range):
            yield self.timespan
        starts_to_exclude.append(self.start)

        start = self.start
        duration = self.computed_duration
        if not start or not duration:
            return None

        iterator = property_utils.expand_component_in_range(
            exdate_list=self.exdate or [],
            rdate_list=self.rdate or [],
            rrule=self.rrule,
            first_event_start=self.start,
            first_event_duration=self.computed_duration,
            starts_to_exclude=starts_to_exclude,
            return_range=return_range,
            make_tz_aware=None,
        )

        for event_start_time, event_end_time in iterator:
            yield VRecurringToDo(
                original_component_instance=self,
                start=event_start_time,
                end=event_end_time,
            ).timespan

ending: Optional[_DTBoth] property

Return the ending of the vtodo.

Note: This is an abstract method from :class:AbstractComponentWithRecurringProperties we have to implement.

expand_component_in_range(return_range, starts_to_exclude)

Expand this VToDo in range according to its recurring RDate, EXDate and RRule properties.

Parameters:

Name Type Description Default
return_range Timespan

The timespan range on which we should return VToDo instances.

 required
starts_to_exclude Union[List[Date], List[DateTime]]

List of start Dates or list of start DateTimes of which we already know we should exclude them from our recurrence computation (as they have been completely redefined in another element).

 required

Returns:

Type Description
Iterator[TimespanWithParent]

Yield all recurring VToDo instances related to this VToDo in the given return_range.
Source code in ical_library/ical_components/v_todo.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
def expand_component_in_range(
    self, return_range: Timespan, starts_to_exclude: Union[List[Date], List[DateTime]]
) -> Iterator[TimespanWithParent]:
    """
    Expand this VToDo in range according to its recurring *RDate*, *EXDate* and *RRule* properties.
    :param return_range: The timespan range on which we should return VToDo instances.
    :param starts_to_exclude: List of start Dates or list of start DateTimes of which we already know we should
    exclude them from our recurrence computation (as they have been completely redefined in another element).
    :return: Yield all recurring VToDo instances related to this VToDo in the given *return_range*.
    """
    if self.timespan.intersects(return_range):
        yield self.timespan
    starts_to_exclude.append(self.start)

    start = self.start
    duration = self.computed_duration
    if not start or not duration:
        return None

    iterator = property_utils.expand_component_in_range(
        exdate_list=self.exdate or [],
        rdate_list=self.rdate or [],
        rrule=self.rrule,
        first_event_start=self.start,
        first_event_duration=self.computed_duration,
        starts_to_exclude=starts_to_exclude,
        return_range=return_range,
        make_tz_aware=None,
    )

    for event_start_time, event_end_time in iterator:
        yield VRecurringToDo(
            original_component_instance=self,
            start=event_start_time,
            end=event_end_time,
        ).timespan

get_duration()

Return the duration of the vtodo.

Note: This is an abstract method from :class:AbstractComponentWithRecurringProperties we have to implement.

Source code in ical_library/ical_components/v_todo.py 
185
186
187
188
189
190
191
def get_duration(self) -> Optional[Duration]:
    """
    Return the duration of the vtodo.

    Note: This is an abstract method from :class:`AbstractComponentWithRecurringProperties` we have to implement.
    """
    return self.duration.duration if self.duration else None

VRecurringToDo

Bases: AbstractRecurrence, VToDo

This class represents VToDo that are recurring. Inside the AbstractRecurrence class we overwrite specific dunder methods and property methods. This way our end users have a very similar interface to an actual VToDo but without us needing to code the exact same thing twice.

Parameters:

Name Type Description Default
original_component_instance VToDo

The original VToDo instance.

 required
start DateTime

The start of this occurrence.

 required
end DateTime

The end of this occurrence.

 required
Source code in ical_library/ical_components/v_todo.py 
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
class VRecurringToDo(AbstractRecurrence, VToDo):
    """
    This class represents VToDo that are recurring.
    Inside the AbstractRecurrence class we overwrite specific dunder methods and property methods.
    This way our end users have a very similar interface to an actual VToDo but without us needing to code the exact
    same thing twice.

    :param original_component_instance: The original VToDo instance.
    :param start: The start of this occurrence.
    :param end: The end of this occurrence.
    """

    def __init__(self, original_component_instance: VToDo, start: DateTime, end: DateTime):
        self._original = original_component_instance
        self._start = start
        self._end = end
        super(VToDo, self).__init__("VTODO", parent=original_component_instance)

    def __repr__(self) -> str:
        """Overwrite the repr to create a better representation for the item."""
        return f"RVToDo({self._start} - {self._end}: {self.original.summary.value if self.original.summary else ''})"

VJournal

Bases: AbstractComponentWithRecurringProperties

This class represents the VJOURNAL component specified in RFC 5545 in '3.6.3. Journal Component'.

A "VJOURNAL" calendar component is a grouping of component properties that represent one or more descriptive text notes associated with a particular calendar date. The "DTSTART" property is used to specify the calendar date with which the journal entry is associated. Generally, it will have a DATE value data type, but it can also be used to specify a DATE-TIME value data type. Examples of a journal entry include a daily record of a legislative body or a journal entry of individual telephone contacts for the day or an ordered list of accomplishments for the day. The "VJOURNAL" calendar component can also be used to associate a document with a calendar date.

Parameters:

Name Type Description Default
name

The actual name of this component instance. E.g. VEVENT, RRULE, VCUSTOMCOMPONENT.

 required
dtstamp Optional[DTStamp]

The DTStamp property. Required and must occur exactly once.

 None
uid Optional[UID]

The UID property. Required and must occur exactly once.

 None
dtstart Optional[DTStart]

The DTStart property. Optional and may occur at most once.

 None
rrule Optional[RRule]

The RRule property. Optional and may occur at most once.

 None
summary Optional[Summary]

The Summary property. Optional and may occur at most once.

 None
exdate Optional[List[EXDate]]

The EXDate property. Optional, but may occur multiple times.

 None
rdate Optional[List[RDate]]

The RDate property. Optional, but may occur multiple times.

 None
comment Optional[List[Comment]]

The Comment property. Optional, but may occur multiple times.

 None
ical_class Optional[Class]

Optional Class property. Optional, but may occur at most once.

 None
created Optional[Created]

The Created property. Optional, but may occur at most once.

 None
last_modified Optional[LastModified]

Optional LastModified property. Optional, but may occur at most once.

 None
organizer Optional[Organizer]

The Organizer property. Optional, but may occur at most once.

 None
sequence Optional[Sequence]

The Sequence property. Optional, but may occur at most once.

 None
status Optional[Status]

The Status property. Optional, but may occur at most once.

 None
url Optional[URL]

The URL property. Optional, but may occur at most once.

 None
recurrence_id Optional[RecurrenceID]

Optional RecurrenceID property. Optional, but may occur at most once.

 None
attach Optional[List[Attach]]

The Attach property. Optional, but may occur multiple times.

 None
attendee Optional[List[Attendee]]

The Attendee property. Optional, but may occur multiple times.

 None
categories Optional[List[Categories]]

The Categories property. Optional, but may occur multiple times.

 None
contact Optional[List[Contact]]

The Contact property. Optional, but may occur multiple times.

 None
description Optional[List[Description]]

The Description property. Optional, but may occur multiple times.

 None
related Optional[List[RelatedTo]]

The RelatedTo property. Optional, but may occur multiple times.

 None
rstatus Optional[List[RequestStatus]]

The RequestStatus property. Optional, but may occur multiple times.

 None
parent Optional[Component]

The Component this item is encapsulated by in the iCalendar data file.

 None
Source code in ical_library/ical_components/v_journal.py 
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
class VJournal(AbstractComponentWithRecurringProperties):
    """
    This class represents the VJOURNAL component specified in RFC 5545 in '3.6.3. Journal Component'.

    A "VJOURNAL" calendar component is a grouping of component properties that represent one or more descriptive text
    notes associated with a particular calendar date. The "DTSTART" property is used to specify the calendar date with
    which the journal entry is associated. Generally, it will have a DATE value data type, but it can also be used to
    specify a DATE-TIME value data type. Examples of a journal entry include a daily record of a legislative body or
    a journal entry of individual telephone contacts for the day or an ordered list of accomplishments for the day.
    The "VJOURNAL" calendar component can also be used to associate a document with a calendar date.

    :param name: The actual name of this component instance. E.g. VEVENT, RRULE, VCUSTOMCOMPONENT.
    :param dtstamp: The DTStamp property. Required and must occur exactly once.
    :param uid: The UID property. Required and must occur exactly once.
    :param dtstart: The DTStart property. Optional and may occur at most once.
    :param rrule: The RRule property. Optional and may occur at most once.
    :param summary: The Summary property. Optional and may occur at most once.
    :param exdate: The EXDate property. Optional, but may occur multiple times.
    :param rdate: The RDate property. Optional, but may occur multiple times.
    :param comment: The Comment property. Optional, but may occur multiple times.
    :param ical_class: Optional Class property. Optional, but may occur at most once.
    :param created: The Created property. Optional, but may occur at most once.
    :param last_modified: Optional LastModified property. Optional, but may occur at most once.
    :param organizer: The Organizer property. Optional, but may occur at most once.
    :param sequence: The Sequence property. Optional, but may occur at most once.
    :param status: The Status property. Optional, but may occur at most once.
    :param url: The URL property. Optional, but may occur at most once.
    :param recurrence_id: Optional RecurrenceID property. Optional, but may occur at most once.
    :param attach: The Attach property. Optional, but may occur multiple times.
    :param attendee: The Attendee property. Optional, but may occur multiple times.
    :param categories: The Categories property. Optional, but may occur multiple times.
    :param contact: The Contact property. Optional, but may occur multiple times.
    :param description: The Description property. Optional, but may occur multiple times.
    :param related: The RelatedTo property. Optional, but may occur multiple times.
    :param rstatus: The RequestStatus property. Optional, but may occur multiple times.
    :param parent: The Component this item is encapsulated by in the iCalendar data file.
    """

    def __init__(
        self,
        dtstamp: Optional[DTStamp] = None,
        uid: Optional[UID] = None,
        dtstart: Optional[DTStart] = None,
        rrule: Optional[RRule] = None,
        summary: Optional[Summary] = None,
        exdate: Optional[List[EXDate]] = None,
        rdate: Optional[List[RDate]] = None,
        comment: Optional[List[Comment]] = None,
        ical_class: Optional[Class] = None,
        created: Optional[Created] = None,
        last_modified: Optional[LastModified] = None,
        organizer: Optional[Organizer] = None,
        sequence: Optional[Sequence] = None,
        status: Optional[Status] = None,
        url: Optional[URL] = None,
        recurrence_id: Optional[RecurrenceID] = None,
        attach: Optional[List[Attach]] = None,
        attendee: Optional[List[Attendee]] = None,
        categories: Optional[List[Categories]] = None,
        contact: Optional[List[Contact]] = None,
        description: Optional[List[Description]] = None,
        related: Optional[List[RelatedTo]] = None,
        rstatus: Optional[List[RequestStatus]] = None,
        parent: Optional[Component] = None,
    ):
        super().__init__(
            name="VJOURNAL",
            dtstamp=dtstamp,
            uid=uid,
            dtstart=dtstart,
            rrule=rrule,
            summary=summary,
            exdate=exdate,
            rdate=rdate,
            comment=comment,
            parent=parent,
        )

        # Optional, may only occur once
        # As class is a reserved keyword in python, we prefixed it with `ical_`.
        self.ical_class: Optional[Class] = self.as_parent(ical_class)
        self.created: Optional[Created] = self.as_parent(created)
        self.last_modified: Optional[LastModified] = self.as_parent(last_modified)
        self.organizer: Optional[Organizer] = self.as_parent(organizer)
        self.sequence: Optional[Sequence] = self.as_parent(sequence)
        self.status: Optional[Status] = self.as_parent(status)
        self.url: Optional[URL] = self.as_parent(url)

        # Optional, may occur more than once
        self.attach: Optional[List[Attach]] = self.as_parent(attach)
        self.attendee: Optional[List[Attendee]] = self.as_parent(attendee)
        self.categories: Optional[List[Categories]] = self.as_parent(categories)
        self.contact: Optional[List[Contact]] = self.as_parent(contact)
        self.description: Optional[List[Description]] = self.as_parent(description)
        self.related: Optional[List[RelatedTo]] = self.as_parent(related)
        self.rstatus: Optional[List[RequestStatus]] = self.as_parent(rstatus)

    def __repr__(self) -> str:
        """Overwrite the repr to create a better representation for the item."""
        return f"VJournal({self.start}: {self.summary.value if self.summary else ''})"

    @property
    def ending(self) -> Optional[_DTBoth]:
        """
        Return the start time of the journal. This is because the Journal does not have a duration.

        Note: This is an abstract method from :class:`AbstractComponentWithRecurringProperties` we have to implement.
        """
        return self.dtstart

    def get_duration(self) -> Optional[Duration]:
        """
        Return an empty Duration as a Journal does not have a duration.

        Note: This is an abstract method from :class:`AbstractComponentWithRecurringProperties` we have to implement.
        """
        return Duration()

    def expand_component_in_range(
        self, return_range: Timespan, starts_to_exclude: Union[List[Date], List[DateTime]]
    ) -> Iterator[TimespanWithParent]:
        """
        Expand this VJournal in range according to its recurring *RDate*, *EXDate* and *RRule* properties.
        :param return_range: The timespan range on which we should return VJournal instances.
        :param starts_to_exclude: List of start Dates or list of start DateTimes of which we already know we should
        exclude them from our recurrence computation (as they have been completely redefined in another element).
        :return: Yield all recurring VJournal instances related to this VJournal in the given *return_range*.
        """
        if self.timespan.intersects(return_range):
            yield self.timespan
        starts_to_exclude.append(self.start)

        start = self.start
        duration = self.computed_duration
        if not start or not duration:
            return None

        iterator = property_utils.expand_component_in_range(
            exdate_list=self.exdate or [],
            rdate_list=self.rdate or [],
            rrule=self.rrule,
            first_event_start=self.start,
            first_event_duration=self.computed_duration,
            starts_to_exclude=starts_to_exclude,
            return_range=return_range,
            make_tz_aware=None,
        )

        for event_start_time, event_end_time in iterator:
            yield VRecurringJournal(original_component_instance=self, start=event_start_time).timespan

ending: Optional[_DTBoth] property

Return the start time of the journal. This is because the Journal does not have a duration.

Note: This is an abstract method from :class:AbstractComponentWithRecurringProperties we have to implement.

expand_component_in_range(return_range, starts_to_exclude)

Expand this VJournal in range according to its recurring RDate, EXDate and RRule properties.

Parameters:

Name Type Description Default
return_range Timespan

The timespan range on which we should return VJournal instances.

 required
starts_to_exclude Union[List[Date], List[DateTime]]

List of start Dates or list of start DateTimes of which we already know we should exclude them from our recurrence computation (as they have been completely redefined in another element).

 required

Returns:

Type Description
Iterator[TimespanWithParent]

Yield all recurring VJournal instances related to this VJournal in the given return_range.
Source code in ical_library/ical_components/v_journal.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
def expand_component_in_range(
    self, return_range: Timespan, starts_to_exclude: Union[List[Date], List[DateTime]]
) -> Iterator[TimespanWithParent]:
    """
    Expand this VJournal in range according to its recurring *RDate*, *EXDate* and *RRule* properties.
    :param return_range: The timespan range on which we should return VJournal instances.
    :param starts_to_exclude: List of start Dates or list of start DateTimes of which we already know we should
    exclude them from our recurrence computation (as they have been completely redefined in another element).
    :return: Yield all recurring VJournal instances related to this VJournal in the given *return_range*.
    """
    if self.timespan.intersects(return_range):
        yield self.timespan
    starts_to_exclude.append(self.start)

    start = self.start
    duration = self.computed_duration
    if not start or not duration:
        return None

    iterator = property_utils.expand_component_in_range(
        exdate_list=self.exdate or [],
        rdate_list=self.rdate or [],
        rrule=self.rrule,
        first_event_start=self.start,
        first_event_duration=self.computed_duration,
        starts_to_exclude=starts_to_exclude,
        return_range=return_range,
        make_tz_aware=None,
    )

    for event_start_time, event_end_time in iterator:
        yield VRecurringJournal(original_component_instance=self, start=event_start_time).timespan

get_duration()

Return an empty Duration as a Journal does not have a duration.

Note: This is an abstract method from :class:AbstractComponentWithRecurringProperties we have to implement.

Source code in ical_library/ical_components/v_journal.py 
143
144
145
146
147
148
149
def get_duration(self) -> Optional[Duration]:
    """
    Return an empty Duration as a Journal does not have a duration.

    Note: This is an abstract method from :class:`AbstractComponentWithRecurringProperties` we have to implement.
    """
    return Duration()

VRecurringJournal

Bases: AbstractRecurrence, VJournal

This class represents VJournal that are recurring. Inside the AbstractRecurrence class we overwrite specific dunder methods and property methods. This way our end users have a very similar interface to an actual VJournal but without us needing to code the exact same thing twice.

Parameters:

Name Type Description Default
original_component_instance VJournal

The original VJournal instance.

 required
start DateTime

The start of this occurrence.

 required
end

The end of this occurrence.

 required
Source code in ical_library/ical_components/v_journal.py 
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
class VRecurringJournal(AbstractRecurrence, VJournal):
    """
    This class represents VJournal that are recurring.
    Inside the AbstractRecurrence class we overwrite specific dunder methods and property methods.
    This way our end users have a very similar interface to an actual VJournal but without us needing to code the exact
    same thing twice.

    :param original_component_instance: The original VJournal instance.
    :param start: The start of this occurrence.
    :param end: The end of this occurrence.
    """

    def __init__(self, original_component_instance: VJournal, start: DateTime):
        self._original = original_component_instance
        self._start = start
        self._end = start
        super(VJournal, self).__init__("VJOURNAL", parent=original_component_instance)

    def __repr__(self) -> str:
        """Overwrite the repr to create a better representation for the item."""
        return f"RVJournal({self._start}: {self.original.summary.value if self.original.summary else ''})"