ical.event

  1"""A grouping of component properties that describe a calendar event.
  2
  3An event can be an activity (e.g. a meeting from 8am to 9am tomorrow)
  4grouping of properties such as a summary or a description. An event will
  5take up time on a calendar as an opaque time interval, but can alternatively
  6have transparency set to transparent to prevent blocking of time as busy.
  7
  8An event start and end time may either be a date and time or just a day
  9alone. Events may also span more than one day. Alternatively, an event
 10can have a start and a duration.
 11"""
 12
 13# pylint: disable=unnecessary-lambda
 14
 15from __future__ import annotations
 16
 17import datetime
 18import enum
 19import logging
 20from collections.abc import Iterable
 21from typing import Annotated, Any, Optional, Self, Union
 22
 23from pydantic import BeforeValidator, Field, field_serializer, model_validator
 24
 25from ical.compat import duration_dtend_compat, same_day_dtend_compat
 26from ical.types.data_types import serialize_field
 27
 28from .alarm import Alarm
 29from .component import (
 30    ComponentModel,
 31    validate_duration_unit,
 32    validate_until_dtstart,
 33    validate_recurrence_dates,
 34)
 35from .iter import RulesetIterable, as_rrule
 36from .timespan import Timespan
 37from .types import (
 38    Attachment,
 39    CalAddress,
 40    Classification,
 41    Conference,
 42    ExtraProperty,
 43    Geo,
 44    Image,
 45    Priority,
 46    Recur,
 47    RecurrenceId,
 48    RequestStatus,
 49    Uri,
 50    RelatedTo,
 51    Period,
 52)
 53from .util import (
 54    dtstamp_factory,
 55    normalize_datetime,
 56    parse_date_and_datetime,
 57    parse_date_and_datetime_list,
 58    parse_rdate_list,
 59    uid_factory,
 60)
 61
 62_LOGGER = logging.getLogger(__name__)
 63
 64__all__ = ["Event", "EventStatus"]
 65
 66
 67class EventStatus(str, enum.Enum):
 68    """Status or confirmation of the event set by the organizer."""
 69
 70    CONFIRMED = "CONFIRMED"
 71    """Indicates event is definite."""
 72
 73    TENTATIVE = "TENTATIVE"
 74    """Indicates event is tentative."""
 75
 76    CANCELLED = "CANCELLED"
 77    """Indicates event was cancelled."""
 78
 79
 80class Event(ComponentModel):
 81    """A single event on a calendar.
 82
 83    Can either be for a specific day, or with a start time and duration/end time.
 84
 85    The dtstamp and uid functions have factory methods invoked with a lambda to facilitate
 86    mocking in unit tests.
 87
 88
 89    Example:
 90    ```python
 91    import datetime
 92    from ical.event import Event
 93
 94    event = Event(
 95        dtstart=datetime.datetime(2022, 8, 31, 7, 00, 00),
 96        dtend=datetime.datetime(2022, 8, 31, 7, 30, 00),
 97        summary="Morning exercise",
 98    )
 99    print("The event duration is: ", event.computed_duration)
100    ```
101
102    An Event is a pydantic model, so all properties of a pydantic model apply here to such as
103    the constructor arguments, properties to return the model as a dictionary or json, as well
104    as other parsing methods.
105    """
106
107    dtstamp: Annotated[
108        Union[datetime.date, datetime.datetime],
109        BeforeValidator(parse_date_and_datetime),
110    ] = Field(default_factory=lambda: dtstamp_factory())
111    """Specifies the date and time the event was created."""
112
113    uid: str = Field(default_factory=lambda: uid_factory())
114    """A globally unique identifier for the event."""
115
116    # Has an alias of 'start'
117    dtstart: Annotated[
118        Union[datetime.date, datetime.datetime, None],
119        BeforeValidator(parse_date_and_datetime),
120    ] = Field(default=None)
121    """The start time or start day of the event."""
122
123    # Has an alias of 'end'
124    dtend: Annotated[
125        Union[datetime.date, datetime.datetime, None],
126        BeforeValidator(parse_date_and_datetime),
127    ] = None
128    """The end time or end day of the event.
129
130    This may be specified as an explicit date. Alternatively, a duration
131    can be used instead.
132    """
133
134    duration: Optional[datetime.timedelta] = None
135    """The duration of the event as an alternative to an explicit end date/time."""
136
137    summary: Optional[str] = None
138    """Defines a short summary or subject for the event."""
139
140    attendees: list[CalAddress] = Field(alias="attendee", default_factory=list)
141    """Specifies participants in a group-scheduled calendar."""
142
143    categories: list[str] = Field(default_factory=list)
144    """Defines the categories for an event.
145
146    Specifies a category or subtype. Can be useful for searching for a particular
147    type of event.
148    """
149
150    classification: Optional[Classification] = Field(alias="class", default=None)
151    """An access classification for a calendar event.
152
153    This provides a method of capturing the scope of access of a calendar, in
154    conjunction with an access control system.
155    """
156
157    comment: list[str] = Field(default_factory=list)
158    """Specifies a comment to the calendar user."""
159
160    contacts: list[str] = Field(alias="contact", default_factory=list)
161    """Contact information associated with the event."""
162
163    created: Optional[datetime.datetime] = None
164    """The date and time the event information was created."""
165
166    description: Optional[str] = None
167    """A more complete description of the event than provided by the summary."""
168
169    geo: Optional[Geo] = None
170    """Specifies a latitude and longitude global position for the event activity."""
171
172    last_modified: Optional[datetime.datetime] = Field(
173        alias="last-modified", default=None
174    )
175
176    color: Optional[str] = None
177    """Specifies a color associated with the event.
178
179    The value MUST be a case-insensitive color name defined in CSS3-Color (e.g., "blue" or "turquoise")
180    or a CSS3 RGB/RGBA color value in hex or functional notation (e.g., "#0000FF").
181    """
182
183    image: list[Image] = Field(default_factory=list)
184    """Specifies one or more images associated with the event."""
185
186    conference: list[Conference] = Field(default_factory=list)
187    """Specifies one or more conferences associated with the event."""
188
189    location: Optional[str] = None
190    """Defines the intended venue for the activity defined by this event."""
191
192    organizer: Optional[CalAddress] = None
193    """The organizer of a group-scheduled calendar entity."""
194
195    priority: Optional[Priority] = None
196    """Defines the relative priority of the calendar event."""
197
198    recurrence_id: Optional[RecurrenceId] = Field(alias="recurrence-id", default=None)
199    """Defines a specific instance of a recurring event.
200
201    The full range of calendar events specified by a recurrence set is referenced
202    by referring to just the uid. The `recurrence_id` allows reference of an individual
203    instance within the recurrence set.
204    """
205
206    related_to: list[RelatedTo] = Field(alias="related-to", default_factory=list)
207    """Used to represent a relationship or reference between events."""
208
209    related: list[str] = Field(default_factory=list)
210    """Unused and will be deleted in a future release"""
211
212    resources: list[str] = Field(default_factory=list)
213    """Defines the equipment or resources anticipated for the calendar event."""
214
215    rrule: Optional[Recur] = None
216    """A recurrence rule specification.
217
218    Defines a rule for specifying a repeated event. The recurrence set is the complete
219    set of recurrence instances for a calendar component (based on rrule, rdate, exdate).
220    The recurrence set is generated by gathering the rrule and rdate properties then
221    excluding any times specified by exdate. The recurrence is generated with the dtstart
222    property defining the first instance of the recurrence set.
223
224    Typically a dtstart should be specified with a date local time and timezone to make
225    sure all instances have the same start time regardless of time zone changing.
226    """
227
228    rdate: Annotated[
229        list[Union[datetime.date, datetime.datetime, Period]],
230        BeforeValidator(parse_rdate_list),
231    ] = Field(default_factory=list)
232    """Defines the list of date/time values for recurring events.
233
234    Can appear along with the rrule property to define a set of repeating occurrences of the
235    event. The recurrence set is the complete set of recurrence instances for a calendar component
236    (based on rrule, rdate, exdate). The recurrence set is generated by gathering the rrule
237    and rdate properties then excluding any times specified by exdate.
238    """
239
240    exdate: Annotated[
241        list[Union[datetime.date, datetime.datetime]],
242        BeforeValidator(parse_date_and_datetime_list),
243    ] = Field(default_factory=list)
244    """Defines the list of exceptions for recurring events.
245
246    The exception dates are used in computing the recurrence set. The recurrence set is
247    the complete set of recurrence instances for a calendar component (based on rrule, rdate,
248    exdate). The recurrence set is generated by gathering the rrule and rdate properties
249    then excluding any times specified by exdate.
250    """
251
252    request_status: list[RequestStatus] = Field(
253        alias="request-status",
254        default_factory=list,
255    )
256
257    sequence: Optional[int] = None
258    """The revision sequence number in the calendar component.
259
260    When an event is created, its sequence number is 0. It is monotonically incremented
261    by the organizer's calendar user agent every time a significant revision is made to
262    the calendar event.
263    """
264
265    status: Optional[EventStatus] = None
266    """Defines the overall status or confirmation of the event.
267
268    In a group-scheduled calendar, used by the organizer to provide a confirmation
269    of the event to attendees.
270    """
271
272    transparency: Optional[str] = Field(alias="transp", default=None)
273    """Defines whether or not an event is transparent to busy time searches."""
274
275    url: Optional[Uri] = None
276    """Defines a url associated with the event.
277
278    May convey a location where a more dynamic rendition of the calendar event
279    information associated with the event can be found.
280    """
281
282    attach: list[Attachment] = Field(default_factory=list)
283    """Associate a document object with the event."""
284
285    # Unknown or unsupported properties
286    extras: list[ExtraProperty] = Field(default_factory=list)
287
288    alarm: list[Alarm] = Field(alias="valarm", default_factory=list)
289    """A grouping of reminder alarms for the event."""
290
291    def __init__(self, **data: Any) -> None:
292        """Initialize a Calendar Event.
293
294        This method accepts keyword args with field names on the Calendar such as `summary`,
295        `start`, `end`, `description`, etc.
296        """
297        if "start" in data:
298            data["dtstart"] = data.pop("start")
299        if "end" in data:
300            data["dtend"] = data.pop("end")
301        super().__init__(**data)
302
303    @property
304    def start(self) -> datetime.datetime | datetime.date:
305        """Return the start time for the event."""
306        if self.dtstart is None:
307            raise AttributeError(
308                "Event.start accessed before dtstart was set; "
309                "ensure the event was fully validated before use."
310            )
311        return self.dtstart
312
313    @property
314    def end(self) -> datetime.datetime | datetime.date:
315        """Return the end time for the event."""
316        if self.duration:
317            return self.start + self.duration
318        if self.dtend:
319            return self.dtend
320
321        if isinstance(self.start, datetime.datetime):
322            return self.start
323        return self.start + datetime.timedelta(days=1)
324
325    @property
326    def start_datetime(self) -> datetime.datetime:
327        """Return the events start as a datetime in UTC"""
328        return normalize_datetime(self.start).astimezone(datetime.timezone.utc)
329
330    @property
331    def end_datetime(self) -> datetime.datetime:
332        """Return the events end as a datetime in UTC."""
333        return normalize_datetime(self.end).astimezone(datetime.timezone.utc)
334
335    @property
336    def computed_duration(self) -> datetime.timedelta:
337        """Return the event duration."""
338        if self.duration is not None:
339            return self.duration
340        return self.end - self.start
341
342    @property
343    def timespan(self) -> Timespan:
344        """Return a timespan representing the event start and end."""
345        return Timespan.of(self.start, self.end)
346
347    def timespan_of(self, tzinfo: datetime.tzinfo) -> Timespan:
348        """Return a timespan representing the event start and end."""
349        return Timespan.of(
350            normalize_datetime(self.start, tzinfo), normalize_datetime(self.end, tzinfo)
351        )
352
353    def starts_within(self, other: "Event") -> bool:
354        """Return True if this event starts while the other event is active."""
355        return self.timespan.starts_within(other.timespan)
356
357    def ends_within(self, other: "Event") -> bool:
358        """Return True if this event ends while the other event is active."""
359        return self.timespan.ends_within(other.timespan)
360
361    def intersects(self, other: "Event") -> bool:
362        """Return True if this event overlaps with the other event."""
363        return self.timespan.intersects(other.timespan)
364
365    def includes(self, other: "Event") -> bool:
366        """Return True if the other event starts and ends within this event."""
367        return self.timespan.includes(other.timespan)
368
369    def is_included_in(self, other: "Event") -> bool:
370        """Return True if this event starts and ends within the other event."""
371        return self.timespan.is_included_in(other.timespan)
372
373    def __lt__(self, other: Any) -> bool:
374        if not isinstance(other, Event):
375            return NotImplemented
376        return self.timespan < other.timespan
377
378    def __gt__(self, other: Any) -> bool:
379        if not isinstance(other, Event):
380            return NotImplemented
381        return self.timespan > other.timespan
382
383    def __le__(self, other: Any) -> bool:
384        if not isinstance(other, Event):
385            return NotImplemented
386        return self.timespan <= other.timespan
387
388    def __ge__(self, other: Any) -> bool:
389        if not isinstance(other, Event):
390            return NotImplemented
391        return self.timespan >= other.timespan
392
393    @property
394    def recurring(self) -> bool:
395        """Return true if this event is recurring.
396
397        A recurring event is typically evaluated specially on the timeline. The
398        data model has a single event, but the timeline evaluates the recurrence
399        to expand and copy the event to multiple places on the timeline
400        using `as_rrule`.
401        """
402        if self.rrule or self.rdate:
403            return True
404        return False
405
406    def as_rrule(self) -> Iterable[datetime.datetime | datetime.date] | None:
407        """Return an iterable containing the occurrences of a recurring event.
408
409        A recurring event is typically evaluated specially on the timeline. The
410        data model has a single event, but the timeline evaluates the recurrence
411        to expand and copy the event to multiple places on the timeline.
412
413        This is only valid for events where `recurring` is True.
414        """
415        return as_rrule(self.rrule, self.rdate, self.exdate, self.dtstart)
416
417    @model_validator(mode="before")
418    @classmethod
419    def _inspect_date_types(cls, values: dict[str, Any]) -> dict[str, Any]:
420        """Debug the date and date/time values of the event."""
421        dtstart = values.get("dtstart")
422        dtend = values.get("dtend")
423        if not dtstart or not dtend:
424            return values
425        _LOGGER.debug("Found initial values dtstart=%s, dtend=%s", dtstart, dtend)
426        return values
427
428    _validate_until_dtstart = model_validator(mode="after")(validate_until_dtstart)
429    _validate_recurrence_dates = model_validator(mode="after")(
430        validate_recurrence_dates
431    )
432
433    @model_validator(mode="after")
434    def _validate_date_types(self) -> Self:
435        """Validate that start and end values are the same date or datetime type."""
436        dtstart = self.dtstart
437        dtend = self.dtend
438
439        if not dtstart or not dtend:
440            return self
441        if isinstance(dtstart, datetime.datetime):
442            if not isinstance(dtend, datetime.datetime):
443                _LOGGER.debug("Unexpected data types for values: %s", self)
444                raise ValueError(
445                    f"Unexpected dtstart value '{dtstart}' was datetime but "
446                    f"dtend value '{dtend}' was not datetime"
447                )
448        elif isinstance(dtstart, datetime.date):
449            if isinstance(dtend, datetime.datetime):
450                raise ValueError(
451                    f"Unexpected dtstart value '{dtstart}' was date but "
452                    f"dtend value '{dtend}' was datetime"
453                )
454        return self
455
456    @model_validator(mode="after")
457    def _validate_datetime_timezone(self) -> Self:
458        """Validate that start and end values have the same timezone information."""
459        if (
460            not (dtstart := self.dtstart)
461            or not (dtend := self.dtend)
462            or not isinstance(dtstart, datetime.datetime)
463            or not isinstance(dtend, datetime.datetime)
464        ):
465            return self
466        if dtstart.tzinfo is None and dtend.tzinfo is not None:
467            raise ValueError(
468                f"Expected end datetime value in localtime but was {dtend}"
469            )
470        if dtstart.tzinfo is not None and dtend.tzinfo is None:
471            raise ValueError(f"Expected end datetime with timezone but was {dtend}")
472        return self
473
474    @model_validator(mode="after")
475    def _validate_one_end_or_duration(self) -> Self:
476        """Validate that only one of duration or end date may be set."""
477        if self.dtend and self.duration:
478            if duration_dtend_compat.is_duration_dtend_compat_enabled():
479                # RFC 5545 3.6.1 forbids specifying both DTEND and DURATION,
480                # but some real-world generators emit both anyway (often
481                # redundantly). Prefer the more explicit DTEND value and
482                # drop DURATION rather than failing to parse.
483                _LOGGER.warning(
484                    "Event has both DTEND (%s) and DURATION (%s) set; "
485                    "dropping DURATION per compat mode",
486                    self.dtend,
487                    self.duration,
488                )
489                self.duration = None
490            else:
491                raise ValueError("Only one of dtend or duration may be set.")
492        return self
493
494    @model_validator(mode="after")
495    def _validate_same_day_dtend(self) -> Self:
496        """Fix same-day DTEND for all-day events when compat mode is enabled."""
497        if same_day_dtend_compat.is_same_day_dtend_compat_enabled():
498            if isinstance(self.dtstart, datetime.date) and not isinstance(
499                self.dtstart, datetime.datetime
500            ):
501                if self.dtend and self.dtend == self.dtstart:
502                    self.dtend = self.dtstart + datetime.timedelta(days=1)
503        return self
504
505    _validate_duration_unit = model_validator(mode="after")(validate_duration_unit)
506
507    serialize_fields = field_serializer("*")(serialize_field)  # type: ignore[pydantic-field]