Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bergercookie/tw-hooks
Collection of Taskwarrior hooks + detection and registration mechanism
https://github.com/bergercookie/tw-hooks
automation python python3 task taskmanager taskwarrior taskwarrior-hooks
Last synced: 2 months ago
JSON representation
Collection of Taskwarrior hooks + detection and registration mechanism
- Host: GitHub
- URL: https://github.com/bergercookie/tw-hooks
- Owner: bergercookie
- License: mit
- Created: 2022-06-02T17:56:21.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2023-01-22T18:34:28.000Z (almost 2 years ago)
- Last Synced: 2024-09-18T10:45:36.884Z (4 months ago)
- Topics: automation, python, python3, task, taskmanager, taskwarrior, taskwarrior-hooks
- Language: Python
- Homepage:
- Size: 219 KB
- Stars: 7
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Taskwarrior Hooks
## Description
This is a collection of [Taskwarrior
hooks](https://taskwarrior.org/docs/hooks_guide.html) that I use in my
day-to-day workflows. It comes along a detection and easy-registration mechanism
that should make it easy to develop and then distribute your own hooks. The
hooks are structured as classes under the `tw_hooks/hooks` directory.
## Installation
Install it from `PyPI`:
```sh
pip3 install --user --upgrade tw_hooks
```
To get the latest version install directly from source:
```sh
pip3 install --user --upgrade git+https://github.com/bergercookie/tw-hooks
```
After the installation, you have to run the `install-hooks-shims` executable
(which by this point should be in your `$PATH`). Running it will create shims
(thin wrapper scripts) under `~/.task/hooks` in order to register all the hooks
with Taskwarrior.
## Available hooks
Currently the following hooks are available out-of-the-box:
Hook
Description
Events
AutoTagBasedOnTags
Inspect the list of tags in the added/modified tasks provided and add additional tags if required
on-modify, on-add
CorrectTagNames
Change tag names based on a predefined lookup table
on-modify, on-add
DetectMutuallyExclusiveTags
See whether the user has specified an incompatible combination of tags
on-modify, on-add
PostLatestStartToI3Status
When a task is started, send the title of the task to i3status-rs via DBus
on-modify
WarnOnTaskCongestion
Warn the user if there are too many tasks (due:today)
on-exit
## Structure of a Hook
The purpose of this package is to facilitate the development and distribution of
Taskwarrior hooks. To this purpose `install-hooks-shims` allows you to easily
register your own hooks, without having to manually copy items over to the
taskwarrior hooks location. `install-hooks-shims` will install a shim which will
call your hook automatically when required.
This is an example of a Taskwarrior hook that will be executed on Taskwarrior
exit:
```python
from tw_hooks import OnExitHook
class WarnOnTaskCongestion(OnExitHook):
"""Warn the user if there are too many tasks."""
def _on_exit(self, _): # <--- Mandatory to implement this signature
# ...
return 0
```
Assuming that this hook is in a module called `warn_on_task_congestion.py` and
that the directory of this module is in your python path (e.g., by adding it
explicitly to `$PYTHONPATH`), then you can run the following to register your
hook with taskwarrior:
```sh
install-hooks-shims -r warn_on_task_congestion
```
During your next Taskwarrior operation, if there are too many due:today tasks,
you should see something like this:
```sh
t add +test kalimera
Created task 719.
[WarnOnTaskCongestion] Too many due:today tasks [threshold=9]
```
## Hooks API
Subclass one of the following base hooks, and your method is going to be called
during that event:
- [`OnAddHook`](https://github.com/bergercookie/tw-hooks/blob/master/tw_hooks/base_hooks/on_add_hook.py)
- Implement the `_on_add(self, added_task: TaskT)` method.
- [`OnExitHook`](https://github.com/bergercookie/tw-hooks/blob/master/tw_hooks/base_hooks/on_exit_hook.py)
- Implement the `_on_exit(self, added_modified_tasks: List[TaskT])` method.
- [`OnLaunchHook`](https://github.com/bergercookie/tw-hooks/blob/master/tw_hooks/base_hooks/on_launch_hook.py)
- Implement the `_on_launch(self)` method.
- [`OnModifyHook`](https://github.com/bergercookie/tw-hooks/blob/master/tw_hooks/base_hooks/on_modify_hook.py)
- Implement the `_on_modify(self, original_task: TaskT, modified_task: TaskT)`
method.
## Usage instructions for `install-hooks-shims`
```python
usage: Detect Taskwarrior hooks and register an executable shim for each one of them.
[-h] [-t TASK_DIR] [-a] [-l]
[-r REGISTER_ADDITIONAL [REGISTER_ADDITIONAL ...]]
optional arguments:
-h, --help show this help message and exit
-t TASK_DIR, --task-dir TASK_DIR
Path to the taskwarrior main directory
-a, --all-hooks Install shims for all the hooks
-l, --list-hooks List the available hooks and exit
-r REGISTER_ADDITIONAL [REGISTER_ADDITIONAL ...], --register-additional REGISTER_ADDITIONAL [REGISTER_ADDITIONAL ...]
Usage examples:
===============
- Install only the WarnOnTaskCongestion hook (assuming you've installed tw_hooks with e.g., pip3)
install-hook-shims -r tw_hooks.hooks.warn_on_task_congestion
- Install all the available hooks from this repo (assuming you've installed tw_hooks with e.g., pip3)
install-hook-shims --all-hooks
- Install a custom hook defined in .../dir/mod/hook_name.py. "dir" should be in your PYTHONPATH
install-hook-shims -r mod.hook_name
- List all the available hooks and exit
install-hook-shims --list-hooks
```
## Miscellaneous
- [Contributing Guide](CONTRIBUTING.md)
## FAQ
- Why should I use this over raw taskwarrior hooks?
- Because this package does the heavy lifting pre-processing the input tasks
from the command line. It does so in a robust manner making sure it does
the right thing regardless of weather one or two commands are provided and
being robust to errors (e.g., `utf-8` decoding errors).
- It takes care to make the hooks fail safely even if it can't find required
modules (e.g., if you try invoking `task` from inside a `virtualenv` where
`tw-hooks` is not importable.
- It gives you a class-oriented approach and lets you install multiple hooks
from the same class, thus allowing these hooks to share common
configuration.
- It allows you to keep all your hooks together and keep
them as a package in some other place in your filesystem, e.g., in your
dotfiles and automatically adds the right glue-code so that Taskwarrior your
scripts without having to explicitly place it in `~/.task/hooks` or
symlinking it.
## Self Promotion
If you find this tool useful, please [star it on
Github](https://github.com/bergercookie/tw-hooks)
and consider donating.
## Support
If something doesn't work, feel free to open an issue. You can also find me in
the [#taskwarrior Libera Chat](https://matrix.to/#/#taskwarrior:libera.chat).
## TODO List
See [ISSUES
list](https://github.com/bergercookie/tw-hooks/issues)
for the things that I'm currently either working on or interested in
implementing in the near future. In case there's something you are interesting
in working on, don't hesitate to either ask for clarifications or just do it and
directly make a PR.