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

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 typing import TYPE_CHECKING, TypeVar 

15 

16from icalendar import enums 

17 

18if TYPE_CHECKING: 

19 from collections.abc import Callable 

20 from datetime import timedelta 

21 from enum import Enum 

22 

23 

24if TYPE_CHECKING: 

25 from icalendar.prop import VPROPERTY 

26 

27 

28def _default_return_none() -> str | None: 

29 """Return None by default.""" 

30 return None 

31 

32 

33def _default_return_string() -> str: 

34 """Return None by default.""" 

35 return "" 

36 

37 

38T = TypeVar("T") 

39 

40 

41def string_parameter( 

42 name: str, 

43 doc: str, 

44 default: Callable = _default_return_none, 

45 convert: Callable[[str], T] | None = None, 

46 convert_to: Callable[[T], str] | None = None, 

47) -> property: 

48 """Create a property for a string parameter with optional conversion. 

49 

50 This helper function is used to define properties that read from and write to 

51 ``self.params`` while optionally converting values between their stored 

52 string representation and a more convenient Python type. 

53 

54 Parameters: 

55 name: Name of the parameter in the params dictionary. 

56 doc: Documentation for the property. 

57 default: 

58 Function that returns a default value if the parameter is not found. 

59 convert: 

60 Function that converts the stored string value to the desired type. 

61 convert_to: 

62 Function to convert a value back to a string for storage. 

63 

64 Returns: 

65 A property object with a getter, setter, and deleter for the parameter. 

66 

67 Example: 

68 

69 Define a parameter that is stored as a string but used as an integer: 

70 

71 >>> from icalendar.param import string_parameter 

72 

73 >>> class Dummy: 

74 ... def __init__(self): 

75 ... self.params = {} 

76 ... 

77 >>> Dummy.priority = string_parameter( 

78 ... "PRIORITY", 

79 ... "Priority of the component", 

80 ... default=lambda: 0, 

81 ... convert=int, 

82 ... convert_to=str, 

83 ... ) 

84 >>> obj = Dummy() 

85 

86 Accessing the property converts the stored string value to the type 

87 specified by the ``convert`` parameter, in this case, an ``int``. 

88 

89 >>> obj.priority = "5" 

90 >>> obj.priority 

91 5 

92 

93 Setting the property stores the new value. 

94 

95 >>> obj.priority = 10 

96 >>> obj.priority 

97 10 

98 """ 

99 

100 if convert_to is None: 

101 convert_to = convert 

102 

103 @functools.wraps(default) 

104 def fget(self: VPROPERTY) -> str | None: 

105 value = self.params.get(name) 

106 if value is None: 

107 return default() 

108 return convert(value) if convert else value 

109 

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

111 if value is None: 

112 fdel(self) 

113 else: 

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

115 

116 def fdel(self: VPROPERTY): 

117 self.params.pop(name, None) 

118 

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

120 

121 

122ALTREP = string_parameter( 

123 "ALTREP", 

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

125 

126Description: 

127 This parameter specifies a URI that points to an 

128 alternate representation for a textual property value. A property 

129 specifying this parameter MUST also include a value that reflects 

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

131 value MUST be specified in a quoted-string. 

132 

133.. note:: 

134 

135 While there is no restriction imposed on the URI schemes 

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

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

138 commonly used by current implementations. 

139""", 

140) 

141 

142CN = string_parameter( 

143 "CN", 

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

145 

146Description: 

147 This parameter can be specified on properties with a 

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

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

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

151 display text to be associated with the calendar address specified 

152 by the property. 

153""", 

154 default=_default_return_string, 

155) 

156 

157 

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

159 """Default value.""" 

160 return enums.CUTYPE.INDIVIDUAL 

161 

162 

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

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

165 """Convert if possible.""" 

166 try: 

167 return enum(value.upper()) 

168 except ValueError: 

169 return value 

170 

171 return convert 

172 

173 

174CUTYPE = string_parameter( 

175 "CUTYPE", 

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

177 

178Description: 

179 This parameter can be specified on properties with a 

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

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

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

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

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

185""", 

186 default=_default_return_individual, 

187 convert=_convert_enum(enums.CUTYPE), 

188) 

189 

190 

191def quoted_list_parameter(name: str) -> property: 

192 """Create a property for a parameter that contains a quoted list. 

193 

194 Parameters: 

195 name: The parameter name in the ``params`` dictionary. 

196 

197 Returns: 

198 A property with a getter, setter, and deleter for the parameter. 

199 """ 

200 

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

202 value = self.params.get(name) 

203 if value is None: 

204 return () 

205 if isinstance(value, str): 

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

207 return value 

208 

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

210 if value == (): 

211 fdel(self) 

212 else: 

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

214 

215 def fdel(self: VPROPERTY): 

216 self.params.pop(name, None) 

217 

218 return property(fget, fset, fdel) 

219 

220 

221DELEGATED_FROM = quoted_list_parameter("DELEGATED-FROM") 

222 

223DELEGATED_TO = quoted_list_parameter("DELEGATED-TO") 

224 

225DIR = string_parameter( 

226 "DIR", 

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

228 

229Description: 

230 This parameter can be specified on properties with a 

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

232 the directory entry associated with the calendar user specified by 

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

234 value MUST be specified in a quoted-string. 

235 

236.. note:: 

237 

238 While there is no restriction imposed on the URI schemes 

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

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

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

242 used by current implementations. 

243""", # noqa: E501 

244) 

245 

246 

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

248 """Default value.""" 

249 return enums.FBTYPE.BUSY 

250 

251 

252FBTYPE = string_parameter( 

253 "FBTYPE", 

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

255 

256Description: 

257 This parameter specifies the free or busy time type. 

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

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

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

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

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

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

264 because one or more events have been tentatively scheduled for 

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

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

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

268 would the BUSY value. 

269""", 

270 default=_default_return_busy, 

271 convert=_convert_enum(enums.FBTYPE), 

272) 

273 

274LANGUAGE = string_parameter( 

275 "LANGUAGE", 

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

277 

278Description: 

279 This parameter identifies the language of the text in 

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

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

282 defined in :rfc:`5646`. 

283 

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

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

286 Otherwise, no default language is assumed. 

287""", 

288) 

289 

290MEMBER = quoted_list_parameter("MEMBER") 

291 

292 

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

294 """Default value.""" 

295 return enums.PARTSTAT.NEEDS_ACTION 

296 

297 

298PARTSTAT = string_parameter( 

299 "PARTSTAT", 

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

301 

302Description: 

303 This parameter can be specified on properties with a 

304 CAL-ADDRESS value type. The parameter identifies the 

305 participation status for the calendar user specified by the 

306 property value. The parameter values differ depending on whether 

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

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

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

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

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

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

313""", 

314 default=_default_return_needs_action, 

315 convert=_convert_enum(enums.PARTSTAT), 

316) 

317 

318 

319def _default_range_none() -> enums.RANGE | str | None: 

320 return None 

321 

322 

323RANGE = string_parameter( 

324 "RANGE", 

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

326 

327Description: 

328 This parameter can be specified on a property that 

329 specifies a recurrence identifier. The parameter specifies the 

330 effective range of recurrence instances that is specified by the 

331 property. The effective range is from the recurrence identifier 

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

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

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

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

336 defined by the recurrence identifier and all subsequent instances. 

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

338 iCalendar and MUST NOT be generated by applications. 

339""", # noqa: E501 

340 default=_default_range_none, 

341 convert=_convert_enum(enums.RANGE), 

342) 

343 

344 

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

346 return enums.RELATED.START 

347 

348 

349RELATED = string_parameter( 

350 "RELATED", 

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

352 

353Description: 

354 This parameter can be specified on properties that 

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

356 parameter specifies whether the alarm will trigger relative to the 

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

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

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

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

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

362 

363""", # noqa: E501 

364 default=_default_related, 

365 convert=_convert_enum(enums.RELATED), 

366) 

367 

368 

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

370 return enums.ROLE.REQ_PARTICIPANT 

371 

372 

373ROLE = string_parameter( 

374 "ROLE", 

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

376 

377Description: 

378 This parameter can be specified on properties with a 

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

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

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

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

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

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

385""", 

386 default=_default_req_participant, 

387 convert=_convert_enum(enums.ROLE), 

388) 

389 

390 

391def boolean_parameter(name: str, default: bool) -> property: 

392 """Create a property for a Boolean parameter. 

393 

394 Parameters: 

395 default: The value to return when the parameter is absent. 

396 name: The parameter name in the ``params`` dictionary. 

397 

398 Returns: 

399 A property with a getter, setter, and deleter for the parameter. 

400 """ 

401 

402 def _default() -> bool: 

403 return default 

404 

405 return string_parameter( 

406 name, 

407 "", 

408 default=_default, 

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

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

411 ) 

412 

413 

414RSVP = boolean_parameter("RSVP", False) 

415"""Indicate whether a reply is expected from the ATTENDEE. 

416 

417The RSVP Expectation parameter can be specified on properties with a 

418CAL-ADDRESS value type, specifically ATTENDEE, as part of the ``attendees`` 

419property. An organizer uses it to request a participation status reply from 

420an attendee in a group-scheduled event or to-do. 

421 

422.. note:: 

423 

424 According to :rfc:`5545#section-3.2.17`, if the parameter is absent from 

425 the property, it should return a value of ``False``. However, it 

426 currently raises a ``KeyError``. See :issue:`1778`. 

427 

428Example: 

429 

430 Create a VCALADDRESS with an attendee who's expected to respond. 

431 

432 .. code-block:: pycon 

433 

434 >>> from icalendar import vCalAddress 

435 >>> attendee = vCalAddress("mailto:someone@example.com") 

436 >>> attendee.params["RSVP"] = True 

437 >>> attendee.params["RSVP"] 

438 True 

439 

440.. seealso:: 

441 

442 - :attr:`Alarm.attendees <icalendar.cal.alarm.Alarm.attendees>` 

443 - :attr:`Event.attendees <icalendar.cal.event.Event.attendees>` 

444 - :attr:`Journal.attendees <icalendar.cal.journal.Journal.attendees>` 

445 - :attr:`Todo.attendees <icalendar.cal.todo.Todo.attendees>` 

446""" 

447 

448SENT_BY = string_parameter( 

449 "SENT-BY", 

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

451 

452Description: 

453 This parameter can be specified on properties with a 

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

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

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

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

458 each be specified in a quoted-string. 

459""", # noqa: E501 

460) 

461 

462TZID = string_parameter( 

463 "TZID", 

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

465 

466Description: 

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

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

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

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

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

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

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

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

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

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

477 individual "VTIMEZONE" calendar component MUST be specified for 

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

479 object. 

480 

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

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

483 Failure to include and follow VTIMEZONE definitions in iCalendar 

484 objects may lead to inconsistent understanding of the local time 

485 at any given location. 

486 

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

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

489 registry (when such registry is defined). 

490 

491.. note:: 

492 

493 This document does not define a naming convention for 

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

495 conventions defined in existing time zone specifications such 

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

497 globally unique time zone identifiers is not addressed by this 

498 document and is left for future study. 

499""", # noqa: E501 

500) 

501 

502 

503def _default_return_parent() -> enums.RELTYPE: 

504 return enums.RELTYPE.PARENT 

505 

506 

507RELTYPE = string_parameter( 

508 "RELTYPE", 

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

510 

511Conformance: 

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

513 :rfc:`9253` adds new values. 

514 

515Description: 

516 This parameter can be specified on a property that 

517 references another related calendar. The parameter specifies the 

518 hierarchical relationship type of the calendar component 

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

520 indicate that the referenced calendar component is a superior of 

521 calendar component; CHILD to indicate that the referenced calendar 

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

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

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

525 allowable property, the default relationship type is PARENT. 

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

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

528""", 

529 default=_default_return_parent, 

530 convert=_convert_enum(enums.RELTYPE), 

531) 

532 

533 

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

535 """The VALUE parameter or the default. 

536 

537 Purpose: 

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

539 

540 Description: 

541 This parameter specifies the value type and format of 

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

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

544 of DATE-TIME and TIME value types. 

545 

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

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

548 default value type is overridden by some other allowable value 

549 type, then this parameter MUST be specified. 

550 

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

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

553 to interpret or parse the value data. 

554 

555 Returns: 

556 The VALUE parameter or the default. 

557 

558 Examples: 

559 The VALUE defaults to the name of the property. 

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

561 

562 .. code-block:: pycon 

563 

564 >>> from icalendar import vBoolean 

565 >>> b = vBoolean(True) 

566 >>> b.VALUE 

567 'BOOLEAN' 

568 

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

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

571 an uppercase string. 

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

573 

574 .. code-block:: pycon 

575 

576 >>> from icalendar import vUnknown, Event 

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

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

579 >>> v.VALUE 

580 'X-TYPE' 

581 >>> event = Event() 

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

583 >>> print(event.to_ical()) 

584 BEGIN:VEVENT 

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

586 END:VEVENT 

587 

588 """ 

589 value = self.params.value 

590 if value is None: 

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

592 if _get_default_value is not None: 

593 value = _get_default_value() 

594 return self.default_value if value is None else value 

595 

596 

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

598 """Set the VALUE parameter.""" 

599 self.params.value = value 

600 

601 

602def _del_value(self: VPROPERTY): 

603 """Delete the VALUE parameter.""" 

604 del self.params.value 

605 

606 

607VALUE = property(_get_value, _set_value, _del_value) 

608 

609LABEL = string_parameter( 

610 "LABEL", 

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

612 

613Conformance: 

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

615 iCalendar Property Extensions. 

616 

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

618 This parameter maps to the "title" 

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

620 LABEL is used to label the destination 

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

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

623 (if present). The LABEL MUST NOT 

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

625 MUST be ignored by parsers. 

626 

627Description: 

628 This property parameter MAY be specified on the 

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

630 iCalendar will reuse this property parameter on new properties 

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

632 property parameter present on many different properties. It 

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

634 users to allow them to discriminate between properties that might 

635 be similar or provide additional information for properties that 

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

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

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

639 

640Examples: 

641 This is a label of a chat. 

642 

643 .. code-block:: ics 

644 

645 CONFERENCE;VALUE=URI;FEATURE=VIDEO; 

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

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

648 

649""", 

650) 

651 

652FMTTYPE = string_parameter( 

653 "FMTTYPE", 

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

655 

656Conformance: 

657 :rfc:`5545` specifies the FMTTYPE. 

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

659 FMTTYPE maps to the "type" 

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

661 See :rfc:`6838`. 

662 

663Description: 

664 This parameter can be specified on properties that are 

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

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

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

668 necessarily convey the type of content associated with the 

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

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

671 

672Example: 

673 A Microsoft Word document: 

674 

675 .. code-block:: ics 

676 

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

678 agenda.doc 

679 

680 A website: 

681 

682 .. code-block:: ics 

683 

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

685 https://example.com/venue 

686 

687 """, 

688) 

689 

690LINKREL = string_parameter( 

691 "LINKREL", 

692 """LINKREL 

693 

694Purpose: 

695 LINKREL specifies the relationship of data referenced 

696 by a LINK property. 

697 

698Conformance: 

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

700 This parameter maps to the link relation type defined in 

701 Section 2.1 of :rfc:`8288`. 

702 It is always quoted. 

703 

704Description: 

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

706 the type of reference. 

707 This allows programs consuming this data to automatically scan 

708 for references they support. 

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

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

711 may be used. 

712 It is expected that link relation types seeing significant usage 

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

714 

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

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

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

718 the link target. 

719 

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

721 resource has particular attributes, or exhibits particular 

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

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

724 service description). 

725 

726Registration: 

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

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

729 

730.. seealso:: 

731 

732 `Registered Link Relation Types 

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

734 

735 

736Examples: 

737 This identifies the latest version of the event information. 

738 

739 .. code-block:: ics 

740 

741 LINKREL=latest-version 

742 

743""", 

744) 

745 

746 

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

748 """GAP 

749 

750 Purpose: 

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

752 between two components with a temporal relationship. 

753 

754 Format Definition: 

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

756 

757 Description: 

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

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

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

761 When negative, it defines the lead time. 

762 

763 Examples: 

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

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

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

767 

768 .. code-block:: text 

769 

770 ==================== 

771 | paint the room |--+ 

772 ==================== | 

773 |(lag of one day) 

774 | 

775 | =================== 

776 +->| lay the carpet | 

777 =================== 

778 

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

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

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

782 

783 .. code-block:: text 

784 

785 ===================== 

786 | electrical work |--+ 

787 ===================== | 

788 +-------------+ 

789 |(lead of estimated time) 

790 | ================== 

791 +->| painting | 

792 ================== 

793 """ 

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

795 if value is None: 

796 return None 

797 from icalendar.prop import vDuration 

798 

799 if isinstance(value, str): 

800 return vDuration.from_ical(value) 

801 if not isinstance(value, vDuration): 

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

803 return value.td 

804 

805 

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

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

808 if value is None: 

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

810 return 

811 from icalendar.prop import vDuration 

812 

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

814 

815 

816def _del_GAP(prop): # noqa: N802 

817 """Delete the GAP parameter.""" 

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

819 

820 

821GAP = property(_get_GAP, _set_GAP, _del_GAP) 

822 

823__all__ = [ 

824 "ALTREP", 

825 "CN", 

826 "CUTYPE", 

827 "DELEGATED_FROM", 

828 "DELEGATED_TO", 

829 "DIR", 

830 "FBTYPE", 

831 "FMTTYPE", 

832 "GAP", 

833 "LABEL", 

834 "LANGUAGE", 

835 "LINKREL", 

836 "MEMBER", 

837 "PARTSTAT", 

838 "RANGE", 

839 "RELATED", 

840 "ROLE", 

841 "RSVP", 

842 "SENT_BY", 

843 "TZID", 

844 "VALUE", 

845 "quoted_list_parameter", 

846 "string_parameter", 

847]