tastic.tastic (module)

A library of tools for working with plain-text taskpaper documents

Authors:@thespacedoctor
Date Created:September 2, 2016
class tastic.tastic.baseClass(matchObject, parentObject=None)[source]

This is the base class for all taskpaper objects: documents, projects and tasks

Key Arguments:
  • matchObject – a dictionary containing the constituent parts of the object
  • parentObject – the parent object containing this taskpaper object. Default None
add_note(note)[source]

Add a note to this taskpaper object

Key Arguments:
  • note – the note (string)
Return:
  • None

Usage:

To add a note to a document, project or task object:

newNote = doc.add_note(And another note with a link http://www.thespacedoctor.co.uk")
add_project(title, tags=None)[source]

Add a project to this taskpaper object

Key Arguments:
  • title – the title for the project.
  • tags – tag string (“@one @two(data)”) or list of tags ([‘one’, ‘two(data)’])
  • oldContent – the old content to be replaced in parent object (user sould not need to give this)
  • newContent – the replacement text for the parent object (user sould not need to give this)
Return:
  • project – the new taskpaper project object

Usage:

To add a sub-project to a taskpaper document or project use:

newProject = doc.add_project(
    title="this is a projects I added",
    tags="@with @tags"
)
add_tag(tag)[source]

Add a tag this taskpaper object

Key Arguments:
  • tag – the tag to add to the object

Usage:

aTask.add_tag("@due")
add_task(title, tags=None)[source]

Add a task to this taskpaper object

Key Arguments:
  • title – the title for the task.
  • tags – tag string (‘@one @two(data)’) or list of tags ([‘one’, ‘two(data)’])
Return:
  • task – the new taskpaper task object

Usage:

To add a task to an object (document, project, or task) use:

newTask = doc.add_task("this is a task I added", "@with @tags")
all_tasks()[source]

return a flat list of all tasks contained within this taskpaper object

Return:
  • taskList – a flat list of all tasks

Usage:

To return a flat list of all tasks recursively found with a taskpaper document object, use the following:

allTasks = doc.all_tasks()
for t in allTasks:
     print t.title
content

The text content of this object (excluding title)

Much like the raw_content of an object, but does not include a title or tags. The initial indentation is also removed. For a document object the content is synonymous with raw_content.

Usage:

pContent = aProject.content
tContent = aTask.content
del_tag(tag)[source]

delete a tag this taskpaper object

Key Arguments:
  • tag – the tag to delete to the object

Usage:

aTask.del_tag("@due")
done(depth='root')[source]

mark this object as done

Key Arguments:
  • depth – either mark root item as done or all recursive items. Default “root”. [“root”|”all”]

Usage:

To mark a task or project as done”

aTask.done()

Or or mark the object as done as well all descendant tasks and projects:

aTask.done("all")
get_project(projectName)[source]

recursively scan this taskpaper object to find a descendant project by name

Key Arguments:
  • projectName – the name, or title, of the project you want to return
Return:
  • project – the taskpaper project object you requested (or None if no project was matched)

Usage:

archiveProject = doc.get_project("Archive")
get_task(taskName)[source]

recursively scan this taskpaper object to find a descendant task by name

Key Arguments:
  • taskName – the name, or title, of the task you want to return
Return:
  • task – the taskpaper task object you requested (or None if no task was matched)

Usage:

aTask = doc.get_task("cut the grass")
notes

list of the notes assoicated with this object

Usage:

The document, project and task objects can all contain notes.

docNotes = doc.notes
projectNotes = aProject.notes
taskNotes = aTask.notes
notestr()[source]

return the notes of this object as a string

Return:
  • notestr – the notes as a string

Usage:

doc.notestr
parent

This taskpaper object’s parent object (if any)

Usage:

To reserve up the taskpaper document tree and find the parent object that contains this object (e.g. the document containing the task you’re working with) use the following:

taskParent = aTasks.parent
print taskParent

prints the following

<Taskpaper Document `saturday-tasks.taskpaper`>
projects

All child projects of this taskpaper object

Usage:

Given a taskpaper document object (doc), to get a list of the project objects found within the document use:

docProjects = doc.projects

The same is true of project objects which may contain sub-projects:

aProject = docProjects[0]
subProjects = aProject.projects
raw_content

The raw, untidied content of the taskpaper object

Usage:

To return the inital raw content for the matched object (document, project, task or note)

print project.raw_content
print note.raw_content
print task.raw_content
set_tags(tags='')[source]

Set the tags for this taskpaper object

Key Arguments:
  • tags – a tag string to set

Usage:

aTask.set_tags("@due @mac")
sort_projects(workflowTags)[source]

order the projects within this taskpaper object via a list of tags

The order of the tags in the list dictates the order of the sort - first comes first*
Key Arguments:
  • workflowTags – a string of space/comma seperated tags.
Return:
  • None

Usage:

To recursively sort the projects within a taskpaper document with the following order:

  1. @due
  2. @flag
  3. @hold
  4. @next
  5. @someday
  6. @wait

use the following:

doc.sort_projects("@due, @flag, @hold, @next, @someday, @wait")
sort_tasks(workflowTags, indentLevel=1)[source]

order tasks within this taskpaper object via a list of tags

The order of the tags in the list dictates the order of the sort - first comes first*

Key Arguments:
  • workflowTags – a string of space seperated tags.
Return:
  • None

Usage:

To recursively sort the tasks within a taskpaper document with the following order:

  1. @due
  2. @flag
  3. @hold
  4. @next
  5. @someday
  6. @wait

use the following:

doc.sort_tasks("@due, @flag, @hold, @next, @someday, @wait")
tagged_projects(tag)[source]

return a list of projects contained within this taskpaper object filtered by a given tag

Key Arguments:
  • tag – the tag to filter the projects by.
Return:
  • projectList – the list of filtered projects

Usage:

To filter the projects recursively found with a taskpaper document object and return only those projects tagged with flag, using the following:

filteredProjects = doc.tagged_projects("flag")
for p in filteredProjects:
    print p.title

Note you can give the tag with or without the @, and you can also give a tag attribute, e.g. @due(today)

tagged_tasks(tag)[source]

return a list of tasks contained within this taskpaper object filtered by a given tag

Key Arguments:
  • tag – the tag to filter the tasks by.
Return:
  • taskList – the list of filtered tasks

Usage:

To filter the tasks recursively found with a taskpaper document object and return only those tasks tagged with flag, using the following:

filteredTasks = doc.tagged_tasks("@flag")
for t in filteredTasks:
     print t.title

Note you can give the tag with or without the @, and you can also give a tag attribute, e.g. @due(today)

tags

The list of tags associated with this taskpaper object

Usage:

project and task objects can have associated tags. To get a list of tags assigned to an object use:

projectTag = aProject.tags
taskTags = aTasks.tags

print projectTag
> ['flag', 'home(bathroom)']
tasks

list of the tasks assoicated with this object

Usage:

Given a taskpaper document object (doc), get a list of top-level tasks associated with the document using:

docTasks = doc.tasks

The same is true of project and task objects that may contain sub-tasks:

aProject.tasks
aTasks.tasks
tidy()[source]

Tidy this taskpapaer object so that sub-objects appear in this order: title, tags, notes, tasks, projects

Return:
  • None

Usage:

When a taskpaper document is opened it is tidied by default. To tidy the document object (or project or task) use the command:

doc.tidy()
title

The title of this taskpaper object

Usage:

aProject.title
aTasks.title
aNote.title
to_string(indentLevel=1, title=True, tags=None, projects=None, tasks=None, notes=None)[source]

convert this taskpaper object to a string

Key Arguments:
  • indentLevel – the level of the indent for this object. Default 1.
  • title – print the title of the taskpaper object alongside the contents. Default True
  • tags – replace tags with these tags. Default None
  • projects – replace projects with these projects, pass empty list to delete all projects. Default None
  • tasks – replace tasks with these ones, pass empty list to delete all tasks. Default None
  • notes – replace notes with these ones, pass empty list to delete all notes. Default None
Return:
  • objectString – the taskpaper object as a string

Usage:

If we have the archive project from a taskpaper document, we can convert it to a string using:

print archiveProject.to_string()
Archive:
    - and a third task @done(2016-09-04) @project(parent project / child-project)
    - and a forth task @done(2016-09-04) @project(parent project / child-project)
    - fill the kettle @done(2016-09-04) @project(parent project / make coffee)
    - boil the kettle @done(2016-09-04) @project(parent project / make coffee)
class tastic.tastic.document(filepath, parentObject=None)[source]

This is the taskpaper document object - top level object

Key Arguments:
  • filepath – path to the taskpaper document

Usage:

To read a taskpaper document, use something like this:

# READ IN A TASKPAPER FILE
from tastic.tastic import document
taskpaperFile = "path/to/saturday-tasks.taskpaper"
doc = document(taskpaperFile)

Note that tastic will tidy the contents of the file when it is read into memory. See the tidy() method for details.

raw_content

The raw, untidied content of this taskpaper document

Usage:

# DISPLAY THE RAW CONTENT OF THE DOCUMENT
print doc.raw_content
refresh

Refreshs this documents’s attributesd

Usage:

To refresh the taskpaper document:

doc.refresh
save(copypath=None)[source]

save the content of the document back to the file

Key Arguments:
  • copypath – the path to a new file if you want to make a copy of the document instead of saving it to the original filepath. Default None

Usage:

To save the document to file run:

doc.save()

Or to copy the content to another file run the save method with a new filepath as an argument:

doc.save("/path/to/saturday-tasks-copy.taskpaper")
searches

The search-block (if any) associated with this document

Usage:

# DOCUMENT SEARCHES
docSearchBlock = doc.searches
tags

document objects have no tags

class tastic.tastic.note(matchObject, parentObject=None)[source]

The taskpaper note object

class tastic.tastic.project(matchObject, parentObject=None)[source]

The taskpaper project object

delete()[source]

delete a project from the document

Return:
  • None

Usage:

myProject.delete()
refresh

Refreshs this project’s attributes if, for example, the parent document’s projects or tasks has been sorted

Usage:

To refresh the project:

myProject.refresh
class tastic.tastic.task(matchObject, parentObject=None)[source]

The taskpaper task object

refresh

Refreshs this tasks’s attributes if, for example, the parent document’s projects or tasks has been sorted

Usage:

To refresh the task:

aTask.refresh