Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/icalendar/cal/event.py: 51%

1""":rfc:`5545` VEVENT component.""" 

2 

3from __future__ import annotations 

4 

5import uuid 

6from datetime import date, datetime, timedelta 

7from typing import TYPE_CHECKING, Optional, Sequence 

8 

9from icalendar.attr import ( 

10 X_MOZ_LASTACK_property, 

11 X_MOZ_SNOOZE_TIME_property, 

12 attendees_property, 

13 categories_property, 

14 class_property, 

15 color_property, 

16 contacts_property, 

17 create_single_property, 

18 description_property, 

19 exdates_property, 

20 location_property, 

21 organizer_property, 

22 priority_property, 

23 property_del_duration, 

24 property_doc_duration_template, 

25 property_get_duration, 

26 property_set_duration, 

27 rdates_property, 

28 rrules_property, 

29 sequence_property, 

30 status_property, 

31 summary_property, 

32 transparency_property, 

33 uid_property, 

34 url_property, 

35) 

36from icalendar.cal.component import Component 

37from icalendar.cal.examples import get_example 

38from icalendar.error import IncompleteComponent, InvalidCalendar 

39from icalendar.tools import is_date 

40 

41if TYPE_CHECKING: 

42 from icalendar.alarms import Alarms 

43 from icalendar.enums import CLASS, STATUS, TRANSP 

44 from icalendar.prop import vCalAddress 

45 

46 

47class Event(Component): 

48 """A grouping of component properties that describe an event. 

49 

50 Description: 

51 A "VEVENT" calendar component is a grouping of 

52 component properties, possibly including "VALARM" calendar 

53 components, that represents a scheduled amount of time on a 

54 calendar. For example, it can be an activity; such as a one-hour 

55 long, department meeting from 8:00 AM to 9:00 AM, tomorrow. 

56 Generally, an event will take up time on an individual calendar. 

57 Hence, the event will appear as an opaque interval in a search for 

58 busy time. Alternately, the event can have its Time Transparency 

59 set to "TRANSPARENT" in order to prevent blocking of the event in 

60 searches for busy time. 

61 

62 The "VEVENT" is also the calendar component used to specify an 

63 anniversary or daily reminder within a calendar. These events 

64 have a DATE value type for the "DTSTART" property instead of the 

65 default value type of DATE-TIME. If such a "VEVENT" has a "DTEND" 

66 property, it MUST be specified as a DATE value also. The 

67 anniversary type of "VEVENT" can span more than one date (i.e., 

68 "DTEND" property value is set to a calendar date after the 

69 "DTSTART" property value). If such a "VEVENT" has a "DURATION" 

70 property, it MUST be specified as a "dur-day" or "dur-week" value. 

71 

72 The "DTSTART" property for a "VEVENT" specifies the inclusive 

73 start of the event. For recurring events, it also specifies the 

74 very first instance in the recurrence set. The "DTEND" property 

75 for a "VEVENT" calendar component specifies the non-inclusive end 

76 of the event. For cases where a "VEVENT" calendar component 

77 specifies a "DTSTART" property with a DATE value type but no 

78 "DTEND" nor "DURATION" property, the event's duration is taken to 

79 be one day. For cases where a "VEVENT" calendar component 

80 specifies a "DTSTART" property with a DATE-TIME value type but no 

81 "DTEND" property, the event ends on the same calendar date and 

82 time of day specified by the "DTSTART" property. 

83 

84 The "VEVENT" calendar component cannot be nested within another 

85 calendar component. However, "VEVENT" calendar components can be 

86 related to each other or to a "VTODO" or to a "VJOURNAL" calendar 

87 component with the "RELATED-TO" property. 

88 

89 Examples: 

90 The following is an example of the "VEVENT" calendar 

91 component used to represent a meeting that will also be opaque to 

92 searches for busy time: 

93 

94 .. code-block:: text 

95 

96 BEGIN:VEVENT 

97 UID:19970901T130000Z-123401@example.com 

98 DTSTAMP:19970901T130000Z 

99 DTSTART:19970903T163000Z 

100 DTEND:19970903T190000Z 

101 SUMMARY:Annual Employee Review 

102 CLASS:PRIVATE 

103 CATEGORIES:BUSINESS,HUMAN RESOURCES 

104 END:VEVENT 

105 

106 The following is an example of the "VEVENT" calendar component 

107 used to represent a reminder that will not be opaque, but rather 

108 transparent, to searches for busy time: 

109 

110 .. code-block:: text 

111 

112 BEGIN:VEVENT 

113 UID:19970901T130000Z-123402@example.com 

114 DTSTAMP:19970901T130000Z 

115 DTSTART:19970401T163000Z 

116 DTEND:19970402T010000Z 

117 SUMMARY:Laurel is in sensitivity awareness class. 

118 CLASS:PUBLIC 

119 CATEGORIES:BUSINESS,HUMAN RESOURCES 

120 TRANSP:TRANSPARENT 

121 END:VEVENT 

122 

123 The following is an example of the "VEVENT" calendar component 

124 used to represent an anniversary that will occur annually: 

125 

126 .. code-block:: text 

127 

128 BEGIN:VEVENT 

129 UID:19970901T130000Z-123403@example.com 

130 DTSTAMP:19970901T130000Z 

131 DTSTART;VALUE=DATE:19971102 

132 SUMMARY:Our Blissful Anniversary 

133 TRANSP:TRANSPARENT 

134 CLASS:CONFIDENTIAL 

135 CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION 

136 RRULE:FREQ=YEARLY 

137 END:VEVENT 

138 

139 The following is an example of the "VEVENT" calendar component 

140 used to represent a multi-day event scheduled from June 28th, 2007 

141 to July 8th, 2007 inclusively. Note that the "DTEND" property is 

142 set to July 9th, 2007, since the "DTEND" property specifies the 

143 non-inclusive end of the event. 

144 

145 .. code-block:: text 

146 

147 BEGIN:VEVENT 

148 UID:20070423T123432Z-541111@example.com 

149 DTSTAMP:20070423T123432Z 

150 DTSTART;VALUE=DATE:20070628 

151 DTEND;VALUE=DATE:20070709 

152 SUMMARY:Festival International de Jazz de Montreal 

153 TRANSP:TRANSPARENT 

154 END:VEVENT 

155 

156 Create a new Event: 

157 

158 .. code-block:: python 

159 

160 >>> from icalendar import Event 

161 >>> from datetime import datetime 

162 >>> event = Event.new(start=datetime(2021, 1, 1, 12, 30, 0)) 

163 >>> print(event.to_ical()) 

164 BEGIN:VEVENT 

165 DTSTART:20210101T123000 

166 DTSTAMP:20250517T080612Z 

167 UID:d755cef5-2311-46ed-a0e1-6733c9e15c63 

168 END:VEVENT 

169 

170 """ 

171 

172 name = "VEVENT" 

173 

174 canonical_order = ( 

175 "SUMMARY", 

176 "DTSTART", 

177 "DTEND", 

178 "DURATION", 

179 "DTSTAMP", 

180 "UID", 

181 "RECURRENCE-ID", 

182 "SEQUENCE", 

183 "RRULE", 

184 "RDATE", 

185 "EXDATE", 

186 ) 

187 

188 required = ( 

189 "UID", 

190 "DTSTAMP", 

191 ) 

192 singletons = ( 

193 "CLASS", 

194 "CREATED", 

195 "COLOR", 

196 "DESCRIPTION", 

197 "DTSTART", 

198 "GEO", 

199 "LAST-MODIFIED", 

200 "LOCATION", 

201 "ORGANIZER", 

202 "PRIORITY", 

203 "DTSTAMP", 

204 "SEQUENCE", 

205 "STATUS", 

206 "SUMMARY", 

207 "TRANSP", 

208 "URL", 

209 "RECURRENCE-ID", 

210 "DTEND", 

211 "DURATION", 

212 "UID", 

213 ) 

214 exclusive = ( 

215 "DTEND", 

216 "DURATION", 

217 ) 

218 multiple = ( 

219 "ATTACH", 

220 "ATTENDEE", 

221 "CATEGORIES", 

222 "COMMENT", 

223 "CONTACT", 

224 "EXDATE", 

225 "RSTATUS", 

226 "RELATED", 

227 "RESOURCES", 

228 "RDATE", 

229 "RRULE", 

230 ) 

231 ignore_exceptions = True 

232 

233 @property 

234 def alarms(self) -> Alarms: 

235 """Compute the alarm times for this component. 

236 

237 >>> from icalendar import Event 

238 >>> event = Event.example("rfc_9074_example_1") 

239 >>> len(event.alarms.times) 

240 1 

241 >>> alarm_time = event.alarms.times[0] 

242 >>> alarm_time.trigger # The time when the alarm pops up 

243 datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='America/New_York')) 

244 >>> alarm_time.is_active() # This alarm has not been acknowledged 

245 True 

246 

247 Note that this only uses DTSTART and DTEND, but ignores 

248 RDATE, EXDATE, and RRULE properties. 

249 """ 

250 from icalendar.alarms import Alarms 

251 

252 return Alarms(self) 

253 

254 @classmethod 

255 def example(cls, name: str = "rfc_9074_example_3") -> Event: 

256 """Return the calendar example with the given name.""" 

257 return cls.from_ical(get_example("events", name)) 

258 

259 DTSTART = create_single_property( 

260 "DTSTART", 

261 "dt", 

262 (datetime, date), 

263 date, 

264 'The "DTSTART" property for a "VEVENT" specifies the inclusive start of the event.', # noqa: E501 

265 ) 

266 DTEND = create_single_property( 

267 "DTEND", 

268 "dt", 

269 (datetime, date), 

270 date, 

271 'The "DTEND" property for a "VEVENT" calendar component specifies the non-inclusive end of the event.', # noqa: E501 

272 ) 

273 

274 def _get_start_end_duration(self): 

275 """Verify the calendar validity and return the right attributes.""" 

276 start = self.DTSTART 

277 end = self.DTEND 

278 duration = self.DURATION 

279 if duration is not None and end is not None: 

280 raise InvalidCalendar( 

281 "Only one of DTEND and DURATION may be in a VEVENT, not both." 

282 ) 

283 if ( 

284 isinstance(start, date) 

285 and not isinstance(start, datetime) 

286 and duration is not None 

287 and duration.seconds != 0 

288 ): 

289 raise InvalidCalendar( 

290 "When DTSTART is a date, DURATION must be of days or weeks." 

291 ) 

292 if start is not None and end is not None and is_date(start) != is_date(end): 

293 raise InvalidCalendar( 

294 "DTSTART and DTEND must be of the same type, either date or datetime." 

295 ) 

296 return start, end, duration 

297 

298 DURATION = property( 

299 property_get_duration, 

300 property_set_duration, 

301 property_del_duration, 

302 property_doc_duration_template.format(component="VEVENT"), 

303 ) 

304 

305 @property 

306 def duration(self) -> timedelta: 

307 """The duration of the VEVENT. 

308 

309 This duration is calculated from the start and end of the event. 

310 When setting duration, the end time is automatically calculated from start + duration. 

311 """ 

312 return self.end - self.start 

313 

314 @duration.setter 

315 def duration(self, duration: timedelta): 

316 """Set the duration of the event. 

317 

318 This automatically calculates and sets the end time as start + duration. 

319 If no start time is set, raises IncompleteComponent. 

320 """ 

321 if ( 

322 not hasattr(self, "_get_start_end_duration") 

323 or self._get_start_end_duration()[0] is None 

324 ): 

325 raise IncompleteComponent( 

326 "Cannot set duration without DTSTART. Set start time first." 

327 ) 

328 

329 start_time = self.start 

330 self.end = start_time + duration 

331 

332 @property 

333 def start(self) -> date | datetime: 

334 """The start of the event. 

335 

336 Invalid values raise an InvalidCalendar. 

337 If there is no start, we also raise an IncompleteComponent error. 

338 

339 You can get the start, end and duration of an event as follows: 

340 

341 >>> from datetime import datetime 

342 >>> from icalendar import Event 

343 >>> event = Event() 

344 >>> event.start = datetime(2021, 1, 1, 12) 

345 >>> event.end = datetime(2021, 1, 1, 12, 30) # 30 minutes 

346 >>> event.duration # 1800 seconds == 30 minutes 

347 datetime.timedelta(seconds=1800) 

348 >>> print(event.to_ical()) 

349 BEGIN:VEVENT 

350 DTSTART:20210101T120000 

351 DTEND:20210101T123000 

352 END:VEVENT 

353 """ 

354 start = self._get_start_end_duration()[0] 

355 if start is None: 

356 raise IncompleteComponent("No DTSTART given.") 

357 return start 

358 

359 @start.setter 

360 def start(self, start: Optional[date | datetime]): 

361 """Set the start.""" 

362 self.DTSTART = start 

363 

364 @property 

365 def end(self) -> date | datetime: 

366 """The end of the event. 

367 

368 Invalid values raise an InvalidCalendar error. 

369 If there is no end, we also raise an IncompleteComponent error. 

370 """ 

371 start, end, duration = self._get_start_end_duration() 

372 if end is None and duration is None: 

373 if start is None: 

374 raise IncompleteComponent("No DTEND or DURATION+DTSTART given.") 

375 if is_date(start): 

376 return start + timedelta(days=1) 

377 return start 

378 if duration is not None: 

379 if start is not None: 

380 return start + duration 

381 raise IncompleteComponent("No DTEND or DURATION+DTSTART given.") 

382 return end 

383 

384 @end.setter 

385 def end(self, end: date | datetime | None): 

386 """Set the end.""" 

387 self.DTEND = end 

388 

389 X_MOZ_SNOOZE_TIME = X_MOZ_SNOOZE_TIME_property 

390 X_MOZ_LASTACK = X_MOZ_LASTACK_property 

391 color = color_property 

392 sequence = sequence_property 

393 categories = categories_property 

394 rdates = rdates_property 

395 exdates = exdates_property 

396 rrules = rrules_property 

397 uid = uid_property 

398 summary = summary_property 

399 description = description_property 

400 classification = class_property 

401 url = url_property 

402 organizer = organizer_property 

403 location = location_property 

404 priority = priority_property 

405 contacts = contacts_property 

406 transparency = transparency_property 

407 status = status_property 

408 attendees = attendees_property 

409 

410 @classmethod 

411 def new( 

412 cls, 

413 /, 

414 attendees: Optional[list[vCalAddress]] = None, 

415 categories: Sequence[str] = (), 

416 classification: Optional[CLASS] = None, 

417 color: Optional[str] = None, 

418 comments: list[str] | str | None = None, 

419 contacts: list[str] | str | None = None, 

420 created: Optional[date] = None, 

421 description: Optional[str] = None, 

422 end: Optional[date | datetime] = None, 

423 last_modified: Optional[date] = None, 

424 location: Optional[str] = None, 

425 organizer: Optional[vCalAddress | str] = None, 

426 priority: Optional[int] = None, 

427 sequence: Optional[int] = None, 

428 stamp: Optional[date] = None, 

429 start: Optional[date | datetime] = None, 

430 status: Optional[STATUS] = None, 

431 transparency: Optional[TRANSP] = None, 

432 summary: Optional[str] = None, 

433 uid: Optional[str | uuid.UUID] = None, 

434 url: Optional[str] = None, 

435 ): 

436 """Create a new event with all required properties. 

437 

438 This creates a new Event in accordance with :rfc:`5545`. 

439 

440 Arguments: 

441 attendees: The :attr:`attendees` of the event. 

442 categories: The :attr:`categories` of the event. 

443 classification: The :attr:`classification` of the event. 

444 color: The :attr:`color` of the event. 

445 comments: The :attr:`Component.comments` of the event. 

446 created: The :attr:`Component.created` of the event. 

447 description: The :attr:`description` of the event. 

448 end: The :attr:`end` of the event. 

449 last_modified: The :attr:`Component.last_modified` of the event. 

450 location: The :attr:`location` of the event. 

451 organizer: The :attr:`organizer` of the event. 

452 priority: The :attr:`priority` of the event. 

453 sequence: The :attr:`sequence` of the event. 

454 stamp: The :attr:`Component.stamp` of the event. 

455 If None, this is set to the current time. 

456 start: The :attr:`start` of the event. 

457 status: The :attr:`status` of the event. 

458 summary: The :attr:`summary` of the event. 

459 transparency: The :attr:`transparency` of the event. 

460 uid: The :attr:`uid` of the event. 

461 If None, this is set to a new :func:`uuid.uuid4`. 

462 url: The :attr:`url` of the event. 

463 

464 Returns: 

465 :class:`Event` 

466 

467 Raises: 

468 InvalidCalendar: If the content is not valid according to :rfc:`5545`. 

469 

470 .. warning:: As time progresses, we will be stricter with the validation. 

471 """ 

472 event = super().new( 

473 stamp=stamp if stamp is not None else cls._utc_now(), 

474 created=created, 

475 last_modified=last_modified, 

476 comments=comments, 

477 ) 

478 event.summary = summary 

479 event.description = description 

480 event.uid = uid if uid is not None else uuid.uuid4() 

481 event.start = start 

482 event.end = end 

483 event.color = color 

484 event.categories = categories 

485 event.sequence = sequence 

486 event.classification = classification 

487 event.url = url 

488 event.organizer = organizer 

489 event.location = location 

490 event.priority = priority 

491 event.transparency = transparency 

492 event.contacts = contacts 

493 event.status = status 

494 event.attendees = attendees 

495 if cls._validate_new: 

496 cls._validate_start_and_end(start, end) 

497 return event 

498 

499 

500__all__ = ["Event"]