ics-query 0.2.0a0__py3-none-any.whl → 0.3.0b0__py3-none-any.whl

ics_query/__init__.py

@@ -1,11 +1,12 @@
-from .cli import main
+from .cli import cli, main
 from .version import __version__, __version_tuple__, version, version_tuple
 
 __all__ = [
-    "main",
+    "cli",
     "app",
     "__version__",
     "version",
     "__version_tuple__",
     "version_tuple",
+    "main",
 ]

ics_query/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.2.0a0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.3.0b0'
+__version_tuple__ = version_tuple = (0, 3, 0)

ics_query/cli.py

@@ -8,21 +8,25 @@ import sys
 import typing as t
 
 import click
-import recurring_ical_events
+import zoneinfo
 from icalendar.cal import Calendar, Component
 
 from . import parse
-from .version import __version__
+from .query import Query
+from .version import cli_version
 
 if t.TYPE_CHECKING:
     from io import FileIO
 
+    import recurring_ical_events
     from icalendar.cal import Component
 
     from .parse import Date
 
 print = functools.partial(print, file=sys.stderr)  # noqa: A001
 
+ENV_PREFIX = "ICS_QUERY"
+
 
 class ComponentsResult:
     """Output interface for components."""
@@ -56,9 +60,13 @@ class ComponentsResultArgument(click.File):
 
 
 class JoinedCalendars:
-    def __init__(self, calendars: list[Calendar]):
+    def __init__(
+        self, calendars: list[Calendar], timezone: str, components: t.Sequence[str]
+    ):
         """Join multiple calendars."""
-        self.queries = [recurring_ical_events.of(calendar) for calendar in calendars]
+        self.queries = [
+            Query(calendar, timezone, components=components) for calendar in calendars
+        ]
 
     def at(self, dt: tuple[int]) -> t.Generator[Component]:
         """Return the components."""
@@ -72,6 +80,11 @@ class JoinedCalendars:
                 yield component
                 break
 
+    def all(self) -> t.Generator[Component]:
+        """Return the first events of all calendars."""
+        for query in self.queries:
+            yield from query.all()
+
     def between(
         self, start: parse.Date, end: parse.DateAndDelta
     ) -> t.Generator[Component]:
@@ -91,16 +104,88 @@ class CalendarQueryInputArgument(click.File):
         """Return a CalendarQuery."""
         file = super().convert(value, param, ctx)
         calendars = Calendar.from_ical(file.read(), multiple=True)
-        return JoinedCalendars(calendars)
+        components = ctx.params.get("component", ("VEVENT", "VTODO", "VJOURNAL"))
+        timezone = ctx.params.get("tz", "")
+        return JoinedCalendars(calendars, timezone, components)
+
+
+opt_components = click.option(
+    "--component",
+    "-c",
+    multiple=True,
+    envvar=ENV_PREFIX + "_COMPONENT",
+    help=(
+        "Select the components which can be returned. "
+        "By default all supported components can be in the result. "
+        "Possible values are: VEVENT, VTODO, VJOURNAL. "
+    ),
+)
+
+opt_timezone = click.option(
+    "--tz",
+    envvar=ENV_PREFIX + "_TZ",
+    help=("Set the timezone. See also --available-timezones"),
+)
+
+
+def arg_calendar(func):
+    """Decorator for a calendar argument with all used options."""
+    arg = click.argument("calendar", type=CalendarQueryInputArgument("rb"))
+
+    @functools.wraps(func)
+    def wrapper(*args, component=(), tz="", **kw):  # noqa: ARG001
+        """Remove some parameters."""
+        return func(*args, **kw)
+
+    return opt_timezone(opt_components(arg(wrapper)))
+
+
+arg_output = click.argument("output", type=ComponentsResultArgument("wb"), default="-")
+# Option with many values and list as result
+# see https://click.palletsprojects.com/en/latest/options/#multiple-options
 
 
-arg_calendar = click.argument("calendar", type=CalendarQueryInputArgument("rb"))
-arg_output = click.argument("output", type=ComponentsResultArgument("wb"))
+def opt_available_timezones(*param_decls: str, **kwargs: t.Any) -> t.Callable:
+    """Add a ``--help`` option which immediately prints the help page
+    and exits the program.
+
+    This is usually unnecessary, as the ``--help`` option is added to
+    each command automatically unless ``add_help_option=False`` is
+    passed.
+
+    :param param_decls: One or more option names. Defaults to the single
+        value ``"--help"``.
+    :param kwargs: Extra arguments are passed to :func:`option`.
+    """
+
+    def callback(ctx: click.Context, param: click.Parameter, value: bool) -> None:  # noqa: FBT001, ARG001
+        if not value or ctx.resilient_parsing:
+            return
+
+        first_zones = ["localtime", "UTC"]
+        all_zones = zoneinfo.available_timezones()
+        for zone in first_zones:
+            if zone in all_zones:
+                click.echo(zone)
+        for zone in sorted(all_zones, key=str.lower):
+            click.echo(zone)
+        ctx.exit()
+
+    if not param_decls:
+        param_decls = ("--available-timezones",)
+
+    kwargs.setdefault("is_flag", True)
+    kwargs.setdefault("expose_value", False)
+    kwargs.setdefault("is_eager", True)
+    kwargs.setdefault("help", "List all available timezones and exit.")
+    kwargs["callback"] = callback
+    return click.option(*param_decls, **kwargs)
 
 
 @click.group()
-@click.version_option(__version__)
-def main():
+@click.version_option(cli_version)
+@opt_available_timezones()
+def cli():
     """Find out what happens in ICS calendar files.
 
     ics-query can query and filter RFC 5545 compatible .ics files.
@@ -124,8 +209,8 @@ def main():
     If OUTPUT is "-", then the standard output is used.
 
     \b
-    Notes on Calculation
-    --------------------
+    Calculation
+    -----------
 
     An event can be very long. If you request smaller time spans or a time as
     exact as a second, the event will still occur within this time span if it
@@ -138,20 +223,72 @@ def main():
     The START is INCLUSIVE, then END is EXCLUSIVE.
 
     \b
-    Notes on Timezones
-    ------------------
+    Timezones
+    ---------
+
+    We have several timezones available to choose from.
+    While the calendar entries might use their own timezone definitions,
+    the timezone parameters of ics-query use the timezone definitions of
+    Python's tzdata package.
+
+    You can list all timezones available with this command:
+
+    \b
+        ics-query --available-timezones
+
+    By default the local time of the components is assumed.
+    In this example, two events happen at 6am, one in Berlin and one in Los Angeles.
+    Both are hours apart though.
+
+    \b
+        $ ics-query at 2024-08-20 Berlin-Los-Angeles.ics - | grep -E 'DTSTART|SUMMARY'
+        SUMMARY:6:00-7:00 Europe/Berlin 20th August
+        DTSTART;TZID=Europe/Berlin:20240820T060000
+        SUMMARY:6:00-7:00 Amerika/Los Angeles 20th August
+        DTSTART;TZID=America/Los_Angeles:20240820T060000
+
+    If you however wish to get all events in a certain timezone, use the --tz parameter.
+    In this example, the event that happens at the 19th of August at 21:00 in
+    Los Angeles is actually happening on the 20th in local Berlin time.
+
+    \b
+        $ ics-query at --tz=Europe/Berlin 2024-08-20 Berlin-Los-Angeles.ics - \\
+            | grep -E 'DTSTART|SUMMARY'
+        SUMMARY:6:00-7:00 Europe/Berlin 20th August
+        DTSTART;TZID=Europe/Berlin:20240820T060000
+        SUMMARY:6:00-7:00 Amerika/Los Angeles 20th August
+        DTSTART;TZID=Europe/Berlin:20240820T150000
+        SUMMARY:21:00-22:00 Amerika/Los Angeles 19th August
+        DTSTART;TZID=Europe/Berlin:20240820T060000
+
+    If you wish to get events in your local time, use --tz localtime.
+    If you like UTC, use --tz UTC.
+
+    You can also set the environment variable ICS_QUERY_TZ to the timezone instead of
+    passing --tz.
+
+    \b
+    Components
+    ----------
+
+    We support different types of recurring components: VEVENT, VTODO, VJOURNAL.
+    You can specify which can be in the result using the --component parameter.
+
+    You can also set the environment variable ICS_QUERY_COMPONENT to the timezone
+    instead of passing --component.
+
     """  # noqa: D301
 
 
 pass_datetime = click.make_pass_decorator(parse.to_time)
 
 
-@main.command()
+@cli.command()
 @click.argument("date", type=parse.to_time)
 @arg_calendar
 @arg_output
 def at(calendar: JoinedCalendars, output: ComponentsResult, date: Date):
-    """Occurrences at a certain dates.
+    """Print occurrences at a certain date or time.
 
     YEAR
 
@@ -273,22 +410,48 @@ def at(calendar: JoinedCalendars, output: ComponentsResult, date: Date):
     output.add_components(calendar.at(date))
 
 
-@main.command()
+@cli.command()
 @arg_calendar
 @arg_output
 def first(calendar: JoinedCalendars, output: ComponentsResult):
-    """Print only the first occurrence in each calendar.
+    """Print only the first occurrence.
+
+    This prints the first occurrence in each calendar that is given.
 
     \b
     This example prints the first event in calendar.ics:
     \b
-        ics-query first calendar.ics -
+        ics-query first --component VEVENT calendar.ics -
 
     """  # noqa: D301
     output.add_components(calendar.first())
 
 
-@main.command()
+@cli.command()
+@arg_calendar
+@arg_output
+def all(calendar: JoinedCalendars, output: ComponentsResult):  # noqa: A001
+    """Print all occurrences in a calendar.
+
+    The result is ordered by the start of the occurrences.
+    If you have multiple calendars, the result will contain
+    the occurrences of the first calendar before those of the second calendar
+    and so on.
+
+    \b
+    This example prints all events in calendar.ics:
+    \b
+        ics-query all --component VEVENT calendar.ics -
+
+    Note that calendars can create hundreds of occurrences and especially
+    contain endless repetitions. Use this with care as the output is
+    potentially enourmous. You can mitigate this by closing the OUTPUT
+    when you have enough e.g. with a head command.
+    """  # noqa: D301
+    output.add_components(calendar.all())
+
+
+@cli.command()
 @click.argument("start", type=parse.to_time)
 @click.argument("end", type=parse.to_time_and_delta)
 @arg_calendar
@@ -299,20 +462,20 @@ def between(
     calendar: JoinedCalendars,
     output: ComponentsResult,
 ):
-    """Print all occurrences between the START and the END.
+    """Print occurrences between a START and an END.
 
     The start is inclusive, the end is exclusive.
 
     This example returns the events within the next week:
 
     \b
-        ics-query between `date +%Y%m%d` +7d calendar.ics -
+        ics-query between --component VEVENT `date +%Y%m%d` +7d calendar.ics -
 
     This example saves the events from the 1st of May 2024 to the 10th of June in
     events.ics:
 
     \b
-        ics-query between 2024-5-1 2024-6-10 calendar.ics events.ics
+        ics-query between --component VEVENT 2024-5-1 2024-6-10 calendar.ics events.ics
 
     In this example, you can check what is happening on New Years Eve 2025 around
     midnight:
@@ -472,4 +635,9 @@ def between(
     output.add_components(calendar.between(start, end))
 
 
-__all__ = ["main"]
+def main():
+    """Run the program."""
+    cli(auto_envvar_prefix=ENV_PREFIX)
+
+
+__all__ = ["main", "ENV_PREFIX", "cli"]

ics_query/query.py

@@ -0,0 +1,54 @@
+"""This is an adaptation of the CalendarQuery."""
+
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING, Sequence
+
+import x_wr_timezone
+import zoneinfo
+from recurring_ical_events import CalendarQuery, Occurrence
+
+if TYPE_CHECKING:
+    from icalendar import Calendar
+
+
+class Query(CalendarQuery):
+    def __init__(self, calendar: Calendar, timezone: str, components: Sequence[str]):
+        """Create a new query."""
+        super().__init__(
+            x_wr_timezone.to_standard(calendar),
+            components=components,
+            skip_bad_series=True,
+        )
+        self.timezone = zoneinfo.ZoneInfo(timezone) if timezone else None
+
+    def with_timezone(self, dt: datetime.date | datetime.datetime):
+        """Add the timezone."""
+        if self.timezone is None:
+            return dt
+        if not isinstance(dt, datetime.datetime):
+            return datetime.datetime(
+                year=dt.year, month=dt.month, day=dt.day, tzinfo=self.timezone
+            )
+        if dt.tzinfo is None:
+            return dt.replace(tzinfo=self.timezone)
+        return dt.astimezone(self.timezone)
+
+    def _occurrences_between(
+        self,
+        start: datetime.date | datetime.datetime,
+        end: datetime.date | datetime.datetime,
+    ) -> list[Occurrence]:
+        """Override to adapt timezones."""
+        result = []
+        for occurrence in super()._occurrences_between(
+            self.with_timezone(start), self.with_timezone(end)
+        ):
+            occurrence.start = self.with_timezone(occurrence.start)
+            occurrence.end = self.with_timezone(occurrence.end)
+            result.append(occurrence)
+        return result
+
+
+__all__ = ["Query"]

ics_query/tests/runs/all --tz Singapore one-event.ics -.run

@@ -0,0 +1,9 @@
+BEGIN:VEVENT
+SUMMARY:test1
+DTSTART;TZID=Singapore:20190304T150000
+DTEND;TZID=Singapore:20190304T153000
+DTSTAMP:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+CREATED:20190303T111937
+LAST-MODIFIED:20190303T111937
+END:VEVENT

ics_query/tests/runs/all three-events.ics -.run

@@ -0,0 +1,33 @@
+BEGIN:VEVENT
+SUMMARY:test4
+DTSTART;TZID=Europe/Berlin:20190304T000000
+DTEND;TZID=Europe/Berlin:20190304T010000
+DTSTAMP:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+CLASS:PUBLIC
+CREATED:20190303T111937
+LAST-MODIFIED:20190303T111937
+STATUS:CONFIRMED
+END:VEVENT
+BEGIN:VEVENT
+SUMMARY:test4
+DTSTART;TZID=Europe/Berlin:20190307T000000
+DTEND;TZID=Europe/Berlin:20190307T010000
+DTSTAMP:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+CLASS:PUBLIC
+CREATED:20190303T111937
+LAST-MODIFIED:20190303T111937
+STATUS:CONFIRMED
+END:VEVENT
+BEGIN:VEVENT
+SUMMARY:test4
+DTSTART;TZID=Europe/Berlin:20190310T000000
+DTEND;TZID=Europe/Berlin:20190310T010000
+DTSTAMP:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+CLASS:PUBLIC
+CREATED:20190303T111937
+LAST-MODIFIED:20190303T111937
+STATUS:CONFIRMED
+END:VEVENT

ics_query/tests/runs/at 2024-08-20 Berlin-Los-Angeles.ics -.run

@@ -0,0 +1,23 @@
+BEGIN:VEVENT
+SUMMARY:6:00-7:00 Europe/Berlin 20th August
+DTSTART;TZID=Europe/Berlin:20240820T060000
+DTEND;TZID=Europe/Berlin:20240820T070000
+DTSTAMP:20240823T130444Z
+UID:b27ea261-f23d-4e03-a7ac-f8cb0d00f07f
+CREATED:20240823T120639Z
+LAST-MODIFIED:20240823T130444Z
+TRANSP:OPAQUE
+X-MOZ-GENERATION:3
+END:VEVENT
+BEGIN:VEVENT
+SUMMARY:6:00-7:00 Amerika/Los Angeles 20th August
+DTSTART;TZID=America/Los_Angeles:20240820T060000
+DTEND;TZID=America/Los_Angeles:20240820T070000
+DTSTAMP:20240823T130711Z
+UID:6d7ff7f3-4bc4-4d89-afa0-771bd690518a
+SEQUENCE:1
+CREATED:20240823T120639Z
+LAST-MODIFIED:20240823T130711Z
+TRANSP:OPAQUE
+X-MOZ-GENERATION:4
+END:VEVENT