ics-query 0.1.dev8__py3-none-any.whl → 0.2.0a0__py3-none-any.whl

{ics_query-0.1.dev8.dist-info → ics_query-0.2.0a0.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.3
 Name: ics-query
-Version: 0.1.dev8
-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.2.0a0
+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/3f1c4acd60666416eb899f7a0c07a05999d443c3.zip
+Project-URL: source_archive, https://github.com/niccokunzmann/ics-query/archive/c7eeb503fae7da069308a27a37232be96851c3e5.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
@@ -690,12 +690,15 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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-Python: >=3.9
 Requires-Dist: click
 Requires-Dist: icalendar
-Requires-Dist: recurring-ical-events
+Requires-Dist: recurring-ical-events<4,>=3.2.0
 Provides-Extra: test
 Requires-Dist: pytest; extra == 'test'
 Description-Content-Type: text/markdown
@@ -713,7 +716,117 @@ You can install this package from the [PyPI](https://pypi.org/project/ics-query/
 pip install ics-query
 ```
 
-## `ics-query at` - occurrences at certain times
+## 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:
+
+```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
+...
+```
+
+### Events at Certain Times
+
+You can query which events happen at certain times:
+
+```shell
+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:
+
+```shell
+ics-query at --help
+ics-query --help
+```
+
+### Events within a Time Span
+
+You can query which events happen between certain times:
+
+```shell
+ics-query between <start> <end> calendar.ics -
+ics-query between <start> <duration> calendar.ics -
+```
+
+Please see the command documentation for more help:
+
+```shell
+ics-query between --help
+ics-query --help
+```
+
+### Time Span Examples
+
+This example returns the events within the next week:
+
+```shell
+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:
+
+```shell
+ics-query between 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:
+
+```shell
+ics-query between 2025-12-31T21:00 +6h calendar.ics events.ics
+```
+
+## 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**.
 
@@ -733,33 +846,28 @@ You can get all **TODO**s 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 at` - time ranges
 
-## `ics-query --output=ics` - use ics as output (default)
+### `ics-query --output=count` - count occurrences
 
+### `ics-query --output=ics` - use ics as output (default)
 
-## `ics-query --select-index` - reduce output size
+### `ics-query --select-index` - reduce output size
 
 Examples: `0,2,4` `0-10`
 
-## `ics-query all` - the whole calendar
+### `ics-query all` - the whole calendar
 
-## `ics-query between` - time ranges
+### `ics-query between` - time ranges
 
 ```shell
 ics-query between dt dt
 ics-query between dt duration
 ```
 
-## `ics-query --select-component` - filter for components
-
-
-## `ics-query --select-uid` - filter by uid
+### `ics-query --select-component` - filter for components
 
+### `ics-query --select-uid` - filter by uid
 
 ## How to edit an event
 
@@ -787,8 +895,102 @@ Examples:
 - 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](https://github.com/niccokunzmann/ics-query/tree/main/ics_query/tests)
+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](https://github.com/niccokunzmann/ics-query/issues) 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.
+
+```shell
+pip3 install tox
+```
+
+To run all the tests:
+
+```shell
+tox
+```
+
+To run the tests in a specific Python version:
+
+```shell
+tox -e py39
+```
+
+We use ``ruff`` to format the code.
+Run this to format the code and show problems:
+
+```shell
+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](https://github.com/niccokunzmann/ics-query/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
 
+- 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
+  - Add development documentation
+
 - v0.0.1a
 
   - first version
+
+## Related Work
+
+- [icalBuddy](https://hasseg.org/icalBuddy/)

ics_query-0.2.0a0.dist-info/RECORD

@@ -0,0 +1,30 @@
+ics_query/__init__.py,sha256=YxyZzqxwfA77sBVFjUyUj3_fvR2gL3bs0pkE93prRFY,216
+ics_query/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+ics_query/_version.py,sha256=uRzu9Kl96sLvzy9j33tEqvTz_UjQeHK61WNjh5la-qA,413
+ics_query/cli.py,sha256=230EXFOKdZYXrJhRlpuqKle30H6DxrVhNTqU5uWF1uk,12372
+ics_query/parse.py,sha256=mq6d1m7ITiEqD901nu54yvnYfY4U71J8_l5c9JdlPZ8,1730
+ics_query/version.py,sha256=LgqmHh_dcmWi9HMxfWJ8OhfmbzWsBTq3h08jIE18pYM,468
+ics_query/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ics_query/tests/conftest.py,sha256=MGwKXod7sFfepXK0mtvKkR8SaIiI1SZNW_rAhz6aSA0,2258
+ics_query/tests/test_command_line.py,sha256=-XnpYWETEVEc1dJ5_dpd8dqBoMQFz1CyGaSoe_ETq5o,488
+ics_query/tests/test_parse_date.py,sha256=vVOj5bBvYel3euKmuBMy2v-uhpMDnC03OVcjyahhXPE,2100
+ics_query/tests/test_parse_timedelta.py,sha256=wsAdfyagfndkZXX-KfAVDf4Ui2o2hcSu_yoUeyKuSuo,784
+ics_query/tests/runs/at 2019-03-04 multiple-calendars.ics -.run,sha256=Cyeg9DMK6BibiCwkM8nW0ZtULUYSZFIgDvKRlSo_jTw,482
+ics_query/tests/runs/at 2019-03-04 one-event-twice.ics -.run,sha256=hc-0yJhWpnSVzPNB_0_tJfR6dskNMm9xdbHeAhsX1zI,452
+ics_query/tests/runs/at 2019-03-04 one-event.ics -.run,sha256=GVVmVpqzFjQLw2_RuhxnVTpCnwflNqeWbkFZ6u5WXxA,226
+ics_query/tests/runs/at 2019-03-07 multiple-calendars.ics -.run,sha256=ZlLXxPMIai7vvmQTL4NyXJwdCQzoU1scEn_FpjmkkUA,256
+ics_query/tests/runs/between 20240823 4d recurring-work-events.ics -.run,sha256=2_sM7CkSW4SDk6wbwyLURZ8WZm2rT0hgmx1k7O07T3M,574
+ics_query/tests/runs/first empty-calendar.ics -.run,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ics_query/tests/runs/first empty-file.ics -.run,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ics_query/tests/runs/first recurring-work-events.ics -.run,sha256=-mGNYgI4vBSkBMMJ0WCYdkg97JpnOJ64rlaqdSKCi2Y,287
+ics_query/tests/runs/calendars/empty-calendar.ics,sha256=78162P3KYUj6Qhbdnjsm3E84jv--_--p5U0h_jovrpw,153
+ics_query/tests/runs/calendars/empty-file.ics,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ics_query/tests/runs/calendars/multiple-calendars.ics,sha256=lS1Q9eSPpzLs2TRDKUiwF9HmpnJMw8xqjLudA0-KtY4,1516
+ics_query/tests/runs/calendars/one-event-twice.ics,sha256=GZ5wE-U4kjO91N2nIaLsYZpSOLvQTjkoLPI6saMocOM,1450
+ics_query/tests/runs/calendars/one-event.ics,sha256=-uwohttEzg-jsTETNb6tQ5dO9PE3DXzlicwRiXJs1KQ,725
+ics_query/tests/runs/calendars/recurring-work-events.ics,sha256=4ASS_-xZl2pVv1kZ7nDOU9jpkmbo4zJC2KEAgHtpsNU,5115
+ics_query-0.2.0a0.dist-info/METADATA,sha256=XC_fP8LNXU151JQdT-irzijqZO2nKCiFsCqwqGhif1I,49120
+ics_query-0.2.0a0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+ics_query-0.2.0a0.dist-info/entry_points.txt,sha256=Jq_39vCKVOkNZjL7Wngf_04V_n_QRszLgLT2CbJKiH4,49
+ics_query-0.2.0a0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+ics_query-0.2.0a0.dist-info/RECORD,,

ics_query-0.1.dev8.dist-info/RECORD

@@ -1,16 +0,0 @@
-ics_query/__init__.py,sha256=YxyZzqxwfA77sBVFjUyUj3_fvR2gL3bs0pkE93prRFY,216
-ics_query/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
-ics_query/_version.py,sha256=lI2AbAnFrmlrT0e_rrLW0sxbHP3fZzYfncKr1OGEhdw,419
-ics_query/cli.py,sha256=P6eLIH7hgbfwhbJHloilHS9ut_YDjEP_QDabLTf0NQs,2367
-ics_query/parse.py,sha256=6bCKtY39jr2NFSsqspVyGn32pwn6bMoEqJMHE26Ap1o,261
-ics_query/version.py,sha256=LgqmHh_dcmWi9HMxfWJ8OhfmbzWsBTq3h08jIE18pYM,468
-ics_query/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ics_query/tests/conftest.py,sha256=A6R9pB3emaSo1DAIxyt-5QhWPq8LbsOoWJIRIsku2Zk,2003
-ics_query/tests/test_command_line.py,sha256=bIJp2SCVW8MXF_lNZ1ol9A-r9Y_9zjnY2jhdTJET59g,283
-ics_query/tests/runs/at 2019-03-04 one-event.ics -.run,sha256=GVVmVpqzFjQLw2_RuhxnVTpCnwflNqeWbkFZ6u5WXxA,226
-ics_query/tests/runs/calendars/one-event.ics,sha256=-uwohttEzg-jsTETNb6tQ5dO9PE3DXzlicwRiXJs1KQ,725
-ics_query-0.1.dev8.dist-info/METADATA,sha256=5jVr-o3Elo_hWgEjN-t3GFB5fAd65JSyw23Tp2JvBZc,43902
-ics_query-0.1.dev8.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-ics_query-0.1.dev8.dist-info/entry_points.txt,sha256=Jq_39vCKVOkNZjL7Wngf_04V_n_QRszLgLT2CbJKiH4,49
-ics_query-0.1.dev8.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-ics_query-0.1.dev8.dist-info/RECORD,,