Refactoring search and filters

CHANGELOG.md

@@ -22,11 +22,27 @@ I'm still working on "compatibility hints".  Unfortunately, documentation is sti
 * Use `features: nextcloud` and `url: my.nextcloud.provider.eu` instead of `url: https://my.nextcloud.provider.eu/remote.php/dav`
 * The library will work around some known issues dependent on what feature-set it's given.
 
+Searching may now be done by creating a `caldav.CalDAVSearcher` object and do a `searcher.search(cal)` instead of doing `cal.search(...)`.  However, there are no plans to deprecate the latter method.  Major refactoring work has been done here, and some of the logic has been moved to a new package icalendar-searcher.
+
+## Breaking Changes
+
+Some code has been split out into a new package - `icalendar-searcher`.  This does not affect compatibility, hence it's not needed to bump the major version number, but if you manage the dependencies manually it may still cause things to break.
+
+## Deprecations
+
+* `Event.expand_rrule` will be removed in some future release, unless someone protests.
+* `Event.split_expanded` too.  Both of them were used internally, now it's not.  It's dead code, most lkely nobody and nothing is using them.
+
+## Changed
+
+* Major refactoring!  Some of the logic has been pushed out of the CalDAV package and into a new package, icalendar-searcher.  New logic for doing client-side filtering of search results have also been added to that package.
+
 ## Added
 
 * The client connection parameter `features` may now simply be a string label referencing a well-known server or cloud solution - like `features: posteo`.  https://github.com/python-caldav/caldav/pull/561
 * The client connection parameter `url` is no longer needed when referencing a well-known cloud solution. https://github.com/python-caldav/caldav/pull/561
 * The client connection parameter `url` may contain just the domain name (without any slashes) and the URL will be constructed, if referencing a well-known caldav server implementation. https://github.com/python-caldav/caldav/pull/561
+* New interface for searches.  `mysearcher = caldav.CalDAVSearcher(...) ; mysearcher.add_property_filter(...) ; mysearcher.search(calendar)`.  May be useful for complicated searches.
 
 ## [2.1.2] - [2025-11-08]
 

CONTACT.md

@@ -0,0 +1,3 @@
+Reach out through GitHub issues or email caldav@plann.no.  If you feel ignored, be aware that messages sometimes are drowned in spam or forgotten about because I had more urgent issues to handle.  Urgent issues may be escalated by reaching out through +47-91700050 or @tobixen on different alternative communication services.  Please keep in mind that things like providing food to the table for himself and the family typially will have a higher priority than fiddling with the calendaring projects for free on a hobby basis.
+
+See also the contacts document in the documentation.

CONTRIBUTING.md

@@ -2,6 +2,10 @@
 
 Contributions are mostly welcome.  If the length of this text scares you, then I'd rather want you to skip reading and just produce a pull-request in GitHub.
 
+## GitHub
+
+The official guidelines currently involves contributors to have a GitHub account - but this is not a requirement!  If you for some reason or another don't want to use GitHub, then that's fine.  Reach out by email, IRC, matrix, signal, deltachat, telegram or whatnot.
+
 ## Considerations
 
 * Contributions that break backward compatibility will (generally) not be accepted

SECURITY.md

@@ -0,0 +1,44 @@
+# Security policy
+
+Issues should be fixed ASAP, and information on any security issue should be published as soon as it's fixed. Use the GitHub issue tracker or check up [CONTACT](CONTACT.md) or even the [CODE OF CONDUCT](CODE_OF_CONDUCT) file to get in touch with the maintainer.
+
+There is no "LTS"-releases of the CalDAV package, but the maintainer will always consider backporting security fixes if it's deemed relevant.  The maintainer is doing most of the maintenance on hobby-basis and may have other things in life preventing him from dealing with issues on the go, so no guarantees are given.
+
+All contributions are carefully reviewed by the maintainer, and all releases are carefully tested and tagged with a PGP-signed commit.
+
+# Known security issues and risks
+
+## DDoS/OOM risk
+
+The package offers both client-side and server-side expansion of recurring events and tasks.  It currently does not offer expansion for open-ended date searches - but with a large enough timespan and a frequent enough RRULE, there may be millions of recurrences returned.  Those recurrences are returned as a generator, so things will not break down immediately.  However, there is no guaranteed sort order of the recurrences ... and once you add sorting parameters to the search, bad things may happen.
+
+## Bugs causing weird things happening
+
+Weird things may happen due to bugs both on in the CalDAV package, on your side and on the server side.  Here are some weird experiences with Zimbra:
+
+* I have experiences that cancelling participation in an event caused the event to be cancelled for all participants (even if the person deciding to not go to the event was not an organizer and should have no permissions to edit the event).  Clearly a server-side issue.
+* I once tried to restore from backup and push ten years of ical code to the calendar server.  The calendar server responded by re-inviting people to the meetings we had ten years ago.  I'm inclined to call that also a server side bug.
+* Many other things may happen.
+
+## Malicious usage
+
+Beware of risks and exposure when creating applications:
+
+* Your code may handle username and password, be careful not to expose such credentials.  Even the URL to the calendar server and/or calendar may be something people want to keep private.
+* Consider that calendar events and such is personal data, which deserves protection.  In the EU with the GDPR, such protection is even mandated by law.
+* If you allow arbitrary people to create calendar content to be saved to a server, there may be some risks involved:
+  * Depending on the server implementation, it may be possible to use the caldav library for sending spam emails.
+  * Be aware of DoS-attacks: By storing too much / too big / specially crafted icalendar data, the server and/or client may crash or consume all available resources.
+  * If allowing anonymous parties to save and retrieve data from your server, you may end up with responsibility for spreading illicit information.  This may include things like child porn.  Political or religious propaganda may be legitimate and legal in some countries, but may involve death penalty in other countries.  Your calendar server may also be used for coordinating criminal activity.
+* If you allow arbitrary people to fetch calendar content from the server, there may also be some risks involved - in particular, a DoS-attack by requesting a large time span of expanded events.
+
+## Malicious code
+
+All code contributions are carefully reviewed by Tobias Brox.  Version tags are signed with PGP.  Of course there is always a risk that someone takes over my PGP key and github access (It's hard to be immune against a  [5$ wrench attack](https://xkcd.com/538/)).  The original owner of the repository is still alive and may take over the project again should something happen to me.  I would anyway encourage using AI to do risk assessments.
+
+The library comes with a number of dependencies, one may need to evaluate the security of those too.  The pyproject contains the current list.  Some notes:
+
+* niquests is an optional dependency - you may replace it with requests if you don't trust niquests
+* recurring-ical-events and icalendar both has the same maintainer (Nicco Kunzmann).  He is considered trustworthy.
+* Tobias now has a policy of moving code not related to CalDAV into separate packages.  Packages under the `python-caldav` ownership on GitHub should be considered to be of the same quality and security level as the CalDAV library.
+* No security review have been done of the other dependencies.

caldav/__init__.py

@@ -11,6 +11,7 @@
         "You need to install the `build` package and do a `python -m build` to get caldav.__version__ set correctly"
     )
 from .davclient import DAVClient
+from .search import CalDAVSearcher
 
 ## TODO: this should go away in some future version of the library.
 from .objects import *

caldav/calendarobjectresource.py

@@ -176,20 +176,22 @@ def add_organizer(self) -> None:
         self.icalendar_component.add("organizer", principal.get_vcal_address())
 
     def split_expanded(self) -> List[Self]:
-        """This is used internally for processing search results.
+        """This was used internally for processing search results.
         Library users probably don't need to care about this one.
 
-        In the CalDAV protocol, a VCALENDAR object returned from the
-        server may contain only one event/task/journal - but if the object is
-        recurrent, it may contain several recurrences.  This method
-        will split the recurrences into several objects.
+        The logic is now handled directly in the search method.
 
-        It's meant to be used for expanded data, where each component
-        is a recurrence, and where the recurrence set is complete for
-        some given time range.  However, it will also work on a
-        non-expanded object, containing the "master" component first
-        followed by "special" recurrences.
+        This method is probably used by nobody and nothing, but
+        it can't be removed easily as it's exposed as part of the
+        public API
         """
+
+        warnings.warn(
+            "obj.split_expanded is likely to be removed in a future version of caldav.  Feel free to protest if you need it",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         i = self.icalendar_instance.subcomponents
         tz_ = [x for x in i if isinstance(x, icalendar.Timezone)]
         ntz = [x for x in i if not isinstance(x, icalendar.Timezone)]
@@ -223,6 +225,17 @@ def expand_rrule(
         :param end: datetime
 
         """
+        ## TODO: this has been *copied* over to the icalendar-searcher package.
+        ## This code was previously used internally by the search.
+        ## By now it's probably dead code, used by nothing and nobody.
+        ## Since it's exposed as part of the API, I cannot delete it, but I can
+        ## deprecate it.
+        warnings.warn(
+            "obj.expand_rrule is likely to be removed in a future version of caldav.  Feel free to protest if you need it",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         import recurring_ical_events
 
         recurrings = recurring_ical_events.of(
@@ -452,6 +465,7 @@ def _get_icalendar_component(self, assert_one=False):
         self.load(only_if_unloaded=True)
         if not self.icalendar_instance:
             return None
+        ## PERFORMANCE TODO: no point creating a big list here
         ret = [
             x
             for x in self.icalendar_instance.subcomponents