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
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""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 datetime import timedelta
15from typing import TYPE_CHECKING, Callable, Optional, TypeVar
17from icalendar import enums
19if TYPE_CHECKING:
20 from enum import Enum
23if TYPE_CHECKING:
24 from icalendar.prop import VPROPERTY
27def _default_return_none() -> Optional[str]:
28 """Return None by default."""
29 return None
32def _default_return_string() -> str:
33 """Return None by default."""
34 return ""
37T = TypeVar("T")
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)."""
49 if convert_to is None:
50 convert_to = convert
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
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
65 def fdel(self: VPROPERTY):
66 self.params.pop(name, None)
68 return property(fget, fset, fdel, doc=doc)
71ALTREP = string_parameter(
72 "ALTREP",
73 """ALTREP - Specify an alternate text representation for the property value.
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.
82.. note::
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)
91CN = string_parameter(
92 "CN",
93 """Specify the common name to be associated with the calendar user specified.
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)
107def _default_return_individual() -> enums.CUTYPE | str:
108 """Default value."""
109 return enums.CUTYPE.INDIVIDUAL
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
120 return convert
123CUTYPE = string_parameter(
124 "CUTYPE",
125 """Identify the type of calendar user specified by the property.
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)
140def quoted_list_parameter(name: str, doc: str) -> property:
141 """Return a parameter that contains a quoted list."""
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
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
157 def fdel(self: VPROPERTY):
158 self.params.pop(name, None)
160 return property(fget, fset, fdel, doc=doc)
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.
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)
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.
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)
191DIR = string_parameter(
192 "DIR",
193 """Specify reference to a directory entry associated with the calendar user specified by the property.
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.
202.. note::
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)
213def _default_return_busy() -> enums.FBTYPE | str:
214 """Default value."""
215 return enums.FBTYPE.BUSY
218FBTYPE = string_parameter(
219 "FBTYPE",
220 """Specify the free or busy time type.
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)
240LANGUAGE = string_parameter(
241 "LANGUAGE",
242 """Specify the language for text values in a property or property parameter.
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`.
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)
256MEMBER = quoted_list_parameter(
257 "MEMBER",
258 """Specify the group or list membership of the calendar user specified by the property.
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)
272def _default_return_needs_action() -> enums.PARTSTAT | str:
273 """Default value."""
274 return enums.PARTSTAT.NEEDS_ACTION
277PARTSTAT = string_parameter(
278 "PARTSTAT",
279 """Specify the participation status for the calendar user specified by the property.
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)
298def _default_range_none() -> Optional[enums.RANGE | str]:
299 return None
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.
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)
324def _default_related() -> enums.RELATED | str:
325 return enums.RELATED.START
328RELATED = string_parameter(
329 "RELATED",
330 """Specify the relationship of the alarm trigger with respect to the start or end of the calendar component.
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.
342""", # noqa: E501
343 default=_default_related,
344 convert=_convert_enum(enums.RELATED),
345)
348def _default_req_participant() -> enums.ROLE | str:
349 return enums.ROLE.REQ_PARTICIPANT
352ROLE = string_parameter(
353 "ROLE",
354 """Specify the participation role for the calendar user specified by the property.
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)
370def boolean_parameter(name: str, default: bool, doc: str) -> property: # noqa: FBT001
371 def _default() -> bool:
372 return default
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 )
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.
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)
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.
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)
413TZID = string_parameter(
414 "TZID",
415 """Specify the identifier for the time zone definition for a time component in the property value.
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.
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.
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).
442.. note::
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)
454def _default_return_parent() -> enums.RELTYPE:
455 return enums.RELTYPE.PARENT
458RELTYPE = string_parameter(
459 "RELTYPE",
460 """Specify the type of hierarchical relationship associated with a component.
462Conformance:
463 :rfc:`5545` introduces the RELTYPE property parameter.
464 :rfc:`9253` adds new values.
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)
485def _get_value(self: VPROPERTY) -> str:
486 """The VALUE parameter or the default.
488 Purpose:
489 VALUE explicitly specify the value type format for a property value.
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.
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.
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.
506 Returns:
507 The VALUE parameter or the default.
509 Examples:
510 The VALUE defaults to the name of the property.
511 Note that it is case-insensitive but always uppercase.
513 .. code-block:: pycon
515 >>> from icalendar import vBoolean
516 >>> b = vBoolean(True)
517 >>> b.VALUE
518 'BOOLEAN'
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:
525 .. code-block:: pycon
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
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
548def _set_value(self: VPROPERTY, value: str | None):
549 """Set the VALUE parameter."""
550 self.params.value = value
553def _del_value(self: VPROPERTY):
554 """Delete the VALUE parameter."""
555 del self.params.value
558VALUE = property(_get_value, _set_value, _del_value)
560LABEL = string_parameter(
561 "LABEL",
562 """LABEL provides a human-readable label.
564Conformance:
565 This property parameter is specified in :rfc:`7986`,
566 iCalendar Property Extensions.
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.
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`).
591Examples:
592 This is a label of a chat.
594 .. code-block:: text
596 CONFERENCE;VALUE=URI;FEATURE=VIDEO;
597 LABEL="Web video chat, access code=76543";
598 :https://video-chat.example.com/;group-id=1234
600""",
601)
603FMTTYPE = string_parameter(
604 "FMTTYPE",
605 """FMTTYPE specfies the content type of a referenced object.
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`.
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.
623Example:
624 A Microsoft Word document:
626 .. code-block:: text
628 ATTACH;FMTTYPE=application/msword:ftp://example.com/pub/docs/
629 agenda.doc
631 A website:
633 .. code-block:: text
635 LINK;FMTTYPE=text/html;LINKREL=SOURCE;LABEL=Venue;VALUE=URI:
636 https://example.com/venue
638 """,
639)
641LINKREL = string_parameter(
642 "LINKREL",
643 """LINKREL
645Purpose:
646 LINKREL specifies the relationship of data referenced
647 by a LINK property.
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.
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.
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.
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).
677Registration:
678 There are two kinds of relation types: registered and extension.
679 These relation types are registered in :rfc:`8288`.
681.. seealso::
683 `Registered Link Relation Types
684 <https://www.iana.org/assignments/link-relations/link-relations.xhtml>`_.
687Examples:
688 This identifies the latest version of the event information.
690 .. code-block:: text
692 LINKREL=latest-version
694""",
695)
698def _get_GAP(prop) -> timedelta | None: # noqa: N802
699 """GAP
701 Purpose:
702 GAP specifies the length of the gap, positive or negative,
703 between two components with a temporal relationship.
705 Format Definition:
706 Same as the DURATION value type defined in :rfc:`5545`, Section 3.3.6.
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.
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.
719 .. code-block:: text
721 ====================
722 | paint the room |--+
723 ==================== |
724 |(lag of one day)
725 |
726 | ===================
727 +->| lay the carpet |
728 ===================
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.
734 .. code-block:: text
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
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
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
764 prop.params["GAP"] = vDuration(value)
767def _del_GAP(prop): # noqa: N802
768 """Delete the GAP parameter."""
769 prop.params.pop("GAP", None)
772GAP = property(_get_GAP, _set_GAP, _del_GAP)
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]