"""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
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")
[docs]
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),
)
[docs]
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.
""", # noqa: E501
)
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.
""", # noqa: E501
)
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.
""", # noqa: E501
)
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.
""", # noqa: E501
)
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.
""", # noqa: E501
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.
""", # noqa: E501
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: # noqa: FBT001
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, # noqa: FBT003
"""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``.
""", # noqa: E501
)
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.
""", # noqa: E501
)
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.
""", # noqa: E501
)
def _default_return_parent() -> enums.RELTYPE:
return enums.RELTYPE.PARENT
RELTYPE = string_parameter(
"RELTYPE",
"""Specify the type of hierarchical relationship associated with a component.
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__ = [
"ALTREP",
"CN",
"CUTYPE",
"DELEGATED_FROM",
"DELEGATED_TO",
"DIR",
"FBTYPE",
"LANGUAGE",
"MEMBER",
"PARTSTAT",
"RANGE",
"RELATED",
"ROLE",
"RSVP",
"SENT_BY",
"TZID",
"quoted_list_parameter",
"string_parameter",
]