Python的taskwarrior绑定

从Python与您的本地taskwarrior任务列表交互。

本项目深受@ralphbean的taskw库（我也是贡献者之一）的启发，但与其许多过去的决策不同，以便拥有更干净的内部API、更合理的与Taskwarrior交互的方法、类型注解以及更好的可维护性。

安装

pip install taskwarrior

您还可以使用以下命令安装开发版本：

pip install https://github.com/coddingtonbear/taskwarrior/archive/master.zip

快速入门

>>> from taskwarrior import Client
>>> client = Client()
>>> tasks = client.filter(status='pending')
[Task(annotations=None, depends=None, description='Wake up', due=None, end=None, entry=datetime.datetime(2022, 1, 24, 4, 28, 11, tzinfo=tzutc()), id=1, imask=None, mask=None, modified=datetime.datetime(2022, 1, 24, 4, 28, 51, tzinfo=tzutc()), parent=None, project=None, recur=None, scheduled=None, start=None, status='pending', tags=['alarm'], until=None, urgency=0.8, uuid=UUID('a39ea0fa-682a-4815-9556-8b6785ee301c'), wait=None)]
>>>

示例

查找任务

使用filter方法查找任务

>>> from taskwarrior import Client
>>> client = Client()
>>> client.filter(status='pending')
[Task(annotations=None, depends=None, description='Wake up', due=None, end=None, entry=datetime.datetime(2023, 1, 24, 4, 28, 11, tzinfo=tzutc()), id=1, imask=None, mask=None, modified=datetime.datetime(2022, 1, 24, 4, 28, 51, tzinfo=tzutc()), parent=None, project=None, recur=None, scheduled=None, start=None, status='pending', tags=['alarm'], until=None, urgency=0.8, uuid=UUID('a39ea0fa-682a-4815-9556-8b6785ee301c'), wait=None)]

它接受以下参数中的任意一个

• 任意数量的关键字参数
  • 关键字参数示例包括
    • status='pending'
    • description__contains='Some string'
    • due__after='yesterday'
  • 在将过滤器发送给Taskwarrior时，双下划线会被转换为.，这样您就可以使用如description.contains或due.after这样的过滤器。
• 任意数量的过滤器字典
  • 这些与上述关键字参数的工作方式非常相似，但允许您将这些指定为原始字典。
• 任意数量的原始字符串
  • 例如，为了过滤具有特定标签的任务，您可以提供值+mytag。
• 可以有任意数量的 Q 对象
  • 您可以使用 Q 对象来执行复杂的 or 和 and 查询，使用与上述相同的键参数、筛选字典或字符串值。
  • 有关更多信息，请参阅下方的“使用 Q 对象”。

如果有多个参数提供，则这些参数将通过 and 连接起来。如果您需要使用 or 表达式，请参阅下方的“使用 Q 对象”。

如果您期望只检索一个任务，您也可以使用 .get 方法。

>>> from taskwarrior import Client
>>> client = Client()
>>> client.get(uuid="a39ea0fa-682a-4815-9556-8b6785ee301c")
Task(annotations=None, depends=None, description='Wake up', due=None, end=None, entry=datetime.datetime(2023, 1, 24, 4, 28, 11, tzinfo=tzutc()), id=1, imask=None, mask=None, modified=datetime.datetime(2022, 1, 24, 4, 28, 51, tzinfo=tzutc()), parent=None, project=None, recur=None, scheduled=None, start=None, status='pending', tags=['alarm'], until=None, urgency=0.8, uuid=UUID('a39ea0fa-682a-4815-9556-8b6785ee301c'), wait=None)

如果查询返回零个或多个任务，则会引发异常。

检索任务

>>> from taskwarrior import Client
>>> client = Client()
>>> client.get(uuid="a39ea0fa-682a-4815-9556-8b6785ee301c")
Task(annotations=None, depends=None, description='Wake up', due=None, end=None, entry=datetime.datetime(2023, 1, 24, 4, 28, 11, tzinfo=tzutc()), id=1, imask=None, mask=None, modified=datetime.datetime(2022, 1, 24, 4, 28, 51, tzinfo=tzutc()), parent=None, project=None, recur=None, scheduled=None, start=None, status='pending', tags=['alarm'], until=None, urgency=0.8, uuid=UUID('a39ea0fa-682a-4815-9556-8b6785ee301c'), wait=None)

请参阅“查找任务”以获取更多详细信息——这允许使用那里描述的所有功能，但断言只返回一个任务。请注意，您可以使用任何组合的字段来检索单个任务，但 uuid 和 id 可能对您最有用。

计数任务

>>> from taskwarrior import Client
>>> client = Client()
>>> client.count(status='pending')
1

这允许使用与上方“查找任务”中描述相同的筛选逻辑；请参阅该部分以获取更多详细信息。

添加任务

>>> from taskwarrior import Client, Task
>>> client = Client()
>>> task = Task(description="my new task")
>>> client.add(task)
>>> task.uuid
UUID('29d06231-525f-4a62-9e9f-dd0f680aaaff')'

更改任务

>>> from taskwarrior import Client
>>> import pytz
>>> client = Client()
>>> task = client.get(uuid="a39ea0fa-682a-4815-9556-8b6785ee301c")
>>> task.due = datetime.datetime(2029, 1, 1, 10, 0, tzinfo=pytz.timezone('America/Los_Angeles'))
>>> client.modify(task)

只需直接使用原生 Python 数据类型修改对象上的字段，然后将修改后的对象传递给 modify，您的任务将立即更新。

灵活多变

>>> from taskwarrior import Client
>>> client = Client(
        config_filename="/path/to/my/taskrc",
        config_overrides={
            "some": {
                "config": "values",
            }
        },
        task_bin="/path/to/bin/task",
    )

在实例化客户端时，您可以提供以下参数：

• config_filename：(默认：~/.taskrc）要使用的 taskrc 文件的路径。
• config_overrides：表示要用于与 Taskwarrior 交互时配置覆盖的字典对象。嵌套字典将使用其父字典中的键名称编码为点配置路径。
• task_bin：要使用的 task 二进制文件的路径。

使用 Q 对象

Q 对象（受 Django 的同名对象 启发）可用于构建用于筛选任务的复杂逻辑查询。

Q 对象接受“查找任务”上方描述的所有相同参数类型，但也可以使用 | 或 & 通过 or 或 and 连接起来。

>>> from taskwarrior import Client, Q
>>> import pytz
>>> client = Client()
>>> client.filter(
        Q(status='pending') | Q(
            status='waiting',
            due__before=pytz.timezone('America/Los_Angeles').localize(
                datetime.datetime.utcnow() + datetime.timedelta(days=7)
            )
        )
    )

这与 taskw 有何不同？

• 这是一个较新的库，可能仍然存在错误。
• 它通过 export 和 import（“管道”）接口与 Taskwarrior 交互，而不是通过其“瓷器”接口（如 modify）交互。这使得这个库在内部更加简单，并且不太可能在 Taskwarrior 的命令行 API 更改时出现故障。
• 它具有更少的选择和控制。主要：那些选项和控制的价值有限，维护成本高，所以您可能甚至都不会注意到。
• 它具有更复杂的筛选功能。
• 它使用一个稍微简单的 API 来检索任务——而不是给您一个值二元组 (id, {data})，它只给您一个数据对象（或它们的列表）。
• 它使用第三方库（Pydantic）进行数据序列化/反序列化，以便将这些责任从库本身中删除（并且希望使其更容易维护）。
• 它仅支持 Taskwarrior 的现代版本。具体来说：仅支持 Taskwarrior 2.5.1 版本之后的版本。
• 它仅支持当前受支持的 Python 版本。具体来说：仅支持目前接收安全更新的 Python 版本——目前是 Python 3.7+。