Tools for working with plain text todo lists.
Python Shell
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
setup.cfg add new query lexer Oct 2, 2016

TodoFlow 5

TodoFlow is Python module that provides functions to parse, filter, search and modify todo lists stored in plain text files with TaskPaper syntax.


  • 2016-10-08 - 5.0.0
    • updates to TaskPaper 3 queries!
    • drops dependency on ply
    • removes separation between Nodes and Todos
    • removes printers and file reading methods
  • 2015-10-02 - 4.0.2
  • 2015-04-24 - Removal of workflows
  • 2014-10-24 - Release of version 4


pip install TodoFlow


TodoFlow is based on two classes: Todos and Todoitem.


Todos is a tree-like collection of todo items. Todos have list of subitems and one todoitem (except tree root that doesn't have one).

Creating todos

You can create todos from string:

from todoflow import Todos
todos = todoflow.Todos("""
project 1:
    - task 1
    - task 2 @today

Saving todos

You can stringify todos in order to write them to a file:

>>> print(todos)
project 1:
    - task 1
    - task 2 @today
project 2:
    - task 3

Filtering todos

TodoFlow tries to provide the same queries as TaskPaper 3. If something doesn't work the same way please create an Issue.

>>> today = todos.filter('/*/@today')
>>> print(today)
project 1:
    - task 2 @today
  • todos.filter(query) - Returns new Todos, with items, that match given query, or are parent of one. It's analogous to how TaskPaper app works.
  • - Returns iterator of Todos that match query (and only them).


Todoitems belong to Todos and have methods to modify them and to retrive data from them:

  • tag(tag_to_use, param=None)
  • remove_tag(tag_to_remove)
  • has_tag(tag)
  • get_tag_param(tag)
  • get_type(tag)
  • get_text()
  • get_line_number()
  • get_line_id()
  • edit(new_text)
  • change_to_task()
  • change_to_project()
  • change_to_note()

They can be mutaded, then and those changes are visible in every Todos that they belong to.

>>> for item in'@today'):
>>>     item.tag('@done', '2016-10-08')
>>>     item.remove_tag('@today')
>>> print(todos)
project 1:
   - task 1
   - task 2 @done(2014-10-24)


Module todoflow.textutils provides functions that operate on strings and are used internally in TodoFlow but can be useful outside of it:

  • is_task(text)
  • is_project(text)
  • is_note(text)
  • has_tag(text, tag)
  • get_tag_param(text, tag)
  • remove_tag(text, tag)
  • replace_tag(text, tag, replacement)
  • add_tag(text, tag, param=None)
  • enclose_tag(text, tag, prefix, suffix=None)
  • get_all_tags(text, include_indicator=False)
  • modify_tag_param(text, tag, modification)
  • sort_by_tag_param(texts_collection, tag, reverse=False)