PyGTD Documentation

Overview

In March of 2004 I read David Allen's personal-productivity book Getting Things Done, and I took to heart its central tenets of getting everything out of your head and into a trusted system, and writing down the very next physical action that will move you toward each of your stated goals. Allen's system is missing the dimensions of Urgency and Importance that Stephen Covey preaches in his Seven Habits of Highly Effective People, and that's an especially important aspect for any system that I will use. I have several long-term projects at work, and I need reminders to spend time on the important things that aren't too urgent.

I tried several software packages for managing to-do lists, including Natara's Bonsai and Llamagraphics' Life Balance, but I found that the former made it hard to keep track of what was important, and the latter made it a chore to enter data. I wanted something lightweight and flexible, and so, after several months of occasional experimentation, I decided to write my own tool.

PyGTD is a simple system that incorporates major features from both Allen and Covey. It's a small Python program that crunches any number of lightly-formatted text files containing project to-do lists, and creates a prioritized to-do list based on the next physical action in each project. The prioritization takes into account the importance, the urgency, the effort required, and the schedule pressure. The project to-do files are hierarchical, enabling a very rich range of usage patterns.

It's very easy to set up a programmer's text editor (I am currently using Zeus) to run the Python script whenever you hit the compile button, and the new master to-do list is automatically reloaded. Alternatively, you can just run the gtd.py script manually, from the command line or by double-clicking the file.

The PyGTD software is in a state where I find it quite usable and useful, and I'm releasing it under the GPL so that anyone who thinks it might be useful can try it out and make their own modifications. If you do try it out, please drop me a line and let me know.

PyGTD has been tested under windows and Linux, and I don't see any reason why it wouldn't work unchanged on a Macintosh. Be forewarned that error handling is not robust, so if you deviate from the expected input format (described below), the script will not work the way you expect (it will probably bomb out on an exception).

Installation

Download pyGTD.zip (17 kb)

Unzip the archive to a convenient location (a directory called gtd will be created with all the files you need).

Read the "Starting Out" section below.

How it works

You create several text files that represent your context-dependent Project and Next Action lists. The sample files included with PyGTD are:

GTD.gtd
Personal.gtd
ProfessionalDevelopment.gtd

When you run gtd.py, all of the next actions from each of these files are pulled out, prioritized, sorted, and put into a single todo.gtd file.

When you make some progress on a task, you change the todo.gtd file to describe how much you've completed on that task and add any notes you have about the task. The next time you run gtd.py, the updated status is transfered back to each of your context-dependent Project and Next Action lists, and a new todo.gtd is created.

  Context
   lists    -> todo.gtd -> update todo.gtd ->
     ^                                      | 
     |                                      V
     <-        <-        <-       <-       <-

Running it

python gtd.py

This will parse all of the Context list files in the current directory and create a todo.gtd file in the current directory.

What it looks like

Text files!

An entry in a Context list file looks like:

--start of file--

* Weekly review
  C=0 I=5 U=4 T=1H D=2004-11-08 S=0D R=2004-11-01+1W ID=1
  Review previous week's accomplishments
  Look over long-term projects to determine relative priorities

* Morning Review
  C=0 I=5 U=4 T=1H D=2004-11-08 S=0D R=2004-11-01+1W ID=1
  1. Review upcoming tasks and appointments
     T=10M
  2. Clear your head
     T=20M

--end of file--

where

* An asterisk at the start of a line indicates this is a new task/subtask that can be completed in any order
n. A line starting with a number followed by "." is a subtask that needs to be completed in a specific order. The lower number tasks 'block' the higher numbered tasks.
title A * or n. is followed by the brief description or title of the task or project.
status line

C=0 I=5 U=4 T=1H D=2004-11-08 S=0D R=2004-11-01+1W ID=1

Note that you need not create a status line yourself. If you omit it, PyGTD will create it for you.

Here:

C=n Percent complete, where n is a number between 0 and 100.
I={1,2,3,4,5} Importance (a 5 is a task that is crucial to your life or livelihood; a 1 might be nice to do someday).
U={1,2,3,4,5} Urgency on a logarithmic scale (5=today, 4=this week, 3=this month, 2=this quarter, 1=this year).
T=\d+[MHDW] Time required in minutes, hours, days, or weeks. By default, days are counted as 8 hours, weeks at 40 hours (you can override both of these values by changing constants in the script). Examples: T=10H (ten hours), T=3W (three weeks, or 120 hours).
R=(YYYY-MM-DD\+)?\d+[DWMY] Recurrence, either on a fixed schedule (if the date is specified), or from time of completion (if not), in days, weeks, months, or years.
Examples:
  • 1904-06-16+1Y - Every year on Bloomsday
  • 2004-11-29+1W - Every Monday, starting November 29th, 2004
  • 3D - The due date resets to three days later each time the task is completed.
  • 1M - The due date resets to 30.42 days later each time the task is completed (365 days/12 months ~= 30 days).
S=\d+[DWMY] Startup time -- time in advance of due date where this task will start showing up in the todo list, in days, weeks, months or years.
D=YYYY-MM-DD Due date.
ID=n The id for the note. PyGTD will assign this automatically. If you choose to assign ids yourself, be sure that no two tasks in the same Context File have the same id.


Any lines following the status options are notes. Notes lines can't start with * or a number plus ".", and should not contain elements that could be confused with the status line (the parser isn't very smart).

New items need to be added to the Context list files. New sub items can be added in either the Context list files or todo.gtd.

A note on indentation: The first line of each subtask of a particular task must be indented with the same number of spaces. All lines, except for the first line of root-level tasks, must be indented by at least one space.

todo.gtd

The automatically-generated todo.gtd file contains entries of the form:

--start of file--

4.96 1:00 Exercise
          C=0 P=6 I=5 U=4 T=1H D=2004-11-24 R=1D ID=14
          Row
          [Stay fit]
          [./RecurringTasks.gtd]

--end of file--

where

4.96 Priority: a derived index that is a measure of the time to complete the tast, the importance, the urgency and any deadline specified. Modifying this field will have no effect.
1:00 Time required to complete the Next Action in hours:minutes or hours. To modify this field, change the 'T=' portion of the status line.
Exercise The title of the Next Action.
C=0 P=6 [...] Status line: you can modify all fields here (except ID and P), and the changes will be propagated back to the individual Context list files. P={1,2,3,4,5,6}
Row Notes associated with the next action.
[Stay fit] Title of parent task, if one exists.
[./RecurringTasks.gtd] File name of the Context list. Changes to this entry will be reflected back to that file. This allows you to tell the difference between Next Actions that have identical titles but different contexts, such as doing the same thing for several different clients/projects.

In the todo.gtd file, the second line (status variables) must exist for each item, and the ID variable must be set. This will happen automatically in normal usage.

One an item gets from the Context list file into todo.gtd, all changes need to be made in todo.gtd. They will get propagated back correctly to the Context list file.

You can also add new sub-items to tasks in todo.gtd, and they will get propagated correctly back to the Context list files.

New items cannot be added to todo.gtd, only new sub-items.

Starting out

I suggest modifying the included Context list files to start out, and modifying the todo.gtd file to get a sense for how the changes propagate.

  1. You can create as many Context list files as you like. Each file needs must have the extension ".gtd".

  2. Run gtd.py to create the todo.gtd file.

  3. Edit todo.gtd to change the C= (Completion flag) on an item to 100, and re-run gtd.py.

  4. A new file, done.gtd was created in the same directory, with the completed item in it. The Context file has been updated, to show the item completed, and todo.gtd has also been updated, with a re-priortized, list without the completed item.

Credits

Documentation drafted by Evelyn Mitchell and edited by Keith Martin.

Code by Keith Martin, with thanks to Stephen Waits for pointing me toward the datetime module, and to Evelyn for helping debug the script under Linux.