fix: check_component() must not mutate self

check_component() resolved None fields (include_completed, todo, event,
journal) and normalised date start/end/alarm_start/alarm_end values by
writing back to self.  This made a Searcher instance stateful: calling
check_component() twice could yield different results, and reusing a
Searcher across multiple operations changed behaviour after the first call.

Fix: compute all resolved/normalised values as local variables inside
check_component().  Thread them to the internal filter helpers via new
keyword parameters (_start, _end, _alarm_start, _alarm_end for
_check_range/_check_alarm_range; _include_completed for
_check_completed_filter).  The parameters default to None which falls
back to self.* for existing callers that do not pass them.

Add tests/test_no_mutation.py to guard against regression.

Triggered by python-caldav/caldav#650

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tobixen

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+
+- **`check_component()` mutated `self` on every call**: The method resolved `None` fields (`include_completed`, `todo`, `event`, `journal`) and normalised `start`/`end`/`alarm_start`/`alarm_end` date objects to datetimes by writing back to `self`.  This made a `Searcher` instance stateful: calling `check_component()` twice could produce different results, and reusing a `Searcher` across multiple search operations (e.g. in the python-caldav library) could silently change behaviour after the first call.  All these values are now computed as local variables inside `check_component()` and threaded to the internal filter methods via new keyword parameters (`_start`, `_end`, `_alarm_start`, `_alarm_end`, `_include_completed`), keeping `self` immutable throughout.  (Triggered by https://github.com/python-caldav/caldav/issues/650)
+
 ## [1.0.5] - 2026-02-19
 
 ### Changes

src/icalendar_searcher/filters.py

@@ -25,14 +25,26 @@ class FilterMixin:
     - _property_locale: dict of property locales
     """
 
-    def _check_range(self, component: Component) -> bool:
+    def _check_range(
+        self,
+        component: Component,
+        _start: datetime | None = None,
+        _end: datetime | None = None,
+    ) -> bool:
         """Check if a component falls within the time range specified by self.start and self.end.
 
         Implements RFC4791 section 9.9 time-range filtering logic for VEVENT, VTODO, and VJOURNAL.
 
         :param component: A single calendar component (VEVENT, VTODO, or VJOURNAL)
+        :param _start: Effective start datetime (defaults to self.start).  Pass a pre-normalised
+            value from check_component() to avoid mutating self.
+        :param _end: Effective end datetime (defaults to self.end).  See _start.
         :return: True if the component matches the time range, False otherwise
         """
+        ## Resolve effective values — callers may pass pre-computed normalised datetimes
+        ## so that self is not mutated during filtering.
+        start = _start if _start is not None else self.start
+        end = _end if _end is not None else self.end
         comp_name = component.name
 
         ## The logic below should correspond neatly with RFC4791 section 9.9
@@ -126,22 +138,29 @@ def _check_range(self, component: Component) -> bool:
 
         ## After the logic above, all rows in the matrix boils down to
         ## this: (we could reduce it even more by defaulting
-        ## self.start and self.end to DATE_MIN_DT etc)
-        if self.start and self.end and comp_end:
-            return self.start < comp_end and self.end > comp_start
-        elif self.end:
-            return self.end > comp_start
-        elif self.start and comp_end:
-            return self.start < comp_end
+        ## start and end to DATE_MIN_DT etc)
+        if start and end and comp_end:
+            return start < comp_end and end > comp_start
+        elif end:
+            return end > comp_start
+        elif start and comp_end:
+            return start < comp_end
         return True
 
-    def _check_completed_filter(self, component: Component) -> bool:
+    def _check_completed_filter(
+        self,
+        component: Component,
+        _include_completed: bool | None = None,
+    ) -> bool:
         """Check if a component should be included based on the include_completed filter.
 
         :param component: A single calendar component
+        :param _include_completed: Effective value (defaults to self.include_completed).  Pass a
+            pre-resolved value from check_component() to avoid mutating self.
         :return: True if the component should be included, False if it should be filtered out
         """
-        if self.include_completed:
+        include_completed = _include_completed if _include_completed is not None else self.include_completed
+        if include_completed:
             return True
 
         ## If include_completed is False, exclude completed/cancelled VTODOs
@@ -372,16 +391,28 @@ def _check_property_filters(self, component: Component, skip_undef: bool = False
 
     ## DISCLAIMER: Mostly AI-generated code, with a touch of human polishing
     ## and bugfixing. Alarms are a bit complex.
-    def _check_alarm_range(self, component: Component) -> bool:
+    def _check_alarm_range(
+        self,
+        component: Component,
+        _alarm_start: datetime | None = None,
+        _alarm_end: datetime | None = None,
+    ) -> bool:
         """Check if a component has alarms that fire within the alarm time range.
 
         Implements RFC 4791 section 9.9 alarm time-range filtering.
 
         :param component: A single calendar component (VEVENT, VTODO, or VJOURNAL)
+        :param _alarm_start: Effective alarm start (defaults to self.alarm_start).  Pass a
+            pre-normalised value from check_component() to avoid mutating self.
+        :param _alarm_end: Effective alarm end (defaults to self.alarm_end).  See _alarm_start.
         :return: True if any alarm fires within the alarm range, False otherwise
         """
         from datetime import timedelta
 
+        ## Resolve effective values — callers may pass pre-computed normalised datetimes
+        alarm_start = _alarm_start if _alarm_start is not None else self.alarm_start
+        alarm_end = _alarm_end if _alarm_end is not None else self.alarm_end
+
         ## Get all VALARM subcomponents
         alarms = [x for x in component.subcomponents if x.name == "VALARM"]
 
@@ -451,27 +482,27 @@ def _check_alarm_range(self, component: Component) -> bool:
                     for i in range(int(repeat_count) + 1):
                         repeat_time = alarm_time + (duration * i)
                         ## Check if this repetition fires within the alarm range
-                        if self.alarm_start and self.alarm_end:
-                            if self.alarm_start <= repeat_time < self.alarm_end:
+                        if alarm_start and alarm_end:
+                            if alarm_start <= repeat_time < alarm_end:
                                 return True
-                        elif self.alarm_start:
-                            if repeat_time >= self.alarm_start:
+                        elif alarm_start:
+                            if repeat_time >= alarm_start:
                                 return True
-                        elif self.alarm_end:
-                            if repeat_time < self.alarm_end:
+                        elif alarm_end:
+                            if repeat_time < alarm_end:
                                 return True
                     ## None of the repetitions matched
                     continue
 
             ## Check if this alarm (first occurrence) fires within the alarm range
-            if self.alarm_start and self.alarm_end:
-                if self.alarm_start <= alarm_time < self.alarm_end:
+            if alarm_start and alarm_end:
+                if alarm_start <= alarm_time < alarm_end:
                     return True
-            elif self.alarm_start:
-                if alarm_time >= self.alarm_start:
+            elif alarm_start:
+                if alarm_time >= alarm_start:
                     return True
-            elif self.alarm_end:
-                if alarm_time < self.alarm_end:
+            elif alarm_end:
+                if alarm_time < alarm_end:
                     return True
 
         return False

src/icalendar_searcher/searcher.py

@@ -348,14 +348,21 @@ def check_component(
             return orig_recurrence_set
 
         ## Ensure timezone is set.  Ensure start and end are datetime objects.
-        for attr in ("start", "end", "alarm_start", "alarm_end"):
-            value = getattr(self, attr)
-            if value:
-                if not isinstance(value, datetime):
-                    logging.warning(
-                        "Date-range searches not well supported yet; use datetime rather than dates"
-                    )
-                setattr(self, attr, _normalize_dt(value))
+        ## Compute normalised copies locally — do NOT mutate self, as check_component()
+        ## must be idempotent and safe to call multiple times on the same Searcher.
+        def _normalise_dt_local(value: datetime | None) -> datetime | None:
+            if not value:
+                return value
+            if not isinstance(value, datetime):
+                logging.warning(
+                    "Date-range searches not well supported yet; use datetime rather than dates"
+                )
+            return _normalize_dt(value)
+
+        _start = _normalise_dt_local(self.start)
+        _end = _normalise_dt_local(self.end)
+        _alarm_start = _normalise_dt_local(self.alarm_start)
+        _alarm_end = _normalise_dt_local(self.alarm_end)
 
         ## recurrence_set is our internal generator/iterator containing
         ## everything that hasn't been filtered out yet (in most
@@ -407,10 +414,11 @@ def check_component(
                 ## filtering out occurrences with properties added by expansion.
                 skip_undef_for_expanded = True
 
-        ## self.include_completed should default to False if todo is explicity set,
-        ## otherwise True
-        if self.include_completed is None:
-            self.include_completed = not self.todo
+        ## include_completed should default to False if todo is explicitly set, otherwise True.
+        ## Compute locally — do NOT mutate self.include_completed so the Searcher stays reusable.
+        _include_completed = self.include_completed
+        if _include_completed is None:
+            _include_completed = not self.todo
 
         ## Component type flags are a bit difficult.  In the CalDAV library,
         ## if all of them are None, everything should be returned.  If only
@@ -421,19 +429,18 @@ def check_component(
         ## correct solution from the start: 1) if any flags are True,
         ## then consider flags set as None as False.  2) if any flags
         ## are still None, then consider those to be True.  3) List
-        ## the flags that are True as acceptable component types:
+        ## the flags that are True as acceptable component types.
+        ## Computed locally — do NOT mutate self.todo / self.event / self.journal.
 
         comptypesl = ("todo", "event", "journal")
         if any(getattr(self, x) for x in comptypesl):
-            for x in comptypesl:
-                if getattr(self, x) is None:
-                    setattr(self, x, False)
+            ## At least one type is explicitly True: treat remaining Nones as False (opt-in mode)
+            _compflags = {x: bool(getattr(self, x)) for x in comptypesl}
         else:
-            for x in comptypesl:
-                if getattr(self, x) is None:
-                    setattr(self, x, True)
+            ## No type is explicitly True: treat Nones as True, but respect explicit Falses (opt-out mode)
+            _compflags = {x: getattr(self, x) is not False for x in comptypesl}
 
-        comptypesu = set([f"V{x.upper()}" for x in comptypesl if getattr(self, x)])
+        comptypesu = set([f"V{x.upper()}" for x in comptypesl if _compflags[x]])
 
         ## if expand_only, expand all comptypes, otherwise only the comptypes specified in the filters
         comptypes_for_expansion = ["VTODO", "VEVENT", "VJOURNAL"] if expand_only else comptypesu
@@ -444,15 +451,15 @@ def check_component(
         if not expand_only:
             ## OPTIMIZATION TODO: If the object was recurring, we should
             ## probably trust recur.between to do the right thing?
-            if not _ignore_rrule_and_time and (self.start or self.end):
-                recurrence_set = (x for x in recurrence_set if self._check_range(x))
+            if not _ignore_rrule_and_time and (_start or _end):
+                recurrence_set = (x for x in recurrence_set if self._check_range(x, _start=_start, _end=_end))
 
             ## This if is just to save some few CPU cycles - skip filtering if it's not needed
-            if not all(getattr(self, x) for x in comptypesl):
+            if not all(_compflags[x] for x in comptypesl):
                 recurrence_set = (x for x in recurrence_set if x.name in comptypesu)
 
             ## Filter based on include_completed setting
-            recurrence_set = (x for x in recurrence_set if self._check_completed_filter(x))
+            recurrence_set = (x for x in recurrence_set if self._check_completed_filter(x, _include_completed=_include_completed))
 
             ## Apply property filters
             if self._property_filters or self._property_operator:
@@ -463,8 +470,8 @@ def check_component(
                 )
 
             ## Apply alarm filters
-            if not _ignore_rrule_and_time and (self.alarm_start or self.alarm_end):
-                recurrence_set = (x for x in recurrence_set if self._check_alarm_range(x))
+            if not _ignore_rrule_and_time and (_alarm_start or _alarm_end):
+                recurrence_set = (x for x in recurrence_set if self._check_alarm_range(x, _alarm_start=_alarm_start, _alarm_end=_alarm_end))
 
         if self.expand:
             ## TODO: fix wrapping, if needed

tests/test_no_mutation.py

@@ -0,0 +1,110 @@
+"""
+Tests that check_component() does not mutate the Searcher object.
+
+A Searcher must be reusable: calling check_component() (or filter()) multiple
+times must produce consistent results and must not change the Searcher's own
+fields as a side effect.
+
+Ref: https://github.com/python-caldav/caldav/issues/650
+"""
+
+from datetime import date, datetime, timezone
+
+from icalendar import Calendar, Todo
+
+from icalendar_searcher import Searcher
+
+
+def _pending_todo(uid: str = "pending") -> Todo:
+    task = Todo()
+    task.add("uid", uid)
+    task.add("summary", "Pending task")
+    task.add("status", "NEEDS-ACTION")
+    return task
+
+
+def _completed_todo(uid: str = "done") -> Todo:
+    task = Todo()
+    task.add("uid", uid)
+    task.add("summary", "Done task")
+    task.add("status", "COMPLETED")
+    task.add("completed", datetime(2000, 1, 2, tzinfo=timezone.utc))
+    return task
+
+
+def test_include_completed_none_not_mutated() -> None:
+    """include_completed=None must remain None after check_component()."""
+    searcher = Searcher(todo=True)
+    assert searcher.include_completed is None
+
+    searcher.check_component(_pending_todo())
+
+    assert searcher.include_completed is None, (
+        "check_component() mutated include_completed from None — "
+        "this breaks reuse of the Searcher object"
+    )
+
+
+def test_include_completed_none_not_mutated_on_completed_todo() -> None:
+    """include_completed=None must remain None even after filtering a completed todo."""
+    searcher = Searcher(todo=True)
+    assert searcher.include_completed is None
+
+    searcher.check_component(_completed_todo())
+
+    assert searcher.include_completed is None, (
+        "check_component() mutated include_completed from None"
+    )
+
+
+def test_component_type_flags_not_mutated() -> None:
+    """todo/event/journal flags that are None must remain None after check_component()."""
+    searcher = Searcher(todo=True)
+    assert searcher.event is None
+    assert searcher.journal is None
+
+    searcher.check_component(_pending_todo())
+
+    assert searcher.event is None, (
+        "check_component() mutated event flag from None"
+    )
+    assert searcher.journal is None, (
+        "check_component() mutated journal flag from None"
+    )
+
+
+def test_all_none_flags_not_mutated() -> None:
+    """When all of todo/event/journal are None, they must remain None after check_component()."""
+    searcher = Searcher()  # all type flags None
+    assert searcher.todo is None
+    assert searcher.event is None
+    assert searcher.journal is None
+
+    cal = Calendar()
+    cal.add_component(_pending_todo())
+    searcher.check_component(cal)
+
+    assert searcher.todo is None, "check_component() mutated todo flag from None"
+    assert searcher.event is None, "check_component() mutated event flag from None"
+    assert searcher.journal is None, "check_component() mutated journal flag from None"
+
+
+def test_start_date_not_mutated_to_datetime() -> None:
+    """start/end given as date objects must not be replaced with datetime after check_component()."""
+    start = date(2020, 1, 1)
+    end = date(2030, 1, 1)
+    searcher = Searcher(todo=True, start=start, end=end)
+    assert type(searcher.start) is date
+    assert type(searcher.end) is date
+
+    task = _pending_todo()
+    task.add("dtstart", datetime(2025, 6, 1, tzinfo=timezone.utc))
+    task.add("due", datetime(2025, 7, 1, tzinfo=timezone.utc))
+    searcher.check_component(task)
+
+    assert type(searcher.start) is date, (
+        f"check_component() replaced start with {searcher.start!r} (type {type(searcher.start).__name__})"
+    )
+    assert type(searcher.end) is date, (
+        f"check_component() replaced end with {searcher.end!r} (type {type(searcher.end).__name__})"
+    )