]> git.madduck.net Git - etc/taskwarrior.git/blob - README.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Merge pull request #4 from thawk/master
[etc/taskwarrior.git] / README.md
1 Taskpirate
2 ----------
3
4 Taskpirate is a pluggable system for TaskWarrior python hooks.
5
6 Why?
7 ----
8
9 Simpler hooks:
10
11     def hook_example(task):
12         task['description'] += "changed by a hook"
13
14 The above is fully working example, no more boilerplate needed.
15
16 Much faster execution time in case of multiple hooks (read the more details section).
17
18 Install
19 -------
20
21 You'll need tasklib as a dependency:
22
23     pip install --user git+git://github.com/tbabej/tasklib@develop
24
25 Then you need to drop ```on-add-pirate``` and ```on-modify-pirate``` into ~/.task/hooks/.
26
27 After that, you can just clone any taskpirate-enabled hook as a subfolder into ~/.task/hooks/:
28
29     git clone https://github.com/tbabej/task.default-date-time ~/.task/hooks/default-date-time/
30
31 How to write a taskpirate hook
32 ------------------------------
33
34 In your hook's repository, any file matching ```pirate_add*.py``` will be searched for hooks in on-add event. In the same sense, any file matching ```pirate_mod*.py``` will be searched for hooks in on-modify event.
35
36 Now, the pirate_add_example.py might look as follows:
37
38     def hook_example(task):
39         task['description'] += "changed by a hook"
40
41 Any function in pirate_add_example that is called ```hook_*``` will be considered as a hook in on-add event. It will be passed the ```Task``` object corresponding to the current state of the task being added (as modified by the previous hooks).
42
43 More details
44 ------------
45
46 TaskWarrior hooks are intended to be simple, but they involve writing some boilerplate code (parsing/formatting json). To allow users to write dead simple code, they can leverage tasklib.
47
48 Using tasklib simplifies things a lot, however, it's not a super-lightweight - usage of tasklib can slow down the hook by as much as 30-50ms (usual python hook can probably run in under 40ms), since it imports multiple libraries.
49
50 This becomes a problem when user has multiple tasklib-based hooks, since the import time adds up.
51
52 Also, note that taskpirate with arbitrary number of hooks will be most likely faster than 2-3 regular python hooks.
53
54 Example hooks
55 -------------
56
57 You can look into my ```task.default-date-time``` or ```task.shift-recurrence``` hooks.