Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
version: 2
formats: all
build:
os: ubuntu-24.04
tools:
python: "3.14"
commands:
- git fetch --tags
- pip install -r docs/requirements.txt
- pip install -e .
- sphinx-build docs/ $READTHEDOCS_OUTPUT/html/
14 changes: 14 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
SPHINXBUILD = .venv/bin/sphinx-build
DOCS_DIR = .
BUILDDIR = _build

.venv:
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e ..

html: .venv
$(SPHINXBUILD) -W $(DOCS_DIR) $(BUILDDIR)/html

clean:
rm -rf $(BUILDDIR) .venv
26 changes: 26 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
import datetime
import importlib.metadata

project = "ics-query"
this_year = datetime.date.today().year
copyright = f"{this_year}, Nicco Kunzmann"
release = version = importlib.metadata.version("ics-query")

extensions = [
"sphinx.ext.intersphinx",
"sphinx_copybutton",
"myst_parser",
]

Comment thread
SashankBhamidi marked this conversation as resolved.
Resolved
html_theme = "pydata_sphinx_theme"
html_theme_options = {
"github_url": "https://github.com/pycalendar/ics-query",
Comment thread
SashankBhamidi marked this conversation as resolved.
Resolved
"icon_links": [
{
"name": "PyPI",
"url": "https://pypi.org/project/ics-query",
"icon": "fa-solid fa-download",
"type": "fontawesome",
},
],
}
44 changes: 44 additions & 0 deletions docs/download.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Download

Pre-built binaries are available on the [Releases] page.
No Python installation required.

## Windows

Download `ics-query.exe` from the [Releases] page and run it directly:

```shell
ics-query.exe --version
```

## Linux (x86_64)

Download `ics-query-linux-x86_64` from the [Releases] page.
Make it executable and run it:

```shell
chmod +x ics-query-linux-x86_64
./ics-query-linux-x86_64 --version
```

To use it without the path prefix, move it somewhere on your PATH:

```shell
mv ics-query-linux-x86_64 ~/.local/bin/ics-query
ics-query --version
```

## macOS

macOS binaries are not provided.
Use [Homebrew or pip](install.md) instead.

## Verifying the download

After downloading, check that the version matches the release you downloaded:

```shell
ics-query --version
```

[Releases]: https://github.com/pycalendar/ics-query/releases
Comment thread
SashankBhamidi marked this conversation as resolved.
Resolved
236 changes: 236 additions & 0 deletions docs/examples.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,236 @@
# Examples

`ics-query` takes a command, a time argument, one or more calendar files, and an output.
Pass `-` as the calendar to read from stdin. Pass `-` as the output to write to stdout.

```shell
ics-query at 2019-03-04 calendar.ics -
```

## Events at a specific time

Use `at` to get all occurrences at a date, month, year, or precise time.

Get everything happening on a specific day:

```shell
ics-query at 2019-03-04 calendar.ics -
```

Get everything happening this month:

```shell
ics-query at `date +%Y-%m` calendar.ics -
```

Get everything happening right now (to the second):

```shell
ics-query at `date +%Y%m%d%H%M%S` calendar.ics -
```

Accepted time formats for `at` and for the `START` argument of `between`:

| Format | Description |
| ------ | ----------- |
| `2019` | all of 2019 |
| `2019-08` | August 2019 |
| `2019-08-12` | 12 August 2019 |
| `2019-08-12T17` | 17:00 to 18:00 on 12 August 2019 |
| `2019-08-12T17:20` | 17:20 to 17:21 on 12 August 2019 |
| `2019-08-12T17:20:00` | exactly 17:20:00 on 12 August 2019 |

Compact formats without separators are also accepted: `20190812`, `20190812T1720`, `201908121720`.

## Events within a time span

Use `between` to get occurrences between a start and an end.
Start is inclusive, end is exclusive.

Get events in the next 7 days:

```shell
ics-query between `date +%Y%m%d` +7d calendar.ics -
```

Get events between two specific dates:

```shell
ics-query between 2024-05-01 2024-06-10 calendar.ics events.ics
```

Get events around New Year's Eve midnight:

```shell
ics-query between 2025-12-31T21:00 +6h calendar.ics -
```

The `END` argument can be a relative duration after `START`:

| Duration | Description |
| -------- | ----------- |
| `+1d` | one day |
| `+1h` | one hour |
| `+1m` | one minute |
| `+1s` | one second |
| `+3600s` | one hour as seconds |
| `+5d10h` | five days and 10 hours |

The `+` prefix is optional.

## First occurrence

Use `first` to get only the first occurrence in each calendar file.

```shell
ics-query first calendar.ics -
```

## All occurrences

Use `all` to get every occurrence in a calendar.

```shell
ics-query all calendar.ics -
```

Calendars with recurring events can produce a very large number of occurrences.
Use `head` to limit the output:

```shell
ics-query all calendar.ics - | head -100
```

## Filtering by component type

By default, `ics-query` returns `VEVENT`, `VTODO`, and `VJOURNAL` components.
Use `-c` or `--component` to filter.

Only events:

```shell
ics-query at 2024-08 -c VEVENT calendar.ics -
```

Only to-dos:

```shell
ics-query at 2024-08 -c VTODO calendar.ics -
```

Only journal entries:

```shell
ics-query at 2024-08 -c VJOURNAL calendar.ics -
```

Pass `-c` multiple times to include more than one type:

```shell
ics-query at 2024-08 -c VEVENT -c VTODO calendar.ics -
```

You can also set the component via environment variable:

```shell
export ICS_QUERY_COMPONENT=VEVENT
ics-query at 2024-08 calendar.ics -
```

## Querying alarms

Use `-c VALARM` to query components by their alarm times.
`VALARM` is not included in the default output.

Alarms behave differently from other components:

- The parent component (`VEVENT`, `VTODO`) may fall outside the queried time span
while the alarm falls within it, and it will still be included.
- Absolute alarms may appear only once, not for every recurrence.
- Each result contains only one alarm.
- Do not mix `-c VALARM` with other types. You will not be able to tell whether
the alarm or the parent component matched the time span.

Get all alarms and show their trigger time and event summary:

```shell
ics-query all -c VALARM calendar.ics - | grep -E 'TRIGGER|SUMMARY'
```

## Timezones

By default, `ics-query` uses each component's own timezone.
Two events at 6am in different timezones both appear when you query by date,
even though they are hours apart in absolute time.

Use `--tz` to query in a specific timezone:

```shell
ics-query at --tz=Europe/Berlin 2024-08-20 calendar.ics -
```

Use `--tz=localtime` to query in your local system timezone:

```shell
ics-query at --tz=localtime 2024-08-20 calendar.ics -
```

Use `--tz=UTC` for UTC:

```shell
ics-query at --tz=UTC 2024-08-20 calendar.ics -
```

Set the timezone via environment variable:

```shell
export ICS_QUERY_TZ=Europe/Berlin
ics-query at 2024-08-20 calendar.ics -
```

List all available timezone names:

```shell
ics-query --available-timezones
```

## Valid ICS output

By default, the output contains only the matched components with no `VCALENDAR` wrapper
and no `VTIMEZONE`. This is intentional for piping into other tools.

To produce a valid `.ics` file that calendar applications can open, use `--as-calendar`:

```shell
ics-query at --as-calendar 2014-05-03 calendar.ics output.ics
```

The output is wrapped in a `VCALENDAR` block and includes any `VTIMEZONE` components
from the source calendar.

You can also set this via environment variable:

```shell
export ICS_QUERY_AS_CALENDAR=1
ics-query at 2014-05-03 calendar.ics output.ics
```

## Multiple calendars

Pass multiple files directly:

```shell
ics-query at 2024-08 calendar1.ics calendar2.ics -
```

Or concatenate them through stdin:

```shell
cat calendar1.ics calendar2.ics | ics-query at 2024-08 - -
```

## Fetching a calendar from the web

```shell
wget -qO- 'https://example.com/calendar.ics' | ics-query at 2024-08 - -
```
13 changes: 13 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# ics-query

Find out what happens in ICS calendar files - query and filter RFC 5545 compatible `.ics` files for events, journals, TODOs and more.

```{toctree}
:maxdepth: 1

overview
install
download
examples
maintenance
```
Loading