Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
0d00f86
feat(recur): add interval property accessor
aspire488 Nov 6, 2026
efd7cbe
fix(recur): align interval accessor docs and errors
aspire488 Nov 6, 2026
54d9f27
test(recur): cover deleting multiple interval values
aspire488 Nov 6, 2026
ee6c8c1
fix(recur): reject boolean interval values
aspire488 Nov 6, 2026
5856f11
Merge branch 'main' into feat/vrecur-interval-accessor
angatha Nov 7, 2026
77af158
Add positive integer value type for recurrence intervals
aspire488 Nov 12, 2026
9f53729
Validate INTERVAL with positive integer parser
aspire488 Nov 12, 2026
fbfb138
Test positive INTERVAL parsing and accessor behavior
aspire488 Nov 12, 2026
fcf8a98
Validate positive integers in xCal recurrence parsing
aspire488 Nov 12, 2026
d7fe84b
Clarify INTERVAL accessor documentation
aspire488 Nov 12, 2026
025fe61
Cover invalid parsed and stored recurrence intervals
aspire488 Nov 12, 2026
e29247c
Fix recurrence interval tests after CI lint feedback
aspire488 Nov 12, 2026
84c26f2
Clarify invalid RRULE parsing behavior in accessor docs
aspire488 Nov 12, 2026
48742db
Cover malformed INTERVAL values during parsing
aspire488 Nov 12, 2026
e3661e3
docs(recur): clarify INTERVAL accessor documentation
aspire488 Nov 14, 2026
e99015c
test(recur): align xCal interval expectations with positive integer
aspire488 Nov 15, 2026
20b575b
test(recur): accept positive integer validation for jCal interval
aspire488 Nov 15, 2026
26f330d
style(recur): format xCal interval regression test
aspire488 Nov 15, 2026
3851d56
Merge branch 'main' into feat/vrecur-interval-accessor
stevepiercy Nov 15, 2026
e343f7c
Merge branch 'main' into feat/vrecur-interval-accessor
stevepiercy Nov 15, 2026
85965c1
Clarify interval accessor parsing errors
aspire488 Nov 15, 2026
4855bfb
Polish positive integer docstring
aspire488 Nov 15, 2026
022ab05
Cover zero and negative stored intervals
aspire488 Nov 15, 2026
488b6bb
fix(recur): clarify interval access errors
aspire488 Nov 16, 2026
8d8a90f
test(recur): cover interval dictionary access errors
aspire488 Nov 16, 2026
b921445
test(recur): assert interval error value types
aspire488 Nov 16, 2026
7f6e06d
Merge branch 'main' into feat/vrecur-interval-accessor
stevepiercy Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions news/1851.feature.1
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Added an :attr:`~icalendar.prop.recur.recur.vRecur.interval` accessor for reading, setting, and deleting the positive INTERVAL value of a recurrence rule. I used OpenAI GPT-6 to assist with implementation and tests. @aspire488
27 changes: 26 additions & 1 deletion src/icalendar/prop/integer.py
Original file line number Diff line number Diff line change
Expand Up @@ -243,4 +243,29 @@ def examples(cls) -> list[vInt]:
XCAL_TYPE = "xsd:nonNegativeInteger"


__all__ = ["vInt", "vNonNegativeInt"]
class vPositiveInt(vInt):
"""This is an integer that is at least ``1``."""

min: ClassVar[int] = 1

@classmethod
def examples(cls) -> list[vInt]:
"""Examples of vPositiveInt."""
return [cls(1000), cls(1)]

XCAL_TYPE = "xsd:positiveInteger"

@classmethod
def from_xcal_element(cls, element: ElementAdapter, params: Parameters) -> Self:
"""Parse a positive integer from xCal."""
value = super().from_xcal_element(element, params)
if value < cls.min:
raise XCalParsingError(
f"Expected {cls.XCAL_TYPE}",
element.get_xsd_token(),
element,
)
return value


__all__ = ["vInt", "vNonNegativeInt", "vPositiveInt"]
73 changes: 71 additions & 2 deletions src/icalendar/prop/recur/recur.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
from icalendar.parser.xcal.wrapper import from_xcal_wrapper
from icalendar.parser_tools import DEFAULT_ENCODING, SEQUENCE_TYPES
from icalendar.prop.dt import vDDDTypes
from icalendar.prop.integer import vInt, vNonNegativeInt
from icalendar.prop.integer import vInt, vNonNegativeInt, vPositiveInt
from icalendar.prop.recur.frequency import vFrequency
from icalendar.prop.recur.month import vMonth
from icalendar.prop.recur.skip import vSkip
Expand Down Expand Up @@ -170,7 +170,7 @@ class vRecur(CaselessDict):
] = CaselessDict(
{
"COUNT": vNonNegativeInt,
"INTERVAL": vNonNegativeInt,
"INTERVAL": vPositiveInt,
"BYSECOND": vNonNegativeInt,
"BYMINUTE": vNonNegativeInt,
"BYHOUR": vNonNegativeInt,
Expand Down Expand Up @@ -414,6 +414,75 @@ def count(self) -> None:
"""Delete the COUNT part of the recurrence rule."""
self.pop("COUNT", None)

@property
def interval(self) -> int | None:
"""The INTERVAL part of the recurrence rule.

This is the positive integer interval between occurrences of the
recurrence frequency. When omitted, although :rfc:`5545#section-3.3.10`
defines the default as ``1``, this accessor returns ``None`` instead.
As such, callers can distinguish an omitted value from an explicit one.

If multiple values are present, only the first one is returned. If the
value is missing or an empty sequence, ``None`` is returned. Assigning
``None`` or deleting the property removes the entire INTERVAL entry,
including all values in a multi-value entry.

Raises:
ValueError: when parsing an RRULE whose INTERVAL is not a positive
integer.
InvalidCalendar: after using :ref:`dictionary-access`, if a stored
value cannot be read through :ref:`property-access` as an
:class:`int` or is less than ``1``, or when setting a value
less than ``1``.
TypeError: when setting a value that is not an :class:`int`.

Example:
.. code-block:: pycon

>>> from icalendar.prop import vRecur
>>> vRecur.from_ical("FREQ=DAILY;INTERVAL=2").interval
2
>>> vRecur(FREQ=["DAILY"], INTERVAL=[2, 3]).interval
2
>>> vRecur.from_ical("FREQ=DAILY").interval is None
True
Comment thread
angatha marked this conversation as resolved.
Resolved
"""
values = self.get("INTERVAL")
if values is None or (isinstance(values, SEQUENCE_TYPES) and len(values) == 0):
return None
value = values[0] if isinstance(values, SEQUENCE_TYPES) else values
if isinstance(value, bool):
raise InvalidCalendar(
f"INTERVAL must be an int, got {type(value).__name__}"
)
try:
interval = int(value)
except (TypeError, ValueError) as e:
raise InvalidCalendar(
f"INTERVAL must be an int, got {type(value).__name__}"
) from e
if interval < 1:
raise InvalidCalendar(f"INTERVAL must be >= 1, got {interval}.")
return interval

@interval.setter
def interval(self, value: int | None) -> None:
"""Set the INTERVAL part of the recurrence rule, or delete it if ``None``."""
if value is None:
del self.interval
return
if not isinstance(value, int) or isinstance(value, bool):
raise TypeError(f"interval must be an int, got {value!r}")
if value < 1:
raise InvalidCalendar(f"INTERVAL must be >= 1, got {value}")
Comment thread
angatha marked this conversation as resolved.
Resolved
Comment thread
stevepiercy marked this conversation as resolved.
Resolved
self["INTERVAL"] = [vPositiveInt(value)]

@interval.deleter
def interval(self) -> None:
"""Delete the INTERVAL part of the recurrence rule."""
self.pop("INTERVAL", None)

@property
def wkst(self) -> vWeekday | None:
"""The WKST part of the recurrence rule.
Expand Down
134 changes: 134 additions & 0 deletions src/icalendar/tests/prop/recur/test_interval.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
"""Tests for the vRecur.interval accessor (issue #1851)."""

import pytest

from icalendar.error import InvalidCalendar
from icalendar.prop import vRecur
from icalendar.prop.integer import vPositiveInt


def test_interval_returns_none_when_absent():
assert vRecur.from_ical("FREQ=DAILY").interval is None


def test_interval_returns_the_value():
assert vRecur.from_ical("FREQ=DAILY;INTERVAL=2").interval == 2


def test_interval_returns_first_value_when_multiple_are_present():
recur = vRecur(FREQ=["DAILY"], INTERVAL=[2, 3])
assert recur.interval == 2


def test_interval_returns_none_when_value_is_an_empty_list():
recur = vRecur(FREQ=["DAILY"], INTERVAL=[])
assert recur.interval is None


def test_setting_interval_stores_a_registered_positive_int():
recur = vRecur.from_ical("FREQ=DAILY")
recur.interval = 3

assert recur.interval == 3
assert isinstance(recur["INTERVAL"][0], vPositiveInt)
assert recur.to_ical() == b"FREQ=DAILY;INTERVAL=3"


def test_setting_interval_to_none_deletes_the_value():
recur = vRecur.from_ical("FREQ=DAILY;INTERVAL=2")
recur.interval = None

assert recur.interval is None
assert "INTERVAL" not in recur


def test_setting_interval_to_none_removes_all_multiple_values():
recur = vRecur(FREQ=["DAILY"], INTERVAL=[2, 3])
recur.interval = None

assert recur.interval is None
assert "INTERVAL" not in recur


def test_deleting_interval_removes_the_value():
recur = vRecur.from_ical("FREQ=DAILY;INTERVAL=2")
del recur.interval

assert recur.interval is None
assert "INTERVAL" not in recur
Comment thread
angatha marked this conversation as resolved.
Resolved


def test_deleting_interval_removes_all_multiple_values():
recur = vRecur(FREQ=["DAILY"], INTERVAL=[2, 3])
del recur.interval

assert recur.interval is None
assert "INTERVAL" not in recur


def test_deleting_interval_when_absent_does_not_raise():
recur = vRecur.from_ical("FREQ=DAILY")
del recur.interval
assert recur.interval is None


@pytest.mark.parametrize("value", ["2", 2.0, True])
def test_setting_interval_to_non_int_raises_type_error(value):
recur = vRecur.from_ical("FREQ=DAILY")
with pytest.raises(TypeError):
recur.interval = value


@pytest.mark.parametrize("value", [0, -1])
def test_setting_interval_to_non_positive_value_raises_invalid_calendar(value):
recur = vRecur.from_ical("FREQ=DAILY")
with pytest.raises(InvalidCalendar, match="INTERVAL must be >= 1"):
recur.interval = value


@pytest.mark.parametrize("value", ["0", "-1", "True", "abc"])
def test_parsing_invalid_interval_raises_value_error(value):
with pytest.raises(ValueError):
vRecur.from_ical(f"FREQ=DAILY;INTERVAL={value}")


@pytest.mark.parametrize("stored", [0, -1])
def test_dictionary_access_non_positive_interval_raises_invalid_calendar(stored):
recur = vRecur.from_ical("FREQ=DAILY")
recur["INTERVAL"] = [stored]
with pytest.raises(InvalidCalendar, match="INTERVAL must be >= 1"):
recur.interval


@pytest.mark.parametrize(
("stored", "value_type"),
[("abc", "str"), ("", "str"), (["abc"], "str"), (True, "bool")],
)
def test_dictionary_access_unreadable_interval_raises_invalid_calendar(
stored, value_type
):
recur = vRecur.from_ical("FREQ=DAILY")
recur["INTERVAL"] = stored
with pytest.raises(
InvalidCalendar,
match=f"INTERVAL must be an int, got {value_type}",
):
recur.interval


def test_interval_roundtrips_through_ical():
recur = vRecur.from_ical("FREQ=DAILY;INTERVAL=3")
roundtripped = vRecur.from_ical(recur.to_ical().decode())

assert roundtripped.interval == 3
assert isinstance(roundtripped["INTERVAL"][0], vPositiveInt)


def test_setting_interval_matches_parsed_vrecur():
parsed = vRecur.from_ical("FREQ=DAILY;INTERVAL=3")
assigned = vRecur.from_ical("FREQ=DAILY")
assigned.interval = 3

assert assigned == parsed
assert assigned["INTERVAL"] == parsed["INTERVAL"]
assert assigned.to_ical() == parsed.to_ical()
14 changes: 12 additions & 2 deletions src/icalendar/tests/rfc_6321_xcal/prop/test_recur.py
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ def test_leap_month_from_xcal(leap):
(
key,
"asd",
f"Expected xsd:nonNegativeInteger, got 'asd' in /recur/{key.lower()}[1].",
f"Expected xsd:{'positiveInteger' if key == 'INTERVAL' else 'nonNegativeInteger'}, got 'asd' in /recur/{key.lower()}[1].",
)
)

Expand All @@ -282,7 +282,7 @@ def test_invalid_values_raise_xcal_error(key, xml, message):
assert e.value.message == message


@pytest.mark.parametrize("key", POSITIVE_INTS)
@pytest.mark.parametrize("key", [key for key in POSITIVE_INTS if key != "INTERVAL"])
def test_negative_integer_still_parses(key):
"""We still want to preserve invalid values because
- we might just want to convert a calendar
Expand All @@ -294,6 +294,16 @@ def test_negative_integer_still_parses(key):
assert result[key][0].min == 0


def test_negative_interval_raises_xcal_error():
"""INTERVAL is an xsd:positiveInteger and cannot be negative."""
xml = list2xml(["recur", ["interval", "-1"]])
with pytest.raises(XCalParsingError) as exc_info:
vRecur.from_xcal(xml)
assert exc_info.value.message == (
"Expected xsd:positiveInteger, got '-1' in /recur/interval[1]."
)


def test_weekday_becomes_uppercase():
"""Uppercase is required for xCal."""
xml = list2xml(["recur", ["byday", "su"]])
Expand Down
2 changes: 1 addition & 1 deletion src/icalendar/tests/rfc_7265_jcal/test_invalid_jcal.py
Original file line number Diff line number Diff line change
Expand Up @@ -434,7 +434,7 @@ def test_int_parameters(int_expected, key, as_list):
# parse bad value
with pytest.raises(
JCalParsingError,
match=f'\\[3\\]\\["{key}"\\](?:\\[0\\])? in v(NonNegative)?Int: The value must be an integer.',
match=f'\\[3\\]\\["{key}"\\](?:\\[0\\])? in v(?:NonNegative|Positive)?Int: The value must be an integer.',
):
vRecur.from_jcal(["rrule", {}, "recur", {key: int_expected}])

Expand Down
Loading