Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/icalendar/cal/event.py: 61%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1""":rfc:`5545` VEVENT component."""
3from __future__ import annotations
5import uuid
6from datetime import date, datetime, timedelta
7from typing import TYPE_CHECKING, Literal
9from icalendar.attr import (
10 CONCEPTS_TYPE_SETTER,
11 LINKS_TYPE_SETTER,
12 RELATED_TO_TYPE_SETTER,
13 X_MOZ_LASTACK_property,
14 X_MOZ_SNOOZE_TIME_property,
15 attendees_property,
16 categories_property,
17 class_property,
18 color_property,
19 conferences_property,
20 contacts_property,
21 create_single_property,
22 description_property,
23 exdates_property,
24 get_duration_property,
25 get_end_property,
26 get_start_end_duration_with_validation,
27 get_start_property,
28 images_property,
29 location_property,
30 organizer_property,
31 priority_property,
32 property_del_duration,
33 property_doc_duration_template,
34 property_get_duration,
35 property_set_duration,
36 rdates_property,
37 rrules_property,
38 sequence_property,
39 set_duration_with_locking,
40 set_end_with_locking,
41 set_start_with_locking,
42 status_property,
43 summary_property,
44 transparency_property,
45 uid_property,
46 url_property,
47)
48from icalendar.cal.component import Component
49from icalendar.cal.examples import get_example
51if TYPE_CHECKING:
52 from collections.abc import Sequence
54 from icalendar.alarms import Alarms
55 from icalendar.enums import CLASS, STATUS, TRANSP
56 from icalendar.prop import vCalAddress
57 from icalendar.prop.conference import Conference
60class Event(Component):
61 """A grouping of component properties that describe an event.
63 Description:
64 A "VEVENT" calendar component is a grouping of
65 component properties, possibly including "VALARM" calendar
66 components, that represents a scheduled amount of time on a
67 calendar. For example, it can be an activity; such as a one-hour
68 long, department meeting from 8:00 AM to 9:00 AM, tomorrow.
69 Generally, an event will take up time on an individual calendar.
70 Hence, the event will appear as an opaque interval in a search for
71 busy time. Alternately, the event can have its Time Transparency
72 set to "TRANSPARENT" in order to prevent blocking of the event in
73 searches for busy time.
75 The "VEVENT" is also the calendar component used to specify an
76 anniversary or daily reminder within a calendar. These events
77 have a DATE value type for the "DTSTART" property instead of the
78 default value type of DATE-TIME. If such a "VEVENT" has a "DTEND"
79 property, it MUST be specified as a DATE value also. The
80 anniversary type of "VEVENT" can span more than one date (i.e.,
81 "DTEND" property value is set to a calendar date after the
82 "DTSTART" property value). If such a "VEVENT" has a "DURATION"
83 property, it MUST be specified as a "dur-day" or "dur-week" value.
85 The "DTSTART" property for a "VEVENT" specifies the inclusive
86 start of the event. For recurring events, it also specifies the
87 very first instance in the recurrence set. The "DTEND" property
88 for a "VEVENT" calendar component specifies the non-inclusive end
89 of the event. For cases where a "VEVENT" calendar component
90 specifies a "DTSTART" property with a DATE value type but no
91 "DTEND" nor "DURATION" property, the event's duration is taken to
92 be one day. For cases where a "VEVENT" calendar component
93 specifies a "DTSTART" property with a DATE-TIME value type but no
94 "DTEND" property, the event ends on the same calendar date and
95 time of day specified by the "DTSTART" property.
97 The "VEVENT" calendar component cannot be nested within another
98 calendar component. However, "VEVENT" calendar components can be
99 related to each other or to a "VTODO" or to a "VJOURNAL" calendar
100 component with the "RELATED-TO" property.
102 Examples:
103 The following is an example of the "VEVENT" calendar
104 component used to represent a meeting that will also be opaque to
105 searches for busy time:
107 .. code-block:: text
109 BEGIN:VEVENT
110 UID:19970901T130000Z-123401@example.com
111 DTSTAMP:19970901T130000Z
112 DTSTART:19970903T163000Z
113 DTEND:19970903T190000Z
114 SUMMARY:Annual Employee Review
115 CLASS:PRIVATE
116 CATEGORIES:BUSINESS,HUMAN RESOURCES
117 END:VEVENT
119 The following is an example of the "VEVENT" calendar component
120 used to represent a reminder that will not be opaque, but rather
121 transparent, to searches for busy time:
123 .. code-block:: text
125 BEGIN:VEVENT
126 UID:19970901T130000Z-123402@example.com
127 DTSTAMP:19970901T130000Z
128 DTSTART:19970401T163000Z
129 DTEND:19970402T010000Z
130 SUMMARY:Laurel is in sensitivity awareness class.
131 CLASS:PUBLIC
132 CATEGORIES:BUSINESS,HUMAN RESOURCES
133 TRANSP:TRANSPARENT
134 END:VEVENT
136 The following is an example of the "VEVENT" calendar component
137 used to represent an anniversary that will occur annually:
139 .. code-block:: text
141 BEGIN:VEVENT
142 UID:19970901T130000Z-123403@example.com
143 DTSTAMP:19970901T130000Z
144 DTSTART;VALUE=DATE:19971102
145 SUMMARY:Our Blissful Anniversary
146 TRANSP:TRANSPARENT
147 CLASS:CONFIDENTIAL
148 CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION
149 RRULE:FREQ=YEARLY
150 END:VEVENT
152 The following is an example of the "VEVENT" calendar component
153 used to represent a multi-day event scheduled from June 28th, 2007
154 to July 8th, 2007 inclusively. Note that the "DTEND" property is
155 set to July 9th, 2007, since the "DTEND" property specifies the
156 non-inclusive end of the event.
158 .. code-block:: text
160 BEGIN:VEVENT
161 UID:20070423T123432Z-541111@example.com
162 DTSTAMP:20070423T123432Z
163 DTSTART;VALUE=DATE:20070628
164 DTEND;VALUE=DATE:20070709
165 SUMMARY:Festival International de Jazz de Montreal
166 TRANSP:TRANSPARENT
167 END:VEVENT
169 Create a new Event:
171 .. code-block:: python
173 >>> from icalendar import Event
174 >>> from datetime import datetime
175 >>> event = Event.new(start=datetime(2021, 1, 1, 12, 30, 0))
176 >>> print(event.to_ical())
177 BEGIN:VEVENT
178 DTSTART:20210101T123000
179 DTSTAMP:20250517T080612Z
180 UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
181 END:VEVENT
183 """
185 name = "VEVENT"
187 canonical_order = (
188 "SUMMARY",
189 "DTSTART",
190 "DTEND",
191 "DURATION",
192 "DTSTAMP",
193 "UID",
194 "RECURRENCE-ID",
195 "SEQUENCE",
196 "RRULE",
197 "RDATE",
198 "EXDATE",
199 )
201 required = (
202 "UID",
203 "DTSTAMP",
204 )
205 singletons = (
206 "CLASS",
207 "CREATED",
208 "COLOR",
209 "DESCRIPTION",
210 "DTSTART",
211 "GEO",
212 "LAST-MODIFIED",
213 "LOCATION",
214 "ORGANIZER",
215 "PRIORITY",
216 "DTSTAMP",
217 "SEQUENCE",
218 "STATUS",
219 "SUMMARY",
220 "TRANSP",
221 "URL",
222 "RECURRENCE-ID",
223 "DTEND",
224 "DURATION",
225 "UID",
226 )
227 exclusive = (
228 "DTEND",
229 "DURATION",
230 )
231 multiple = (
232 "ATTACH",
233 "ATTENDEE",
234 "CATEGORIES",
235 "COMMENT",
236 "CONTACT",
237 "EXDATE",
238 "RSTATUS",
239 "RELATED",
240 "RESOURCES",
241 "RDATE",
242 "RRULE",
243 )
244 ignore_exceptions = True
246 @property
247 def alarms(self) -> Alarms:
248 """Compute the alarm times for this component.
250 >>> from icalendar import Event
251 >>> event = Event.example("rfc_9074_example_1")
252 >>> len(event.alarms.times)
253 1
254 >>> alarm_time = event.alarms.times[0]
255 >>> alarm_time.trigger # The time when the alarm pops up
256 datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='America/New_York'))
257 >>> alarm_time.is_active() # This alarm has not been acknowledged
258 True
260 Note that this only uses DTSTART and DTEND, but ignores
261 RDATE, EXDATE, and RRULE properties.
262 """
263 from icalendar.alarms import Alarms
265 return Alarms(self)
267 @classmethod
268 def example(cls, name: str = "rfc_9074_example_3") -> Event:
269 """Return the calendar example with the given name."""
270 return cls.from_ical(get_example("events", name))
272 DTSTART = create_single_property(
273 "DTSTART",
274 "dt",
275 (datetime, date),
276 date,
277 'The "DTSTART" property for a "VEVENT" specifies the inclusive start of the event.',
278 )
279 DTEND = create_single_property(
280 "DTEND",
281 "dt",
282 (datetime, date),
283 date,
284 'The "DTEND" property for a "VEVENT" calendar component specifies the non-inclusive end of the event.',
285 )
287 def _get_start_end_duration(self):
288 """Verify the calendar validity and return the right attributes."""
289 return get_start_end_duration_with_validation(
290 self, "DTSTART", "DTEND", "VEVENT"
291 )
293 DURATION = property(
294 property_get_duration,
295 property_set_duration,
296 property_del_duration,
297 property_doc_duration_template.format(component="VEVENT"),
298 )
300 @property
301 def duration(self) -> timedelta:
302 """The duration of the VEVENT.
304 Returns the DURATION property if set, otherwise calculated from start and end.
305 When setting duration, the end time is automatically calculated from start +
306 duration.
308 You can set the duration to automatically adjust the end time while keeping
309 start locked.
311 Setting the duration will:
313 1. Keep the start time locked (unchanged)
314 2. Adjust the end time to start + duration
315 3. Remove any existing DTEND property
316 4. Set the DURATION property
317 """
318 return get_duration_property(self)
320 @duration.setter
321 def duration(self, value: timedelta):
322 if not isinstance(value, timedelta):
323 raise TypeError(f"Use timedelta, not {type(value).__name__}.")
325 # Use the set_duration method with default start-locked behavior
326 self.set_duration(value, locked="start")
328 @property
329 def start(self) -> date | datetime:
330 """The start of the event.
332 Invalid values raise an InvalidCalendar.
333 If there is no start, we also raise an IncompleteComponent error.
335 You can get the start, end and duration of an event as follows:
337 >>> from datetime import datetime
338 >>> from icalendar import Event
339 >>> event = Event()
340 >>> event.start = datetime(2021, 1, 1, 12)
341 >>> event.end = datetime(2021, 1, 1, 12, 30) # 30 minutes
342 >>> event.duration # 1800 seconds == 30 minutes
343 datetime.timedelta(seconds=1800)
344 >>> print(event.to_ical())
345 BEGIN:VEVENT
346 DTSTART:20210101T120000
347 DTEND:20210101T123000
348 END:VEVENT
349 """
350 return get_start_property(self)
352 @start.setter
353 def start(self, start: date | datetime | None):
354 """Set the start."""
355 self.DTSTART = start
357 @property
358 def end(self) -> date | datetime:
359 """The end of the event.
361 Invalid values raise an InvalidCalendar error.
362 If there is no end, we also raise an IncompleteComponent error.
363 """
364 return get_end_property(self, "DTEND")
366 @end.setter
367 def end(self, end: date | datetime | None):
368 """Set the end."""
369 self.DTEND = end
371 def set_duration(
372 self, duration: timedelta | None, locked: Literal["start", "end"] = "start"
373 ):
374 """Set the duration of the event relative to either start or end.
376 Parameters:
377 duration: The duration to set, or None to convert to DURATION property
378 locked: Which property to keep unchanged ('start' or 'end')
379 """
380 set_duration_with_locking(self, duration, locked, "DTEND")
382 def set_start(
383 self, start: date | datetime, locked: Literal["duration", "end"] | None = None
384 ):
385 """Set the start and keep the duration or end of the event.
387 Parameters:
388 start: The start time to set
389 locked: Which property to keep unchanged ('duration', 'end', or None
390 for auto-detect)
391 """
392 set_start_with_locking(self, start, locked, "DTEND")
394 def set_end(
395 self, end: date | datetime, locked: Literal["start", "duration"] = "start"
396 ):
397 """Set the end of the component, keeping either the start or the duration same.
399 Parameters:
400 end: The end time to set
401 locked: Which property to keep unchanged ('start' or 'duration')
402 """
403 set_end_with_locking(self, end, locked, "DTEND")
405 X_MOZ_SNOOZE_TIME = X_MOZ_SNOOZE_TIME_property
406 X_MOZ_LASTACK = X_MOZ_LASTACK_property
407 color = color_property
408 sequence = sequence_property
409 categories = categories_property
410 rdates = rdates_property
411 exdates = exdates_property
412 rrules = rrules_property
413 uid = uid_property
414 summary = summary_property
415 description = description_property
416 classification = class_property
417 url = url_property
418 organizer = organizer_property
419 location = location_property
420 priority = priority_property
421 contacts = contacts_property
422 transparency = transparency_property
423 status = status_property
424 attendees = attendees_property
425 images = images_property
426 conferences = conferences_property
428 @classmethod
429 def new(
430 cls,
431 /,
432 attendees: list[vCalAddress] | None = None,
433 categories: Sequence[str] = (),
434 classification: CLASS | None = None,
435 color: str | None = None,
436 comments: list[str] | str | None = None,
437 concepts: CONCEPTS_TYPE_SETTER = None,
438 conferences: list[Conference] | None = None,
439 contacts: list[str] | str | None = None,
440 created: date | None = None,
441 description: str | None = None,
442 end: date | datetime | None = None,
443 last_modified: date | None = None,
444 links: LINKS_TYPE_SETTER = None,
445 location: str | None = None,
446 organizer: vCalAddress | str | None = None,
447 priority: int | None = None,
448 refids: list[str] | str | None = None,
449 related_to: RELATED_TO_TYPE_SETTER = None,
450 sequence: int | None = None,
451 stamp: date | None = None,
452 start: date | datetime | None = None,
453 status: STATUS | None = None,
454 transparency: TRANSP | None = None,
455 summary: str | None = None,
456 uid: str | uuid.UUID | None = None,
457 url: str | None = None,
458 ):
459 """Create a new event with all required properties.
461 This creates a new Event in accordance with :rfc:`5545`.
463 Parameters:
464 attendees: The :attr:`attendees` of the event.
465 categories: The :attr:`categories` of the event.
466 classification: The :attr:`classification` of the event.
467 color: The :attr:`color` of the event.
468 comments: The :attr:`~icalendar.Component.comments` of the event.
469 concepts: The :attr:`~icalendar.Component.concepts` of the event.
470 conferences: The :attr:`conferences` of the event.
471 created: The :attr:`~icalendar.Component.created` of the event.
472 description: The :attr:`description` of the event.
473 end: The :attr:`end` of the event.
474 last_modified: The :attr:`~icalendar.Component.last_modified` of the event.
475 links: The :attr:`~icalendar.Component.links` of the event.
476 location: The :attr:`location` of the event.
477 organizer: The :attr:`organizer` of the event.
478 priority: The :attr:`priority` of the event.
479 refids: :attr:`~icalendar.Component.refids` of the event.
480 related_to: :attr:`~icalendar.Component.related_to` of the event.
481 sequence: The :attr:`sequence` of the event.
482 stamp: The :attr:`~icalendar.Component.stamp` of the event.
483 If None, this is set to the current time.
484 start: The :attr:`start` of the event.
485 status: The :attr:`status` of the event.
486 summary: The :attr:`summary` of the event.
487 transparency: The :attr:`transparency` of the event.
488 uid: The :attr:`uid` of the event.
489 If None, this is set to a new :func:`uuid.uuid4`.
490 url: The :attr:`url` of the event.
492 Returns:
493 :class:`Event`
495 Raises:
496 ~error.InvalidCalendar: If the content is not valid
497 according to :rfc:`5545`.
499 .. warning:: As time progresses, we will be stricter with the validation.
500 """
501 event: Event = super().new(
502 stamp=stamp if stamp is not None else cls._utc_now(),
503 created=created,
504 last_modified=last_modified,
505 comments=comments,
506 links=links,
507 related_to=related_to,
508 refids=refids,
509 concepts=concepts,
510 )
511 event.summary = summary
512 event.description = description
513 event.uid = uid if uid is not None else uuid.uuid4()
514 event.start = start
515 event.end = end
516 event.color = color
517 event.categories = categories
518 event.sequence = sequence
519 event.classification = classification
520 event.url = url
521 event.organizer = organizer
522 event.location = location
523 event.priority = priority
524 event.transparency = transparency
525 event.contacts = contacts
526 event.status = status
527 event.attendees = attendees
528 event.conferences = conferences
530 if cls._validate_new:
531 cls._validate_start_and_end(start, end)
532 return event
535__all__ = ["Event"]