Find out what happens in ICS calendar files - query and filter RFC 5545 compatible .ics files for events, journals, TODOs and more.
Project description
ics-query
Find out what happens in ICS calendar files - query and filter RFC 5545 compatible .ics
files for events, journals, TODOs and more.
Installation
You can install this package from the PyPI.
pip install ics-query
For Windows, you can download ics-query.exe
from our Releases.
Support
- Support using GitHub Sponsors
- Fund specific issues using Polar
- Support using Open Collective
- Support using thanks.dev
We accept donations to sustain our work, once or regular. Consider donating money to open-source as everyone benefits.
Supported Features
This library is based on
For a list of supported features and RFC compatibility, please refer to their documentation, too.
Usage
ics-query
is a command line tool that aims to make icalendar occurance calculations
accessible and easy.
This section walks you though the different functionalities.
ics-query --help
Examples
You can get a calendar from the web and see what is on. In this example, we show which German National Holidays happening in August 2024:
$ 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.
$ 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.
$ cat calendar1.ics calendar2.ics | ics-query at `date +%Y%m%d%H%M%S` - -
BEGIN:VEVENT
...
Piping calendars
You can pipe one or more calendars into the input.
cat calendar.ics | ics-query first -
Events at Certain Times
You can query which events happen at certain times:
ics-query at TIME calendar.ics -
The format of TIME:
TIME | description |
---|---|
2019 |
the whole year 2019 |
2019-08 |
August 2019 |
2019-08-12 |
12th of August 2019 |
2019-08-12T17 |
17:00-18:00 at the 12th of August 2019 |
2019-08-12T17:20 |
17:20-17:21 at the 12th of August 2019 |
2019-08-12T17:20:00 |
17:20 at the 12th of August 2019 |
Please see the command documentation for more help:
ics-query at --help
ics-query --help
You can get all events that happen at a certain day.
ics-query at --components VEVENT 2029-12-24 calendar.ics
You can get all events that happen today.
ics-query at --components VEVENT `date +%Y-%m-%d` calendar.ics
You can get all TODOs that happen in a certain month.
ics-query at --components VTODO 2029-12-24 calendar.ics
Events within a Time Span
You can query which events happen between certain times:
ics-query between START END calendar.ics -
ics-query between START DURATION calendar.ics -
Please see the command documentation for more help:
ics-query between --help
ics-query --help
The format of START and END with examples:
START or END | Description |
---|---|
2019 |
the whole year 2019 |
2019-08 |
August 2019 |
2019-08-12 |
12th of August 2019 |
2019-08-12T17 |
17:00-18:00 at the 12th of August 2019 |
2019-08-12T17:20 |
17:20-17:21 at the 12th of August 2019 |
2019-08-12T17:20:00 |
17:20 at the 12th of August 2019 |
Instead of an absolute time, you can specify a duration after the START.
The +
is optional.
DURATION | Description |
---|---|
+1d |
one more day |
+1h |
one more hour |
+1m |
one more minute |
+1s |
one more second |
+3600s |
one more hour or 3600 seconds |
+5d10h |
five more days and 10 more hours |
Time Span Examples
This example returns the occurrences within the next week:
ics-query between `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:
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:
ics-query between 2025-12-31T21:00 +6h calendar.ics events.ics
ics-query all
- the whole calendar
You can get everything that is happening in a calendar but that can be a lot!
ics-query all calendar.ics
Filtering Components
We support different component types: VEVENT
, VJOURNAL
and VTODO
.
By default, we include all types in the result.
You can specify which components you would like to get using the
--component
or -c
parameter.
-c VEVENT # only events
-c VTODO # only TODOs
-c VJOURNAL # only journal entries
-c VEVENT -c VTODO # only events and journal entries
This example returns the first event of a calendar.
ics-query first -c VEVENT calendar.ics -
This option is also available as ICS_QUERY_COMPONENT
variable.
export ICS_QUERY_COMPONENT=VEVENT
# from now on, you will get only events
ics-query first calendar.ics
Please see the command documentation for more help:
ics-query --help
Timezones
You can set the timezone of the query, otherwise the event's local timezone is used and you might miss events in your own timezone.
The first event at New Year 2000 in the event's local time:
ics-query at 2000-01-01 calendar.ics
The first event at New Year 2000 in your local time:
ics-query at --tz=localtime 2000-01-01 calendar.ics
The first event at New Year 2000 in UTC:
ics-query at --tz=UTC 2000-01-01 calendar.ics
The first event at New Year 2000 in Berlin time:
ics-query at --tz=Europe/Berlin 2000-01-01 calendar.ics
You can also use the ICS_QUERY_TZ
variable.
export ICS_QUERY_TZ=localtime
# from now on, we use your local time
ics-query at 2000-01-01 calendar.ics
For all avaiable timezones see:
ics-query --available-timezones
Please see the command documentation for more help:
ics-query --help
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 developing ics-query
.
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
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 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.
pip3 install tox
To run all the tests:
tox
To run the tests in a specific Python version:
tox -e py39
We use ruff
to format the code.
Run this to format the code and show problems:
tox -e ruff
New Release
Renovate updates the dependencies automatically on the main
branch.
New commits on main
are automatically published with an increased
PATCH version number.
To release a new version with a new MINOR or MAJOR version number change, follow these steps:
-
edit the Changelog Section
-
create a commit and push it
-
wait for GitHub Actions to finish the build
-
create a tag and push it
git tag v0.1.0 git push origin v0.1.0
-
Notify the issues about their release
Changelog
We automatically release the versions that only update dependencies. If the version you installed does not show up here, only the dependencies have been updated.
-
v0.4.1
- Automatic release with patch level version number increased
- Increase patch version instead of minor version for automatic releases
-
v0.3.4
- Update dependencies
- Start automatic release of dependencies increasing the version number
-
v0.3.3b
- Update dependencies
-
v0.3.2b
- Fix that
--tz localtime
would uselocaltime
as timezone name instead of the local timezone name. - Fix tests on Windows
- Add Windows .exe build artifact
- Fix that
-
v0.3.1b
- Add
--license
option
- Add
-
v0.3.0b
- Add
--tz
timezone parameter - Add
ics-query all
to get all occurrences
- Add
-
v0.2.1a
- Add
--component
to filter component types VEVENT, VJOURNAL and VTODO
- Add
-
v0.2.0a
- Add
ics-query first <calendar> <output>
for earliest occurrences - Add
ics-query between <span_start> <span_stop> <calendar> <output>
to query time ranges
- Add
-
v0.1.1a
- Add
--version
- Add
ics-query at <date> <calendar> <output>
- Add support for multiple calendars in one input
- Add
-
v0.1.0a
- Update Python version compatibility
- Add development documentation
-
v0.0.1a
- first version
Related Work
Vision
This section shows where we would like to get to.
ics-query --select-index
- reduce output size
Examples: 0,2,4
0-10
ics-query --select-uid
- filter by uid
How to edit an event
To edit a component like an event, you can append it to the calendar and increase the sequence number.
Example:
- get the event
--select-index=0
- change the summary
- increase sequence number
- add the event to the end of the calendar file
- show that the occurrence has changed
Notifications
Examples:
- There are x todos in the next hour
- There are x events today
- Please write a journal entry!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ics_query-0.4.9-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ba827a2cd58a57bca367d7621b16015b5fdc3d4a38df91a1b398b0ca7744885a |
|
MD5 | 7f2bfdff5135adffbf375e569ddb6b34 |
|
BLAKE2b-256 | 6e68ce21cf5c3840cec06fda6f5fb00fe456e17ca9bad6e4c980592d29a68fc8 |