taskw package

Subpackages

• taskw.fields package
  • Submodules
  • taskw.fields.annotationarray module
  • taskw.fields.array module
  • taskw.fields.base module
  • taskw.fields.choice module
  • taskw.fields.commaseparateduuid module
  • taskw.fields.date module
  • taskw.fields.duration module
  • taskw.fields.numeric module
  • taskw.fields.string module
  • taskw.fields.uuid module
  • Module contents

Submodules

taskw.exceptions module

exception taskw.exceptions.TaskwarriorError(command, stderr, stdout, code)

Bases: Exception

taskw.task module

class taskw.task.Task(data, udas=None)

Bases: dict

FIELDS = {'annotations': <AnnotationArrayField 'Annotations'>, 'depends': <CommaSeparatedUUIDField 'Depends Upon'>, 'description': <StringField 'Description'>, 'due': <DateField 'Due'>, 'end': <DateField 'Ended'>, 'entry': <DateField 'Entered'>, 'id': <NumericField 'ID'>, 'imask': <NumericField 'Imask'>, 'mask': <StringField 'Mask'>, 'modified': <DateField 'Modified'>, 'parent': <StringField 'Parent'>, 'priority': <ChoiceField 'Priority'>, 'project': <StringField 'Project'>, 'recur': <DurationField 'Recurrence'>, 'scheduled': <DateField 'Scheduled'>, 'start': <DateField 'Started'>, 'status': <ChoiceField 'Status'>, 'tags': <ArrayField 'Tags'>, 'until': <DateField 'Until'>, 'urgency': <NumericField 'Urgency'>, 'uuid': <UUIDField 'UUID'>, 'wait': <DateField 'Wait'>}

classmethod from_input(input_file=<_io.TextIOWrapper name='<stdin>' mode='r' encoding='UTF-8'>, modify=False, udas=None)

Create a Task directly from stdin by reading one line. If modify=True, two lines are expected, which is consistent with the Taskwarrior hook system. The first line is interpreted as the original state of the Task, and the second one as the new, modified state.

Parameters:

• input_file – Input file. Defaults to sys.stdin.
• modify – Flag for on-modify hook event. Defaults to False.
• udas – Taskrc udas. Defaults to None.

:return Task

classmethod from_stub(data, udas=None)

Create a Task from an already deserialized dict.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

get_changes(serialized=False, keep=False)

Get a journal of changes that have occurred

Parameters:

• serialized – Return changes in the serialized format used by TaskWarrior.
• keep_changes – By default, the list of changes is reset after running .get_changes; set this to True if you would like to keep the changes recorded following running this command.

Returns:

A dictionary of 2-tuples of changes, where the key is the name of the field that has changed, and the value is a 2-tuple containing the original value and the final value respectively.

serialized()

Returns a serialized representation of this task.

serialized_changes(keep=False)

set(key, value)

Set a key’s value regardless of whether a change is seen.

update(values, force=False)

Update this task dictionary

Returns:A dictionary mapping field names specified to be updated and a boolean value indicating whether the field was changed.

taskw.taskrc module

class taskw.taskrc.TaskRc(path=None, overrides=None)

Bases: dict

Access the user’s taskRC using a dictionary-like interface.

There is a downside, though:

Unfortunately, collapsing our configuration into a dict has a jarring limitation – we can’t store both of the following simultaneously:

• color = on
• color.header = something

In this module, we err on the side of storing subkeys rather than the actual value in situations where both are necessary.

Please forgive me.

UDA_TYPE_MAP = {'date': <class 'taskw.fields.date.DateField'>, 'duration': <class 'taskw.fields.duration.DurationField'>, 'numeric': <class 'taskw.fields.numeric.NumericField'>, 'string': <class 'taskw.fields.string.StringField'>}

get_udas()

update([E, ]**F) → None. Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

taskw.taskrc.sanitize(line)

taskw.utils module

Various utilties

taskw.utils.annotation_exists_in_list(authoritative, new)

taskw.utils.annotation_list_to_comparison_map(annotations)

taskw.utils.clean_ctrl_chars(s)

Clean string removing most (but not all) control characters

taskw.utils.clean_task(task)

Clean a task by replacing any dangerous characters

taskw.utils.convert_dict_to_override_args(config, prefix='')

Converts a dictionary of override arguments into CLI arguments.

• Converts leaf nodes into dot paths of key names leading to the leaf node.
• Does not include paths to leaf nodes not being non-dictionary type.

See taskw.test.test_utils.TestUtils.test_convert_dict_to_override_args for details.

taskw.utils.decode_task(line)

Parse a single record (task) from a task database file.

I don’t understand why they don’t just use JSON or YAML. But that’s okay.

>>> decode_task('[description:"Make a python API for taskwarrior"]')
{'description': 'Make a python API for taskwarrior'}

taskw.utils.encode_query(value, version, query=True)

taskw.utils.encode_task(task)

Convert a dict-like task to its string representation

taskw.utils.encode_task_experimental(task)

Convert a dict-like task to its string representation Used for adding a task via task add

taskw.utils.encode_task_value(key, value, query=False)

taskw.utils.get_annotation_value(annotation)

Can either be a dictionary, or a string.

taskw.utils.make_annotation_comparable(annotation)

Make an annotation comparable.

Some transformations occur internally when storing a message in Taskwarrior. Let’s flatten those out.

taskw.utils.merge_annotations(left, right)

taskw.warrior module

Code to interact with taskwarrior

This module contains an abstract base class and two different implementations for interacting with taskwarrior: TaskWarriorDirect and TaskWarriorShellout.

If it is determined that there is a binary ‘task’ on the system and that it is of a sufficiently advanced version, then TaskWarriorShellout will be made the default TaskWarrior class. If not, then the default TaskWarrior class will fall back to the older TaskWarriorDirect implementation.

class taskw.warrior.Command

Bases: object

Encapsulates available commands.

ALL = 'all'

COMPLETED = 'completed'

PENDING = 'pending'

classmethod files(command)

class taskw.warrior.DataFile

Bases: object

Encapsulates data file names.

COMPLETED = 'completed'

PENDING = 'pending'

classmethod filename(name)

class taskw.warrior.Status

Bases: object

Encapsulates task status values.

COMPLETED = 'completed'

DELETED = 'deleted'

PENDING = 'pending'

WAITING = 'waiting'

classmethod is_pending(status)

Identifies if the specified status is a ‘pending’ state.

classmethod to_file(status)

Returns the file in which this task is stored.

taskw.warrior.TaskWarrior

alias of taskw.warrior.TaskWarriorShellout

class taskw.warrior.TaskWarriorBase(config_filename='~/.taskrc', config_overrides=None, marshal=False)

Bases: object

The task warrior

Really though, a python object with methods allowing you to interact with a taskwarrior database.

filter_by(func)

get_task(**kw)

classmethod load_config(config_filename='~/.taskrc', overrides=None)

Load ~/.taskrc into a python dict

>>> config = TaskWarrior.load_config()
>>> config['data']['location']
'/home/threebean/.task'
>>> config['_forcecolor']
'yes'

load_tasks(command='all')

Load all tasks.

Similar to TaskWarrior, a specific command may be specified:

all - a list of all issues pending - a list of all pending issues completed - a list of all completed issues

By default, the ‘all’ command is run.

>>> w = TaskWarrior()
>>> tasks = w.load_tasks()
>>> tasks.keys()
['completed', 'pending']
>>> type(tasks['pending'])
<type 'list'>
>>> type(tasks['pending'][0])
<type 'dict'>

task_add(description, tags=None, **kw)

Add a new task.

Takes any of the keywords allowed by taskwarrior like proj or prior.

task_delete(**kw)

task_done(**kw)

task_start(**kw)

task_stop(**kw)

task_update(task)

class taskw.warrior.TaskWarriorShellout(config_filename='~/.taskrc', config_overrides=None, marshal=False)

Bases: taskw.warrior.TaskWarriorBase

Interacts with taskwarrior by invoking shell commands.

This is currently the supported version and should be considered stable.

See https://github.com/ralphbean/taskw/pull/15 for discussion and https://github.com/ralphbean/taskw/issues/30 for more.

DEFAULT_CONFIG_OVERRIDES = {'confirmation': 'no', 'dependency': {'confirmation': 'no'}, 'json': {'array': 'TRUE'}, 'verbose': 'nothing'}

filter_tasks(filter_dict)

Return a filtered list of tasks from taskwarrior.

Filter dict should be a dictionary mapping filter constraints with their values. For example, to return only pending tasks, you could use:

{'status': 'pending'}

Or, to return tasks that have the word “Abjad” in their description that are also pending:

{
    'status': 'pending',
    'description.contains': 'Abjad',
}

Filters can be quite complex, and are documented on Taskwarrior’s website.

get_configuration_override_args()

get_task(**kw)

classmethod get_version()

classmethod is_supported_version()

Returns true if minimum runtime requirements are met

load_tasks(command='all')

Returns a dictionary of tasks for a list of command.

sync(init=False)

task_add(description, tags=None, **kw)

Add a new task.

Takes any of the keywords allowed by taskwarrior like proj or prior.

task_annotate(task, annotation)

Annotates a task.

task_delete(**kw)

Marks a task as deleted.

task_denotate(task, annotation)

Removes an annotation from a task.

task_done(**kw)

task_info(**kw)

task_start(**kw)

Marks a task as started.

task_stop(**kw)

Marks a task as stopped.

task_update(task)

exception taskw.warrior.UnsupportedVersionException

Bases: Exception

taskw.warrior.open(fname, mode)

Module contents

taskw.TaskWarrior

alias of taskw.warrior.TaskWarriorShellout

class taskw.TaskWarriorShellout(config_filename='~/.taskrc', config_overrides=None, marshal=False)

Bases: taskw.warrior.TaskWarriorBase

Interacts with taskwarrior by invoking shell commands.

This is currently the supported version and should be considered stable.

See https://github.com/ralphbean/taskw/pull/15 for discussion and https://github.com/ralphbean/taskw/issues/30 for more.

DEFAULT_CONFIG_OVERRIDES = {'confirmation': 'no', 'dependency': {'confirmation': 'no'}, 'json': {'array': 'TRUE'}, 'verbose': 'nothing'}

filter_tasks(filter_dict)

Return a filtered list of tasks from taskwarrior.

Filter dict should be a dictionary mapping filter constraints with their values. For example, to return only pending tasks, you could use:

{'status': 'pending'}

Or, to return tasks that have the word “Abjad” in their description that are also pending:

{
    'status': 'pending',
    'description.contains': 'Abjad',
}

Filters can be quite complex, and are documented on Taskwarrior’s website.

get_configuration_override_args()

get_task(**kw)

classmethod get_version()

classmethod is_supported_version()

Returns true if minimum runtime requirements are met

load_tasks(command='all')

Returns a dictionary of tasks for a list of command.

sync(init=False)

task_add(description, tags=None, **kw)

Add a new task.

Takes any of the keywords allowed by taskwarrior like proj or prior.

task_annotate(task, annotation)

Annotates a task.

task_delete(**kw)

Marks a task as deleted.

task_denotate(task, annotation)

Removes an annotation from a task.

task_done(**kw)

task_info(**kw)

task_start(**kw)

Marks a task as started.

task_stop(**kw)

Marks a task as stopped.

task_update(task)

taskw.clean_task(task)

Clean a task by replacing any dangerous characters

taskw.encode_task(task)

Convert a dict-like task to its string representation

taskw.decode_task(line)

Parse a single record (task) from a task database file.

I don’t understand why they don’t just use JSON or YAML. But that’s okay.

>>> decode_task('[description:"Make a python API for taskwarrior"]')
{'description': 'Make a python API for taskwarrior'}

taskw.encode_task_experimental(task)

Convert a dict-like task to its string representation Used for adding a task via task add