doc

Author: tobixen

README.md

@@ -2,6 +2,12 @@
 
 This library should contain logic for searching, filtering and sorting icalendar data, as well as logic for storing and representing an icalendar search query.
 
+## Audience
+
+* This will be used for the python CalDAV client library, both for boundling search parameters together in one object and for doing client-side filtering when the server does not support the desired search query.
+* This may be useful in any kind of software handling collections of calendar content and needing to do filtering or searches on it.
+* This may also be useful by calendar server developers.
+
 ## Status as of v0.x.x
 
 This library is full of stubbed implementations as for now.  The maintainer will urgently prioritize the bare minimum needed for refactoring the search functionality in the CalDAV library.  Version 1.0 may still contain some stubs, but should contain a relatively well-defined feature set.
@@ -10,6 +16,10 @@ This library is full of stubbed implementations as for now.  The maintainer will
 
 This is a spin-off from the python caldav project, started by Tobias Brox in 2025-11, the maintainer of the Python CalDAV client library at that time, in collaboration with the main contributors of the icalendar library.
 
+## Performance
+
+In the early versions, the filter method will take the calendar contents one by one and check if it matches or not.  This will work out well enough for small calendar sets.  If lots of searches are to be done on fairly static data (like what typically may happen at the server side in a calendaring system), then it would be an idea to add indexes.
+
 ## License
 
 As for now I'm releasing this under the GNU Affero General Public License v.3.0.  If you find this too restrictive or if this causes license compatibility issues for you, please get in touch with me and I will consider to fix some dual licensing, like it's done with the python CalDAV library.

src/icalendar_searcher/__init__.py

@@ -20,6 +20,10 @@ class Searcher:
     * Allow to build up a calendar search query.
     * Help filterering or sorting a list of calendar components
 
+    Primarily VJOURNAL, VTODO and VEVENT Calendar components are
+    intended to be supported, but we should consider if there is any
+    point supporting FREEBUSY as well.
+
     This class is a bit stubbed as of 2025-11, many things not working
     yet.  This class was split out from the CalDAV library and is
     intended for generic search logic not related to the CalDAV
@@ -48,7 +52,10 @@ class Searcher:
     ``start`` and ``end`` is giving a time range.  The CalDAV logic
     will be honored, see RFC4791, section 9.9 for very clear
     definitions of what should be returned and what should be filtered
-    away.
+    away.  Timestamps should ideally be with a time zone, if not given
+    the local time zone will be assumed.  All-day events may be tricky
+    to get correct when timestamps are given and calendar data covers
+    multiple time zones.
 
     ``alarm_start`` and ``alarm_end`` is similar for alarm searching
 
@@ -86,6 +93,10 @@ class Searcher:
     robust enough to handle multiple independent components embedded
     in a single Calendar.
 
+    Other ideas that one may consider implementing:
+    * limit, offset.
+    * fuzzy matching
+
     """
 
     todo: bool = None
@@ -153,8 +164,14 @@ def check_component(
         self, component: Union["Calendar", "CalendarObjectResource"]
     ) -> Union["Calendar", "CalendarObjectResource"]:
         """
-        Checks if a component (or a recurrence set) matches the filters.
-        Expands a recurring component if needed.  Returns the component.
+        Checks if a component (or recurrence set) matches the filters.  If the component parameter is a calendar containing several independent components, an Exception may be raised.
+
+        * On a match, the component will be returned, otherwise ``None``.
+        * If a time specification is given and the component given is a
+          recurring component, it will be expanded internally to check if
+          it matches the given time specification.
+        * If ``self.expand`` is set, the expanded  recurrence set matching
+          the time specification will be returned.
         """
         raise NotImplementedError()