todo.py¶
todo.py
is a python script which aims to be an active and accurate
alternative to Gina Trapani’s todo.sh
. todo.py
is extensible with
add-ons that can be written in a few ways, and written in a way that should
be inviting to hackers of varying degrees of experience.
Usage¶
Usage: todo.py [options] action [arg(s)]
Options:
-h, --help show this help message and exit
-c CONFIG, --config=CONFIG
Supply your own configuration file,must be an absolute path
-d TODO_DIR, --dir=TODO_DIR
Directory you wish ./todo.py to use.
-p, --plain-mode Toggle coloring of items
-P, --no-priority Toggle display of priority labels
-t, --prepend-date Toggle whether the date is prepended to new items.
-V, --version Print version, license, and credits
-i, --invert-colors Toggle coloring the text of items or background of items.
-l, --legacy Toggle organization of items in the old manner.
-+ Toggle display of +projects in-line with items.
-@ Toggle display of @contexts in-line with items.
-# Toggle display of #{dates} in-line with items.
Use ./todo.py -h for option help
Usage: ./todo.py command [arg(s)]
add | a "Item to do +project @context #{yyyy-mm-dd}"
Adds 'Item to do +project @context #{yyyy-mm-dd}' to your todo.txt
file.
+project, @context, #{yyyy-mm-dd} are optional
addm "First item to do +project @context #{yyyy-mm-dd}
Second item to do +project @context #{yyyy-mm-dd}
...
Last item to do +project @context #{yyyy-mm-dd}
Adds each line as a separate item to your todo.txt file.
append | app NUMBER "text to append"
Append "text to append" to item NUMBER.
del | rm NUMBER
Deletes the item on line NUMBER in todo.txt
depri | dp NUMBER
Remove the priority of the item on line NUMBER.
do NUMBER
Marks item with corresponding number as done and moves it to
your done.txt file.
help | h
Display this message and exit.
list | ls
Lists all items in your todo.txt file sorted by priority.
listcon | lsc
Lists all items in your todo.txt file sorted by context.
listdate | lsd
Lists all items in your todo.txt file sorted by date.
listproj | lsp
Lists all items in your todo.txt file sorted by project title.
log
Shows the last five commits in your repository.
pri | p NUMBER [A-X]
Add priority specified (A, B, C, etc.) to item NUMBER.
prepend | pre NUMBER "text to prepend"
Add "text to prepend" to the beginning of the item.
pull
Pulls from your remote git repository.
push
Pushes to your remote git repository.
status
"git status" of the repository containing your todo files.
Requires git version 1.7.4 or newer.
Add-ons¶
There are two ways to write add-ons for todo.py
.
- Write an executable that works similar to the specifications for
todo.sh
. - Write a python module.
This documentation will cover the latter.
Writing a python module to extend todo.py
.¶
Your module should start with a doc-string, e.g.,
"""
example_module
~~~~~~~~~~~~~~
My new awesome module to extend todo.py.
------
Author: Ian Cordasco
Commands:
- foo | foobar
- monty | montypython
- spam
"""
You can put as much information in there as you like. It mainly helps other
people and isn’t used by todo.py
.
After that, you should import at least one thing from todo.py
:
usage
(introduced in v0.3.0)
This is a decorator which supplies some crucial information to todo.py
.
usage
will tell todo.py
what to print when a user runs todo.py
help
. An example implementation would be:
from todo import usage
@usage('\tfoo | foobar "Args if you want them"',
'\t\tDescription of what `foo` does.')
def foo(*args):
"""Doc-string for foo()"""
pass
Registering Your Commands¶
Unfortunately, the command
decorator used internally in todo.py
will
not work properly for add-ons. Until I can design a working solution, you can
either use the command
decorator to construct your own dictionary of
commands which todo.py
will then use to recognize your script’s commands.
Send any suggestions to graffatcolmingov [at] gmail or just send a pull request. (I’d rather the latter since it will more clearly attribute the idea to you.)