icalendar-events-cli 1.0.0__py3-none-any.whl

icalendar_events_cli/__init__.py

@@ -0,0 +1 @@
+"""Module init."""

icalendar_events_cli/__main__.py

@@ -0,0 +1,59 @@
+"""Commandline interface entry point."""
+
+# ---- Imports --------------------------------------------------------------------------------------------------------
+import importlib.metadata
+import os
+from typing import Optional
+
+from .argparse import parse_config
+from .downloader import download_ics
+from .icalendar import filter_events, parse_calendar
+from .output import output_events
+
+# ---- Module Meta-Data ------------------------------------------------------------------------------------------------
+__prog__ = "icalendar-events-cli"
+__dist_name__ = "icalendar_events_cli"
+__copyright__ = "Copyright 2023-2025"
+__author__ = "Sebastian Waldvogel"
+
+# ---- Main -----------------------------------------------------------------------------------------------------------
+
+
+def cli(arg_list: Optional[list[str]] = None) -> int:
+    """Main command line handling entry point.
+
+    Arguments:
+        arg_list: Optional list of command line arguments. Only needed for testing.
+                  Productive __main__ will call the API without any argument.
+
+    Returns:
+        Numeric exit code
+    """
+    try:
+        config = parse_config(
+            prog=__prog__,
+            version=importlib.metadata.version(__dist_name__),
+            copy_right=__copyright__,
+            author=__author__,
+            arg_list=arg_list,
+        )
+        return _main_logic(config)
+
+    except SystemExit as e:
+        return e.code
+
+    except BaseException as e:  # pylint: disable=broad-exception-caught;reason=Explicitely capture all exceptions thrown during execution.
+        print(
+            f"ERROR: Any error has occured!{os.linesep}{os.linesep}Exception: {str(e)}"
+            # f"Detailed Traceback: {traceback.format_exc()}"
+        )
+        return 1
+
+
+def _main_logic(config: dict) -> int:
+    calendar_ics = download_ics(config.calendar)
+    events = parse_calendar(calendar_ics, config.filter)
+    events = filter_events(events, config.filter, config.calendar.encoding)
+    output_events(events, config)
+
+    return os.EX_OK

icalendar_events_cli/argparse.py

@@ -0,0 +1,207 @@
+"""Argument parsing."""
+
+# ---- Imports ----
+import re
+import sys
+from argparse import ArgumentTypeError
+from datetime import datetime
+from typing import Optional
+
+import pytz
+from jsonargparse import ArgumentParser, DefaultHelpFormatter
+from pydantic import SecretStr
+from rich_argparse import RawTextRichHelpFormatter
+from tzlocal import get_localzone
+
+from .output import OutputFormat
+
+# ---- Globals ---------------------------------------------------------------------------------------------------------
+
+_local_timezone = pytz.timezone(get_localzone().key)
+
+
+# ---- CommandLine parser ----------------------------------------------------------------------------------------------
+class HelpFormatter(DefaultHelpFormatter, RawTextRichHelpFormatter):
+    """Custom CLI help formatter: Combined DefaultHelpFormatter and RichHelpFormatter."""
+
+
+def parse_config(prog: str, version: str, copy_right: str, author: str, arg_list: Optional[list[str]] = None) -> dict:
+    """Parse the configuration from CLI and/or configuration JSON file.
+
+    Arguments:
+        prog: Program name.
+        version: Program version.
+        copy_right: Copyright info.
+        author: Author info.
+        arg_list: Optional command line arguments list.
+
+    Returns:
+        Dict: Parsed configuration options.
+    """
+    arg_parser = ArgumentParser(
+        prog=prog,
+        description="Command-line tool to read events from a iCalendar (ICS) files."
+        + f" | Version {version} | {copy_right}",
+        version=f"| Version {version}\n{copy_right} {author}",
+        default_config_files=["./config.json"],
+        print_config=None,
+        env_prefix="ICALENDAR_EVENTS_CLI",
+        default_env=False,
+        formatter_class=HelpFormatter,
+    )
+
+    arg_parser.add_argument("-c", "--config", action="config", help="""Path to JSON configuration file.""")
+
+    # ---- Calendar URL / access ----
+    arg_parser.add_argument(
+        "--calendar.url",
+        type=str,
+        required=True,
+        help="""URL of the iCalendar (ICS).
+Also URLs to local files with schema file://<absolute path to local file> are supported.""",
+    )
+    arg_parser.add_argument(
+        "--calendar.verify-url",
+        type=bool,
+        default=True,
+        help="Configure SSL verification of the URL",
+    )
+    arg_parser.add_argument(
+        "--calendar.user",
+        type=SecretStr,
+        help="Username for calendar URL HTTP authentication (basic authentication)",
+    )
+    arg_parser.add_argument(
+        "--calendar.password",
+        type=SecretStr,
+        help="Password for calendar URL HTTP authentication (basic authentication)",
+    )
+    arg_parser.add_argument("--calendar.encoding", default="UTF-8", help="Encoding of the calendar")
+
+    # ---- Filtering ----
+
+    arg_parser.add_argument(
+        "-s",
+        "--filter.start-date",
+        type=datetime_isoformat,
+        default=_local_timezone.localize(datetime.now().replace(microsecond=0)).replace(microsecond=0),
+        help="Start date/time of event filter by time (ISO format). Default: now",
+    )
+    arg_parser.add_argument(
+        "-e",
+        "--filter.end-date",
+        type=datetime_isoformat,
+        default=_local_timezone.localize(datetime.combine(datetime.now(), datetime.max.time())).replace(microsecond=0),
+        help="End date/time of event filter by time (ISO format). Default: end of today",
+    )
+
+    arg_parser.add_argument(
+        "-f",
+        "--filter.summary",
+        type=regex_type,
+        required=False,
+        default=None,
+        help="RegEx to filter calendar events based on the summary attribute.",
+    )
+
+    arg_parser.add_argument(
+        "--filter.description",
+        type=regex_type,
+        required=False,
+        default=None,
+        help="RegEx to filter calendar events based on the description attribute.",
+    )
+
+    arg_parser.add_argument(
+        "--filter.location",
+        type=regex_type,
+        required=False,
+        default=None,
+        help="RegEx to filter calendar events based on the location attribute.",
+    )
+
+    # ---- Output ----
+    arg_parser.add_argument(
+        "--output.format",
+        default=OutputFormat.human_readable,
+        type=OutputFormat,
+        help="Output format.",
+    )
+
+    arg_parser.add_argument(
+        "-o",
+        "--output.file",
+        type=Optional[str],
+        help="Path of JSON output file. If not set the output is written to console / stdout",
+    )
+
+    # ---- Finally parse the inputs  ----
+    config = arg_parser.parse_args(args=arg_list)
+
+    # ---- Post-parse validation ----
+    _validate_config(config)
+
+    return config
+
+
+def datetime_isoformat(arg: str) -> datetime:
+    """Convert isoformat cli argument to datetime.
+
+    Arguments:
+        arg: cli argument in ISO format
+
+    Raises:
+        ArgumentTypeError: in case the parsing failed
+
+    Returns:
+        Parsed datetime instance.
+    """
+    try:
+        dt = datetime.fromisoformat(str(arg))
+    except ValueError:
+        raise ArgumentTypeError(f"invalid datetime value (expected ISO 8601 format): '{arg}'") from None
+
+    if dt.tzinfo is None:
+        dt = _local_timezone.localize(dt)
+    return dt
+
+
+def regex_type(arg: str) -> str:
+    """Check if a string is a valid RegEx.
+
+    Arguments:
+        arg: cli argument to be checked
+
+    Raises:
+        ArgumentTypeError: in case the parsing failed
+
+    Returns:
+        unmodified string argument
+    """
+    try:
+        re.compile(arg)
+    except re.error as e:
+        raise ArgumentTypeError(f"invalid RegEx value '{arg}': {e}") from None
+    return arg
+
+
+def _validate_config(config: dict) -> None:
+    """Validate the configuration.
+
+    Arguments:
+        config: Parsed configuration hierarchy.
+    """
+    found_config_issues = []
+
+    if config.filter.start_date > config.filter.end_date:
+        found_config_issues.append(
+            "filter.end-date must be after filter.start-state"
+            + f" (configured: {config.filter.start_date} -> {config.filter.end_date})"
+        )
+
+    # Finally report all found issues
+    if found_config_issues:
+        print("ERROR: invalid configuration / parameters:", file=sys.stderr)
+        for found_config_issue in found_config_issues:
+            print(f"- {found_config_issue}", file=sys.stderr)
+        sys.exit(1)

icalendar_events_cli/argparse.py.orig

@@ -0,0 +1,131 @@
+"""Argument parsing."""
+
+# ---- Imports ----
+from datetime import datetime
+from typing import Optional
+
+import pytz
+from jsonargparse import ArgumentParser, DefaultHelpFormatter
+from pydantic import SecretStr
+from rich_argparse import RawTextRichHelpFormatter
+from tzlocal import get_localzone
+
+from .output import OutputFormat
+
+
+# ---- CommandLine parser ----------------------------------------------------------------------------------------------
+class E3DCCliHelpFormatter(DefaultHelpFormatter, RawTextRichHelpFormatter):
+    """Custom CLI help formatter: Combined DefaultHelpFormatter and RichHelpFormatter."""
+
+
+def parse_config(prog: str, version: str, copy_right: str, author: str, arg_list: Optional[list[str]] = None) -> dict:
+    """Parse the configuration from CLI and/or configuration JSON file.
+
+    Arguments:
+        prog: Program name.
+        version: Program version.
+        copy_right: Copyright info.
+        author: Author info.
+        arg_list: Optional command line arguments list.
+
+    Returns:
+        Dict: Parsed configuration options.
+    """
+    argparser = ArgumentParser(
+        prog=prog,
+        description="Command-line tool to read events from a iCalendar (ICS) files."
+        + f" | Version {version} | {copy_right}",
+        version=f"| Version {version}\n{copy_right} {author}",
+        default_config_files=["./config.json"],
+        print_config=None,
+        env_prefix="ICALENDAR_EVENTS_CLI",
+        default_env=False,
+        formatter_class=E3DCCliHelpFormatter,
+    )
+
+    argparser.add_argument("-c", "--config", action="config", help="""Path to JSON configuration file.""")
+
+    # ---- Calendar URL / access ----
+<<<<<<< HEAD
+    argparser.add_argument("--calendar.url", type=str, help="URL of the iCalendar (ICS)")
+=======
+    argparser.add_argument(
+        "--calendar.url",
+        type=str,
+        help="""URL of the iCalendar (ICS).
+Also URLs to local files with schema file://<absolute path to local file> are supported.""",
+    )
+>>>>>>> 3b6d07f (Use jsonargparse instead argparse)
+    argparser.add_argument(
+        "--calendar.verify-url",
+        type=bool,
+        default=True,
+        help="Configure SSL verification of the URL",
+    )
+    argparser.add_argument(
+        "--calendar.user",
+        type=SecretStr,
+        help="Username for calendar URL HTTP authentication (basic authentication)",
+    )
+    argparser.add_argument(
+        "--calendar.password",
+        type=SecretStr,
+        help="Password for calendar URL HTTP authentication (basic authentication)",
+    )
+    argparser.add_argument("--calendar.encoding", default="UTF-8", help="Encoding of the calendar")
+
+    # ---- Filtering ----
+    argparser.add_argument(
+        "-f",
+        "--filter.summary",
+        default=".*",
+        help="RegEx to filter calendar events based on summary field.",
+    )
+
+    local_timezone = pytz.timezone(get_localzone().key)
+    argparser.add_argument(
+        "-s",
+        "--filter.start-date",
+        type=_datetime_fromisoformat,
+        default=local_timezone.localize(datetime.now().replace(microsecond=0)).replace(microsecond=0),
+        help="Start date/time of event filter by time (ISO format). Default: now",
+    )
+    argparser.add_argument(
+        "-e",
+        "--filter.end-date",
+        type=_datetime_fromisoformat,
+        default=local_timezone.localize(datetime.combine(datetime.now(), datetime.max.time())).replace(microsecond=0),
+        help="End date/time of event filter by time (ISO format). Default: end of today",
+    )
+
+    # ---- Output ----
+    argparser.add_argument(
+        "--output.format",
+        default=OutputFormat.human_readable,
+        type=OutputFormat,
+        help="Output format.",
+    )
+
+    argparser.add_argument(
+        "-o",
+        "--output.file",
+        type=Optional[str],
+        help="Path of JSON output file. If not set the output is written to console / stdout",
+    )
+
+    # ---- Finally parse the inputs  ----
+    args = argparser.parse_args(args=arg_list)
+
+    return args
+
+
+def _datetime_fromisoformat(arg: str) -> datetime:
+    """Convert isoformat cli argument to datetime.
+
+    Arguments:
+        arg: cli argument in ISO format
+
+    Returns:
+        Parsed datetime instance.
+    """
+    return datetime.fromisoformat(str(arg))

icalendar_events_cli/downloader.py

@@ -0,0 +1,33 @@
+"""ICS calender file downloader."""
+
+# ---- Imports ---------------------------------------------------------------------------------------------------------
+import sys
+
+import requests
+from requests_file import FileAdapter
+
+# ---- Functions -------------------------------------------------------------------------------------------------------
+
+
+def download_ics(calendard_config: dict) -> str:
+    """Download ICS calendar file from URL.
+
+    Arguments:
+        calendard_config: Calendar configuration hierarchy.
+
+    Returns:
+        str: Downloaded file content.
+    """
+    session = requests.Session()
+    session.mount("file://", FileAdapter())
+
+    if calendard_config.user is not None and calendard_config.password is not None:
+        session.auth = (calendard_config.user.get_secret_value(), calendard_config.password.get_secret_value())
+    response = session.get(url=calendard_config.url, verify=calendard_config.verify_url)
+    if response.status_code != 200:
+        print(
+            f"ERROR: Failed to download ical contents from URL '{response.url}'. "
+            + f"Response status: {response.reason} (status {response.status_code})",
+        )
+        sys.exit(1)
+    return response.text

icalendar_events_cli/downloader.py.orig

@@ -0,0 +1,36 @@
+"""ICS calender file downloader."""
+
+# ---- Imports ---------------------------------------------------------------------------------------------------------
+import sys
+
+import requests
+from requests_file import FileAdapter
+
+# ---- Functions -------------------------------------------------------------------------------------------------------
+
+
+def download_ics(calendard_config: dict) -> str:
+    """Download ICS calendar file from URL.
+
+    Arguments:
+        calendard_config: Calendar configuration hierarchy.
+
+    Returns:
+        str: Downloaded file content.
+    """
+    session = requests.Session()
+<<<<<<< HEAD
+=======
+    session.mount("file://", FileAdapter())
+
+>>>>>>> 3b6d07f (Use jsonargparse instead argparse)
+    if calendard_config.user is not None and calendard_config.password is not None:
+        session.auth = (calendard_config.user.get_secret_value(), calendard_config.password.get_secret_value())
+    response = session.get(url=calendard_config.url, verify=calendard_config.verify_url)
+    if response.status_code != 200:
+        print(
+            f"ERROR: Failed to download ical contents from URL '{response.url}'. "
+            + f"Response status: {response.reason} (status {response.status_code})",
+        )
+        sys.exit(1)
+    return response.text

icalendar_events_cli/icalendar.py

@@ -0,0 +1,164 @@
+"""Access to icalendar objects and hierarchies."""
+
+# ---- Imports ---------------------------------------------------------------------------------------------------------
+import re
+from datetime import date, datetime, timedelta
+
+import icalendar
+import pytz
+import recurring_ical_events
+from icalendar.cal import Event
+
+# https://urllib3.readthedocs.io/en/stable/user-guide.html
+from recurring_ical_events import CalendarQuery
+from tzlocal import get_localzone
+
+# ---- Globals ---------------------------------------------------------------------------------------------------------
+__local_timezone = pytz.timezone(get_localzone().key)
+
+
+# ---- Functions -------------------------------------------------------------------------------------------------------
+
+
+def parse_calendar(calendar_ics: str, filter_config: dict) -> CalendarQuery:
+    """Parse the calendar.
+
+    Arguments:
+        calendar_ics: Calendar RAW content string.
+        filter_config: Filter configuration hierarchy.
+
+    Returns:
+        CalendarQuery: Parsed CalendarQuery.
+    """
+    calendar = icalendar.Calendar.from_ical(calendar_ics)
+    calendar_components = ["VEVENT"]  # Only events
+    return recurring_ical_events.of(calendar, components=calendar_components).between(
+        filter_config.start_date, filter_config.end_date
+    )
+
+
+def filter_events(events: CalendarQuery, filter_config: dict, encoding: str) -> CalendarQuery:
+    """Filter the calendar.
+
+    Arguments:
+        events: Calendar to be filtered.
+        filter_config: Filter config hierarchy
+        encoding: Summary attribute encoding
+
+    Returns:
+        CalendarQuery: Filtered calendar.
+    """
+    if filter_config.summary is not None:
+        events = filter(
+            lambda event: (summary := get_event_summary(event, encoding)) is not None
+            and re.match(filter_config.summary, summary) is not None,
+            events,
+        )
+
+    if filter_config.description is not None:
+        events = filter(
+            lambda event: (description := get_event_description(event, encoding)) is not None
+            and re.match(filter_config.description, description) is not None,
+            events,
+        )
+
+    if filter_config.location is not None:
+        events = filter(
+            lambda event: (location := get_event_location(event, encoding)) is not None
+            and re.match(filter_config.location, location) is not None,
+            events,
+        )
+
+    return events
+
+
+def get_event_string_attribute(event: Event, attribute_name: str, encoding: str) -> str:
+    """Get any string attribute from event.
+
+    Arguments:
+        event: Calendar Event.
+        attribute_name: Attribute name to be accessed.
+        encoding: Calender encoding.
+
+    Returns:
+        Decoded attribute value.
+    """
+    attribute = event.decoded(attribute_name, default=None)
+    if attribute is not None:
+        attribute = attribute.decode(encoding)
+    return attribute
+
+
+def get_event_summary(event: Event, encoding: str) -> str:
+    """Get 'SUMMARY' attribute of calendar event.
+
+    Arguments:
+        event: Calendar Event.
+        encoding: Calendar encoding
+
+    Returns:
+        Summary attribute.
+    """
+    return get_event_string_attribute(event, "SUMMARY", encoding)
+
+
+def get_event_description(event: Event, encoding: str) -> str:
+    """Get 'DESCRIPTION' attribute of calendar event.
+
+    Arguments:
+        event: Calendar Event.
+        encoding: Calendar encoding
+
+    Returns:
+        Description attribute.
+    """
+    return get_event_string_attribute(event, "DESCRIPTION", encoding)
+
+
+def get_event_location(event: Event, encoding: str) -> str:
+    """Get 'LOCATION' attribute of calendar event.
+
+    Arguments:
+        event: Calendar Event.
+        encoding: Calendar encoding
+
+    Returns:
+        Location attribute.
+    """
+    return get_event_string_attribute(event, "LOCATION", encoding)
+
+
+def get_event_dtstart(event: Event) -> date:
+    """Get 'DTSTART' start-date of calendar event.
+
+    Arguments:
+        event: Calendar Event.
+
+    Returns:
+        Start Date.
+    """
+    start = event.decoded("DTSTART")
+    if isinstance(start, date) and not isinstance(start, datetime):
+        # Convert full-day event to datetime
+        start = datetime.combine(start, datetime.min.time())
+        start = __local_timezone.localize(start)
+    return start
+
+
+def get_event_dtend(event: Event) -> date:
+    """Get 'DTEND' end-date of calendar event.
+
+    Arguments:
+        event: Calendar Event.
+
+    Returns:
+        End Date.
+    """
+    end = event.decoded("DTEND")
+    if end.resolution == timedelta(days=1):
+        # For full-day events the DTEND is always one day after DTSTART.
+        # Therefore subtract 1 day and then set time to end of day
+        end -= timedelta(days=1)
+        end = datetime.combine(end, datetime.max.time()).replace(microsecond=0)
+        end = __local_timezone.localize(end)
+    return end

icalendar_events_cli/output.py

@@ -0,0 +1,133 @@
+"""Handling of different output target and formats."""
+
+# ---- Imports ---------------------------------------------------------------------------------------------------------
+import json
+import os
+import sys
+from enum import Enum
+
+from recurring_ical_events import CalendarQuery
+
+from .icalendar import get_event_description, get_event_dtend, get_event_dtstart, get_event_location, get_event_summary
+
+# ---- Functions -------------------------------------------------------------------------------------------------------
+
+
+class OutputFormat(Enum):
+    """All possible output formats."""
+
+    human_readable = "human_readable"  # pylint: disable=invalid-name;reason=camel_case style wanted for cli param
+    json = "json"  # pylint: disable=invalid-name;reason=camel_case style wanted for cli param
+
+
+def output_events(events: CalendarQuery, config: dict) -> None:
+    """Output the calendar.
+
+    Arguments:
+        events: Calendar events.
+        config: Configuration hierarchy.
+    """
+    sorted_events = _sort_events(events)
+
+    if config.output.format == OutputFormat.json:
+        output_json(sorted_events, config)
+    else:
+        output_human_readable(sorted_events, config)
+
+
+def output_json(events: CalendarQuery, config: dict) -> None:
+    """Output the events in JSON format.
+
+    Arguments:
+        events: Calendar events.
+        config: Configuration hierarchy.
+    """
+    filters = {"start-date": config.filter.start_date.isoformat(), "end-date": config.filter.end_date.isoformat()}
+    if config.filter.summary:
+        filters["summary"] = config.filter.summary
+    if config.filter.description:
+        filters["description"] = config.filter.description
+    if config.filter.location:
+        filters["location"] = config.filter.location
+
+    # Detailed Events List
+    events_output = []
+    for event in events:
+        event_output = {
+            "start-date": get_event_dtstart(event).isoformat(),
+            "end-date": get_event_dtend(event).isoformat(),
+            "summary": get_event_summary(event, config.calendar.encoding),
+        }
+        description = get_event_description(event, config.calendar.encoding)
+        if description is not None:
+            event_output["description"] = description
+
+        location = get_event_location(event, config.calendar.encoding)
+        if location is not None:
+            event_output["location"] = location
+        events_output.append(event_output)
+
+    json_hierarchy = {"filter": filters, "events": events_output}
+
+    # Finally output the JSON hierarchy to stdout or the configured file
+    if config.output.file is None:
+        json.dump(json_hierarchy, fp=sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        with open(config.output.file, "w", encoding="utf-8") as file:
+            json.dump(json_hierarchy, fp=file, indent=2, ensure_ascii=False)
+
+
+def output_human_readable(events: CalendarQuery, config: dict) -> None:
+    """Output the events in human readable format.
+
+    Arguments:
+        events: Calendar events.
+        config: Configuration hierarchy.
+    """
+    output = []
+
+    output.append(f"Start Date:         {config.filter.start_date.isoformat()}")
+    output.append(f"End Date:           {config.filter.end_date.isoformat()}")
+    if config.filter.summary:
+        output.append(f"Summary Filter:     {config.filter.summary}")
+    if config.filter.description:
+        output.append(f"Description Filter: {config.filter.description}")
+    if config.filter.location:
+        output.append(f"Location Filter:    {config.filter.location}")
+    output.append(f"Number of Events:   {len(events)}{os.linesep}")
+
+    for event in events:
+        start = get_event_dtstart(event)
+        end = get_event_dtend(event)
+        summary = get_event_summary(event, config.calendar.encoding)
+        description = get_event_description(event, config.calendar.encoding)
+        location = get_event_location(event, config.calendar.encoding)
+
+        duration = end - start
+        start_end_string = f"{start.isoformat()} -> {end.isoformat()} [{duration.total_seconds():.0f} sec]"
+        opt_description_string = f" | Description: {description}" if description is not None else ""
+        opt_location_string = f" | Location: {description}" if location is not None else ""
+
+        output.append(f"{start_end_string: <70} | {summary}{opt_description_string}{opt_location_string}")
+
+    # build final output string incl. line separators
+    output = os.linesep.join(output)
+
+    # Finally output to stdout or the configured file
+    if config.output.file is None:
+        print(output)
+    else:
+        with open(config.output.file, "w", encoding="utf-8") as file:
+            file.write(output)
+
+
+def _sort_events(events: CalendarQuery) -> CalendarQuery:
+    """Sort calendar.
+
+    Arguments:
+       events: Calendar to be sorted.
+
+    Returns:
+        CalendarQuery: Sorted calendar.
+    """
+    return sorted(events, key=get_event_dtstart, reverse=False)

icalendar_events_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,249 @@
+Metadata-Version: 2.1
+Name: icalendar-events-cli
+Version: 1.0.0
+Summary: Command-line tool to read events from a iCalendar (ICS)
+Author-Email: Sebastian Waldvogel <sebastian@waldvogels.de>
+License: MIT
+Project-URL: Repository, https://github.com/waldbaer/icalendar-events-cli
+Requires-Python: >=3.9
+Requires-Dist: tzlocal==5.2
+Requires-Dist: pytz==2024.2
+Requires-Dist: recurring-ical-events==3.4.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: requests-file>=2.1.0
+Requires-Dist: jsonargparse>=4.36.0
+Requires-Dist: rich-argparse>=1.6.0
+Requires-Dist: pydantic>=2.10.5
+Description-Content-Type: text/markdown
+
+[![PyPI version](https://badge.fury.io/py/icalendar-events-cli.svg)](https://badge.fury.io/py/icalendar-events-cli)
+[![MIT License](https://img.shields.io/github/license/waldbaer/icalendar-events-cli?style=flat-square)](https://opensource.org/licenses/MIT)
+[![GitHub issues open](https://img.shields.io/github/issues/waldbaer/icalendar-events-cli?style=flat-square)](https://github.com/waldbaer/icalendar-events-cli/issues)
+[![GitHub Actions](https://github.com/waldbaer/icalendar-events-cli/actions/workflows/python-pdm.yml/badge.svg?branch=master)](https://github.com/waldbaer/icalendar-events-cli/actions/workflows/python-pdm.yml)
+
+
+# Command-line tool to read icalendar events
+
+## Introduction
+
+This command-line tool allows users to query and filter [iCalendar (RFC 5545)](https://icalendar.org/RFC-Specifications/iCalendar-RFC-5545/) calendars. It leverages the excellent [recurring-ical-events](https://github.com/niccokunzmann/python-recurring-ical-events) library for parsing and querying the calendar contents.
+
+Leveraging the powerful [jsonargparse](https://jsonargparse.readthedocs.io/) library, this tool supports configuration and control via command-line parameters or a JSON configuration file.
+
+## Features ##
+- Download and parse iCalendar files
+  - from remote HTTP URL (`https://<path to icalendar server>`)
+  - from local file URL (`file://<abs. path to local ICS file>`)
+  - configurable encoding
+- Filtering
+  - by start- and end-date range
+  - by event summary, description or location text (RegEx match)
+- Different Outputs
+  - Formats: JSON, human-readable (pretty printed)
+  - Targets: shell (stdout), file
+
+## Changelog
+Changes can be followed at [CHANGELOG.md](https://github.com/waldbaer/icalendar-events-cli/blob/master/CHANGELOG.md).
+
+## Requirements ##
+
+ - [Python 3.9](https://www.python.org/)
+ - [pip](https://pip.pypa.io/) or [pipx](https://pipx.pypa.io/stable/)
+
+ For development:
+ - [python-pdm (package dependency manager)](https://pdm-project.org/)
+
+## Setup
+
+### With pip / pipx
+```
+pip install icalendar-events-cli
+pipx install icalendar-events-cli
+```
+
+### Setup directly from github repo / clone
+```
+git clone git@github.com:waldbaer/icalendar-events-cli.git
+cd icalendar-events-cli
+
+python -m venv .venv
+source ./.venv/bin/activate
+pip install .
+```
+
+## Usage
+
+All parameters can be provided either as command-line arguments or through a JSON configuration file (default: `config.json`).
+A combination of both methods is also supported.
+
+A common approach is to define the calendar URL and HTTP authentication credentials in the JSON configuration file,
+while specifying filters as command-line arguments.
+Alternatively, you can define all credentials via command-line parameters or include the applied filters directly in the
+JSON configuration file.
+
+The results of all executed queries are returned in human-readable (pretty-printed) or
+machine-readable JSON format.
+This output can be displayed directly on the shell (stdout) or saved to a file.
+
+The machine-readable JSON output format is designed for seamless integration with automation
+platforms, such as [Node-RED](https://nodered.org/), which typically execute the
+`icalendar-events-cli` tool.
+
+
+
+### Examples
+
+#### Example 1: Query Public Holiday Calendar
+
+- Use human-readable output format
+- Pass all parameters as command-line arguments
+
+```
+icalendar-events-cli --calendar.url https://www.thunderbird.net/media/caldata/autogen/GermanHolidays.ics \
+  --filter.start-date $(date +%Y)-01-01T02:00:00+02:00 \
+  --filter.end-date $(date +%Y)-12-31T02:00:00+01:00 \
+  --filter.summary ".*(Weihnacht|Oster).*"
+
+Start Date:         2025-01-01T02:00:00+02:00
+End Date:           2025-12-31T02:00:00+01:00
+Summary Filter:     .*(Weihnacht|Oster).*
+Number of Events:   3
+
+2025-04-20T00:00:00+02:00 -> 2025-04-20T23:59:59+02:00 [86399 sec]     | Ostersonntag  (Brandenburg) | Description: Common local holiday -  Der Ostersonntag ist laut der christlichen Bibel ein Feiertag in Deutschland, um die Auferstehung Jesu Christi zu feiern.
+2025-04-21T00:00:00+02:00 -> 2025-04-21T23:59:59+02:00 [86399 sec]     | Ostermontag  | Description: Christian -  Viele Menschen in Deutschland begehen jährlich den Ostermontag am Tag nach dem Ostersonntag. Es ist in allen Bundesstaaten ein Feiertag.
+2025-12-25T00:00:00+01:00 -> 2025-12-25T23:59:59+01:00 [86399 sec]     | Weihnachten  | Description: Christian -  Der Weihnachtstag markiert die Geburt Jesu Christi und ist ein gesetzlicher Feiertag in Deutschland. Es ist jedes Jahr am 25. Dezember.
+```
+
+#### Example 2: Query School Vacation Calendar
+
+The machine-readable JSON output format is designed for seamless integration with automation platforms, such as [Node-RED](https://nodered.org/), which typically execute the `icalendar-events-cli` tool.
+
+- Use JSON output format++
+- Mixed parameter configuration: Pass only end-date as command-line argument.
+
+Create `school-summer-vacation.json` containing calendar URL, summary filter and output format settings:
+```
+{
+  "calendar" : {
+      "url" : "https://www.feiertage-deutschland.de/kalender-download/ics/schulferien-baden-wuerttemberg.ics",
+      "verify_url": true
+  },
+  "filter": {
+    "summary": "Sommer.*"
+  },
+  "output": {
+    "format": "json"
+  }
+}
+```
+
+Query the calendar for summer vacation until end of next year:
+```
+icalendar-events-cli --config school-summer-vacation.json --filter.end-date $(($(date +%Y) + 1))-12-31T23:59:59
+
+{
+  "filter": {
+    "start-date": "2025-01-25T11:09:20+01:00",
+    "end-date": "2026-12-31T23:59:59+01:00",
+    "summary": "Sommer.*"
+  },
+  "events": [
+    {
+      "start-date": "2025-07-31T00:00:00+02:00",
+      "end-date": "2025-09-13T23:59:59+02:00",
+      "summary": "Sommerferien Baden-Württemberg 2025",
+      "description": "Schulferien 2025: https://www.feiertage-deutschland.de/schulferien/2025/",
+      "location": "BW"
+    },
+    {
+      "start-date": "2026-07-30T00:00:00+02:00",
+      "end-date": "2026-09-12T23:59:59+02:00",
+      "summary": "Sommerferien Baden-Württemberg 2026",
+      "description": "Schulferien 2026: https://www.feiertage-deutschland.de/schulferien/2026/",
+      "location": "BW"
+    }
+  ]
+}
+```
+
+
+### All Available Parameters and Configuration Options
+
+Details about all available options:
+
+```
+Usage: icalendar-events-cli [-h] [--version] [-c CONFIG] --calendar.url URL [--calendar.verify-url {true,false}]
+                            [--calendar.user USER] [--calendar.password PASSWORD] [--calendar.encoding ENCODING]
+                            [-s START_DATE] [-e END_DATE] [-f SUMMARY] [--filter.description DESCRIPTION]
+                            [--filter.location LOCATION] [--output.format {human_readable,json}] [-o FILE]
+
+Command-line tool to read events from a iCalendar (ICS) files. | Version 1.0.0 | Copyright 2023-2025
+
+Default Config File Locations:
+  ['./config.json'], Note: no existing default config file found.
+
+Options:
+  -h, --help            Show this help message and exit.
+  --version             Print version and exit.
+  -c, --config CONFIG   Path to JSON configuration file.
+  --calendar.url URL    URL of the iCalendar (ICS).
+                        Also URLs to local files with schema file://<absolute path to local file> are supported. (required, type: None)
+  --calendar.verify-url {true,false}
+                        Configure SSL verification of the URL (type: None, default: True)
+  --calendar.user USER  Username for calendar URL HTTP authentication (basic authentication) (type: None, default: None)
+  --calendar.password PASSWORD
+                        Password for calendar URL HTTP authentication (basic authentication) (type: None, default: None)
+  --calendar.encoding ENCODING
+                        Encoding of the calendar (default: UTF-8)
+  -s, --filter.start-date START_DATE
+                        Start date/time of event filter by time (ISO format). Default: now (type: datetime_isoformat, default: now)
+  -e, --filter.end-date END_DATE
+                        End date/time of event filter by time (ISO format). Default: end of today (type: datetime_isoformat, default: end of today)
+  -f, --filter.summary SUMMARY
+                        RegEx to filter calendar events based on the summary attribute. (type: regex_type, default: None)
+  --filter.description DESCRIPTION
+                        RegEx to filter calendar events based on the description attribute. (type: regex_type, default: None)
+  --filter.location LOCATION
+                        RegEx to filter calendar events based on the location attribute. (type: regex_type, default: None)
+  --output.format {human_readable,json}
+                        Output format. (type: None, default: human_readable)
+  -o, --output.file FILE
+                        Path of JSON output file. If not set the output is written to console / stdout (type: None, default: None)
+```
+
+
+## Development
+
+### Setup environment
+
+```
+pdm install --dev
+```
+
+### Format / Linter / Tests
+
+```
+# Check code style
+pdm run format
+
+# Check linter
+pdm run lint
+
+# Run tests
+pdm run tests
+```
+
+### Publish
+
+```
+# API token will be requested interactively as password
+pdm publish -u __token__
+
+# or to test.pypi.org
+pdm publish --repository testpypi -u __token__
+```
+
+## Acknowledgments
+Special thanks to [recurring-ical-events](https://github.com/niccokunzmann/python-recurring-ical-events) for providing
+the core library that powers this tool.
+

icalendar_events_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+icalendar_events_cli-1.0.0.dist-info/METADATA,sha256=fmfMuo8IGNHOaw7SoxxylekqN5bzKyDheXV581PMWsw,10023
+icalendar_events_cli-1.0.0.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
+icalendar_events_cli-1.0.0.dist-info/entry_points.txt,sha256=R1ZEdlwKR2jVWZUrZd6Ow3Z06GuXEHn3DNFi0t-fJlo,91
+icalendar_events_cli-1.0.0.dist-info/licenses/LICENSE,sha256=VMNRqNjjlAj58av8QYDG29jshQvvIM8YfpS50NBcBPI,1085
+icalendar_events_cli/__init__.py,sha256=fUje7vgFT24oJYk375-geUaz4RIVixNYE5PqOL9VmUo,19
+icalendar_events_cli/__main__.py,sha256=6X7Faf6vK7DovEfpKiQNXvCTRjWEie8S5AB22dUbzhI,2040
+icalendar_events_cli/argparse.py,sha256=8B56Vcfnyi066w4gfb2fPYknEk7LMdwAc2DqV_jFdt8,6299
+icalendar_events_cli/argparse.py.orig,sha256=hOpOKCgf4NL4dwdC6YOVmL1qgtzh86POGpvwBrXaVUs,4285
+icalendar_events_cli/downloader.py,sha256=5fOPyAevWSSZnK4C0w8VqYEjqEuaMZO6_SuDQsTDpNg,1214
+icalendar_events_cli/downloader.py.orig,sha256=IKeUeAsDe7RV3eM7SvsDcxZa9jXLJfPBf4-Pp8U7zSY,1287
+icalendar_events_cli/icalendar.py,sha256=RSEXJQeeolvpGt1BSMomid6ufh6mzYmsMQKqqtex3wc,4927
+icalendar_events_cli/output.py,sha256=u_rgZd1-T83RZQAIJkTAbORI-32Vjpv7a2SAoEP1CjQ,4970
+icalendar_events_cli-1.0.0.dist-info/RECORD,,

icalendar_events_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.3)
+Root-Is-Purelib: true
+Tag: py3-none-any

icalendar_events_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+icalendar-events-cli = icalendar_events_cli.__main__:cli
+
+[gui_scripts]
+

icalendar_events_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Sebastian Waldvogel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.