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

1"""Parameter access for icalendar.

3Related:

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"""

11from __future__ import annotations

13import functools

14from typing import TYPE_CHECKING, Callable, Optional, TypeVar

16from icalendar import enums

18if TYPE_CHECKING:

19 from datetime import timedelta

20 from enum import Enum

22 from icalendar.parser import Parameters

25class IcalendarProperty:

26 """Interface provided by properties in icalendar.prop."""

28 params: Parameters

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

32 """Return None by default."""

33 return None

36def _default_return_string() -> str:

37 """Return None by default."""

38 return ""

41T = TypeVar("T")

44def string_parameter(

45 name: str,

46 doc: str,

47 default: Callable = _default_return_none,

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

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

50) -> property:

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

53 if convert_to is None:

54 convert_to = convert

56 @functools.wraps(default)

57 def fget(self: IcalendarProperty) -> Optional[str]:

58 value = self.params.get(name)

59 if value is None:

60 return default()

61 return convert(value) if convert else value

63 def fset(self: IcalendarProperty, value: str | None):

64 if value is None:

65 fdel(self)

66 else:

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

69 def fdel(self: IcalendarProperty):

70 self.params.pop(name, None)

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

75ALTREP = string_parameter(

76 "ALTREP",

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

79Description:

80 This parameter specifies a URI that points to an

81 alternate representation for a textual property value. A property

82 specifying this parameter MUST also include a value that reflects

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

84 value MUST be specified in a quoted-string.

86.. note::

88 While there is no restriction imposed on the URI schemes

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

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

91 commonly used by current implementations.

92""",

93)

95CN = string_parameter(

96 "CN",

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

99Description:

100 This parameter can be specified on properties with a

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

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

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

104 display text to be associated with the calendar address specified

105 by the property.

106""",

107 default=_default_return_string,

108)

109

110

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

112 """Default value."""

113 return enums.CUTYPE.INDIVIDUAL

114

115

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

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

118 """Convert if possible."""

119 try:

120 return enum(value.upper())

121 except ValueError:

122 return value

123

124 return convert

125

126

127CUTYPE = string_parameter(

128 "CUTYPE",

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

130

131Description:

132 This parameter can be specified on properties with a

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

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

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

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

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

138""",

139 default=_default_return_individual,

140 convert=_convert_enum(enums.CUTYPE),

141)

142

143

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

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

146

147 def fget(self: IcalendarProperty) -> tuple[str]:

148 value = self.params.get(name)

149 if value is None:

150 return ()

151 if isinstance(value, str):

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

153 return value

154

155 def fset(self: IcalendarProperty, value: str | tuple[str]):

156 if value == ():

157 fdel(self)

158 else:

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

160

161 def fdel(self: IcalendarProperty):

162 self.params.pop(name, None)

163

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

165

166

167DELEGATED_FROM = quoted_list_parameter(

168 "DELEGATED-FROM",

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

170

171Description:

172 This parameter can be specified on properties with a

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

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

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

176 The individual calendar address parameter values MUST each be

177 specified in a quoted-string.

178""", # noqa: E501

179)

180

181DELEGATED_TO = quoted_list_parameter(

182 "DELEGATED-TO",

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

184

185Description:

186 This parameter can be specified on properties with a

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

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

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

190 The individual calendar address parameter values MUST each be

191 specified in a quoted-string.

192 """, # noqa: E501

193)

194

195DIR = string_parameter(

196 "DIR",

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

198

199Description:

200 This parameter can be specified on properties with a

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

202 the directory entry associated with the calendar user specified by

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

204 value MUST be specified in a quoted-string.

205

206.. note::

207

208 While there is no restriction imposed on the URI schemes

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

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

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

212 used by current implementations.

213""", # noqa: E501

214)

215

216

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

218 """Default value."""

219 return enums.FBTYPE.BUSY

220

221

222FBTYPE = string_parameter(

223 "FBTYPE",

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

225

226Description:

227 This parameter specifies the free or busy time type.

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

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

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

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

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

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

234 because one or more events have been tentatively scheduled for

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

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

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

238 would the BUSY value.

239""",

240 default=_default_return_busy,

241 convert=_convert_enum(enums.FBTYPE),

242)

243

244LANGUAGE = string_parameter(

245 "LANGUAGE",

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

247

248Description:

249 This parameter identifies the language of the text in

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

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

252 defined in :rfc:`5646`.

253

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

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

256 Otherwise, no default language is assumed.

257""",

258)

259

260MEMBER = quoted_list_parameter(

261 "MEMBER",

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

263

264Description:

265 This parameter can be specified on properties with a

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

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

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

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

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

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

272""", # noqa: E501

273)

274

275

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

277 """Default value."""

278 return enums.PARTSTAT.NEEDS_ACTION

279

280

281PARTSTAT = string_parameter(

282 "PARTSTAT",

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

284

285Description:

286 This parameter can be specified on properties with a

287 CAL-ADDRESS value type. The parameter identifies the

288 participation status for the calendar user specified by the

289 property value. The parameter values differ depending on whether

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

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

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

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

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

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

296""",

297 default=_default_return_needs_action,

298 convert=_convert_enum(enums.PARTSTAT),

299)

300

301

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

303 return None

304

305

306RANGE = string_parameter(

307 "RANGE",

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

309

310Description:

311 This parameter can be specified on a property that

312 specifies a recurrence identifier. The parameter specifies the

313 effective range of recurrence instances that is specified by the

314 property. The effective range is from the recurrence identifier

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

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

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

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

319 defined by the recurrence identifier and all subsequent instances.

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

321 iCalendar and MUST NOT be generated by applications.

322""", # noqa: E501

323 default=_default_range_none,

324 convert=_convert_enum(enums.RANGE),

325)

326

327

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

329 return enums.RELATED.START

330

331

332RELATED = string_parameter(

333 "RELATED",

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

335

336Description:

337 This parameter can be specified on properties that

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

339 parameter specifies whether the alarm will trigger relative to the

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

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

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

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

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

345

346""", # noqa: E501

347 default=_default_related,

348 convert=_convert_enum(enums.RELATED),

349)

350

351

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

353 return enums.ROLE.REQ_PARTICIPANT

354

355

356ROLE = string_parameter(

357 "ROLE",

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

359

360Description:

361 This parameter can be specified on properties with a

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

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

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

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

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

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

368""",

369 default=_default_req_participant,

370 convert=_convert_enum(enums.ROLE),

371)

372

373

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

375 def _default() -> bool:

376 return default

377

378 return string_parameter(

379 name,

380 doc,

381 default=_default,

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

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

384 )

385

386

387RSVP = boolean_parameter(

388 "RSVP",

389 False, # noqa: FBT003

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

391

392Description:

393 This parameter can be specified on properties with a

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

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

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

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

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

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

400""", # noqa: E501

401)

402

403SENT_BY = string_parameter(

404 "SENT-BY",

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

406

407Description:

408 This parameter can be specified on properties with a

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

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

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

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

413 each be specified in a quoted-string.

414""", # noqa: E501

415)

416

417TZID = string_parameter(

418 "TZID",

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

420

421Description:

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

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

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

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

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

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

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

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

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

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

432 individual "VTIMEZONE" calendar component MUST be specified for

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

434 object.

435

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

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

438 Failure to include and follow VTIMEZONE definitions in iCalendar

439 objects may lead to inconsistent understanding of the local time

440 at any given location.

441

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

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

444 registry (when such registry is defined).

445

446.. note::

447

448 This document does not define a naming convention for

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

450 conventions defined in existing time zone specifications such

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

452 globally unique time zone identifiers is not addressed by this

453 document and is left for future study.

454""", # noqa: E501

455)

456

457

458def _default_return_parent() -> enums.RELTYPE:

459 return enums.RELTYPE.PARENT

460

461

462RELTYPE = string_parameter(

463 "RELTYPE",

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

465

466Conformance:

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

468 :rfc:`9253` adds new values.

469

470Description:

471 This parameter can be specified on a property that

472 references another related calendar. The parameter specifies the

473 hierarchical relationship type of the calendar component

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

475 indicate that the referenced calendar component is a superior of

476 calendar component; CHILD to indicate that the referenced calendar

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

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

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

480 allowable property, the default relationship type is PARENT.

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

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

483""",

484 default=_default_return_parent,

485 convert=_convert_enum(enums.RELTYPE),

486)

487

488LABEL = string_parameter(

489 "LABEL",

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

491

492Conformance:

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

494 iCalendar Property Extensions.

495

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

497 This parameter maps to the "title"

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

499 LABEL is used to label the destination

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

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

502 (if present). The LABEL MUST NOT

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

504 MUST be ignored by parsers.

505

506Description:

507 This property parameter MAY be specified on the

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

509 iCalendar will reuse this property parameter on new properties

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

511 property parameter present on many different properties. It

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

513 users to allow them to discriminate between properties that might

514 be similar or provide additional information for properties that

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

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

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

518

519Examples:

520 This is a label of a chat.

521

522 .. code-block:: text

523

524 CONFERENCE;VALUE=URI;FEATURE=VIDEO;

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

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

527

528""",

529)

530

531FMTTYPE = string_parameter(

532 "FMTTYPE",

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

534

535Conformance:

536 :rfc:`5545` specifies the FMTTYPE.

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

538 FMTTYPE maps to the "type"

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

540 See :rfc:`6838`.

541

542Description:

543 This parameter can be specified on properties that are

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

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

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

547 necessarily convey the type of content associated with the

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

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

550

551Example:

552 A Microsoft Word document:

553

554 .. code-block:: text

555

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

557 agenda.doc

558

559 A website:

560

561 .. code-block:: text

562

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

564 https://example.com/venue

565

566 """,

567)

568

569VALUE = string_parameter(

570 "VALUE",

571 """VALUE explicitly specifies the value type format for a property value.

572

573Conformance:

574 VALUE is specified in :rfc:`5545`.

575

576Description:

577 This parameter specifies the value type and format of

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

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

580 of DATE-TIME and TIME value types.

581

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

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

584 default value type is overridden by some other allowable value

585 type, then this parameter MUST be specified.

586

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

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

589 to interpret or parse the value data.

590

591""",

592)

593

594LINKREL = string_parameter(

595 "LINKREL",

596 """LINKREL

597

598Purpose:

599 LINKREL specifies the relationship of data referenced

600 by a LINK property.

601

602Conformance:

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

604 This parameter maps to the link relation type defined in

605 Section 2.1 of :rfc:`8288`.

606 It is always quoted.

607

608Description:

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

610 the type of reference.

611 This allows programs consuming this data to automatically scan

612 for references they support.

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

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

615 may be used.

616 It is expected that link relation types seeing significant usage

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

618

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

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

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

622 the link target.

623

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

625 resource has particular attributes, or exhibits particular

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

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

628 service description).

629

630Registration:

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

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

633

634.. seealso::

635

636 `Registered Link Relation Types

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

638

639

640Examples:

641 This identifies the latest version of the event information.

642

643 .. code-block:: text

644

645 LINKREL=latest-version

646

647""",

648)

649

650

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

652 """GAP

653

654 Purpose:

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

656 between two components with a temporal relationship.

657

658 Format Definition:

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

660

661 Description:

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

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

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

665 When negative, it defines the lead time.

666

667 Examples:

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

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

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

671

672 .. code-block:: text

673

674 ====================

675 | paint the room |--+

676 ==================== |

677 |(lag of one day)

678 |

679 | ===================

680 +->| lay the carpet |

681 ===================

682

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

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

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

686

687 .. code-block:: text

688

689 =====================

690 | electrical work |--+

691 ===================== |

692 +-------------+

693 |(lead of estimated time)

694 | ==================

695 +->| painting |

696 ==================

697 """

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

699 if value is None:

700 return None

701 from icalendar.prop import vDuration

702

703 if isinstance(value, str):

704 return vDuration.from_ical(value)

705 if not isinstance(value, vDuration):

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

707 return value.td

708

709

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

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

712 if value is None:

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

714 return

715 from icalendar.prop import vDuration

716

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

718

719

720def _del_GAP(prop): # noqa: N802

721 """Delete the GAP parameter."""

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

723

724

725GAP = property(_get_GAP, _set_GAP, _del_GAP)

726

727__all__ = [

728 "ALTREP",

729 "CN",

730 "CUTYPE",

731 "DELEGATED_FROM",

732 "DELEGATED_TO",

733 "DIR",

734 "FBTYPE",

735 "FMTTYPE",

736 "GAP",

737 "LABEL",

738 "LANGUAGE",

739 "LINKREL",

740 "MEMBER",

741 "PARTSTAT",

742 "RANGE",

743 "RELATED",

744 "ROLE",

745 "RSVP",

746 "SENT_BY",

747 "TZID",

748 "VALUE",

749 "quoted_list_parameter",

750 "string_parameter",

751]