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 objectparentObject
– 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 thecontent
is synonymous withraw_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 (orNone
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 (orNone
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 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:
- @due
- @flag
- @hold
- @next
- @someday
- @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:
- @due
- @flag
- @hold
- @next
- @someday
- @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)
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 Truetags
– replace tags with these tags. Default Noneprojects
– replace projects with these projects, pass empty list to delete all projects. Default Nonetasks
– replace tasks with these ones, pass empty list to delete all tasks. Default Nonenotes
– 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
document objects have no tags