From 23ef586b7d6b9bf4108fb7967035eabd9252d11d Mon Sep 17 00:00:00 2001 From: Tobias Brox Date: Fri, 13 Nov 2026 17:39:15 +0100 Subject: [PATCH] feat: Search: support sets In https://github.com/pycalendar/icalendar-searcher/pull/27 the "in"-operator is implemented. The CalDAV protocol does not support this operator, so it's needed to fetch everything and do client-side filtering (for small sets, possibly it would make sense to do multiple text-searches ... but it's deemed not to be worth the complexity). This commit doesn't add any extra logic in the caldav library, it only allows the in-operator to be passed down to the icalendar-searcher libray. Prompt: [in the plann repository, after adding an "in" operator to icalendar-searcher for plann's select --priority:] probably caldav library should also be fixed Assisted-By: Claude Opus 5.5 Reviewed-by: Tobias Brox --- caldav/search.py | 17 +++++--- changes/+in-operator.added.md | 1 + tests/test_search.py | 75 +++++++++++++++++++++++++++++++++++ 3 files changed, 87 insertions(+), 6 deletions(-) create mode 100644 changes/+in-operator.added.md diff --git a/caldav/search.py b/caldav/search.py index 11a9d4df..f93e96bb 100644 --- a/caldav/search.py +++ b/caldav/search.py @@ -139,7 +139,8 @@ def _flag_component_type(searcher: "Searcher", flag: str) -> None: ## Whether servers honour negate-condition, or a bare prop-filter, has not ## been probed yet (caldav-server-tester), so search() decides these ## client-side. https://github.com/python-caldav/caldav/issues/568 -_NEGATED_OR_PRESENCE_OPERATORS = ("!=", "!contains", "def") +## "in" (equal to one of several values) has no CalDAV form at all. +_NEGATED_OR_PRESENCE_OPERATORS = ("!=", "!contains", "def", "in") def _collation_str(searcher: "Searcher", property: str) -> str: @@ -497,8 +498,8 @@ def add_property_filter( Special virtual property "category" (singular) is also supported for substring matching within category names :param value: Filter value, should adhere to the type defined in the RFC - :param operator: Comparison operator ("contains", "==", "!contains", - "!=", "def", "undef"; see below). If not + :param operator: Comparison operator ("contains", "==", "in", + "!contains", "!=", "def", "undef"; see below). If not specified, the server decides the matching behavior (usually substring search per RFC). If explicitly set to "contains" and the server doesn't support substring search, client-side @@ -517,17 +518,21 @@ def add_property_filter( * **contains** - substring match (e.g., "rain" matches "Training session" and "Singing in the rain") * **==** - exact match required, enforced client-side + * **in** - equal to one of the values in a collection (a list, a + range ...), e.g. ``PRIORITY`` in ``range(1, 4)``; the property must + be defined. Not for categories. * **!contains** - no substring match; the property must be defined * **!=** (or **<>**) - not an exact match; the property must be defined * **def** - matches if property is defined (value parameter ignored) * **undef** - matches if property is not defined (value parameter ignored) - The negations and ``def`` need icalendar-searcher 1.1.0 or later. + The negations and ``def`` need icalendar-searcher 1.1.0 or later, + ``in`` an icalendar-searcher release with it. search() decides them client-side and leaves them out of the server query, unless ``post_filter=False``; then, as with build_search_xml_query() on its own, they are sent as the - closest CalDAV filter that never excludes a match, and != and - def match any object where the property is defined. + closest CalDAV filter that never excludes a match, and !=, def + and in match any object where the property is defined. **Special handling for categories:** diff --git a/changes/+in-operator.added.md b/changes/+in-operator.added.md new file mode 100644 index 00000000..a025b35c --- /dev/null +++ b/changes/+in-operator.added.md @@ -0,0 +1 @@ +Searches with the new `in` operator of icalendar-searcher (the property equals one of several values) are decided client-side, as CalDAV has no such filter. It needs an icalendar-searcher release with the operator, https://github.com/pycalendar/icalendar-searcher/pull/27 diff --git a/tests/test_search.py b/tests/test_search.py index 55c68ae2..b7cb9fbd 100644 --- a/tests/test_search.py +++ b/tests/test_search.py @@ -1846,6 +1846,20 @@ def test_search_results_populated_after_batch_load(self) -> None: assert len(results) == 1 +def _searcher_has_in_operator() -> bool: + try: + CalDAVSearcher().add_property_filter("SUMMARY", ["x"], operator="in") + except NotImplementedError: + return False + return True + + +## The "in" operator is newer than the oldest icalendar-searcher supported +needs_in_operator = pytest.mark.skipif( + not _searcher_has_in_operator(), reason="icalendar-searcher has no in operator" +) + + class TestNegatedOperators: """The negated and presence operators: ``!=``, ``!contains`` and ``def``. @@ -1986,6 +2000,67 @@ def test_xml_not_equal_is_a_bare_prop_filter(self) -> None: assert b'prop-filter name="SUMMARY"' in xml assert b"text-match" not in xml + @needs_in_operator + @pytest.mark.parametrize( + ("values", "expected"), + [ + (["rain", "Training session"], {"training", "rain"}), + (["rain", "Training"], {"rain"}), + (["Rain"], set()), + ], + ) + @pytest.mark.parametrize( + "supported", [True, False, "search.text"], ids=["all", "none", "no-text-search"] + ) + def test_search_in_filters_client_side( + self, values: list[str], expected: set[str], supported: bool | str + ) -> None: + """``in`` (equal to one of several values) has no CalDAV form either.""" + cal = self._calendar(supported) + searcher = CalDAVSearcher(event=True) + searcher.add_property_filter("SUMMARY", values, operator="in") + results = searcher.search(cal) + uids = {str(r.icalendar_component["UID"]).split("@")[0] for r in results} + assert uids == expected + + @needs_in_operator + @pytest.mark.parametrize( + "supported", [True, False, "search.text"], ids=["all", "none", "no-text-search"] + ) + def test_search_priority_in_range(self, supported: bool | str) -> None: + """The motivating case: PRIORITY in range(1, 4), an integer property.""" + self._events = {"one": "1", "three": "3", "five": "5", "none": None} + cal = self._calendar(supported, prop="PRIORITY") + searcher = CalDAVSearcher(event=True) + searcher.add_property_filter("PRIORITY", range(1, 4), operator="in") + results = searcher.search(cal) + uids = {str(r.icalendar_component["UID"]).split("@")[0] for r in results} + assert uids == {"one", "three"} + + @needs_in_operator + def test_search_in_without_post_filter_sends_bare_prop_filter(self) -> None: + """With post_filter=False the server's answer is trusted, and the + query asks only for the property to be defined: a superset.""" + from lxml import etree + + cal = self._calendar(True) + searcher = CalDAVSearcher(event=True) + searcher.add_property_filter("SUMMARY", ["rain"], operator="in") + results = searcher.search(cal, post_filter=False) + assert len(results) == 3 + for call in cal._request_report_build_resultlist.call_args_list: + body = etree.tostring(call.args[0].xmlelement()) + assert b'prop-filter name="SUMMARY"' in body + assert b"text-match" not in body + + @needs_in_operator + def test_xml_in_is_a_bare_prop_filter(self) -> None: + searcher = CalDAVSearcher(event=True) + searcher.add_property_filter("SUMMARY", ["rain", "Training"], operator="in") + xml = self._xml(searcher) + assert b'prop-filter name="SUMMARY"' in xml + assert b"text-match" not in xml + def test_xml_def_is_a_bare_prop_filter(self) -> None: searcher = CalDAVSearcher(event=True) searcher.add_property_filter("SUMMARY", None, operator="def")