diff --git a/news/1930.documentation.1 b/news/1930.documentation.1 new file mode 100644 index 000000000..80378ba09 --- /dev/null +++ b/news/1930.documentation.1 @@ -0,0 +1 @@ +Added value type hints to :class:`~icalendar.prop.recur.recur.vRecur`. Also updated the ``CaselessDict.canonical_order`` type annotation to support subclass key ordering. @Gabriel2002Can \ No newline at end of file diff --git a/src/icalendar/caselessdict.py b/src/icalendar/caselessdict.py index 4f4b7226c..71bfa153e 100644 --- a/src/icalendar/caselessdict.py +++ b/src/icalendar/caselessdict.py @@ -288,7 +288,7 @@ def __ne__(self, other: object) -> bool: # A list of keys that must appear first in sorted_keys and sorted_items; # must be uppercase. - canonical_order = None + canonical_order: Iterable[str] | None = None def sorted_keys(self) -> list[str]: """Sort keys according to the canonical order for this class. diff --git a/src/icalendar/prop/recur/recur.py b/src/icalendar/prop/recur/recur.py index 252c708a2..90d11e6d4 100644 --- a/src/icalendar/prop/recur/recur.py +++ b/src/icalendar/prop/recur/recur.py @@ -2,7 +2,8 @@ from __future__ import annotations -from typing import TYPE_CHECKING, Any, ClassVar +from datetime import date, datetime, time, timedelta +from typing import TYPE_CHECKING, Any, ClassVar, TypeAlias, cast from xml.etree.ElementTree import Element, SubElement from icalendar.caselessdict import CaselessDict @@ -26,8 +27,21 @@ from icalendar.parser.xcal.base import XCalParser from icalendar.prop import VPROPERTY +RecurValue: TypeAlias = ( + int + | str + | date + | datetime + | time + | timedelta + | tuple[datetime, datetime | timedelta] + | vDDDTypes +) -class vRecur(CaselessDict): +RecurEntryValue: TypeAlias = RecurValue | list[RecurValue] | tuple[RecurValue, ...] + + +class vRecur(CaselessDict[RecurEntryValue]): """Recurrence definition. Property Name: @@ -147,7 +161,10 @@ class vRecur(CaselessDict): ) types: ClassVar[ - dict[str, type[vInt | vMonth | vFrequency | vWeekday | vSkip | vText]] + dict[ + str, + type[vInt | vMonth | vDDDTypes | vFrequency | vWeekday | vSkip | vText], + ] ] = CaselessDict( { "COUNT": vNonNegativeInt, @@ -187,10 +204,10 @@ def __init__( super().__init__(*args, **kwargs) self.params = Parameters(params) - def to_ical(self): + def to_ical(self) -> bytes: result = [] for key, vals in self.sorted_items(): - typ = self.types.get(key, vText) + typ: Any = self.types.get(key, vText) if not isinstance(vals, SEQUENCE_TYPES): vals = [vals] param_vals = b",".join(typ(val).to_ical() for val in vals) @@ -202,7 +219,7 @@ def to_ical(self): return b";".join(result) @classmethod - def parse_type(cls, key, values): + def parse_type(cls, key: str, values: str) -> list[RecurValue]: # integers parser = cls.types.get(key, vText) return [parser.from_ical(v) for v in values.split(",")] @@ -236,11 +253,11 @@ def examples(cls) -> list[Self]: def to_jcal(self, name: str) -> list: """The jCal representation of this property according to :rfc:`7265`.""" - recur = {} + recur: dict[str, Any] = {} for k, v in self.items(): key = k.lower() if key.upper() in self.jcal_not_a_list: - value = v[0] if isinstance(v, list) and len(v) == 1 else v + value: Any = v[0] if isinstance(v, list) and len(v) == 1 else v elif not isinstance(v, list): value = [v] else: @@ -273,7 +290,7 @@ def from_jcal(cls, jcal_property: list) -> Self: 3, value=jcal_property[3], ) - recur = {} + recur: dict[str, RecurValue | list[RecurValue]] = {} for key, value in jcal_property[3].items(): JCalParsingError.validate_jcal_token( key, "recurrence rule part name", cls, path=[3, key] @@ -281,7 +298,8 @@ def from_jcal(cls, jcal_property: list) -> Self: value_type = cls.types.get(key, vText) with JCalParsingError.reraise_with_path_added(3, key): if isinstance(value, list): - recur[key.lower()] = values = [] + values: list[RecurValue] = [] + recur[key.lower()] = values for i, v in enumerate(value): with JCalParsingError.reraise_with_path_added(i): values.append(value_type.parse_jcal_value(v)) @@ -333,7 +351,7 @@ def count(self) -> int | None: return None value = values[0] if isinstance(values, SEQUENCE_TYPES) else values try: - return int(value) + return int(cast("int | str", value)) except (TypeError, ValueError) as e: # Matches how icalendar.attr.single_int_property surfaces a stored # value that is not readable as an int. @@ -469,7 +487,8 @@ def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: if from_xcal is None: from_xcal = v_prop.from_xcal value = from_xcal(parser) - self.setdefault(key, []).append(value) + values = cast("list[RecurValue]", self.setdefault(key, [])) + values.append(cast("RecurValue", value)) return self def to_xcal(self, element: Element) -> None: @@ -477,8 +496,8 @@ def to_xcal(self, element: Element) -> None: self.params.to_xcal(element) recur_element = SubElement(element, self.default_value.lower()) for key, value in self.sorted_items(): - value = value if isinstance(value, list) else [value] - for v in value: + values: list[Any] = value if isinstance(value, list) else [value] + for v in values: if not hasattr(v, "to_xcal"): v_prop = self.types.get(key, vText) v = v_prop(v) diff --git a/src/icalendar/tests/test_issue_1930.py b/src/icalendar/tests/test_issue_1930.py new file mode 100644 index 000000000..4317d45a3 --- /dev/null +++ b/src/icalendar/tests/test_issue_1930.py @@ -0,0 +1,17 @@ +from typing_extensions import assert_type + +from icalendar.prop.recur.recur import RecurEntryValue, vRecur + + +def test_vrecur_value_type(): + rule = vRecur.from_ical("FREQ=DAILY;COUNT=10") + + assert_type(rule["COUNT"], RecurEntryValue) + assert rule["COUNT"] == [10] + + +def test_vrecur_value_type_with_multiple_values(): + rule = vRecur.from_ical("FREQ=DAILY;BYDAY=MO,TU,WE") + + assert_type(rule["BYDAY"], RecurEntryValue) + assert rule["BYDAY"] == ["MO", "TU", "WE"]