ics-query 0.1.0a0__tar.gz → 0.1.dev1__tar.gz

{ics_query-0.1.0a0 → ics_query-0.1.dev1}/.github/ISSUE_TEMPLATE/bug_report.md

@@ -27,15 +27,9 @@ assignees: ''
 
 **Version:**
 <!-- Which Version do you use? -->
-v0.0.1
 
-<!-- Sometimes, the problems are in other packages. You can provide an overview
-     by running this command and passing the output:
-
-     pip list
--->
 ```shell
-pip list
+$ ics-query --version
 ```
 
 ## Additional context
@@ -45,5 +39,5 @@ pip list
 <!-- If possible, suggest a way of solving this or just let this text down there remain as it is. -->
 
 - [ ] add an ICS file in `ics_query/tests/runs/calendars`
-- [ ] add a test in `ics_query/tests/runs directory`
+- [ ] add a test in `ics_query/tests/runs`
 - [ ] fix the bug and ensure the test code passes

{ics_query-0.1.0a0 → ics_query-0.1.dev1}/.github/workflows/tests.yml

@@ -14,14 +14,15 @@ jobs:
     strategy:
       matrix:
         config:
-        # [Python version, tox env]
-        - ["3.9",   "py39"]
-        - ["3.10",  "py310"]
-        - ["3.11",  "py311"]
-        - ["3.12",  "py312"]
-        - ["3.9",  "ruff"]
+        # [Python version, tox env, OS]
+        - ["3.9",   "py39", "ubuntu-latest"]
+        - ["3.10",  "py310", "ubuntu-latest"]
+        - ["3.11",  "py311", "ubuntu-latest"]
+        - ["3.12",  "py312", "ubuntu-latest"]
+        - ["3.9",  "ruff", "ubuntu-latest"]
+        - ["3.11",  "exe", "windows-latest"]
 
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.config[2] }}
     name: ${{ matrix.config[1] }}
     steps:
     - uses: actions/checkout@v4
@@ -29,14 +30,6 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.config[0] }}
-    - name: Pip cache
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ matrix.config[0] }}-${{ hashFiles('setup.*', 'tox.ini') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-${{ matrix.config[0] }}-
-          ${{ runner.os }}-pip-
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
@@ -44,13 +37,64 @@ jobs:
     - name: Test
       run: |
         tox -e ${{ matrix.config[1] }}
+    - uses: actions/upload-artifact@v4
+      with:
+        name: dist-${{ matrix.config[1] }}-${{ matrix.config[2] }}  # dist-exe-windows-latest
+        path: dist
+        if-no-files-found: ignore
+        retention-days: 1
+        compression-level: 0
+
+  version:
+    name: "Determine a new version"
+    if: ${{ startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    outputs:
+      # see https://docs.github.com/de/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#example-usage-of-the-jobs-context
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "Get tags"
+        uses: actions-ecosystem/action-get-latest-tag@v1
+        id: get-latest-tag
+
+      - name: "Calculate new version"
+        uses: actions-ecosystem/action-bump-semver@v1
+        id: bump-semver
+        with:
+          current_version: ${{ steps.get-latest-tag.outputs.tag }}
+          level: patch
+      
+      - name: "Determine version to use"
+        id: version
+        run: |
+          if [ "$GITHUB_REF" == "refs/heads/main" ]; then
+            TAG="${{ steps.get-latest-tag.outputs.tag }}"
+            echo "On branch main. Using new tag version $TAG."
+          else
+            TAG="${{ steps.bump-semver.outputs.new_version }}"
+            echo "On tag $TAG. Using that version."
+          fi
+          echo "::set-output name=version::$TAG"
+
+      - name: Publish new tag id possible
+        # continue on error: when the tag exists we would like to still work it out
+        continue-on-error: true
+        uses: actions-ecosystem/action-push-tag@v1
+        with:
+          tag: ${{ steps.version.outputs.version }}
+          message: |
+            ${{ steps.version.outputs.version }}: automatic release
+            PR #${{ github.event.pull_request.number }} ${{ github.event.pull_request.title }}
 
   deploy-tag-to-pypi:
     name: Publish Package on PyPI
     # only deploy on tags, see https://stackoverflow.com/a/58478262/1320237
-    if: ${{ startsWith(github.ref, 'refs/tags/v') }}
+    if: ${{ startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main' }}
     needs:
     - run-tests
+    - version
     runs-on: ubuntu-latest
     # This environment stores the TWINE_USERNAME and TWINE_PASSWORD
     # see https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment
@@ -95,19 +139,39 @@ jobs:
         twine check dist/*
         twine upload dist/*
           
+  # artifact-check:
+  #   name: artifact check
+  #   runs-on: ubuntu-latest
+  #   needs:
+  #     - run-tests
+  #   steps:
+  #   - uses: actions/download-artifact@v4
+  #     with:
+  #       pattern: dist-*
+  #       path: dist
+  #   - run: ls -R dist
+  
   github-release:
     name: "Publish GitHub Release"
     # only deploy on tags, see https://stackoverflow.com/a/58478262/1320237
-    if: ${{ startsWith(github.ref, 'refs/tags/v') }}
+    if: ${{ startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main' }}
     needs:
       - run-tests
       - deploy-tag-to-pypi
+      - version
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: dist-*
+          path: dist
+      - run: ls -R dist
       - name: create release
         uses: ncipollo/release-action@v1
         with:
           allowUpdates: true
           body: "For a list of changes, please refer to the [Changelog](https://github.com/niccokunzmann/ics-query#changelog)."
-          generateReleaseNotes: false
+          generateReleaseNotes: false
+          artifacts: "dist/dist-exe-windows-latest/ics-query.exe"
+          tag: ${{ needs.version.outputs.version }}

{ics_query-0.1.0a0 → ics_query-0.1.dev1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.3
 Name: ics-query
-Version: 0.1.0a0
-Summary: Find out what happens in ICS calendar files - query and filter RFC 5545 compatible `.ics` files for events, journals, TODOs and more.
+Version: 0.1.dev1
+Summary: Find out what happens in ICS calendar files - query and filter RFC 5545 compatible .ics files for events, journals, TODOs and more.
 Project-URL: Homepage, https://github.com/niccokunzmann/ics-query/
 Project-URL: Repository, https://github.com/niccokunzmann/ics-query/
-Project-URL: source_archive, https://github.com/niccokunzmann/ics-query/archive/cf4aefe6fb80c98ee554f4030ce9b2e7f16db162.zip
+Project-URL: source_archive, https://github.com/niccokunzmann/ics-query/archive/32d7474b3079da3e7ff40136067b4f68586e7a0e.zip
 Project-URL: Issues, https://github.com/niccokunzmann/ics-query/issues
 Project-URL: Documentation, https://github.com/niccokunzmann/ics-query/
 Project-URL: Changelog, https://github.com/niccokunzmann/ics-query/#changelog
@@ -686,7 +686,7 @@ License:                     GNU GENERAL PUBLIC LICENSE
         <https://www.gnu.org/licenses/why-not-lgpl.html>.
 License-File: LICENSE
 Keywords: calendar,command line,icalendar,ics,rfc5545,scheduling
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Operating System :: OS Independent
@@ -695,100 +695,328 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Office/Business :: Scheduling
-Requires-Python: >=3.8
-Requires-Dist: click
-Requires-Dist: icalendar
-Requires-Dist: recurring-ical-events
+Requires-Python: >=3.9
+Requires-Dist: click==8.1.7
+Requires-Dist: icalendar==6.0.0
+Requires-Dist: python-dateutil==2.9.0.post0
+Requires-Dist: recurring-ical-events==3.3.2
+Requires-Dist: six==1.16.0
+Requires-Dist: tzdata==2024.2
+Requires-Dist: tzlocal==5.2
+Requires-Dist: x-wr-timezone==1.0.1
 Provides-Extra: test
 Requires-Dist: pytest; extra == 'test'
 Description-Content-Type: text/markdown
 
 # ics-query
 
+[![GitHub Actions CI](https://github.com/niccokunzmann/ics-query/actions/workflows/tests.yml/badge.svg)][GitHub Actions]
+[![PyPI Version](https://badge.fury.io/py/ics-query.svg)][PyPI]
+[![PyPI Downloads](https://img.shields.io/pypi/dm/ics-query.svg)][PyPI]
+[![Support on Open Collective](https://img.shields.io/opencollective/all/open-web-calendar?label=support%20on%20open%20collective)][Open Collective]
+[![Fund Issues with Polar](https://img.shields.io/github/issues/niccokunzmann/ics-query?logo=github&label=issues%20seek%20funding&color=%230062ff)][Polar]
+
 <!-- Change description also in pyproject.toml -->
 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](https://pypi.org/project/ics-query/).
+You can install this package from the [PyPI].
 
 ```shell
 pip install ics-query
 ```
 
-## `ics-query at` - occurrences at certain times
+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
+
+- [recurring-ical-events]
+- [icalendar]
+- [x-wr-timezone]
+
+[recurring-ical-events]: https://pypi.org/project/recurring-ical-events/
+[icalendar]: https://pypi.org/project/icalendar/
+[x-wr-timezone]: https://pypi.org/project/x-wr-timezone/
+
+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.
+
+```shell
+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:
+
+```shell
+$ 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.
+
+```shell
+$ 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.
+
+```shell
+$ 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.
+
+```shell
+cat calendar.ics | ics-query first -
+```
+
+### Events at Certain Times
+
+You can query which events happen at certain times:
+
+```shell
+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:
+
+```shell
+ics-query at --help
+ics-query --help
+```
 
 You can get all **events** that happen at a certain **day**.
 
 ```shell
-ics-query --components VEVENT at 2029-12-24 calendar.ics
+ics-query at --components VEVENT 2029-12-24 calendar.ics
 ```
 
 You can get all **events** that happen **today**.
 
 ```shell
-ics-query --components VEVENT at `date +%Y-%m-%d` calendar.ics
+ics-query at --components VEVENT `date +%Y-%m-%d` calendar.ics
 ```
 
-You can get all **TODO**s that happen at in certain **month**.
+You can get all **TODO**s that happen in a certain **month**.
 
 ```shell
-ics-query --components VTODO at 2029-12-24 calendar.ics
+ics-query at --components VTODO 2029-12-24 calendar.ics
 ```
 
-## `ics-query at` - time ranges
+### Events within a Time Span
 
+You can query which events happen between certain times:
 
-## `ics-query --output=count` - count occurrences
+```shell
+ics-query between START END calendar.ics -
+ics-query between START DURATION calendar.ics -
+```
 
+Please see the command documentation for more help:
 
-## `ics-query --output=ics` - use ics as output (default)
+```shell
+ics-query between --help
+ics-query --help
+```
 
+The format of START and END with examples:
 
-## `ics-query --select-index` - reduce output size
+| 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 |
 
-Examples: `0,2,4` `0-10`
+Instead of an absolute time, you can specify a duration after the START.
+The `+` is optional.
 
-## `ics-query all` - the whole calendar
+| 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 |
 
-## `ics-query between` - time ranges
+### Time Span Examples
+
+This example returns the occurrences within the **next week**:
 
 ```shell
-ics-query between dt dt
-ics-query between dt duration
+ics-query between `date +%Y%m%d` +7d calendar.ics -
 ```
 
-## `ics-query --select-component` - filter for components
+This example saves the **events** from the **1st of May 2024 to the 10th of June** in
+events.ics:
 
+```shell
+ics-query between --component VEVENT 2024-5-1 2024-6-10 calendar.ics events.ics
+```
 
-## `ics-query --select-uid` - filter by uid
+In this example, you can check what is happening on **New Years Eve 2025** around
+midnight:
 
+```shell
+ics-query between 2025-12-31T21:00 +6h calendar.ics events.ics
+```
 
-## How to edit an event
+### `ics-query all` - the whole calendar
 
-To edit a component like an event, you can append it to the calendar and increase the sequence number.
+You can get everything that is happening in a calendar but that can be a lot!
 
-Example:
+```shell
+ics-query all calendar.ics
+```
 
-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
+### Filtering Components
+
+We support different component types: `VEVENT`, `VJOURNAL` and `VTODO`.
+By default, we include all types in the result.
 
-## Piping calendars
+You can specify which components you would like to get using the
+`--component` or `-c` parameter.
 
 ```shell
-cat calendar.ics | ics-query --output=count --filter-component=VEVENT all > calendar-event-count.int
+-c VEVENT   # only events
+-c VTODO    # only TODOs
+-c VJOURNAL # only journal entries
+-c VEVENT -c VTODO # only events and journal entries
 ```
 
-## Notifications
+This example returns the first event of a calendar.
 
-Examples:
+```shell
+ics-query first -c VEVENT calendar.ics -
+```
+
+This option is also available as `ICS_QUERY_COMPONENT` variable.
+
+```shell
+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:
+
+```shell
+ics-query --help
+```
 
-- There are x todos in the next hour
-- There are x events today
-- Please write a journal entry!
+
+### 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**:
+
+```shell
+ics-query at 2000-01-01 calendar.ics
+```
+
+The first event at New Year 2000 in **your local time**:
+
+```shell
+ics-query at --tz=localtime 2000-01-01 calendar.ics
+```
+
+The first event at New Year 2000 in **UTC**:
+
+```shell
+ics-query at --tz=UTC 2000-01-01 calendar.ics
+```
+
+The first event at New Year 2000 in **Berlin time**:
+
+```shell
+ics-query at --tz=Europe/Berlin 2000-01-01 calendar.ics
+```
+
+You can also use the `ICS_QUERY_TZ` variable.
+
+```shell
+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:
+
+```shell
+ics-query --available-timezones
+```
+
+Please see the command documentation for more help:
+
+```shell
+ics-query --help
+```
 
 ## Version Fixing
 
@@ -805,7 +1033,7 @@ while `b` and `c` can change.
 
 ## Development
 
-This section should set you up for development.
+This section should set you up for developing `ics-query`.
 
 ### Testing
 
@@ -848,23 +1076,72 @@ Run this to format the code and show problems:
 tox -e ruff
 ```
 
-## New Release
+### New Release
 
 To release new versions,
 
 1. edit the Changelog Section
 2. create a commit and push it
-3. wait for [GitHub Actions](https://github.com/niccokunzmann/ics-query/actions) to finish the build
+3. wait for [GitHub Actions] to finish the build
 4. create a tag and push it
 
     ```shell
     git tag v0.1.0a
+    git push origin v0.1.0a
     ```
 
 5. 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 use `localtime` as timezone name instead of the local timezone name.
+  - Fix tests on Windows
+  - Add Windows .exe build artifact
+
+- v0.3.1b
+
+  - Add `--license` option
+
+- v0.3.0b
+
+  - Add `--tz` timezone parameter
+  - Add `ics-query all` to get all occurrences
+
+- v0.2.1a
+
+  - Add `--component` to filter component types VEVENT, VJOURNAL and VTODO
+
+- 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
+
+- v0.1.1a
+
+  - Add `--version`
+  - Add `ics-query at <date> <calendar> <output>`
+  - Add support for multiple calendars in one input
+
 - v0.1.0a
 
   - Update Python version compatibility
@@ -873,3 +1150,49 @@ To release new versions,
 - v0.0.1a
 
   - first version
+
+## Related Work
+
+- [icalBuddy](https://hasseg.org/icalBuddy/)
+- [Blog Post](https://opencollective.com/open-web-calendar/updates/calendar-calculation-on-the-command-line-ics-query)
+- [#icsquery on mastodon](https://toot.wales/tags/icsquery)
+
+## 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:
+
+1. get the event `--select-index=0`
+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
+
+
+### Notifications
+
+Examples:
+
+- There are x todos in the next hour
+- There are x events today
+- Please write a journal entry!
+
+[PyPI]: https://pypi.org/project/ics-query/
+[GitHub Actions]: https://github.com/niccokunzmann/ics-query/actions
+[Open Collective]: https://opencollective.com/open-web-calendar/
+[Polar]: https://polar.sh/niccokunzmann/ics-query
+[GitHub Sponsors]: https://github.com/sponsors/niccokunzmann
+[thanks.dev]: https://thanks.dev
+[Releases]: https://github.com/niccokunzmann/ics-query/releases