{"id":9045,"library":"icalendar-searcher","title":"iCalendar Searcher","description":"icalendar-searcher is a Python library designed for powerful searching, filtering, and sorting of iCalendar components using a SQL-like Domain Specific Language (DSL). It simplifies interaction with `.ics` data, offering functionalities like expanding recurring events and complex property queries. The current stable version is 1.0.5, with an active development pace characterized by frequent patch and minor releases.","status":"active","version":"1.0.5","language":"en","source_language":"en","source_url":"https://github.com/python-caldav/icalendar-searcher","tags":["icalendar","calendar","search","filter","ics","caldav"],"install":[{"cmd":"pip install icalendar-searcher","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for parsing and manipulating iCalendar data.","package":"icalendar"},{"reason":"Required for timezone handling within iCalendar components.","package":"pytz"}],"imports":[{"symbol":"IcalendarSearcher","correct":"from icalendar_searcher import IcalendarSearcher"},{"symbol":"QueryBuilder","correct":"from icalendar_searcher import QueryBuilder"}],"quickstart":{"code":"from icalendar_searcher import IcalendarSearcher, QueryBuilder\n\nics_data = \"\"\"\nBEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//Example Corp//NONSGML Event Generator//EN\nBEGIN:VEVENT\nUID:19970610T172345Z-AF23B2@example.com\nDTSTAMP:19970610T172345Z\nDTSTART:19970714T170000Z\nDTEND:19970715T035959Z\nSUMMARY:Bastille Day Party\nDESCRIPTION:Party to celebrate Bastille Day.\nLOCATION:Paris, France\nEND:VEVENT\nBEGIN:VEVENT\nUID:19980610T172345Z-AF23C3@example.com\nDTSTAMP:19980610T172345Z\nDTSTART:19980720T100000Z\nDTEND:19980720T110000Z\nSUMMARY:Meeting with client\nEND:VEVENT\nEND:VCALENDAR\n\"\"\"\n\nsearcher = IcalendarSearcher(ics_data)\n\n# Example 1: Find events starting after a specific date\nquery_future = QueryBuilder().filter(\"DTSTART >= 1997-07-15T00:00:00Z\").build()\nresults_future = searcher.search(query_future)\nprint(\"\\nEvents starting after July 15, 1997:\")\nfor component in results_future:\n    print(f\"- {component.get('SUMMARY')}\")\n\n# Example 2: Filter by property value (case-insensitive summary containing 'party')\nquery_party = QueryBuilder().filter(\"SUMMARY ~ 'party'\").build()\nresults_party = searcher.search(query_party)\nprint(\"\\nEvents with 'party' in summary:\")\nfor component in results_party:\n    print(f\"- {component.get('SUMMARY')}\")\n\n# Example 3: Get all components\nall_results = searcher.search()\nprint(\"\\nAll events:\")\nfor component in all_results:\n    print(f\"- {component.get('SUMMARY')}\")","lang":"python","description":"Initialize an `IcalendarSearcher` with iCalendar data and use `QueryBuilder` to construct SQL-like filters for searching. The `search()` method returns an iterator of `icalendar.cal.Component` objects."},"warnings":[{"fix":"Remove the `ignore_exceptions` parameter from your `IcalendarSearcher` instantiation. Exception handling now needs to be managed externally.","message":"The `ignore_exceptions` parameter was removed from the `IcalendarSearcher` constructor. It is no longer supported.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Instead of calling `get_calendars()`, use `search()` directly. If you need to iterate over top-level calendars, you might need to implement custom logic.","message":"The method `IcalendarSearcher.get_calendars()` was removed. `IcalendarSearcher.search()` now directly returns an iterator of `icalendar.cal.Component` objects.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Pass `expand_recurring_events=True/False` directly to `search()` instead of `IcalendarSearcher.__init__()`.","message":"The `expand_recurring_events` parameter was moved from the `IcalendarSearcher` constructor to the `IcalendarSearcher.search()` method.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Iterate directly over the result of `search()` instead of expecting a `QueryResult` object. Access `icalendar.cal.Component` methods directly on each item.","message":"The `search()` method now returns an iterator of `icalendar.cal.Component` objects directly, and the `QueryResult` object was removed.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Remove `ignore_exceptions` from your `IcalendarSearcher` instantiation. If you need custom exception handling, implement it outside the searcher.","cause":"Using the `ignore_exceptions` parameter in the `IcalendarSearcher` constructor, which was removed in version 1.0.0.","error":"TypeError: IcalendarSearcher.__init__() got an unexpected keyword argument 'ignore_exceptions'"},{"fix":"Use the `search()` method directly, which now returns an iterator of `icalendar.cal.Component` objects. The concept of `get_calendars()` is no longer directly exposed.","cause":"Attempting to call the `get_calendars()` method, which was removed in version 1.0.0.","error":"AttributeError: 'IcalendarSearcher' object has no attribute 'get_calendars'"},{"fix":"Pass `expand_recurring_events=True` (or `False`) directly to the `search()` method, e.g., `searcher.search(query, expand_recurring_events=True)`.","cause":"Passing `expand_recurring_events` to the `IcalendarSearcher` constructor, but it was moved to the `search()` method in version 1.0.0.","error":"TypeError: IcalendarSearcher.__init__() got an unexpected keyword argument 'expand_recurring_events'"},{"fix":"Iterate directly over the result of `search()`. Each item in the iteration is an `icalendar.cal.Component` object. Access component properties directly, e.g., `for component in searcher.search(): print(component.get('SUMMARY'))`.","cause":"Attempting to call `get_events()` or similar methods on the object returned by `search()`, which is now an iterator of components, not a `QueryResult` object.","error":"AttributeError: 'generator' object has no attribute 'get_events'"}]}