ics-query 0.1.dev8__py3-none-any.whl → 0.1.1a0__py3-none-any.whl

ics_query/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.1.dev8'
-__version_tuple__ = version_tuple = (0, 1, 'dev8')
+__version__ = version = '0.1.1a0'
+__version_tuple__ = version_tuple = (0, 1, 1)

ics_query/cli.py

@@ -9,10 +9,11 @@ import typing as t
 
 import click
 import recurring_ical_events
-from icalendar import Calendar
+from icalendar.cal import Calendar, Component
 from recurring_ical_events import CalendarQuery
 
 from . import parse
+from .version import __version__
 
 if t.TYPE_CHECKING:
     from io import FileIO
@@ -50,6 +51,17 @@ class ComponentsResultArgument(click.File):
         return ComponentsResult(file)
 
 
+class JoinedCalendars:
+    def __init__(self, calendars: list[Calendar]):
+        """Join multiple calendars."""
+        self.queries = [recurring_ical_events.of(calendar) for calendar in calendars]
+
+    def at(self, dt: tuple[int]) -> t.Generator[Component]:
+        """Return the components."""
+        for query in self.queries:
+            yield from query.at(dt)
+
+
 class CalendarQueryInputArgument(click.File):
     """Argument for the result."""
 
@@ -61,8 +73,8 @@ class CalendarQueryInputArgument(click.File):
     ) -> recurring_ical_events.CalendarQuery:
         """Return a CalendarQuery."""
         file = super().convert(value, param, ctx)
-        calendar = Calendar.from_ical(file.read())
-        return recurring_ical_events.of(calendar)
+        calendars = Calendar.from_ical(file.read(), multiple=True)
+        return JoinedCalendars(calendars)
 
 
 arg_calendar = click.argument("calendar", type=CalendarQueryInputArgument("rb"))
@@ -70,9 +82,48 @@ arg_output = click.argument("output", type=ComponentsResultArgument("wb"))
 
 
 @click.group()
+@click.version_option(__version__)
 def main():
-    """Simple program that greets NAME for a total of COUNT times."""
-    # sys.stdout = sys.stderr  # remove accidential print impact
+    """Find out what happens in ICS calendar files.
+
+    ics-query can query and filter RFC 5545 compatible .ics files.
+    Components are events, journal entries and TODOs.
+
+    \b
+    Common Parameters
+    -----------------
+
+    Common parameters are described below.
+
+    CALENDAR
+
+    The CALENDAR is a readable file with one or more ICS calendars in it.
+    If CALENDAR is "-", then the standard input is used.
+
+    OUTPUT
+
+    This is the OUTPUT file for the result.
+    It is usually a path to a file that can be written to.
+    If OUTPUT is "-", then the standard output is used.
+
+    \b
+    Notes on 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
+    happens during that time.
+
+    Generally, an event occurs within a time span if this applies:
+
+        event.DTSTART <= span.DTEND and span.DTSTART < event.DTEND
+
+    The START is INCLUSIVE, then END is EXCLUSIVE.
+
+    \b
+    Notes on Timezones
+    ------------------
+    """  # noqa: D301
 
 
 pass_datetime = click.make_pass_decorator(parse.to_time)
@@ -83,9 +134,126 @@ pass_datetime = click.make_pass_decorator(parse.to_time)
 @arg_calendar
 @arg_output
 def at(calendar: CalendarQuery, output: ComponentsResult, date: DateArgument):
-    """Get the components at a certain time."""
+    """Occurrences at a certain dates.
+
+    YEAR
+
+        All occurrences in this year.
+
+    \b
+        Formats:
+    \b
+            YYYY
+    \b
+        Examples:
+    \b
+            ics-query at 2024       # all occurrences in year 2024
+            ics-query at `date +%Y` # all occurrences in this year
+
+    MONTH
+
+        All occurrences in this month.
+
+    \b
+        Formats:
+
+            YYYY-MM
+            YYYY-M
+            YYYYMM
+    \b
+        Examples:
+    \b
+            ics-query at 2019-10      # October 2019
+            ics-query at 1990-01      # January 1990
+            ics-query at 1990-1       # January 1990
+            ics-query at 199001       # January 1990
+            ics-query at `date +%Y%m` # this month
+
+    DAY
+
+        All occurrences in one day.
+
+    \b
+        Formats:
+
+            YYYY-MM-DD
+            YYYY-M-D
+            YYYYMMDD
+    \b
+        Examples:
+    \b
+            ics-query at 1990-01-01     # 1st January 1990
+            ics-query at 1990-1-1       # 1st January 1990
+            ics-query at 19900101       # 1st January 1990
+            ics-query at `date +%Y%m%d` # today
+
+    HOUR
+
+        All occurrences within one hour.
+
+    \b
+        Formats:
+    \b
+            YYYY-MM-DD HH
+            YYYY-MM-DDTHH
+            YYYY-M-DTH
+            YYYYMMDDTHH
+            YYYYMMDDHH
+    \b
+        Examples:
+    \b
+            ics-query at 1990-01-01 00    # 1st January 1990, 12am - 1am
+            ics-query at 1990-01-01T00    # 1st January 1990, 12am - 1am
+            ics-query at 1990-1-1T17      # 1st January 1990, 17:00 - 18:00
+            ics-query at 19900101T23      # 1st January 1990, 23:00 - midnight
+            ics-query at 1990010123       # 1st January 1990, 23:00 - midnight
+            ics-query at `date +%Y%m%d%H` # this hour
+
+    MINUTE
+
+        All occurrences within one minute.
+
+    \b
+        Formats:
+    \b
+            YYYY-MM-DD HH:MM
+            YYYY-MM-DDTHH:MM
+            YYYY-M-DTH:M
+            YYYYMMDDTHHMM
+            YYYYMMDDHHMM
+    \b
+        Examples:
+    \b
+            ics-query at 1990-01-01 10:10   # 1st January 1990, 10:10am - 10:11am
+            ics-query at 1990-01-01T10:10   # 1st January 1990, 10:10am - 10:11am
+            ics-query at 1990-1-1T7:2       # 1st January 1990, 07:02 - 07:03
+            ics-query at 19900101T2359      # 1st January 1990, 23:59 - midnight
+            ics-query at 199001012359       # 1st January 1990, 23:59 - midnight
+            ics-query at `date +%Y%m%d%H%M` # this minute
+
+    SECOND
+
+        All occurrences at a precise time.
+
+    \b
+        Formats:
+    \b
+            YYYY-MM-DD HH:MM:SS
+            YYYY-MM-DDTHH:MM:SS
+            YYYY-M-DTH:M:S
+            YYYYMMDDTHHMMSS
+            YYYYMMDDHHMMSS
+    \b
+        Examples:
+    \b
+            ics-query at 1990-01-01 10:10:00  # 1st January 1990, 10:10am
+            ics-query at 1990-01-01T10:10:00  # 1st January 1990, 10:10am
+            ics-query at 1990-1-1T7:2:30      # 1st January 1990, 07:02:30
+            ics-query at 19901231T235959      # 31st December 1990, 23:59:59
+            ics-query at 19900101235959       # 1st January 1990, 23:59:59
+            ics-query at `date +%Y%m%d%H%M%S` # now
+    """  # noqa: D301
     for event in calendar.at(date):
-        print("debug")
         output.add_component(event)
 
 

ics_query/parse.py

@@ -2,12 +2,49 @@
 
 from __future__ import annotations
 
+import re
+
 DateArgument = tuple[int]
 
 
+class InvalidTimeFormat(ValueError):
+    """The value provided does not yield a precise time."""
+
+
+REGEX_TIME = re.compile(
+    r"^(?P<year>\d\d\d\d)"
+    r"(?P<month>-\d?\d|\d\d)?"
+    r"(?P<day>-\d?\d|\d\d)?"
+    r"(?P<hour>[ T]\d?\d|\d\d)?"
+    r"(?P<minute>:\d?\d|\d\d)?"
+    r"(?P<second>:\d?\d|\d\d)?"
+    r"$"
+)
+
+
 def to_time(dt: str) -> DateArgument:
     """Parse the time and date."""
-    return tuple(map(int, dt.split("-")))
+    parsed_dt = REGEX_TIME.match(dt)
+    if parsed_dt is None:
+        raise InvalidTimeFormat(dt)
+
+    def group(group_name: str) -> tuple[int]:
+        """Return a group's value."""
+        result = parsed_dt.group(group_name)
+        while result and result[0] not in "0123456789":
+            result = result[1:]
+        if result is None:
+            return ()
+        return (int(result),)
+
+    return (
+        group("year")
+        + group("month")
+        + group("day")
+        + group("hour")
+        + group("minute")
+        + group("second")
+    )
 
 
 __all__ = ["to_time", "DateArgument"]

ics_query/tests/conftest.py

@@ -5,12 +5,13 @@ from __future__ import annotations
 import subprocess
 from copy import deepcopy
 from pathlib import Path
-from typing import NamedTuple
+from typing import Callable, NamedTuple
 
 import pytest
 
 HERE = Path(__file__).parent
 IO_DIRECTORY = HERE / "runs"
+CALENDARS_DIRECTORY = IO_DIRECTORY / "calendars"
 
 
 class TestRun(NamedTuple):
@@ -34,12 +35,26 @@ class TestRun(NamedTuple):
         )
 
 
+def run_ics_query(*command, cwd=CALENDARS_DIRECTORY) -> TestRun:
+    """Run ics-qeury with a command."""
+    cmd = ["ics-query", *command]
+    print(" ".join(cmd))
+    completed_process = subprocess.run(  # noqa: S603, RUF100
+        cmd,  # noqa: S603, RUF100
+        capture_output=True,
+        timeout=3,
+        check=False,
+        cwd=cwd,
+    )
+    return TestRun.from_completed_process(completed_process)
+
+
 class IOTestCase(NamedTuple):
     """An example test case."""
 
     name: str
     command: list[str]
-    cwd: Path
+    location: Path
     expected_output: str
 
     @classmethod
@@ -50,16 +65,7 @@ class IOTestCase(NamedTuple):
 
     def run(self) -> TestRun:
         """Run this test case and return the result."""
-        command = ["ics-query", *self.command]
-        print(" ".join(command))
-        completed_process = subprocess.run(  # noqa: S603, RUF100
-            command,  # noqa: S603, RUF100
-            capture_output=True,
-            timeout=3,
-            check=False,
-            cwd=self.cwd / "calendars",
-        )
-        return TestRun.from_completed_process(completed_process)
+        return run_ics_query(*self.command)
 
 
 io_test_cases = [
@@ -75,4 +81,10 @@ def io_testcase(request) -> IOTestCase:
     return deepcopy(request.param)
 
 
+@pytest.fixture
+def run() -> Callable[..., TestRun]:
+    """Return a runner function."""
+    return run_ics_query
+
+
 __all__ = ["IOTestCase", "TestRun"]

ics_query/tests/runs/at 2019-03-04 multiple-calendars.ics -.run

@@ -0,0 +1,20 @@
+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:test1
+DTSTART;TZID=Europe/Berlin:20190304T080000
+DTEND;TZID=Europe/Berlin:20190304T083000
+DTSTAMP:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+CREATED:20190303T111937
+LAST-MODIFIED:20190303T111937
+END:VEVENT

ics_query/tests/runs/at 2019-03-04 one-event-twice.ics -.run

@@ -0,0 +1,18 @@
+BEGIN:VEVENT
+SUMMARY:test1
+DTSTART;TZID=Europe/Berlin:20190304T080000
+DTEND;TZID=Europe/Berlin:20190304T083000
+DTSTAMP:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+CREATED:20190303T111937
+LAST-MODIFIED:20190303T111937
+END:VEVENT
+BEGIN:VEVENT
+SUMMARY:test1
+DTSTART;TZID=Europe/Berlin:20190304T080000
+DTEND;TZID=Europe/Berlin:20190304T083000
+DTSTAMP:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+CREATED:20190303T111937
+LAST-MODIFIED:20190303T111937
+END:VEVENT

ics_query/tests/runs/at 2019-03-07 multiple-calendars.ics -.run

@@ -0,0 +1,11 @@
+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

ics_query/tests/runs/calendars/multiple-calendars.ics

@@ -0,0 +1,71 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//SabreDAV//SabreDAV//EN
+CALSCALE:GREGORIAN
+X-WR-CALNAME:test
+X-APPLE-CALENDAR-COLOR:#e78074
+BEGIN:VTIMEZONE
+TZID:Europe/Berlin
+X-LIC-LOCATION:Europe/Berlin
+BEGIN:DAYLIGHT
+TZOFFSETFROM:+0100
+TZOFFSETTO:+0200
+TZNAME:CEST
+DTSTART:19700329T020000
+RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU
+END:DAYLIGHT
+BEGIN:STANDARD
+TZOFFSETFROM:+0200
+TZOFFSETTO:+0100
+TZNAME:CET
+DTSTART:19701025T030000
+RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU
+END:STANDARD
+END:VTIMEZONE
+BEGIN:VEVENT
+CREATED:20190303T111937
+DTSTAMP:20190303T111937
+LAST-MODIFIED:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+SUMMARY:test4
+CLASS:PUBLIC
+STATUS:CONFIRMED
+RRULE:FREQ=DAILY;COUNT=3;INTERVAL=3
+DTSTART;TZID=Europe/Berlin:20190304T000000
+DTEND;TZID=Europe/Berlin:20190304T010000
+END:VEVENT
+END:VCALENDAR
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//SabreDAV//SabreDAV//EN
+CALSCALE:GREGORIAN
+X-WR-CALNAME:test
+X-APPLE-CALENDAR-COLOR:#e78074
+BEGIN:VTIMEZONE
+TZID:Europe/Berlin
+X-LIC-LOCATION:Europe/Berlin
+BEGIN:DAYLIGHT
+TZOFFSETFROM:+0100
+TZOFFSETTO:+0200
+TZNAME:CEST
+DTSTART:19700329T020000
+RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU
+END:DAYLIGHT
+BEGIN:STANDARD
+TZOFFSETFROM:+0200
+TZOFFSETTO:+0100
+TZNAME:CET
+DTSTART:19701025T030000
+RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU
+END:STANDARD
+END:VTIMEZONE
+BEGIN:VEVENT
+CREATED:20190303T111937
+DTSTAMP:20190303T111937
+LAST-MODIFIED:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+SUMMARY:test1
+DTSTART;TZID=Europe/Berlin:20190304T080000
+DTEND;TZID=Europe/Berlin:20190304T083000
+END:VEVENT
+END:VCALENDAR

ics_query/tests/runs/calendars/one-event-twice.ics

@@ -0,0 +1,68 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//SabreDAV//SabreDAV//EN
+CALSCALE:GREGORIAN
+X-WR-CALNAME:test
+X-APPLE-CALENDAR-COLOR:#e78074
+BEGIN:VTIMEZONE
+TZID:Europe/Berlin
+X-LIC-LOCATION:Europe/Berlin
+BEGIN:DAYLIGHT
+TZOFFSETFROM:+0100
+TZOFFSETTO:+0200
+TZNAME:CEST
+DTSTART:19700329T020000
+RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU
+END:DAYLIGHT
+BEGIN:STANDARD
+TZOFFSETFROM:+0200
+TZOFFSETTO:+0100
+TZNAME:CET
+DTSTART:19701025T030000
+RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU
+END:STANDARD
+END:VTIMEZONE
+BEGIN:VEVENT
+CREATED:20190303T111937
+DTSTAMP:20190303T111937
+LAST-MODIFIED:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+SUMMARY:test1
+DTSTART;TZID=Europe/Berlin:20190304T080000
+DTEND;TZID=Europe/Berlin:20190304T083000
+END:VEVENT
+END:VCALENDAR
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//SabreDAV//SabreDAV//EN
+CALSCALE:GREGORIAN
+X-WR-CALNAME:test
+X-APPLE-CALENDAR-COLOR:#e78074
+BEGIN:VTIMEZONE
+TZID:Europe/Berlin
+X-LIC-LOCATION:Europe/Berlin
+BEGIN:DAYLIGHT
+TZOFFSETFROM:+0100
+TZOFFSETTO:+0200
+TZNAME:CEST
+DTSTART:19700329T020000
+RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU
+END:DAYLIGHT
+BEGIN:STANDARD
+TZOFFSETFROM:+0200
+TZOFFSETTO:+0100
+TZNAME:CET
+DTSTART:19701025T030000
+RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU
+END:STANDARD
+END:VTIMEZONE
+BEGIN:VEVENT
+CREATED:20190303T111937
+DTSTAMP:20190303T111937
+LAST-MODIFIED:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+SUMMARY:test1
+DTSTART;TZID=Europe/Berlin:20190304T080000
+DTEND;TZID=Europe/Berlin:20190304T083000
+END:VEVENT
+END:VCALENDAR

ics_query/tests/test_command_line.py

@@ -1,5 +1,7 @@
 """Test the commmand line."""
 
+from ics_query.version import version
+
 from .conftest import IOTestCase
 
 
@@ -8,3 +10,10 @@ def test_check_program_output(io_testcase: IOTestCase):
     result = io_testcase.run()
     print(result.error)
     assert result.output == io_testcase.expected_output
+
+
+def test_version(run):
+    """Check the version is displayed."""
+    result = run("--version")
+    assert result.exit_code == 0
+    assert version in result.output

ics_query/tests/test_parse_date.py

@@ -0,0 +1,63 @@
+"""This tests parsing input times and dates."""
+
+import pytest
+
+from ics_query.parse import InvalidTimeFormat, to_time
+
+
+@pytest.mark.parametrize(
+    ("string_argument", "expected_result"),
+    [
+        # year
+        ("2019", (2019,)),
+        ("1991", (1991,)),
+        # month
+        ("2000-11", (2000, 11)),
+        ("2001-01", (2001, 1)),
+        ("1990-1", (1990, 1)),
+        ("201011", (2010, 11)),
+        ("199003", (1990, 3)),
+        # day
+        ("1990-01-01", (1990, 1, 1)),
+        ("2001-3-4", (2001, 3, 4)),
+        ("19801231", (1980, 12, 31)),
+        # hour
+        ("1990-01-01 00", (1990, 1, 1, 0)),
+        ("1991-12-31T23", (1991, 12, 31, 23)),
+        ("2003-1-1T17", (2003, 1, 1, 17)),
+        ("20010409T12", (2001, 4, 9, 12)),
+        ("2014101018", (2014, 10, 10, 18)),
+        # minute
+        ("1990-01-01 00:10", (1990, 1, 1, 0, 10)),
+        ("1991-12-31T23:11", (1991, 12, 31, 23, 11)),
+        ("2003-1-1T17:0", (2003, 1, 1, 17, 0)),
+        ("2004-1-1T7:0", (2004, 1, 1, 7, 0)),
+        ("20010409T12:59", (2001, 4, 9, 12, 59)),
+        ("201410101830", (2014, 10, 10, 18, 30)),
+        # second
+        ("1990-01-01 00:10:12", (1990, 1, 1, 0, 10, 12)),
+        ("1991-12-31T23:11:0", (1991, 12, 31, 23, 11, 0)),
+        ("2003-1-1T17:0:11", (2003, 1, 1, 17, 0, 11)),
+        ("2004-1-1T7:0:10", (2004, 1, 1, 7, 0, 10)),
+        ("20010409T12:59:58", (2001, 4, 9, 12, 59, 58)),
+        ("20141010183012", (2014, 10, 10, 18, 30, 12)),
+    ],
+)
+def test_parse_to_date_argument(string_argument, expected_result):
+    """Check that we can properly parse what is accepted."""
+    result = to_time(string_argument)
+    assert result == expected_result
+
+
+@pytest.mark.parametrize(
+    "dt",
+    [
+        "",
+        "132",
+        "12345",
+    ],
+)
+def test_invalid_time_format(dt: str):
+    """Check invalid time formats."""
+    with pytest.raises(InvalidTimeFormat):
+        to_time(dt)

{ics_query-0.1.dev8.dist-info → ics_query-0.1.1a0.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.3
 Name: ics-query
-Version: 0.1.dev8
-Summary: Find out what happens in ICS calendar files - query and filter RFC 5545 compatible `.ics` files for events, journals, TODOs and more.
+Version: 0.1.1a0
+Summary: Find out what happens in ICS calendar files - query and filter RFC 5545 compatible .ics files for events, journals, TODOs and more.
 Project-URL: Homepage, https://github.com/niccokunzmann/ics-query/
 Project-URL: Repository, https://github.com/niccokunzmann/ics-query/
-Project-URL: source_archive, https://github.com/niccokunzmann/ics-query/archive/3f1c4acd60666416eb899f7a0c07a05999d443c3.zip
+Project-URL: source_archive, https://github.com/niccokunzmann/ics-query/archive/fb12ef2822d23f693aa5f9faaa0cb97fa9f67516.zip
 Project-URL: Issues, https://github.com/niccokunzmann/ics-query/issues
 Project-URL: Documentation, https://github.com/niccokunzmann/ics-query/
 Project-URL: Changelog, https://github.com/niccokunzmann/ics-query/#changelog
@@ -690,7 +690,10 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Office/Business :: Scheduling
 Requires-Python: >=3.8
 Requires-Dist: click
@@ -713,7 +716,79 @@ You can install this package from the [PyPI](https://pypi.org/project/ics-query/
 pip install ics-query
 ```
 
-## `ics-query at` - occurrences at certain times
+## Usage
+
+See how to use `ics-query`.
+
+### Examples
+
+You can easily get a calendar from the web and see what is on.
+In this example, we show which German National Holidays happen in August 2024:
+
+```shell
+$ wget -qO- 'https://www.calendarlabs.com/ical-calendar/ics/46/Germany_Holidays.ics' | ./ics-query at 2024-08 - -
+BEGIN:VEVENT
+SUMMARY:Assumption Day (BY\, SL)
+DTSTART;VALUE=DATE:20240815
+DTEND;VALUE=DATE:20240815
+DTSTAMP:20231013T092513Z
+UID:65290cf9326601697189113@calendarlabs.com
+SEQUENCE:0
+DESCRIPTION:Visit https://calendarlabs.com/holidays/us/the-assumption-of-m
+ ary.php to know more about Assumption Day (BY\, SL). \n\n Like us on Faceb
+ ook: http://fb.com/calendarlabs to get updates
+LOCATION:Germany
+STATUS:CONFIRMED
+TRANSP:TRANSPARENT
+END:VEVENT
+```
+
+In the following example, we query a calendar file and print the result.
+
+```shell
+$ ics-query at 2019-03-04 one-event.ics -
+BEGIN:VEVENT
+SUMMARY:test1
+DTSTART;TZID=Europe/Berlin:20190304T080000
+DTEND;TZID=Europe/Berlin:20190304T083000
+DTSTAMP:20190303T111937
+UID:UYDQSG9TH4DE0WM3QFL2J
+CREATED:20190303T111937
+LAST-MODIFIED:20190303T111937
+END:VEVENT
+```
+
+We can concatenate calendars and pipe them into `ics-query`.
+In the example below, we get all events that happen right now in two calendars.
+
+```shell
+$ cat calendar1.ics calendar2.ics | ics-query at `date +%Y%m%d%H%M%S` - -
+BEGIN:VEVENT
+...
+```
+
+### Events at Certain Times
+
+You can query which events happen at certain times:
+
+```shell
+ics-query at <date-time> calendar.ics -
+```
+
+`<date-time>` can be built up: It can be a year, a month, a day, an hour, a minute or a second.
+
+Please see the command documentation for more help:
+
+```shell
+ics-query --help
+ics-query at --help
+```
+
+## Vision
+
+This section shows where we would like to get to.
+
+### `ics-query at` - occurrences at certain times
 
 You can get all **events** that happen at a certain **day**.
 
@@ -733,32 +808,32 @@ You can get all **TODO**s that happen at in certain **month**.
 ics-query --components VTODO at 2029-12-24 calendar.ics
 ```
 
-## `ics-query at` - time ranges
+### `ics-query at` - time ranges
 
 
-## `ics-query --output=count` - count occurrences
+### `ics-query --output=count` - count occurrences
 
 
-## `ics-query --output=ics` - use ics as output (default)
+### `ics-query --output=ics` - use ics as output (default)
 
 
-## `ics-query --select-index` - reduce output size
+### `ics-query --select-index` - reduce output size
 
 Examples: `0,2,4` `0-10`
 
-## `ics-query all` - the whole calendar
+### `ics-query all` - the whole calendar
 
-## `ics-query between` - time ranges
+### `ics-query between` - time ranges
 
 ```shell
 ics-query between dt dt
 ics-query between dt duration
 ```
 
-## `ics-query --select-component` - filter for components
+### `ics-query --select-component` - filter for components
 
 
-## `ics-query --select-uid` - filter by uid
+### `ics-query --select-uid` - filter by uid
 
 
 ## How to edit an event
@@ -787,8 +862,93 @@ Examples:
 - There are x events today
 - Please write a journal entry!
 
+## Version Fixing
+
+If you use this library in your code, you may want to make sure that
+updates can be received but they do not break your code.
+The version numbers are handeled this way: `a.b.c` example: `0.1.12`
+
+- `c` is changed for each minor bug fix.
+- `b` is changed whenever new features are added.
+- `a` is changed when the interface or major assumptions change that may break your code.
+
+So, I recommend to version-fix this library to stay with the same `a`
+while `b` and `c` can change.
+
+## Development
+
+This section should set you up for development.
+
+### Testing
+
+This project's development is driven by tests.
+Tests assure a consistent interface and less knowledge lost over time.
+If you like to change the code, tests help that nothing breaks in the future.
+They are required in that sense.
+Example code and ics files can be transferred into tests and speed up fixing bugs.
+
+You can view the tests in the [test folder](https://github.com/niccokunzmann/ics-query/tree/main/ics_query/tests)
+If you have a calendar ICS file for which this library does not
+generate the desired output, you can add it to the ``test/calendars``
+folder and write tests for what you expect.
+If you like, [open an issue](https://github.com/niccokunzmann/ics-query/issues) first, e.g. to discuss the changes and
+how to go about it.
+
+To run the tests, we use `tox`.
+`tox` tests all different Python versions which we want to  be compatible to.
+
+```shell
+pip3 install tox
+```
+
+To run all the tests:
+
+```shell
+tox
+```
+
+To run the tests in a specific Python version:
+
+```shell
+tox -e py39
+```
+
+We use ``ruff`` to format the code.
+Run this to format the code and show problems:
+
+```shell
+tox -e ruff
+```
+
+## New Release
+
+To release new versions,
+
+1. edit the Changelog Section
+2. create a commit and push it
+3. wait for [GitHub Actions](https://github.com/niccokunzmann/ics-query/actions) to finish the build
+4. create a tag and push it
+
+    ```shell
+    git tag v0.1.0a
+    git push origin v0.1.0a
+    ```
+
+5. Notify the issues about their release
+
 ## Changelog
 
+- v0.1.1a
+
+  - Add `--version`
+  - Add `ics-query at <date>`
+  - Add support for multiple calendars in one input
+
+- v0.1.0a
+
+  - Update Python version compatibility
+  - Add development documentation
+
 - v0.0.1a
 
   - first version

ics_query-0.1.1a0.dist-info/RECORD

@@ -0,0 +1,22 @@
+ics_query/__init__.py,sha256=YxyZzqxwfA77sBVFjUyUj3_fvR2gL3bs0pkE93prRFY,216
+ics_query/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+ics_query/_version.py,sha256=cU7fSuITRwo1pTWU-OD7oXC6-FpABHrqGppdiounZFo,413
+ics_query/cli.py,sha256=-ogJQ994ssQNNvU8tojCPDea4wJwFd4f9REoJ1hDCOs,6949
+ics_query/parse.py,sha256=VkF4z5KR-uzg4YmEKaY7Zz67d4Ffxc4rsB6ezNtxBr8,1113
+ics_query/version.py,sha256=LgqmHh_dcmWi9HMxfWJ8OhfmbzWsBTq3h08jIE18pYM,468
+ics_query/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ics_query/tests/conftest.py,sha256=MGwKXod7sFfepXK0mtvKkR8SaIiI1SZNW_rAhz6aSA0,2258
+ics_query/tests/test_command_line.py,sha256=-XnpYWETEVEc1dJ5_dpd8dqBoMQFz1CyGaSoe_ETq5o,488
+ics_query/tests/test_parse_date.py,sha256=ZMbllWHNCwuluGTr55xKlM7xBzoMNsoE7TQUC5uGlVA,1923
+ics_query/tests/runs/at 2019-03-04 multiple-calendars.ics -.run,sha256=Cyeg9DMK6BibiCwkM8nW0ZtULUYSZFIgDvKRlSo_jTw,482
+ics_query/tests/runs/at 2019-03-04 one-event-twice.ics -.run,sha256=hc-0yJhWpnSVzPNB_0_tJfR6dskNMm9xdbHeAhsX1zI,452
+ics_query/tests/runs/at 2019-03-04 one-event.ics -.run,sha256=GVVmVpqzFjQLw2_RuhxnVTpCnwflNqeWbkFZ6u5WXxA,226
+ics_query/tests/runs/at 2019-03-07 multiple-calendars.ics -.run,sha256=ZlLXxPMIai7vvmQTL4NyXJwdCQzoU1scEn_FpjmkkUA,256
+ics_query/tests/runs/calendars/multiple-calendars.ics,sha256=lS1Q9eSPpzLs2TRDKUiwF9HmpnJMw8xqjLudA0-KtY4,1516
+ics_query/tests/runs/calendars/one-event-twice.ics,sha256=GZ5wE-U4kjO91N2nIaLsYZpSOLvQTjkoLPI6saMocOM,1450
+ics_query/tests/runs/calendars/one-event.ics,sha256=-uwohttEzg-jsTETNb6tQ5dO9PE3DXzlicwRiXJs1KQ,725
+ics_query-0.1.1a0.dist-info/METADATA,sha256=cgssIiEuCQItTb7_5Iap9KFcfV6f9-z4DUfy-gd6MsU,48066
+ics_query-0.1.1a0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+ics_query-0.1.1a0.dist-info/entry_points.txt,sha256=Jq_39vCKVOkNZjL7Wngf_04V_n_QRszLgLT2CbJKiH4,49
+ics_query-0.1.1a0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+ics_query-0.1.1a0.dist-info/RECORD,,

ics_query-0.1.dev8.dist-info/RECORD

@@ -1,16 +0,0 @@
-ics_query/__init__.py,sha256=YxyZzqxwfA77sBVFjUyUj3_fvR2gL3bs0pkE93prRFY,216
-ics_query/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
-ics_query/_version.py,sha256=lI2AbAnFrmlrT0e_rrLW0sxbHP3fZzYfncKr1OGEhdw,419
-ics_query/cli.py,sha256=P6eLIH7hgbfwhbJHloilHS9ut_YDjEP_QDabLTf0NQs,2367
-ics_query/parse.py,sha256=6bCKtY39jr2NFSsqspVyGn32pwn6bMoEqJMHE26Ap1o,261
-ics_query/version.py,sha256=LgqmHh_dcmWi9HMxfWJ8OhfmbzWsBTq3h08jIE18pYM,468
-ics_query/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ics_query/tests/conftest.py,sha256=A6R9pB3emaSo1DAIxyt-5QhWPq8LbsOoWJIRIsku2Zk,2003
-ics_query/tests/test_command_line.py,sha256=bIJp2SCVW8MXF_lNZ1ol9A-r9Y_9zjnY2jhdTJET59g,283
-ics_query/tests/runs/at 2019-03-04 one-event.ics -.run,sha256=GVVmVpqzFjQLw2_RuhxnVTpCnwflNqeWbkFZ6u5WXxA,226
-ics_query/tests/runs/calendars/one-event.ics,sha256=-uwohttEzg-jsTETNb6tQ5dO9PE3DXzlicwRiXJs1KQ,725
-ics_query-0.1.dev8.dist-info/METADATA,sha256=5jVr-o3Elo_hWgEjN-t3GFB5fAd65JSyw23Tp2JvBZc,43902
-ics_query-0.1.dev8.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-ics_query-0.1.dev8.dist-info/entry_points.txt,sha256=Jq_39vCKVOkNZjL7Wngf_04V_n_QRszLgLT2CbJKiH4,49
-ics_query-0.1.dev8.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-ics_query-0.1.dev8.dist-info/RECORD,,