ToDonePY - A basic command-line tast manager
Introduction
Move your ToDo's to ToDone's!
Note
This project has only been tested on a Unix OS. I welcome collaborations to test it for MacOS and Windows!
ToDonePy is a command-line interface for managing your to do list. It provides a root command, to, and three subcommands:
- to do adds a new task to your list at different priorities.
- to doing shows you what you should be doing.
- to done removes a completed tast from your list.
Docs and Code
The documentation lives at https://ToDonePy.readthedocs.io/ .
The code lives at https://github.com/rbpatt2019/ToDonePy/ .
Installation
This project has been released on PyPI, so it can be installed with pip:
pip install -U ToDonePy
Alternatively, you can install the project manually by cloning the repo, and using the included Makefile.
git clone https://github.com/rbpatt2019/ToDonePy/
make install
If you would like to contribute to development, the install instructions are slightly different. Please see the section on contributing.
Usage
to
The base command The base command to
has a few useful features of its own. To see what version of the command you are using, call:
to --version
As with any good command-line tool, you can get some basic help by calling:
to --help
You can get help on any subcommand by calling --help
after that subcommand. For example, to get help with to doing
, call:
to doing --help
Under the hood, to
creates the context object that holds the information on the file you use for tracking you're TODOs. If you don't specify a file to use, it will default to $HOME/TODO.tsv
. If you would like to specify a different file to use, than call the command with the --file/-f
flag like so:
to --file /path/to/your/TODO.tsv subcommand
Note
If you plan to use a file other than the default, I recommend setting it by creating the environmental variable, TODO_LIST
.
Regardless of whether you use the default or not, calling to
with any of the subcommands - do
, doing
, or done
- will check to see if the file exists. If it does exist, to
then pass the path on to the subcommand. If it doesn't exist, then to
creates an empty file which it then passes on to the subcommand.
As a final note, it is worth emphasising that the contex object is only created when to
is invoked with a subcommand. So, after a clean install, calling to --help
or to --version
will NOT create your TODO.tsv
file, even if you pass the --file/-f
flag. However, call to do
, and it will pop into existence.
to do
Adding new tasks with To begin tracking your TODOs, call the command as follows:
to do rank tasks
to
is the base command. It must be invoked to use any part of the tool. The do
subcommand is how you add tasks to your TODO.tsv
. After to do
, there are two mandatory arguments: rank
and tasks
. The first argument is rank
. rank
should be a number indicating how important this task is. 1 is very important, 2 less so, etc. Though nothing explicitly bans you from using as many ranks as you want, I'd reccomed using 3 for high, medium, and low priority.
The second argument is tasks
. Here, specify what it is you need to do. If your task takes more than one word to describe, then you need to include it in quotes. tasks
supports an indefinite number of arguments, from 1 to as many as you want.
Note
All tasks specified will be added at the same rank, so only combine tasks you want to give the same priority.
So, if you wanted to remind yourself to write an abstract for that paper you've been delaying and to email your boss, call:
to do 1 'Write my abstract' 'Email boss'
This will create TODO.tsv
if it doesn't already exist, and add 'Write my abstract' and 'Email boss', both with a rank of one, to TODO.tsv
. to do
also logs the date and time the task was added, so that you always know how old a task is.
to do
also has one option: --sort/-s
. This specifies how to sort your list after a new task is added. It must be one of: [rank, date, both, none]
. both
sorts by name and then date, and none
does not sort, simply appending tasks to the end of your list. It defaults to both
, so that your highest priority tasks are first, and, among those, the oldest are first. If you just wanted to sort by date after adding a new task, then you could call:
..code:: sh
to do --sort date 1 'Important work'
to doing
Keeping track of tasks with Once you've added some TODOs to your list, you need to make sure you stay on top of them. To see what needs to be done, call:
to doing
This should echo the 5 tasks at the top of your TODO.tsv
to the terminal.
You can specify how to sort your tasks by passing the --sort/-s
flag with one of: [rank, date, both, none]
. It defaults to none
, thus preserving the order in your TODO.tsv
. Any call to sort will also change the order currently in your TODO.tsv
, not just the order they are echoed.
Also, specifying the --number/-n
flag will let you change how many tasks are returned, and it defaults to 5. So, if you want to return 3 tasks sorted by rank, call:
to doing -s rank -n 3
If you have fewer tasks than number
, the command prints a friendly reminder of that fact!
Sometimes, you might want to correct an error, change a priority, or in some way edit yout TODO.tsv
. In these cases, you can call to doing
in editor mode:
to doing --edit
This will open TODO.tsv
in your system editor. Where you would see something like below, if you've been following along:
1 YYYY-MM-DD HH:MM:SS Write my abstract
1 YYYY-MM-DD HH:MM:SS Email boss
1 YYYY-MM-DD HH:MM:SS Important work
Nothing fancy, just a plain tsv with rank
in the first column, the date/time of addition in the second, and `task
in the third. Now, you can make all the changes you want, then save and close the file to return to the command line.
Calling --edit
will trump any calls to sort
or number
made in the same command.
This call opens the default editor on your system, usually defined by the environmental variable EDITOR for Linux systems. Currently, there is not support to specify a specific editor beside the default.
to done
Completing your tasks with After the end of a productive work session, you've completed a task from your list. Boom! Time well spent. To remove it from your TODO.tsv
, call:
to done tasks
As with to do, to done suports an indefinite number of tasks, as long as all multi-word tasks are enclosed in quotes. For example, if you emailed your boss that finished abstract, then you can remove those tasks like so:
to done 'Write my abstract' 'Email boss'
If to done
finds these tasks in your TODO.tsv
, it'll remove them! If it can't find the tasks, it will print a message saying which ones couldn't be removed.
Under the hood, to done
creates a temp file, then performs a string match to each line of your TODO.tsv
. If a perfect match to ''task'' is not in a line, that line is written to the temp file. If ''task'' is in a line, that line is skipped. This way, the temp file ends up containing only those tasks that aren't completed. Once every line is checked, the temp file replaces TODO.tsv
with its contents. Task deleted!
Warning
If two different tasks contain the same text, they will both be deleted!
Known Bugs
- Test fails when called with
--edit
asresult.output == 1
, likely the result of a hung editor.
Recent Changes
Please see the CHANGELOG
Next Steps
- Addition of TODOs from file parsing
- Graphic notification support for use with cron
- Support removal of tasks by task ID number
- Continue to expand README and doumentation.
Thank Yous
- Click for making an excellent package with absolutely stellar documentation.