idZddlmZddlZddlmZddlmZmZddl m Z ddl m Z m Z ddl Z ddlmZmZmZdd l mZmZd d lmZmZd d lmZd d lmZmZmZe rddlmZeGddeZdS)zBMain Searcher class for icalendar component filtering and sorting.) annotationsN)Iterable) dataclassfield)datetime) TYPE_CHECKINGAny)Calendar ComponentTimezone) DATE_MAX_DT DATE_MIN_DT) Collationget_sort_key_function) FilterMixin)_iterable_or_false _normalize_dt types_factory)CalendarObjectResourcec:eZdZUdZdZded<dZded<dZded<dZded<dZ ded <dZ ded <dZ ded <dZ ded <d Z ded<eeZded<eeZded<eeZded<eeZded<eeZded<eeZded<eeZded<eeZded<eeZded< dGdHd)Z dIdJd+Z dKdLd1Z dMdNd5ZdOd8ZdPd:ZdOd;Z dQd>Z!dRd@Z"dSdBZ#dTdFZ$dS)USearcheraThis class will: * 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 protocol. As of 2025-11, the first priority is to make the bare minimum of support needed for supporting refactorings of the CalDAV library. Long-term plan is to also allow for adding subqueries that can be bound together with logical AND or OR. (Will AND every be needed? After all, add different criterias to one Searcher object, and all of them has to match) Properties (like SUMMARY, CATEGORIES, etc) are not meant to be sent through the constructor, use the :func:`icalendar_searcher.Searcher.add_property_filter` method. Same goes with sort keys, they can be added through the `func:icalendar_searcher.Searcher.add_sort_key` method. The ``todo``, ``event`` and ``journal`` parameters are booleans for filtering the component type. If i.e. both todo and journal is set to True, everything but events should be returned. If none is given (the default), all objects should be returned. If ``todo`` is given ``include_completed`` defaults to False, which means completed tasks will be tfiltered out. ``start`` and ``end`` is giving a time range. RFC4791, section 9.9 gives a very clear and sane definitions of what should be returned when searching a CalDAV calendar for contents over a time span. While this package is not related to CalDAV pper se, the logic seems sane, so we will stick to that one. 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 If ``expand`` is set to True, recurring objects will be expanded into reccurence objects for the time period specified by ``start`` and ``end``. Generators are used, so ``expand`` may even work without ``start`` and ``end`` set if care is taken (i.e. converting the generator to a list may cause problems) Unless you now what you are doing, ``expand`` should probably be set to true, and start and end should be given and shouldn't be too far away from each other. Currently the sorting algorithm will blow up if the expand yields infinite number of events. It may probably blow up even if expand yields millions of events. Be careful. For filtering an icalendar instance ``mycal`` containing a VCALENDAR with multiple independent events, one may do ``searcher.filter([mycal])``. The CalDAV library contains a CalDAVSearcher class inheritating this class and including a ``.search(caldav_calendar)`` method. The idea is that it may be done in the same way also for searching other calendars or calendar-like systems using other protocols. The filtering and sorting methods should accept both wrapper objects (for the CalDAV library, those are called CalendarObjectResource and contains extra information like the URL and the client object) and ``icalendar.Calendar`` objects from the icalendar library. Wrapper objects should have the ``icalendar.Calendar`` object available through a property ``icalendar_instance``. Even for methods expecting a simple component, a ``Calendar`` should be given. This is of imporantance for recurrences with exceptions (like, "daily meeting is held at 10:00, except today the meeting is postponed until 12:00" may be represented through a calendar with two subcomponents) Methods expecting multiple components will always expect a list of calendars (CalDAV-style) - but the algorithms should also be robust enough to handle multiple independent components embedded in a single Calendar. Other ideas that one may consider implementing: * limit, offset. * fuzzy matching Nbooltodoeventjournalrstartend alarm_start alarm_endinclude_completedFexpand)default_factorylist _sort_keysdict_sort_collation _sort_locale_sort_case_sensitive_property_filters_property_operator_property_collation_property_locale_property_case_sensitivecontainsTkeystrvaluer operatorcase_sensitive collationCollation | Nonelocale str | NonereturnNonec<|}|dvrtd|d|dkr|dkrdn|}|dkrPt|tr;t j|}||||j|<n6|dkr ||j|<n%t j|||j|<||j|<| ||j |<||j |<||j |<dStj |j |<d|j |<||j |<dS)u Adds a filter for some specific iCalendar property. Examples of valid iCalendar properties: SUMMARY, LOCATION, DESCRIPTION, DTSTART, STATUS, CLASS, etc :param key: must be an icalendar property, i.e. SUMMARY Special virtual property "category" (singular) is also supported for substring matching within category names :param value: should adhere to the type defined in the RFC :param operator: Comparision operator ("contains", "==", etc) :param case_sensitive: If False, text comparisons are case-insensitive. :param collation: Advanced collation strategy for text comparison. If specified, overrides case_sensitive parameter. Only needed by power users for locale-aware collation. :param locale: Locale string (e.g., "de_DE") for locale-aware collation. Only used with collation=Collation.LOCALE. The case_sensitive parameter only applies to text properties. The default has been made for case sensitive searches. This is contrary to the CalDAV standard, where case insensitive searches are considered the default, but it's in accordance with the CalDAV library, where case sensitive searches has been the default. **Special handling for categories:** - **"categories"** (plural): Exact category name matching - "contains": subset check (all filter categories must be in component) - "==": exact set equality (same categories, order doesn't matter) - Commas in filter values split into multiple categories - **"category"** (singular): Substring matching within category names - "contains": substring match (e.g., "out" matches "outdoor") - "==": exact match to at least one category name - Commas in filter values treated as literal characters For the operator, the following is (planned to be) supported: * contains - will do a substring match (A search for "summary" "contains" "rain" will return both events with summary "Training session" and "Singing in the rain") * == - exact match is required * ~ - regexp match * <, >, <=, >= - comparision * <> or != - inqueality, both supported * def, undef - will match if the property is (not) defined. value can be set to None, the value will be ignored. Examples: # Case-insensitive search (simple API) searcher.add_property_filter("SUMMARY", "meeting", case_sensitive=False) # Case-sensitive search (default) searcher.add_property_filter("SUMMARY", "Meeting") # Advanced: locale-aware collation (requires PyICU) searcher.add_property_filter("SUMMARY", "Müller", collation=Collation.LOCALE, locale="de_DE") )r/undefz==z The operator z is not supported yet.r<category categoriesN)lowerNotImplementedError isinstancer1r for_property from_icalr*r+r,r-r.rSIMPLE) selfr0r2r3r4r5r7 property_keyfacts V/root/projects/butler/venv/lib/python3.11/site-packages/icalendar_searcher/searcher.pyadd_property_filterzSearcher.add_property_filters^fiikk 6 6 6%&Vh&V&V&VWW W w  +.*+<+<<<#Ll""z%'='="%1,??.2d4>>%3H3H.I.I&s++ ""/4&s++.Vm.H.V.VW\.].]&s+'/$  ,5D $S ))/D !# &1?D )# . . .-6,z+Searcher.check_component..s-44AwtQ444444rJc^g|])}t|d|*S)V)r\upperr]s rH z,Searcher.check_component..s6RRRaqAQAQR/aggii//RRRrJ)VTODOVEVENTVJOURNALc3FK|]}||VdSrZ) _check_ranger]s rHr`z+Searcher.check_component..s7!T!Tt?P?PQR?S?S!T!!T!T!T!T!T!TrJc38K|]}t|VdSrZr[r]s rHr`z+Searcher.check_component..s-<.s/!T!Tqv?S?S!?S?S?S?S!T!TrJc3FK|]}||VdSrZ)_check_completed_filterr]s rHr`z+Searcher.check_component..s7[[A4;W;WXY;Z;Z[a[[[[[[rJc3JK|]}||VdS)) skip_undefN)_check_property_filters)r^r_rEskip_undef_for_expandeds rHr`z+Searcher.check_component..sQ""33ABY3ZZ"""""""rJc3FK|]}||VdSrZ)_check_alarm_ranger]s rHr`z+Searcher.check_component..s7!Z!Zt?V?VWX?Y?Y!Z!!Z!Z!Z!Z!Z!ZrJ)!_validate_and_normalize_componentr"r\rArloggingwarningsetattrrcheck_componentr!ranyset_expand_recurrencesrrallr*r+rr rnext)rErRrTrUorig_recurrence_setattrr2recurrence_setfirstbase_element_match comptypeslr_comptypes_for_expansionrmrss` @@rHrzzSearcher.check_component2stL#DDYOO  't{ '& &A : :DD$''E :!%22OddM%$8$8999-:#(#A& /w%//8N/!%!5!5eTX!5!Y!Y % /!/!3 +/'  ! ))-]D "2 4444444 4 4 + , ,4##+D!U+++ ,  + +4##+D!T***RRRR:RRRSS FQ"`"A"A"A"AV`% _'U*:*:!55nF]^^N [* Utz UTX U!T!T!T!T^!T!T!T<<<<<<<<< U!T!T!T!T^!T!T!T\[[[[[[N% )@ """""+"""* [t/? [4> [!Z!Z!Z!Z^!Z!Z!Z ; %n55 5ND)) **trJ componentslist[Calendar | Component]split_expandedc.g}|D]}||}|rt|}|s-|rt|dkr|D]}t|trt }t|t rY|D] \} } | || < d|jD} | D]&} ddlm } | | | 'ddlm } | | || |ΐt|t rt }|D] \} } | || < d|jD} | D]&} ddlm } | | | '|D];}t|ts$ddlm } | | |<| ||D]&}ddlm } | | |'|S)aFilter components according to the search criteria, optionally expanding recurrences. This method does not modify the input list. It returns a new list with filtered components. :param components: List of Calendar or Component objects to filter :param split_expanded: If True and recurrences are expanded, return each recurrence as a separate Calendar object. If False, all matching recurrences from a single input will be returned in one Calendar. :return: New list containing only components that match the filter criteria Examples: searcher = Searcher(event=True, start=datetime(2025, 1, 1)) searcher.add_property_filter("SUMMARY", "meeting", operator="contains") filtered = searcher.filter(calendars) # Returns matching calendars # With split_expanded=True, each recurrence becomes a separate Calendar searcher.expand = True split_results = searcher.filter(calendars, split_expanded=True) rc<g|]}t|t|SrAr r^tzs rHrdz#Searcher.filter..s9)))') SUW_H`H`) ")))rJrdeepcopyc<g|]}t|t|Srrrs rHrdz#Searcher.filter..'s8%%%#%JrS[D\D\%%%%rJ) rzr$lenrAr r items subcomponentscopyr add_componentrP)rErrresultsrRmatched matched_listcompnew_calr0r2 timezonesrrs rHfilterzSearcher.filters./1#E ;E ;I**955G@ ;#G}} #!;;c,&7&7!&;&;!-00%dH55%$#+**&i:: D.7oo.?.?55 U/4 ))-6-D)))I'0DD 9 9 9 9 9 9 ' 5 5hhrll C C C C211111--hhtnn===w////308")X66;"****3//*;*;11JC+0GCLL%%)2)@%%% #,@@B555555#11((2,,????%1FFD#-dH#=#=F 9 9 9 9 9 9 ' 5 5hhtnn E E Ew////%1;;D555555#NN88D>>::::rJcalendarr cddlm}d|jD}d|jD}g}|D]?}||}|r&t |}|r||@|sdSt } |D] \} } | | | < |D] } | || !|D]5}t|ts| ||6| S)aFilter subcomponents within a Calendar object according to search criteria. This method does not modify the input Calendar. It returns a new Calendar containing only the subcomponents that match the filter criteria. :param calendar: Calendar object containing multiple subcomponents to filter :return: New Calendar object with only matching subcomponents, or None if no matches Examples: searcher = Searcher(event=True, start=datetime(2025, 1, 1)) searcher.add_property_filter("SUMMARY", "meeting", operator="contains") filtered_cal = searcher.filter_calendar(calendar) # Returns Calendar with matching events rrc<g|]}t|t|Srrr^rs rHrdz,Searcher.filter_calendar..Qs([[[d 4QY@Z@Z[T[[[rJc<g|]}t|t|Srrrs rHrdz,Searcher.filter_calendar..Rs7   :dH;U;U    rJN) rrrrzr$extendr rrrAr ) rErrrother_componentsmatching_componentsrrr new_calendarr0r2rs rHfilter_calendarzSearcher.filter_calendar@sg "!!!!!\[h&<[[[   %3    !$ = =D**400G =#G}} ='..|<<<# 4 zz #..** & &JC %L   5 5B  & &xx|| 4 4 4 4( ; ;DdH-- ;**88D>>:::rJ(list[Component | CalendarObjectResource]cd|jrt||jS|S)aSort calendar objects according to configured sort keys. This method does not modify the input list. It returns a new sorted list. (the idea with this is that the input may be a generator) :param components: List of Calendar or CalendarObjectResource objects to sort :return: New sorted list Examples: searcher = Searcher() searcher.add_sort_key("DTSTART") sorted_events = searcher.sort(events) # Returns new sorted list r0)r%sorted sorting_valuer)rErs rHsortz Searcher.sortvs4" ? %*$*<=== =??$$ $rJc |jsddlm}||Sddlm  fd|jD} fd|jD}t ||j}ddlm}t}| D] \}}|||< |D] } | || !|D] } | || !|S)aHSort subcomponents within a Calendar object according to configured sort keys. This method does not modify the input Calendar. It returns a new Calendar with sorted subcomponents (excluding VTIMEZONE components). :param calendar: Calendar object containing multiple subcomponents to sort :return: New Calendar object with sorted subcomponents Examples: searcher = Searcher() searcher.add_sort_key("DTSTART") sorted_cal = searcher.sort_calendar(calendar) # Returns new Calendar with sorted events rr)r c4g|]}t||SrrAr^rr s rHrdz*Searcher.sort_calendar..s)[[[d 4QY@Z@Z[T[[[rJc4g|]}t||Srrrs rHrdz*Searcher.sort_calendar..s8   :dH;U;U    rJr) r%rr icalendarr rrrr rr) rErrrrsorted_componentsrr0r2rrr s @rH sort_calendarzSearcher.sort_calendarsU & % % % % % %8H%% % '&&&&&[[[[h&<[[[     %3    ##39KLLL "!!!!!zz #..** & &JC %L   5 5B  & &xx|| 4 4 4 4& 7 7D  & &xx~~ 6 6 6 6rJ"Component | CalendarObjectResourcetuplec g}||}t|tr!d|jD}t |}n|}ddddddd|jd d |voG|d jd tj d k d |voG|d jd tj d kd }|j D]\}}|dkr|j }n| |d}|*| | |d Vt|to||jv} t!|dr|j}t!|dr|d }t|t"r.t%|}dd|D}| rst|tr^|j|} |j |} |j |d} t-| | | } | |}|rbt|tt.frCt|tr|}t/d|D}n| }| ||S)zReturns a sortable value from the component, based on the sort keys The component may be an icalendar.Calendar, an icalendar.Component (i.e. icalendar.Event) or an caldav.CalendarObjectResource (i.e. caldav.Event). c3DK|]}t|t|VdSrZrr^r_s rHr`z)Searcher.sorting_value..s3 c cq:VWYaKbKb c c c c c c crJz 2050-01-01z 1970-01-01rz NEEDS-ACTIONFINAL TENTATIVE)rergrfduez%F%H%M%Sdtstart)rrprioritystatusr=rMrNr>Ndtstrftime,c,g|]}t|Sr)r1rs rHrdz*Searcher.sorting_value.. s4441A444rJTc3 K|] }|dz V dS)Nr)r^bs rHr`z)Searcher.sorting_value..s&66QD666666rJ)_unwraprAr rrrlrrrnowr%r>getrPr1r'hasattrr$rjoinr(r)rbytesencode)rErRretnot_tz_componentsrdefaultssort_keyreversevalis_text_propertyr5r7r4 sort_key_fns rHrzSearcher.sorting_values LL++ i * *  c cI,C c c c )**DDD #'#%i   ^KN++J77(,..:Q:QR\:]:]] T!bO&// ;;hlnn>U>UV`>a>aa'  ,"&5 5  Hg<''ohhx..{ 8<<"55666 *#s33XDDX8X sD!! fsJ'' /ll:..#t$$ 6Skkhh4444455  'JsC$8$8 ' 0: *..x88!%!:!>!>x!N!N3I~vVV !k#&& cC<00!#s+++!jjll66#66666CC$C JJsOOOO rJ!Calendar | CalendarObjectResourcec |j}n#t$rYnwxYwt|tr:t|ts%t }|||}|S)z To support the caldav library (and possibly other libraries where the icalendar component is wrapped) )icalendar_instanceAttributeErrorrAr r r)rErRcals rHrzSearcher._unwrap s|  !4II    D  i + + Jy(4S4S **C   i ( ( (Is  list[Component]c||}d|jD}t|std|dt|dkred|dvr d|dvsBt d|ddDr!t d |ddDrtd t fd |Drtd |S) a8This method serves two purposes: 1) Be liberal in what "component" it accepts and return something well-defined. For instance, coponent may be a wrapped object (caldav.Event), an icalendar.Calendar or an icalendar.Event. The return value will always be a list of icalendar components (i.e. Event), and Timezone components will be removed. 2) Do some verification that the "component" is as expected and raise a ValueError if not. The "component" should either be one single component or a recurrence set. A recurrence set should conform to those rules: 2.1) All components in the recurrence set should have the same UID 2.2) First element ("master") of the recurrence set may have the RRULE property set 2.3) Any following elements of a recurrence set ("exception recurrences") should have the RECURRENCE-ID property set. 2.4) (there are more properties that may only be set in the master or only in the recurrences, but currently we don't do more checking than this) As for now, we do not support component to be a generator or a list, and things will blow up if component.subcomponents is a generator yielding infinite or too many subcomponents. c<g|]}t|t|Srrrs rHrdz>Searcher._validate_and_normalize_component..Ss'XXXA 1h@W@WXaXXXrJzEmpty component?rrrXz RECURRENCE-IDc3K|]}d|vV dS)z recurrence-idNrrs rHr`z=Searcher._validate_and_normalize_component..`s'HHA?a/HHHHHHrJNc3K|]}d|vV dS)rXNrrs rHr`z=Searcher._validate_and_normalize_component..as&<<w!|<<<<<.ks5AAQ%E%L(@(@q(@(@(@(@AArJzqInput parameter component is supposed to contain a single component or a recurrence set - but multiple UIDs found)rrr ValueErrorr~r{)rErRrrs @rHrvz*Searcher._validate_and_normalize_component/s7FLL++ XX!8XXX : 1/00 01  z??Q   1 --/TU2V2VHHABBHHHHH3W<rsiHH""""""$$$$$$((((((((%%%%%%%%3333333333::::::::77777777 CCCCCCCCCCEDDDDDD o )o )o )o )o ){o )o ) o )o )o )rJ