ics-query

了解ICS日历文件中发生的事情 - 查询和过滤与RFC 5545兼容的.ics文件以获取事件、日志、待办事项等。

安装

您可以从PyPI安装此软件包。

pip install ics-query

对于 Windows，您可以从我们的发布中下载ics-query.exe。

支持

• 使用GitHub Sponsors提供支持
• 使用Polar资助特定问题
• 使用Open Collective提供支持
• 使用thanks.dev提供支持

我们接受捐款以维持我们的工作，一次性或定期。考虑捐赠资金给开源项目，因为每个人都能从中受益。

支持的功能

这个库基于

• recurring-ical-events
• icalendar
• x-wr-timezone

有关支持的功能和RFC兼容性的列表，请参阅其文档。

使用方法

ics-query 是一个命令行工具，旨在使 icalendar 事件计算易于访问和简单。本节将带您了解不同的功能。

ics-query --help

示例

您可以从网上获取一个日历并查看内容。在本例中，我们展示了2024年8月发生的德国国庆日。

$ 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

在以下示例中，我们查询一个日历文件并打印结果。

$ 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

我们可以连接日历并将它们传递给 ics-query。以下示例显示两个日历中现在发生的事件。

$ cat calendar1.ics calendar2.ics | ics-query at `date +%Y%m%d%H%M%S` - -
BEGIN:VEVENT
...

传递日历

您可以将一个或多个日历传递到输入中。

cat calendar.ics | ics-query first -

特定时间的事件

您可以查询在特定时间发生的事件

ics-query at TIME calendar.ics -

TIME 的格式

TIME	描述
2019	整个2019年
2019-08	2019年8月
2019-08-12	2019年8月12日
2019-08-12T17	2019年8月12日的17:00-18:00
2019-08-12T17:20	2019年8月12日的17:20-17:21
2019-08-12T17:20:00	2019年8月12日的17:20

请参阅命令文档以获取更多帮助

ics-query at --help
ics-query --help

您可以获取特定 一天 发生的所有 事件。

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

您可以获取当天发生的所有 事件。

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

您可以获取特定 月份 发生的所有 TODO。

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

时间段内的事件

您可以查询在特定时间段内发生的事件

ics-query between START END calendar.ics -
ics-query between START DURATION calendar.ics -

请参阅命令文档以获取更多帮助

ics-query between --help
ics-query --help

START 和 END 的格式及示例

START 或 END	描述
2019	整个2019年
2019-08	2019年8月
2019-08-12	2019年8月12日
2019-08-12T17	2019年8月12日的17:00-18:00
2019-08-12T17:20	2019年8月12日的17:20-17:21
2019-08-12T17:20:00	2019年8月12日的17:20

您可以在 START 后指定一个持续时间，而不是绝对时间。+ 是可选的。

持续时间	描述
+1d	再过一天
+1h	再过一小时
+1m	再过一分钟
+1s	再过一秒钟
+3600s	再过一小时或3600秒
+5d10h	再过五天和十个小时

时间段示例

此示例返回下周的 发生的事件。

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

此示例将 从2024年5月1日到6月10日 的 事件 保存到 events.ics 中。

ics-query between --component VEVENT 2024-5-1 2024-6-10 calendar.ics events.ics

在此示例中，您可以在午夜时分查看 2025年新年除夕 发生的事情。

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

ics-query all - 整个日历

您可以得到日历中发生的所有事情，但这可能很多！

ics-query all calendar.ics

筛选组件

我们支持不同的组件类型：VEVENT、VJOURNAL 和 VTODO。默认情况下，我们将所有类型包含在结果中。

您可以使用 --component 或 -c 参数指定您想获取的组件。

-c VEVENT   # only events
-c VTODO    # only TODOs
-c VJOURNAL # only journal entries
-c VEVENT -c VTODO # only events and journal entries

此示例返回日历中的第一个事件。

ics-query first -c VEVENT calendar.ics -

此选项也作为 ICS_QUERY_COMPONENT 变量提供。

export ICS_QUERY_COMPONENT=VEVENT
# from now on, you will get only events
ics-query first calendar.ics

请参阅命令文档以获取更多帮助

ics-query --help

时区

您可以设置查询的时区，否则将使用事件的本地时区，您可能会错过您自己时区的事件。

2000年新年的第一个事件在 事件的本地时间

ics-query at 2000-01-01 calendar.ics

2000年新年的第一个事件在 您的本地时间

ics-query at --tz=localtime 2000-01-01 calendar.ics

2000年新年的第一个事件在 UTC

ics-query at --tz=UTC 2000-01-01 calendar.ics

2000年新年的第一个事件在 柏林时间

ics-query at --tz=Europe/Berlin 2000-01-01 calendar.ics

您还可以使用 ICS_QUERY_TZ 变量。

export ICS_QUERY_TZ=localtime
# from now on, we use your local time
ics-query at 2000-01-01 calendar.ics

有关所有可用的时区，请参阅

ics-query --available-timezones

请参阅命令文档以获取更多帮助

ics-query --help

版本修复

如果您在代码中使用此库，您可能希望确保可以接收更新，但它们不会破坏您的代码。版本号是这样处理的：a.b.c 示例：0.1.12

• c 是针对每个次要错误修复而更改的。
• b 会在添加新功能时发生变化。
• a 在接口或主要假设发生变化时也会发生变化，这些变化可能会破坏您的代码。

因此，我建议将此库的版本固定，以便在 b 和 c 可以更改的同时保持相同的 a。

开发

本节应为您开发 ics-query 做好准备。

测试

此项目开发由测试驱动。测试确保接口的一致性，并在长时间内减少知识损失。如果您想更改代码，测试可以帮助确保未来不会出现任何错误。从这个意义上说，它们是必需的。示例代码和 ics 文件可以转换为测试，并加快修复错误的速度。

您可以在 测试文件夹 中查看测试。如果您有一个日历 ICS 文件，而这个库没有生成您期望的输出，您可以将其添加到 test/calendars 文件夹，并为期望的结果编写测试。如果您愿意，可以先 提交一个问题，例如讨论更改及其实现方法。

要运行测试，我们使用 tox。 tox 测试所有我们希望兼容的不同 Python 版本。

pip3 install tox

要运行所有测试

tox

在特定 Python 版本中运行测试

tox -e py39

我们使用 ruff 来格式化代码。运行此命令来格式化代码并显示问题

tox -e ruff

新版本发布

要发布新版本，

1. 编辑 Changelog 部分

2. 创建提交并将其推送

3. 等待 GitHub Actions 完成构建

4. 创建标签并将其推送

   git tag v0.1.0a
   git push origin v0.1.0a
   

5. 通知问题有关其发布的消息

Changelog

• v0.3.3b

  • 更新依赖项

• v0.3.2b

  • 修复了 --tz localtime 会使用 localtime 而不是本地时区名称作为时区名称的问题。
  • 修复了 Windows 上的测试问题
  • 添加了 Windows .exe 构建工件

• v0.3.1b

  • 添加了 --license 选项

• v0.3.0b

  • 添加了 --tz 时区参数
  • 添加了 ics-query all 以获取所有发生的事件

• v0.2.1a

  • 添加了 --component 以筛选组件类型 VEVENT、VJOURNAL 和 VTODO

• v0.2.0a

  • 添加了 ics-query first <calendar> <output> 以获取最早发生的事件
  • 添加了 ics-query between <span_start> <span_stop> <calendar> <output> 以查询时间范围

• v0.1.1a

  • 添加了 --version
  • 添加了 ics-query at <date> <calendar> <output>
  • 添加了对一个输入中多个日历的支持

• v0.1.0a

  • 更新了 Python 版本兼容性
  • 添加了开发文档

• v0.0.1a

  • 第一个版本

相关工作

• icalBuddy
• 博客文章
• #icsquery on mastodon

愿景

本节展示了我们希望达到的目标。

ics-query --select-index - 减少输出大小

示例：0,2,4 0-10

ics-query --select-uid - 通过 uid 过滤

如何编辑事件

要编辑事件等组件，您可以将其附加到日历中并增加序列号。

示例

1. 获取事件 --select-index=0
2. 更改摘要
3. 增加序列号
4. 将事件添加到日历文件的末尾
5. 显示发生的变化

通知

示例

• 下一小时有 x 个待办事项
• 今天有 x 个事件
• 请写一篇日志条目！