Skip to main content

Taskwarrior bindings for Python

Interact with your local taskwarrior task list from Python.

This is heavily inspired by @ralphbean's taskw library (that I'm also a contributor to), but breaks with many past decisions so as to have a cleaner internal API, a saner method of interacting with Taskwarrior itself, type annotations, and much improved maintainability.

Installation

pip install taskwarrior

You can also install the in-development version with:


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

Quickstart

>>> 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)]
>>>

Examples

Finding Tasks

The filter method is used for finding tasks:

>>> 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)]

It accepts as parameters any of the following:

  • Any number of keyword arguments:
    • Example of filter keyword arguments include:
      • status='pending'
      • description__contains='Some string'
      • due__after='yesterday'
    • Double-underscores are transformed into a . when sending the filter to Taskwarrior so as to allow you to use filters like description.contains or due.after.
  • Any number of filter dictionaries:
    • These work much the same way as keyword arguments described above, but allow you to specify these as raw dictionaries instead.
  • Any number of raw strings:
    • E.g. for filtering to tasks having only a certain tag, you can provide as a value +mytag.
  • Any number of Q objects:
    • You can use Q objects to perform complex or and and queries using exactly the same keyword arguments, filter dictionaries, or string values descrribed above.
    • See "Using Q Objects" below for more information.

Each of these parameters are and-ed together should more than one parameter be provided. If you need to use or expressions, see "Using Q Objects" below.

If you are expecting to retrieve just a single task, you can use the .get method, too:

>>> 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)

if either zero or more than one task is returned from your query, an exception will be raised.

Retrieving tasks

>>> 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)

See "Finding Tasks" for more details -- this allows all of the functionality described there, except that it asserts that only a single task be returned. Note that you can use any combination of fields you might like for retrieving your single task, but uuid and id are the ones most likely to be of use to you.

Counting tasks

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

This allows all of the same filtering logic that you can find described in "Finding tasks" above; see that section for more details.

Adding Tasks

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

Changing tasks

>>> 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)

Just alter the fields on the object directly using native python datatypes and pass your altered object to modify and your task will be updated immediately.

Being Flexible

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

You can provide the following parameters when instantiating your client:

  • config_filename: (Default: ~/.taskrc) The path of the taskrc file to use.
  • config_overrides: A dictionary object representing configuration overrides to use when interacting with Taskwarrior. Nested dictionaries will be encoded into dotted configuration paths using the key name in their parent dictionary.
  • task_bin: The path to the task binary to use.

Using Q Objects

Q objects (inspired by Django's objects of the same name can be used for building complex logical queries for filtering your tasks.

Q objects accept all of the same parameter types described in "Finding tasks" above, but can also be or or and-ed together using | or &:

>>> 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)
            )
        )
    )

How does this differ from taskw?

  • This is a much younger library and may still have bugs.
  • This interacts with Taskwarrior over its export and import ("plumbing") interfaces instead of interacting with its "porcelain" interfaces like modify. This makes this library internally a lot simpler and less likely to break as Taskwarrior's command-line API is changed in the future.
  • This has far fewer options and controls. Mostly: those options and controls are of limited value and high maintenance cost anyway, so it's likely you won't even notice.
  • This has much more sophisticated filtering capabilities.
  • This uses a slightly simpler API for retrieving tasks -- rather than handing you a 2-tuple of values (id, {data}) this just hands you a data object (or list of them).
  • This uses a third-party library (Pydantic) for data serialization/deserialization so as to remove those responsibilities from the library itself (and hopefully make it somewhat easier to maintain).
  • This supports only modern versions of Taskwarrior. Specifically: only versions of Taskwarrior newer than 2.5.1 are supported.
  • This supports only currently supported versions of Python. Specifically: only versions of Python currently receiving security updates are supported -- that means Python 3.7+ at the moment.

Metadata

Release files for taskwarrior 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for taskwarrior 0.1.2
File Size Uploaded Provenance Actions
taskwarrior-0.1.2.tar.gz 14.8 kB Without provenance Details for taskwarrior-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for taskwarrior 0.1.2
File Interpreter ABI Platform Actions
taskwarrior-0.1.2-py2.py3-none-any.whl Python 2, Python 3 none any Details for taskwarrior-0.1.2-py2.py3-none-any.whl

Total release size: 27.3 kB

Release files / taskwarrior-0.1.2.tar.gz

Download URL taskwarrior-0.1.2.tar.gz
Size 14.8 kB
Tags Source
SHA-256 checksum
How to use checksums
41b1d8fdfd22a0073690b86965f34eaaddd3fa0e0494020e2dbafc6c8bc96687
BLAKE2b-256 checksum
How to use checksums
9a31bbbba4188fa699cff7c9a4dc9bee635d7617183af931e5c52b569c9e5658
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.7.1 importlib_metadata/4.10.1 pkginfo/1.8.2 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.7

Release files / taskwarrior-0.1.2-py2.py3-none-any.whl

Download URL taskwarrior-0.1.2-py2.py3-none-any.whl
Size 12.4 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
7cda0a92e3c136243fdb7dfc67f70f4be0537a42f6030e1682c786a9f70d1240
BLAKE2b-256 checksum
How to use checksums
9a0d2ef2c03403b775daa4314fd5c7206203e86d5fce1ac8e255fd409d850a4e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.7.1 importlib_metadata/4.10.1 pkginfo/1.8.2 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.7

Security for taskwarrior 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page