Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/icalendar/param.py: 54%

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

123 statements  

1"""Parameter access for icalendar. 

2 

3Related: 

4 

5- :rfc:`5545`, Section 3.2. Property Parameters 

6- :rfc:`7986`, Section 6. Property Parameters 

7- :rfc:`9253` 

8- https://github.com/collective/icalendar/issues/798 

9""" 

10 

11from __future__ import annotations 

12 

13import functools 

14from datetime import timedelta 

15from typing import TYPE_CHECKING, Callable, Optional, TypeVar 

16 

17from icalendar import enums 

18 

19if TYPE_CHECKING: 

20 from enum import Enum 

21 

22 

23if TYPE_CHECKING: 

24 from icalendar.prop import VPROPERTY 

25 

26 

27def _default_return_none() -> Optional[str]: 

28 """Return None by default.""" 

29 return None 

30 

31 

32def _default_return_string() -> str: 

33 """Return None by default.""" 

34 return "" 

35 

36 

37T = TypeVar("T") 

38 

39 

40def string_parameter( 

41 name: str, 

42 doc: str, 

43 default: Callable = _default_return_none, 

44 convert: Optional[Callable[[str], T]] = None, 

45 convert_to: Optional[Callable[[T], str]] = None, 

46) -> property: 

47 """Return a parameter with a quoted value (case sensitive).""" 

48 

49 if convert_to is None: 

50 convert_to = convert 

51 

52 @functools.wraps(default) 

53 def fget(self: VPROPERTY) -> Optional[str]: 

54 value = self.params.get(name) 

55 if value is None: 

56 return default() 

57 return convert(value) if convert else value 

58 

59 def fset(self: VPROPERTY, value: str | None): 

60 if value is None: 

61 fdel(self) 

62 else: 

63 self.params[name] = convert_to(value) if convert_to else value 

64 

65 def fdel(self: VPROPERTY): 

66 self.params.pop(name, None) 

67 

68 return property(fget, fset, fdel, doc=doc) 

69 

70 

71ALTREP = string_parameter( 

72 "ALTREP", 

73 """ALTREP - Specify an alternate text representation for the property value. 

74 

75Description: 

76 This parameter specifies a URI that points to an 

77 alternate representation for a textual property value. A property 

78 specifying this parameter MUST also include a value that reflects 

79 the default representation of the text value. The URI parameter 

80 value MUST be specified in a quoted-string. 

81 

82.. note:: 

83 

84 While there is no restriction imposed on the URI schemes 

85 allowed for this parameter, Content Identifier (CID) :rfc:`2392`, 

86 HTTP :rfc:`2616`, and HTTPS :rfc:`2818` are the URI schemes most 

87 commonly used by current implementations. 

88""", 

89) 

90 

91CN = string_parameter( 

92 "CN", 

93 """Specify the common name to be associated with the calendar user specified. 

94 

95Description: 

96 This parameter can be specified on properties with a 

97 CAL-ADDRESS value type. The parameter specifies the common name 

98 to be associated with the calendar user specified by the property. 

99 The parameter value is text. The parameter value can be used for 

100 display text to be associated with the calendar address specified 

101 by the property. 

102""", 

103 default=_default_return_string, 

104) 

105 

106 

107def _default_return_individual() -> enums.CUTYPE | str: 

108 """Default value.""" 

109 return enums.CUTYPE.INDIVIDUAL 

110 

111 

112def _convert_enum(enum: type[Enum]) -> Callable[[str], Enum]: 

113 def convert(value: str) -> str: 

114 """Convert if possible.""" 

115 try: 

116 return enum(value.upper()) 

117 except ValueError: 

118 return value 

119 

120 return convert 

121 

122 

123CUTYPE = string_parameter( 

124 "CUTYPE", 

125 """Identify the type of calendar user specified by the property. 

126 

127Description: 

128 This parameter can be specified on properties with a 

129 CAL-ADDRESS value type. The parameter identifies the type of 

130 calendar user specified by the property. If not specified on a 

131 property that allows this parameter, the default is INDIVIDUAL. 

132 Applications MUST treat x-name and iana-token values they don't 

133 recognize the same way as they would the UNKNOWN value. 

134""", 

135 default=_default_return_individual, 

136 convert=_convert_enum(enums.CUTYPE), 

137) 

138 

139 

140def quoted_list_parameter(name: str, doc: str) -> property: 

141 """Return a parameter that contains a quoted list.""" 

142 

143 def fget(self: VPROPERTY) -> tuple[str]: 

144 value = self.params.get(name) 

145 if value is None: 

146 return () 

147 if isinstance(value, str): 

148 return tuple(value.split(",")) 

149 return value 

150 

151 def fset(self: VPROPERTY, value: str | tuple[str]): 

152 if value == (): 

153 fdel(self) 

154 else: 

155 self.params[name] = (value,) if isinstance(value, str) else value 

156 

157 def fdel(self: VPROPERTY): 

158 self.params.pop(name, None) 

159 

160 return property(fget, fset, fdel, doc=doc) 

161 

162 

163DELEGATED_FROM = quoted_list_parameter( 

164 "DELEGATED-FROM", 

165 """Specify the calendar users that have delegated their participation to the calendar user specified by the property. 

166 

167Description: 

168 This parameter can be specified on properties with a 

169 CAL-ADDRESS value type. This parameter specifies those calendar 

170 users that have delegated their participation in a group-scheduled 

171 event or to-do to the calendar user specified by the property. 

172 The individual calendar address parameter values MUST each be 

173 specified in a quoted-string. 

174""", # noqa: E501 

175) 

176 

177DELEGATED_TO = quoted_list_parameter( 

178 "DELEGATED-TO", 

179 """Specify the calendar users to whom the calendar user specified by the property has delegated participation. 

180 

181Description: 

182 This parameter can be specified on properties with a 

183 CAL-ADDRESS value type. This parameter specifies those calendar 

184 users whom have been delegated participation in a group-scheduled 

185 event or to-do by the calendar user specified by the property. 

186 The individual calendar address parameter values MUST each be 

187 specified in a quoted-string. 

188 """, # noqa: E501 

189) 

190 

191DIR = string_parameter( 

192 "DIR", 

193 """Specify reference to a directory entry associated with the calendar user specified by the property. 

194 

195Description: 

196 This parameter can be specified on properties with a 

197 CAL-ADDRESS value type. The parameter specifies a reference to 

198 the directory entry associated with the calendar user specified by 

199 the property. The parameter value is a URI. The URI parameter 

200 value MUST be specified in a quoted-string. 

201 

202.. note:: 

203 

204 While there is no restriction imposed on the URI schemes 

205 allowed for this parameter, CID :rfc:`2392`, DATA :rfc:`2397`, FILE 

206 :rfc:`1738`, FTP :rfc:`1738`, HTTP :rfc:`2616`, HTTPS :rfc:`2818`, LDAP 

207 :rfc:`4516`, and MID :rfc:`2392` are the URI schemes most commonly 

208 used by current implementations. 

209""", # noqa: E501 

210) 

211 

212 

213def _default_return_busy() -> enums.FBTYPE | str: 

214 """Default value.""" 

215 return enums.FBTYPE.BUSY 

216 

217 

218FBTYPE = string_parameter( 

219 "FBTYPE", 

220 """Specify the free or busy time type. 

221 

222Description: 

223 This parameter specifies the free or busy time type. 

224 The value FREE indicates that the time interval is free for 

225 scheduling. The value BUSY indicates that the time interval is 

226 busy because one or more events have been scheduled for that 

227 interval. The value BUSY-UNAVAILABLE indicates that the time 

228 interval is busy and that the interval can not be scheduled. The 

229 value BUSY-TENTATIVE indicates that the time interval is busy 

230 because one or more events have been tentatively scheduled for 

231 that interval. If not specified on a property that allows this 

232 parameter, the default is BUSY. Applications MUST treat x-name 

233 and iana-token values they don't recognize the same way as they 

234 would the BUSY value. 

235""", 

236 default=_default_return_busy, 

237 convert=_convert_enum(enums.FBTYPE), 

238) 

239 

240LANGUAGE = string_parameter( 

241 "LANGUAGE", 

242 """Specify the language for text values in a property or property parameter. 

243 

244Description: 

245 This parameter identifies the language of the text in 

246 the property value and of all property parameter values of the 

247 property. The value of the "LANGUAGE" property parameter is that 

248 defined in :rfc:`5646`. 

249 

250 For transport in a MIME entity, the Content-Language header field 

251 can be used to set the default language for the entire body part. 

252 Otherwise, no default language is assumed. 

253""", 

254) 

255 

256MEMBER = quoted_list_parameter( 

257 "MEMBER", 

258 """Specify the group or list membership of the calendar user specified by the property. 

259 

260Description: 

261 This parameter can be specified on properties with a 

262 CAL-ADDRESS value type. The parameter identifies the groups or 

263 list membership for the calendar user specified by the property. 

264 The parameter value is either a single calendar address in a 

265 quoted-string or a COMMA-separated list of calendar addresses, 

266 each in a quoted-string. The individual calendar address 

267 parameter values MUST each be specified in a quoted-string. 

268""", # noqa: E501 

269) 

270 

271 

272def _default_return_needs_action() -> enums.PARTSTAT | str: 

273 """Default value.""" 

274 return enums.PARTSTAT.NEEDS_ACTION 

275 

276 

277PARTSTAT = string_parameter( 

278 "PARTSTAT", 

279 """Specify the participation status for the calendar user specified by the property. 

280 

281Description: 

282 This parameter can be specified on properties with a 

283 CAL-ADDRESS value type. The parameter identifies the 

284 participation status for the calendar user specified by the 

285 property value. The parameter values differ depending on whether 

286 they are associated with a group-scheduled "VEVENT", "VTODO", or 

287 "VJOURNAL". The values MUST match one of the values allowed for 

288 the given calendar component. If not specified on a property that 

289 allows this parameter, the default value is NEEDS-ACTION. 

290 Applications MUST treat x-name and iana-token values they don't 

291 recognize the same way as they would the NEEDS-ACTION value. 

292""", 

293 default=_default_return_needs_action, 

294 convert=_convert_enum(enums.PARTSTAT), 

295) 

296 

297 

298def _default_range_none() -> Optional[enums.RANGE | str]: 

299 return None 

300 

301 

302RANGE = string_parameter( 

303 "RANGE", 

304 """Specify the effective range of recurrence instances from the instance specified by the recurrence identifier specified by the property. 

305 

306Description: 

307 This parameter can be specified on a property that 

308 specifies a recurrence identifier. The parameter specifies the 

309 effective range of recurrence instances that is specified by the 

310 property. The effective range is from the recurrence identifier 

311 specified by the property. If this parameter is not specified on 

312 an allowed property, then the default range is the single instance 

313 specified by the recurrence identifier value of the property. The 

314 parameter value can only be "THISANDFUTURE" to indicate a range 

315 defined by the recurrence identifier and all subsequent instances. 

316 The value "THISANDPRIOR" is deprecated by this revision of 

317 iCalendar and MUST NOT be generated by applications. 

318""", # noqa: E501 

319 default=_default_range_none, 

320 convert=_convert_enum(enums.RANGE), 

321) 

322 

323 

324def _default_related() -> enums.RELATED | str: 

325 return enums.RELATED.START 

326 

327 

328RELATED = string_parameter( 

329 "RELATED", 

330 """Specify the relationship of the alarm trigger with respect to the start or end of the calendar component. 

331 

332Description: 

333 This parameter can be specified on properties that 

334 specify an alarm trigger with a "DURATION" value type. The 

335 parameter specifies whether the alarm will trigger relative to the 

336 start or end of the calendar component. The parameter value START 

337 will set the alarm to trigger off the start of the calendar 

338 component; the parameter value END will set the alarm to trigger 

339 off the end of the calendar component. If the parameter is not 

340 specified on an allowable property, then the default is START. 

341 

342""", # noqa: E501 

343 default=_default_related, 

344 convert=_convert_enum(enums.RELATED), 

345) 

346 

347 

348def _default_req_participant() -> enums.ROLE | str: 

349 return enums.ROLE.REQ_PARTICIPANT 

350 

351 

352ROLE = string_parameter( 

353 "ROLE", 

354 """Specify the participation role for the calendar user specified by the property. 

355 

356Description: 

357 This parameter can be specified on properties with a 

358 CAL-ADDRESS value type. The parameter specifies the participation 

359 role for the calendar user specified by the property in the group 

360 schedule calendar component. If not specified on a property that 

361 allows this parameter, the default value is REQ-PARTICIPANT. 

362 Applications MUST treat x-name and iana-token values they don't 

363 recognize the same way as they would the REQ-PARTICIPANT value. 

364""", 

365 default=_default_req_participant, 

366 convert=_convert_enum(enums.ROLE), 

367) 

368 

369 

370def boolean_parameter(name: str, default: bool, doc: str) -> property: # noqa: FBT001 

371 def _default() -> bool: 

372 return default 

373 

374 return string_parameter( 

375 name, 

376 doc, 

377 default=_default, 

378 convert=lambda x: x.upper() == "TRUE", 

379 convert_to=lambda x: "TRUE" if x else "FALSE", 

380 ) 

381 

382 

383RSVP = boolean_parameter( 

384 "RSVP", 

385 False, # noqa: FBT003 

386 """Specify whether there is an expectation of a favor of anreply from the calendar user specified by the property value. 

387 

388Description: 

389 This parameter can be specified on properties with a 

390 CAL-ADDRESS value type. The parameter identifies the expectation 

391 of a reply from the calendar user specified by the property value. 

392 This parameter is used by the "Organizer" to request a 

393 participation status reply from an "Attendee" of a group-scheduled 

394 event or to-do. If not specified on a property that allows this 

395 parameter, the default value is ``False``. 

396""", # noqa: E501 

397) 

398 

399SENT_BY = string_parameter( 

400 "SENT-BY", 

401 """Specify the calendar user that is acting on behalf of the calendar user specified by the property. 

402 

403Description: 

404 This parameter can be specified on properties with a 

405 CAL-ADDRESS value type. The parameter specifies the calendar user 

406 that is acting on behalf of the calendar user specified by the 

407 property. The parameter value MUST be a mailto URI as defined in 

408 :rfc:`2368`. The individual calendar address parameter values MUST 

409 each be specified in a quoted-string. 

410""", # noqa: E501 

411) 

412 

413TZID = string_parameter( 

414 "TZID", 

415 """Specify the identifier for the time zone definition for a time component in the property value. 

416 

417Description: 

418 This parameter MUST be specified on the "DTSTART", 

419 "DTEND", "DUE", "EXDATE", and "RDATE" properties when either a 

420 DATE-TIME or TIME value type is specified and when the value is 

421 neither a UTC or a "floating" time. Refer to the DATE-TIME or 

422 TIME value type definition for a description of UTC and "floating 

423 time" formats. This property parameter specifies a text value 

424 that uniquely identifies the "VTIMEZONE" calendar component to be 

425 used when evaluating the time portion of the property. The value 

426 of the "TZID" property parameter will be equal to the value of the 

427 "TZID" property for the matching time zone definition. An 

428 individual "VTIMEZONE" calendar component MUST be specified for 

429 each unique "TZID" parameter value specified in the iCalendar 

430 object. 

431 

432 The parameter MUST be specified on properties with a DATE-TIME 

433 value if the DATE-TIME is not either a UTC or a "floating" time. 

434 Failure to include and follow VTIMEZONE definitions in iCalendar 

435 objects may lead to inconsistent understanding of the local time 

436 at any given location. 

437 

438 The presence of the SOLIDUS character as a prefix, indicates that 

439 this "TZID" represents a unique ID in a globally defined time zone 

440 registry (when such registry is defined). 

441 

442.. note:: 

443 

444 This document does not define a naming convention for 

445 time zone identifiers. Implementers may want to use the naming 

446 conventions defined in existing time zone specifications such 

447 as the public-domain TZ database (TZDB). The specification of 

448 globally unique time zone identifiers is not addressed by this 

449 document and is left for future study. 

450""", # noqa: E501 

451) 

452 

453 

454def _default_return_parent() -> enums.RELTYPE: 

455 return enums.RELTYPE.PARENT 

456 

457 

458RELTYPE = string_parameter( 

459 "RELTYPE", 

460 """Specify the type of hierarchical relationship associated with a component. 

461 

462Conformance: 

463 :rfc:`5545` introduces the RELTYPE property parameter. 

464 :rfc:`9253` adds new values. 

465 

466Description: 

467 This parameter can be specified on a property that 

468 references another related calendar. The parameter specifies the 

469 hierarchical relationship type of the calendar component 

470 referenced by the property. The parameter value can be PARENT, to 

471 indicate that the referenced calendar component is a superior of 

472 calendar component; CHILD to indicate that the referenced calendar 

473 component is a subordinate of the calendar component; or SIBLING 

474 to indicate that the referenced calendar component is a peer of 

475 the calendar component. If this parameter is not specified on an 

476 allowable property, the default relationship type is PARENT. 

477 Applications MUST treat x-name and iana-token values they don't 

478 recognize the same way as they would the PARENT value. 

479""", 

480 default=_default_return_parent, 

481 convert=_convert_enum(enums.RELTYPE), 

482) 

483 

484 

485def _get_value(self: VPROPERTY) -> str: 

486 """The VALUE parameter or the default. 

487 

488 Purpose: 

489 VALUE explicitly specify the value type format for a property value. 

490 

491 Description: 

492 This parameter specifies the value type and format of 

493 the property value. The property values MUST be of a single value 

494 type. For example, a "RDATE" property cannot have a combination 

495 of DATE-TIME and TIME value types. 

496 

497 If the property's value is the default value type, then this 

498 parameter need not be specified. However, if the property's 

499 default value type is overridden by some other allowable value 

500 type, then this parameter MUST be specified. 

501 

502 Applications MUST preserve the value data for ``x-name`` and 

503 ``iana-token`` values that they don't recognize without attempting 

504 to interpret or parse the value data. 

505 

506 Returns: 

507 The VALUE parameter or the default. 

508 

509 Examples: 

510 The VALUE defaults to the name of the property. 

511 Note that it is case-insensitive but always uppercase. 

512 

513 .. code-block:: pycon 

514 

515 >>> from icalendar import vBoolean 

516 >>> b = vBoolean(True) 

517 >>> b.VALUE 

518 'BOOLEAN' 

519 

520 Setting the VALUE parameter of a typed property usually does not make sense. 

521 For convenience, using this property, the value will be converted to 

522 an uppercase string. 

523 If you have some custom property, you might use it like this: 

524 

525 .. code-block:: pycon 

526 

527 >>> from icalendar import vUnknown, Event 

528 >>> v = vUnknown("Some property text.") 

529 >>> v.VALUE = "x-type" # lower case 

530 >>> v.VALUE 

531 'X-TYPE' 

532 >>> event = Event() 

533 >>> event.add("x-prop", v) 

534 >>> print(event.to_ical()) 

535 BEGIN:VEVENT 

536 X-PROP;VALUE=X-TYPE:Some property text. 

537 END:VEVENT 

538 

539 """ 

540 value = self.params.value 

541 if value is None: 

542 _get_default_value = getattr(self, "_get_value", None) 

543 if _get_default_value is not None: 

544 value = _get_default_value() 

545 return self.default_value if value is None else value 

546 

547 

548def _set_value(self: VPROPERTY, value: str | None): 

549 """Set the VALUE parameter.""" 

550 self.params.value = value 

551 

552 

553def _del_value(self: VPROPERTY): 

554 """Delete the VALUE parameter.""" 

555 del self.params.value 

556 

557 

558VALUE = property(_get_value, _set_value, _del_value) 

559 

560LABEL = string_parameter( 

561 "LABEL", 

562 """LABEL provides a human-readable label. 

563 

564Conformance: 

565 This property parameter is specified in :rfc:`7986`, 

566 iCalendar Property Extensions. 

567 

568 :rfc:`9253` makes use of this for the LINK property. 

569 This parameter maps to the "title" 

570 attribute defined in Section 3.4.1 of :rfc:`8288`. 

571 LABEL is used to label the destination 

572 of a link such that it can be used as a human-readable identifier 

573 (e.g., a menu entry) in the language indicated by the LANGUAGE 

574 (if present). The LABEL MUST NOT 

575 appear more than once in a given link; occurrences after the first 

576 MUST be ignored by parsers. 

577 

578Description: 

579 This property parameter MAY be specified on the 

580 "CONFERENCE" property. It is anticipated that other extensions to 

581 iCalendar will reuse this property parameter on new properties 

582 that they define. As a result, clients MUST expect to find this 

583 property parameter present on many different properties. It 

584 provides a human-readable label that can be presented to calendar 

585 users to allow them to discriminate between properties that might 

586 be similar or provide additional information for properties that 

587 are not self-describing. The "LANGUAGE" property parameter can be 

588 used to specify the language of the text in the parameter value 

589 (as per Section 3.2.10 of :rfc:`5545`). 

590 

591Examples: 

592 This is a label of a chat. 

593 

594 .. code-block:: text 

595 

596 CONFERENCE;VALUE=URI;FEATURE=VIDEO; 

597 LABEL="Web video chat, access code=76543"; 

598 :https://video-chat.example.com/;group-id=1234 

599 

600""", 

601) 

602 

603FMTTYPE = string_parameter( 

604 "FMTTYPE", 

605 """FMTTYPE specfies the content type of a referenced object. 

606 

607Conformance: 

608 :rfc:`5545` specifies the FMTTYPE. 

609 :rfc:`9253` adds FMTTYPE to LINK properties. In a LINK, 

610 FMTTYPE maps to the "type" 

611 attribute defined in Section 3.4.1 of :rfc:`8288`. 

612 See :rfc:`6838`. 

613 

614Description: 

615 This parameter can be specified on properties that are 

616 used to reference an object. The parameter specifies the media 

617 type :rfc:`4288` of the referenced object. For example, on the 

618 "ATTACH" property, an FTP type URI value does not, by itself, 

619 necessarily convey the type of content associated with the 

620 resource. The parameter value MUST be the text for either an 

621 IANA-registered media type or a non-standard media type. 

622 

623Example: 

624 A Microsoft Word document: 

625 

626 .. code-block:: text 

627 

628 ATTACH;FMTTYPE=application/msword:ftp://example.com/pub/docs/ 

629 agenda.doc 

630 

631 A website: 

632 

633 .. code-block:: text 

634 

635 LINK;FMTTYPE=text/html;LINKREL=SOURCE;LABEL=Venue;VALUE=URI: 

636 https://example.com/venue 

637 

638 """, 

639) 

640 

641LINKREL = string_parameter( 

642 "LINKREL", 

643 """LINKREL 

644 

645Purpose: 

646 LINKREL specifies the relationship of data referenced 

647 by a LINK property. 

648 

649Conformance: 

650 LINKREL is specified in :rfc:`9253`. 

651 This parameter maps to the link relation type defined in 

652 Section 2.1 of :rfc:`8288`. 

653 It is always quoted. 

654 

655Description: 

656 This parameter MUST be specified on all LINK properties and define 

657 the type of reference. 

658 This allows programs consuming this data to automatically scan 

659 for references they support. 

660 There is no default relation type. Any link relation in the 

661 link registry established by :rfc:`8288`, or new link relations, 

662 may be used. 

663 It is expected that link relation types seeing significant usage 

664 in calendaring will have the calendaring usage described in an RFC. 

665 

666 In the simplest case, a link relation type identifies the semantics 

667 of a link. For example, a link with the relation type "copyright" 

668 indicates that the current link context has a copyright resource at 

669 the link target. 

670 

671 Link relation types can also be used to indicate that the target 

672 resource has particular attributes, or exhibits particular 

673 behaviours; for example, a "service" link implies that the link 

674 target can be used as part of a defined protocol (in this case, a 

675 service description). 

676 

677Registration: 

678 There are two kinds of relation types: registered and extension. 

679 These relation types are registered in :rfc:`8288`. 

680 

681.. seealso:: 

682 

683 `Registered Link Relation Types 

684 <https://www.iana.org/assignments/link-relations/link-relations.xhtml>`_. 

685 

686 

687Examples: 

688 This identifies the latest version of the event information. 

689 

690 .. code-block:: text 

691 

692 LINKREL=latest-version 

693 

694""", 

695) 

696 

697 

698def _get_GAP(prop) -> timedelta | None: # noqa: N802 

699 """GAP 

700 

701 Purpose: 

702 GAP specifies the length of the gap, positive or negative, 

703 between two components with a temporal relationship. 

704 

705 Format Definition: 

706 Same as the DURATION value type defined in :rfc:`5545`, Section 3.3.6. 

707 

708 Description: 

709 This parameter MAY be specified on the RELATED-TO property and defines 

710 the duration of time between the predecessor and successor in an interval. 

711 When positive, it defines the lag time between a task and its logical successor. 

712 When negative, it defines the lead time. 

713 

714 Examples: 

715 An example of lag time might be if Task-A is "paint the room" and Task-B is 

716 "lay the carpets". Then, Task-A may be related to Task-B with 

717 RELTYPE=FINISHTOSTART with a gap of 1 day -- long enough for the paint to dry. 

718 

719 .. code-block:: text 

720 

721 ==================== 

722 | paint the room |--+ 

723 ==================== | 

724 |(lag of one day) 

725 | 

726 | =================== 

727 +->| lay the carpet | 

728 =================== 

729 

730 For an example of lead time, in constructing a two-story building, 

731 the electrical work must be done before painting. However, 

732 the painter can move in to the first floor as the electricians move upstairs. 

733 

734 .. code-block:: text 

735 

736 ===================== 

737 | electrical work |--+ 

738 ===================== | 

739 +-------------+ 

740 |(lead of estimated time) 

741 | ================== 

742 +->| painting | 

743 ================== 

744 """ 

745 value = prop.params.get("GAP") 

746 if value is None: 

747 return None 

748 from icalendar.prop import vDuration 

749 

750 if isinstance(value, str): 

751 return vDuration.from_ical(value) 

752 if not isinstance(value, vDuration): 

753 raise TypeError("Value MUST be a vDuration instance") 

754 return value.td 

755 

756 

757def _set_GAP(prop, value: timedelta | str | None): # noqa: N802 

758 """Set the GAP parameter as a timedelta.""" 

759 if value is None: 

760 prop.params.pop("GAP", None) 

761 return 

762 from icalendar.prop import vDuration 

763 

764 prop.params["GAP"] = vDuration(value) 

765 

766 

767def _del_GAP(prop): # noqa: N802 

768 """Delete the GAP parameter.""" 

769 prop.params.pop("GAP", None) 

770 

771 

772GAP = property(_get_GAP, _set_GAP, _del_GAP) 

773 

774__all__ = [ 

775 "ALTREP", 

776 "CN", 

777 "CUTYPE", 

778 "DELEGATED_FROM", 

779 "DELEGATED_TO", 

780 "DIR", 

781 "FBTYPE", 

782 "FMTTYPE", 

783 "GAP", 

784 "LABEL", 

785 "LANGUAGE", 

786 "LINKREL", 

787 "MEMBER", 

788 "PARTSTAT", 

789 "RANGE", 

790 "RELATED", 

791 "ROLE", 

792 "RSVP", 

793 "SENT_BY", 

794 "TZID", 

795 "VALUE", 

796 "quoted_list_parameter", 

797 "string_parameter", 

798]