Metadata-Version: 2.1
Name: icalendar-events-cli
Version: 2.0.0
Summary: Command-line tool to read and filter events from iCalendar (RFC 5545) or jCal (RFC 7265) calendars
Author-Email: Sebastian Waldvogel <sebastian@waldvogels.de>
License: MIT
Project-URL: Repository, https://github.com/waldbaer/icalendar-events-cli
Requires-Python: >=3.10
Requires-Dist: tzlocal==5.3.1
Requires-Dist: pytz==2026.1.post1
Requires-Dist: icalendar==7.0.3
Requires-Dist: recurring-ical-events==3.8.1
Requires-Dist: requests==2.32.5
Requires-Dist: requests-file==3.0.1
Requires-Dist: jsonargparse==4.42.0
Requires-Dist: rich-argparse==1.7.2
Requires-Dist: pydantic==2.12.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://datatracker.ietf.org/doc/html/rfc5545)) or
jCal ([RFC 7265](https://datatracker.ietf.org/doc/html/rfc7265)) or
calendars.

It leverages the excellent [icalendar](https://github.com/collective/icalendar) and
[recurring-ical-events](https://github.com/niccokunzmann/python-recurring-ical-events) libraries
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 iCalendar/ICS or jCal file>`)
- Filtering
  - by start- and end-date range
  - by event summary, description or location text (RegEx match)
- Different Outputs
  - Formats: JSON, jCal ([RFC 7265](https://datatracker.ietf.org/doc/html/rfc7265)), 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.10](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
```bash
pip install icalendar-events-cli
pipx install icalendar-events-cli
```

### Setup directly from github repo / clone
```bash
git clone https://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

```bash
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:         2026-01-01T02:00:00+02:00
End Date:           2026-12-31T02:00:00+01:00
Summary Filter:     .*(Weihnacht|Oster).*
Number of Events:   3

2026-04-05T00:00:00+02:00 -> 2026-04-05T23: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.
2026-04-06T00:00:00+02:00 -> 2026-04-06T23: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.
2026-12-25T00:00:00+01:00 -> 2026-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:
```json
{
  "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:
```bash
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"
    }
  ]
}
```

#### Example 3: Convert iCalendar ([RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)) to jCal ([RFC 7265](https://datatracker.ietf.org/doc/html/rfc7265)) format

- Use `jcal` output format

```bash
icalendar-events-cli --calendar.url https://www.thunderbird.net/media/caldata/autogen/GermanHolidays.ics \
  --filter.start-date 1900-01-01T02:00:00+02:00 \
  --filter.end-date 2500-12-31T02:00:00+01:00 \
  --output.format jcal \
  --output.file ./GermanHolidays.json
```

Example jCal contents of the converted `GermanHolidays.json`.
The passed filter criterias are added as `x-filter-...` attributes to the jCal output (`x-filter-date-range`, `x-filter-summary`, `x-filter-description`, `x-filter-location`).
```json
[
  "vcalendar",
  [
    ...
    [
      "x-filter-date-range",
      {},
      "period",
      [
        "1900-01-01T02:00:00+02:00",
        "2500-12-31T02:00:00+01:00"
      ]
    ]
  ],
  [
    [
      "vevent",
      [
        [
          "summary",
          {},
          "text",
          "Neujahrstag "
        ],
  ...
]
```

Parse and filter the converted jCal calendar again producing same result as the first example.
```bash
icalendar-events-cli --calendar.url file://$(pwd)/GermanHolidays.json \
  --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:         2026-01-01T02:00:00+02:00
End Date:           2026-12-31T02:00:00+01:00
Summary Filter:     .*(Weihnacht|Oster).*
Number of Events:   3

2026-04-05T00:00:00+02:00 -> 2026-04-05T23: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.
2026-04-06T00:00:00+02:00 -> 2026-04-06T23: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.
2026-12-25T00:00:00+01:00 -> 2026-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.
```



### All Available Parameters and Configuration Options

Details about all available options:

```bash
Usage: icalendar-events-cli [-h] [--version] [-c CONFIG] --calendar.url URL [--calendar.verify-url {true,false}] [--calendar.user USER] [--calendar.password PASSWORD] [-s START_DATE]
                            [-e END_DATE] [-f SUMMARY] [--filter.description DESCRIPTION] [--filter.location LOCATION] [--output.format {human_readable,json,jcal}] [-o FILE]

Command-line tool to read and filter events from iCalendar (RFC 5545) or jCal (RFC 7265) calendars. | Version 2.0.0 | Copyright 2023-2026

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 calendar (iCalendar or jCal format).
                        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)
  -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: now)
  -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,jcal}
                        Output format. (type: None, default: human_readable)
  -o, --output.file FILE
                        Path of output file. If not set the output is written to console / stdout (type: None, default: None)
```


## Development

### Setup environment

```bash
pdm install --dev
```

### Update dependencies to latest versions

```bash
pdm update --unconstrained --save-exact --no-sync
```

### Format / Linter / Tests

```bash
# Check code style
pdm run format

# Check linter
pdm run lint

# Run tests
pdm run tests
```

### Publish

Done automatically by github workflow / actions.

## Acknowledgments
Special thanks to [icalendar](https://github.com/collective/icalendar) and [recurring-ical-events](https://github.com/niccokunzmann/python-recurring-ical-events) for providing the core libraries that power this tool.

