ics-query 0.1.1a0

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

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

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:

$ 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:[e-mail]
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
...

Events at Certain Times

You can query which events happen at certain times:

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:

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.

ics-query --components VEVENT at 2029-12-24 calendar.ics

You can get all events that happen today.

ics-query --components VEVENT at `date +%Y-%m-%d` calendar.ics

You can get all TODOs that happen at in certain month.

ics-query --components VTODO at 2029-12-24 calendar.ics

ics-query at - time ranges

ics-query --output=count - count occurrences

ics-query --output=ics - use ics as output (default)

ics-query --select-index - reduce output size

Examples: 0,2,4 0-10

ics-query all - the whole calendar

ics-query between - time ranges

ics-query between dt dt
ics-query between dt duration

ics-query --select-component - filter for components

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:

1. get the first event --select-index=0 TODO: recurring-ical-events: set recurrence-id, sequence number
2. change the summary
3. increase sequence number
4. add the event to the end of the calendar file
5. show that the occurrence has changed

Piping calendars

cat calendar.ics | ics-query --output=count --filter-component=VEVENT all > calendar-event-count.int

Notifications

Examples:

• There are x todos in the next hour
• 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 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

To release new versions,

1. edit the Changelog Section

2. create a commit and push it

3. wait for GitHub Actions to finish the build

4. create a tag and push it

   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