Skip to main content
`Ctrl`+`K`

# Source code for icalendar.param

    """Parameter access for icalendar.

    Related:

    - :rfc:`5545`, Section 3.2. Property Parameters
    - :rfc:`7986`, Section 6. Property Parameters
    - https://github.com/collective/icalendar/issues/798
    """
    from __future__ import annotations

    import functools
    from typing import TYPE_CHECKING, Callable, Optional, TypeVar, Union

    from icalendar import enums

    if TYPE_CHECKING:
        from enum import Enum

        from icalendar.parser import Parameters

    class IcalendarProperty:
        """Interface provided by properties in icalendar.prop."""
        params: Parameters

    def _default_return_none() -> Optional[str]:
        """Return None by default."""
        return None

    def _default_return_string() -> str:
        """Return None by default."""
        return ""

    T = TypeVar("T")

    def string_parameter(
            name:str,
            doc:str,
            default:Callable = _default_return_none,
            convert:Optional[Callable[[str], T]] = None,
            convert_to:Optional[Callable[[T], str]] = None
        ) -> property:
        """Return a parameter with a quoted value (case sensitive)."""

        if convert_to is None:
            convert_to = convert

        @functools.wraps(default)
        def fget(self: IcalendarProperty) -> Optional[str]:
            value = self.params.get(name)
            if value is None:
                return default()
            return convert(value) if convert else value

        def fset(self: IcalendarProperty, value: str):
            self.params[name] = convert_to(value) if convert_to else value

        def fdel(self: IcalendarProperty):
            self.params.pop(name, None)

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

    ALTREP = string_parameter(
        "ALTREP",
        """ALTREP - Specify an alternate text representation for the property value.

    Description:
        This parameter specifies a URI that points to an
        alternate representation for a textual property value.  A property
        specifying this parameter MUST also include a value that reflects
        the default representation of the text value.  The URI parameter
        value MUST be specified in a quoted-string.

    .. note::

        While there is no restriction imposed on the URI schemes
        allowed for this parameter, Content Identifier (CID) :rfc:`2392`,
        HTTP :rfc:`2616`, and HTTPS :rfc:`2818` are the URI schemes most
        commonly used by current implementations.
    """)

    CN = string_parameter(
        "CN",
        """Specify the common name to be associated with the calendar user specified.

    Description:
        This parameter can be specified on properties with a
        CAL-ADDRESS value type.  The parameter specifies the common name
        to be associated with the calendar user specified by the property.
        The parameter value is text.  The parameter value can be used for
        display text to be associated with the calendar address specified
        by the property.
    """,
        default=_default_return_string
    )

    def _default_return_individual() -> enums.CUTYPE|str:
        """Default value."""
        return enums.CUTYPE.INDIVIDUAL

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

        def convert(value: str) -> str:
            """Convert if possible."""
            try:
                return enum(value.upper())
            except ValueError:
                return value
        return convert

    CUTYPE = string_parameter(
        "CUTYPE",
        """Identify the type of calendar user specified by the property.

    Description:
        This parameter can be specified on properties with a
        CAL-ADDRESS value type.  The parameter identifies the type of
        calendar user specified by the property.  If not specified on a
        property that allows this parameter, the default is INDIVIDUAL.
        Applications MUST treat x-name and iana-token values they don't
        recognize the same way as they would the UNKNOWN value.
    """, default=_default_return_individual, convert=_convert_enum(enums.CUTYPE))

    def quoted_list_parameter(name: str, doc: str) -> property:
        """Return a parameter that contains a quoted list."""

        def fget(self: IcalendarProperty) -> tuple[str]:
            value = self.params.get(name)
            if value is None:
                return ()
            if isinstance(value, str):
                return tuple(value.split(","))
            return value

        def fset(self: IcalendarProperty, value: str|tuple[str]):
            if value == ():
                fdel(self)
            else:
                self.params[name] = (value,) if isinstance(value, str) else value

        def fdel(self: IcalendarProperty):
            self.params.pop(name, None)

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

    DELEGATED_FROM = quoted_list_parameter(
        "DELEGATED-FROM",
        """Specify the calendar users that have delegated their participation to the calendar user specified by the property.

    Description:
        This parameter can be specified on properties with a
        CAL-ADDRESS value type.  This parameter specifies those calendar
        users that have delegated their participation in a group-scheduled
        event or to-do to the calendar user specified by the property.
        The individual calendar address parameter values MUST each be
        specified in a quoted-string.
    """)

    DELEGATED_TO = quoted_list_parameter(
        "DELEGATED-TO",
        """Specify the calendar users to whom the calendar user specified by the property has delegated participation.

    Description:
        This parameter can be specified on properties with a
        CAL-ADDRESS value type.  This parameter specifies those calendar
        users whom have been delegated participation in a group-scheduled
        event or to-do by the calendar user specified by the property.
        The individual calendar address parameter values MUST each be
        specified in a quoted-string.
        """)

    DIR = string_parameter(
        "DIR",
        """Specify reference to a directory entry associated with the calendar user specified by the property.

    Description:
        This parameter can be specified on properties with a
        CAL-ADDRESS value type.  The parameter specifies a reference to
        the directory entry associated with the calendar user specified by
        the property.  The parameter value is a URI.  The URI parameter
        value MUST be specified in a quoted-string.

    .. note::

        While there is no restriction imposed on the URI schemes
        allowed for this parameter, CID :rfc:`2392`, DATA :rfc:`2397`, FILE
        :rfc:`1738`, FTP :rfc:`1738`, HTTP :rfc:`2616`, HTTPS :rfc:`2818`, LDAP
        :rfc:`4516`, and MID :rfc:`2392` are the URI schemes most commonly
        used by current implementations.
    """)

    def _default_return_busy() -> enums.FBTYPE|str:
        """Default value."""
        return enums.FBTYPE.BUSY

    FBTYPE = string_parameter(
        "FBTYPE",
        """Specify the free or busy time type.

    Description:
        This parameter specifies the free or busy time type.
        The value FREE indicates that the time interval is free for
        scheduling.  The value BUSY indicates that the time interval is
        busy because one or more events have been scheduled for that
        interval.  The value BUSY-UNAVAILABLE indicates that the time
        interval is busy and that the interval can not be scheduled.  The
        value BUSY-TENTATIVE indicates that the time interval is busy
        because one or more events have been tentatively scheduled for
        that interval.  If not specified on a property that allows this
        parameter, the default is BUSY.  Applications MUST treat x-name
        and iana-token values they don't recognize the same way as they
        would the BUSY value.
    """, default=_default_return_busy, convert=_convert_enum(enums.FBTYPE))

    LANGUAGE = string_parameter(
        "LANGUAGE",
        """Specify the language for text values in a property or property parameter.

    Description:
        This parameter identifies the language of the text in
        the property value and of all property parameter values of the
        property.  The value of the "LANGUAGE" property parameter is that
        defined in :rfc:`5646`.

        For transport in a MIME entity, the Content-Language header field
        can be used to set the default language for the entire body part.
        Otherwise, no default language is assumed.
    """)

    MEMBER = quoted_list_parameter(
        "MEMBER",
        """Specify the group or list membership of the calendar user specified by the property.

    Description:
        This parameter can be specified on properties with a
        CAL-ADDRESS value type.  The parameter identifies the groups or
        list membership for the calendar user specified by the property.
        The parameter value is either a single calendar address in a
        quoted-string or a COMMA-separated list of calendar addresses,
        each in a quoted-string.  The individual calendar address
        parameter values MUST each be specified in a quoted-string.
    """
    )

    def _default_return_needs_action() -> enums.PARTSTAT|str:
        """Default value."""
        return enums.PARTSTAT.NEEDS_ACTION

    PARTSTAT = string_parameter(
        "PARTSTAT",
        """Specify the participation status for the calendar user specified by the property.

    Description:
        This parameter can be specified on properties with a
        CAL-ADDRESS value type.  The parameter identifies the
        participation status for the calendar user specified by the
        property value.  The parameter values differ depending on whether
        they are associated with a group-scheduled "VEVENT", "VTODO", or
        "VJOURNAL".  The values MUST match one of the values allowed for
        the given calendar component.  If not specified on a property that
        allows this parameter, the default value is NEEDS-ACTION.
        Applications MUST treat x-name and iana-token values they don't
        recognize the same way as they would the NEEDS-ACTION value.
    """, default=_default_return_needs_action, convert=_convert_enum(enums.PARTSTAT))

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

    RANGE = string_parameter(
        "RANGE",
        """Specify the effective range of recurrence instances from the instance specified by the recurrence identifier specified by the property.

    Description:
        This parameter can be specified on a property that
        specifies a recurrence identifier.  The parameter specifies the
        effective range of recurrence instances that is specified by the
        property.  The effective range is from the recurrence identifier
        specified by the property.  If this parameter is not specified on
        an allowed property, then the default range is the single instance
        specified by the recurrence identifier value of the property.  The
        parameter value can only be "THISANDFUTURE" to indicate a range
        defined by the recurrence identifier and all subsequent instances.
        The value "THISANDPRIOR" is deprecated by this revision of
        iCalendar and MUST NOT be generated by applications.
    """, default=_default_range_none, convert=_convert_enum(enums.RANGE))

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

    RELATED = string_parameter(
        "RELATED",
        """Specify the relationship of the alarm trigger with respect to the start or end of the calendar component.

    Description:
        This parameter can be specified on properties that
        specify an alarm trigger with a "DURATION" value type.  The
        parameter specifies whether the alarm will trigger relative to the
        start or end of the calendar component.  The parameter value START
        will set the alarm to trigger off the start of the calendar
        component; the parameter value END will set the alarm to trigger
        off the end of the calendar component.  If the parameter is not
        specified on an allowable property, then the default is START.

    """, default=_default_related, convert=_convert_enum(enums.RANGE))

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

    ROLE = string_parameter(
        "ROLE",
        """Specify the participation role for the calendar user specified by the property.

    Description:
        This parameter can be specified on properties with a
        CAL-ADDRESS value type.  The parameter specifies the participation
        role for the calendar user specified by the property in the group
        schedule calendar component.  If not specified on a property that
        allows this parameter, the default value is REQ-PARTICIPANT.
        Applications MUST treat x-name and iana-token values they don't
        recognize the same way as they would the REQ-PARTICIPANT value.
    """, default=_default_req_participant, convert=_convert_enum(enums.ROLE)
    )

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

        def _default() -> bool:
            return default

        return string_parameter(
            name,
            doc,
            default=_default,
            convert=lambda x: x.upper() == "TRUE",
            convert_to=lambda x: "TRUE" if x else "FALSE",
        )

    RSVP = boolean_parameter(
        "RSVP",
        False,
        """Specify whether there is an expectation of a favor of anreply from the calendar user specified by the property value.

    Description:
        This parameter can be specified on properties with a
        CAL-ADDRESS value type.  The parameter identifies the expectation
        of a reply from the calendar user specified by the property value.
        This parameter is used by the "Organizer" to request a
        participation status reply from an "Attendee" of a group-scheduled
        event or to-do.  If not specified on a property that allows this
        parameter, the default value is ``False``.
    """
    )

    SENT_BY = string_parameter(
        "SENT-BY",
        """Specify the calendar user that is acting on behalf of the calendar user specified by the property.

    Description:
        This parameter can be specified on properties with a
        CAL-ADDRESS value type.  The parameter specifies the calendar user
        that is acting on behalf of the calendar user specified by the
        property.  The parameter value MUST be a mailto URI as defined in
        :rfc:`2368`.  The individual calendar address parameter values MUST
        each be specified in a quoted-string.
    """
    )

    TZID = string_parameter(
        "TZID",
        """Specify the identifier for the time zone definition for a time component in the property value.

    Description:
        This parameter MUST be specified on the "DTSTART",
        "DTEND", "DUE", "EXDATE", and "RDATE" properties when either a
        DATE-TIME or TIME value type is specified and when the value is
        neither a UTC or a "floating" time.  Refer to the DATE-TIME or
        TIME value type definition for a description of UTC and "floating
        time" formats.  This property parameter specifies a text value
        that uniquely identifies the "VTIMEZONE" calendar component to be
        used when evaluating the time portion of the property.  The value
        of the "TZID" property parameter will be equal to the value of the
        "TZID" property for the matching time zone definition.  An
        individual "VTIMEZONE" calendar component MUST be specified for
        each unique "TZID" parameter value specified in the iCalendar
        object.

        The parameter MUST be specified on properties with a DATE-TIME
        value if the DATE-TIME is not either a UTC or a "floating" time.
        Failure to include and follow VTIMEZONE definitions in iCalendar
        objects may lead to inconsistent understanding of the local time
        at any given location.

        The presence of the SOLIDUS character as a prefix, indicates that
        this "TZID" represents a unique ID in a globally defined time zone
        registry (when such registry is defined).

    .. note::

        This document does not define a naming convention for
        time zone identifiers.  Implementers may want to use the naming
        conventions defined in existing time zone specifications such
        as the public-domain TZ database (TZDB). The specification of
        globally unique time zone identifiers is not addressed by this
        document and is left for future study.
    """
    )

    def _default_return_parent() -> enums.RELTYPE:
        return enums.RELTYPE.PARENT

    RELTYPE = string_parameter(
        "RELTYPE",
        """Specify the type of hierarchical relationship associated with the calendar component specified by the property.

    Description:
        This parameter can be specified on a property that
        references another related calendar.  The parameter specifies the
        hierarchical relationship type of the calendar component
        referenced by the property.  The parameter value can be PARENT, to
        indicate that the referenced calendar component is a superior of
        calendar component; CHILD to indicate that the referenced calendar
        component is a subordinate of the calendar component; or SIBLING
        to indicate that the referenced calendar component is a peer of
        the calendar component.  If this parameter is not specified on an
        allowable property, the default relationship type is PARENT.
        Applications MUST treat x-name and iana-token values they don't
        recognize the same way as they would the PARENT value.
    """, default=_default_return_parent, convert=_convert_enum(enums.RELTYPE))

    __all__ = [
        "string_parameter",
        "quoted_list_parameter",
        "ALTREP",
        "CN",
        "CUTYPE",
        "DELEGATED_FROM",
        "DELEGATED_TO",
        "DIR",
        "FBTYPE",
        "LANGUAGE",
        "MEMBER",
        "PARTSTAT",
        "RANGE",
        "RELATED",
        "ROLE",
        "RSVP",
        "SENT_BY",
        "TZID",
    ]