From: Rob Golding Date: Mon, 19 Jan 2015 08:52:36 +0000 (+0000) Subject: Merge branch 'release/0.8.0' X-Git-Url: https://git.madduck.net/etc/taskwarrior.git/commitdiff_plain/4fe98a10e3269bbd7c43449041d1b7fcd2cbbc8a?hp=c3ad5d17022aad74d430dbbb09248f8ed10b1f66 Merge branch 'release/0.8.0' --- diff --git a/docs/conf.py b/docs/conf.py index e83a5e3..a046e31 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,9 +51,9 @@ copyright = u'2014, Rob Golding' # built documents. # # The short X.Y version. -version = '0.7.1' +version = '0.8.0' # The full version, including alpha/beta/rc tags. -release = '0.7.1' +release = '0.8.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/index.rst b/docs/index.rst index 44ef469..5c8b387 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -309,6 +309,44 @@ To pass your own configuration, you just need to update this dictionary:: >>> tw.config.update({'hooks': 'off'}) # tasklib will not trigger hooks +Creating hook scripts +--------------------- + +From version 2.4.0, TaskWarrior has support for hook scripts. Tasklib provides +some very useful helpers to write those. With tasklib, writing these becomes +a breeze:: + + #!/usr/bin/python + + from tasklib.task import Task + task = Task.from_input() + # ... + print task.export_data() + +For example, plugin which would assign the priority "H" to any task containing +three exclamation marks in the description, would go like this:: + + #!/usr/bin/python + + from tasklib.task import Task + task = Task.from_input() + + if "!!!" in task['description']: + task['priority'] = "H" + + print task.export_data() + +Tasklib can automatically detect whether it's running in the ``on-modify`` event, +which provides more input than ``on-add`` event and reads the data accordingly. + +This means the example above works both for ``on-add`` and ``on-modify`` events! + +Consenquently, you can create just one hook file for both ``on-add`` and +``on-modify`` events, and you just need to create a symlink for the other one. +This removes the need for maintaining two copies of the same code base and/or +boilerplate code. + + Working with UDAs ----------------- diff --git a/setup.py b/setup.py index 64018ea..30b2187 100644 --- a/setup.py +++ b/setup.py @@ -1,6 +1,6 @@ from setuptools import setup, find_packages -version = '0.7.1' +version = '0.8.0' setup( name='tasklib', diff --git a/tasklib/task.py b/tasklib/task.py index b6c3d09..9b3626d 100644 --- a/tasklib/task.py +++ b/tasklib/task.py @@ -5,6 +5,7 @@ import json import logging import os import six +import sys import subprocess DATE_FORMAT = '%Y%m%dT%H%M%SZ' @@ -28,6 +29,18 @@ class SerializingObject(object): """ Common ancestor for TaskResource & TaskFilter, since they both need to serialize arguments. + + Serializing method should hold the following contract: + - any empty value (meaning removal of the attribute) + is deserialized into a empty string + - None denotes a empty value for any attribute + + Deserializing method should hold the following contract: + - None denotes a empty value for any attribute (however, + this is here as a safeguard, TaskWarrior currently does + not export empty-valued attributes) if the attribute + is not iterable (e.g. list or set), in which case + a empty iterable should be used. """ def _deserialize(self, key, value): @@ -42,7 +55,7 @@ class SerializingObject(object): def timestamp_serializer(self, date): if not date: - return None + return '' return date.strftime(DATE_FORMAT) def timestamp_deserializer(self, date_str): @@ -93,13 +106,14 @@ class SerializingObject(object): return ','.join(tags) if tags else '' def deserialize_tags(self, tags): - if isinstance(tags, basestring): + if isinstance(tags, six.string_types): return tags.split(',') if tags else [] - return tags + return tags or [] - def serialize_depends(self, cur_dependencies): + def serialize_depends(self, value): # Return the list of uuids - return ','.join(task['uuid'] for task in cur_dependencies) + value = value if value is not None else set() + return ','.join(task['uuid'] for task in value) def deserialize_depends(self, raw_uuids): raw_uuids = raw_uuids or '' # Convert None to empty string @@ -111,11 +125,11 @@ class TaskResource(SerializingObject): read_only_fields = [] def _load_data(self, data): - self._data = data + self._data = dict((key, self._deserialize(key, value)) + for key, value in data.items()) # We need to use a copy for original data, so that changes - # are not propagated. Shallow copy is alright, since data dict uses only - # primitive data types - self._original_data = data.copy() + # are not propagated. + self._original_data = copy.deepcopy(self._data) def _update_data(self, data, update_original=False): """ @@ -123,11 +137,12 @@ class TaskResource(SerializingObject): updates should already be serialized. If update_original is True, the original_data dict is updated as well. """ - - self._data.update(data) + self._data.update(dict((key, self._deserialize(key, value)) + for key, value in data.items())) if update_original: - self._original_data.update(data) + self._original_data = copy.deepcopy(self._data) + def __getitem__(self, key): # This is a workaround to make TaskResource non-iterable @@ -138,12 +153,15 @@ class TaskResource(SerializingObject): except ValueError: pass - return self._deserialize(key, self._data.get(key)) + if key not in self._data: + self._data[key] = self._deserialize(key, None) + + return self._data.get(key) def __setitem__(self, key, value): if key in self.read_only_fields: raise RuntimeError('Field \'%s\' is read-only' % key) - self._data[key] = self._serialize(key, value) + self._data[key] = value def __str__(self): s = six.text_type(self.__unicode__()) @@ -168,6 +186,11 @@ class TaskAnnotation(TaskResource): def __unicode__(self): return self['description'] + def __eq__(self, other): + # consider 2 annotations equal if they belong to the same task, and + # their data dics are the same + return self.task == other.task and self._data == other._data + __repr__ = __unicode__ @@ -196,6 +219,40 @@ class Task(TaskResource): """ pass + @classmethod + def from_input(cls, input_file=sys.stdin, modify=None): + """ + Creates a Task object, directly from the stdin, by reading one line. + If modify=True, two lines are used, first line interpreted as the + original state of the Task object, and second line as its new, + modified value. This is consistent with the TaskWarrior's hook + system. + + Object created by this method should not be saved, deleted + or refreshed, as t could create a infinite loop. For this + reason, TaskWarrior instance is set to None. + + Input_file argument can be used to specify the input file, + but defaults to sys.stdin. + """ + + # TaskWarrior instance is set to None + task = cls(None) + + # Detect the hook type if not given directly + name = os.path.basename(sys.argv[0]) + modify = name.startswith('on-modify') if modify is None else modify + + # Load the data from the input + task._load_data(json.loads(input_file.readline().strip())) + + # If this is a on-modify event, we are provided with additional + # line of input, which provides updated data + if modify: + task._update_data(json.loads(input_file.readline().strip())) + + return task + def __init__(self, warrior, **kwargs): self.warrior = warrior @@ -236,9 +293,21 @@ class Task(TaskResource): def _modified_fields(self): writable_fields = set(self._data.keys()) - set(self.read_only_fields) for key in writable_fields: - if self._data.get(key) != self._original_data.get(key): + new_value = self._data.get(key) + old_value = self._original_data.get(key) + + # Make sure not to mark data removal as modified field if the + # field originally had some empty value + if key in self._data and not new_value and not old_value: + continue + + if new_value != old_value: yield key + @property + def modified(self): + return bool(list(self._modified_fields)) + @property def completed(self): return self['status'] == six.text_type('completed') @@ -261,7 +330,7 @@ class Task(TaskResource): def serialize_depends(self, cur_dependencies): # Check that all the tasks are saved - for task in cur_dependencies: + for task in (cur_dependencies or set()): if not task.saved: raise Task.NotSaved('Task \'%s\' needs to be saved before ' 'it can be set as dependency.' % task) @@ -276,8 +345,7 @@ class Task(TaskResource): # to keep a list of all depedencies in the _data dictionary, # not just currently added/removed ones - old_dependencies_raw = self._original_data.get('depends','') - old_dependencies = self.deserialize_depends(old_dependencies_raw) + old_dependencies = self._original_data.get('depends', set()) added = self['depends'] - old_dependencies removed = old_dependencies - self['depends'] @@ -330,6 +398,9 @@ class Task(TaskResource): self.refresh(only_fields=['status']) def save(self): + if self.saved and not self.modified: + return + args = [self['uuid'], 'modify'] if self.saved else ['add'] args.extend(self._get_modified_fields_as_args()) output = self.warrior.execute_command(args) @@ -347,6 +418,9 @@ class Task(TaskResource): # Circumvent the ID storage, since ID is considered read-only self._data['id'] = int(id_lines[0].split(' ')[2].rstrip('.')) + # Refreshing is very important here, as not only modification time + # is updated, but arbitrary attribute may have changed due hooks + # altering the data before saving self.refresh() def add_annotation(self, annotation): @@ -372,13 +446,22 @@ class Task(TaskResource): def add_field(field): # Add the output of format_field method to args list (defaults to - # field:'value') - format_default = lambda k: "{0}:{1}".format(k, - "'{0}'".format(self._data[k]) - if self._data[k] is not None - else '') + # field:value) + serialized_value = self._serialize(field, self._data[field]) + + # Empty values should not be enclosed in quotation marks, see + # TW-1510 + if serialized_value is '': + escaped_serialized_value = '' + else: + escaped_serialized_value = "'{0}'".format(serialized_value) + + format_default = lambda: "{0}:{1}".format(field, + escaped_serialized_value) + format_func = getattr(self, 'format_{0}'.format(field), - lambda: format_default(field)) + format_default) + args.append(format_func()) # If we're modifying saved task, simply pass on all modified fields @@ -411,6 +494,20 @@ class Task(TaskResource): else: self._load_data(new_data) + def export_data(self): + """ + Exports current data contained in the Task as JSON + """ + + # We need to remove spaces for TW-1504, use custom separators + data_tuples = ((key, self._serialize(key, value)) + for key, value in six.iteritems(self._data)) + + # Empty string denotes empty serialized value, we do not want + # to pass that to TaskWarrior. + data_tuples = filter(lambda t: t[1] is not '', data_tuples) + data = dict(data_tuples) + return json.dumps(data, separators=(',',':')) class TaskFilter(SerializingObject): """ diff --git a/tasklib/tests.py b/tasklib/tests.py index 6d67a12..6407221 100644 --- a/tasklib/tests.py +++ b/tasklib/tests.py @@ -1,12 +1,37 @@ # coding=utf-8 import datetime +import itertools +import six import shutil import tempfile import unittest from .task import TaskWarrior, Task +# http://taskwarrior.org/docs/design/task.html , Section: The Attributes +TASK_STANDARD_ATTRS = ( + 'status', + 'uuid', + 'entry', + 'description', + 'start', + 'end', + 'due', + 'until', + 'wait', + 'modified', + 'scheduled', + 'recur', + 'mask', + 'imask', + 'parent', + 'project', + 'priority', + 'depends', + 'tags', + 'annotation', +) class TasklibTest(unittest.TestCase): @@ -181,9 +206,9 @@ class TaskTest(TasklibTest): # We only save the parent task, dependency task is unsaved t.save() + t['depends'] = set([dependency]) - self.assertRaises(Task.NotSaved, - t.__setitem__, 'depends', set([dependency])) + self.assertRaises(Task.NotSaved, t.save) def test_set_simple_dependency_set(self): # Adds only one dependency to task with no dependencies @@ -223,7 +248,7 @@ class TaskTest(TasklibTest): t['depends'] = set([dependency1, dependency2]) t.save() - t['depends'] = t['depends'] - set([dependency2]) + t['depends'].remove(dependency2) t.save() self.assertEqual(t['depends'], set([dependency1])) @@ -240,11 +265,23 @@ class TaskTest(TasklibTest): t['depends'] = set([dependency1]) t.save() - t['depends'] = t['depends'] | set([dependency2]) + t['depends'].add(dependency2) t.save() self.assertEqual(t['depends'], set([dependency1, dependency2])) + def test_add_to_empty_dependency_set(self): + # Adds dependency to task with one dependencies + t = Task(self.tw, description="test task") + dependency = Task(self.tw, description="needs to be done first") + + dependency.save() + + t['depends'].add(dependency) + t.save() + + self.assertEqual(t['depends'], set([dependency])) + def test_simple_dependency_set_save_repeatedly(self): # Adds only one dependency to task with no dependencies t = Task(self.tw, description="test task") @@ -399,6 +436,14 @@ class TaskTest(TasklibTest): t['depends'] = set([dependency]) self.assertEqual(set(t._modified_fields), set()) + def test_modified_fields_not_affected_by_reading(self): + t = Task(self.tw) + + for field in TASK_STANDARD_ATTRS: + value = t[field] + + self.assertEqual(set(t._modified_fields), set()) + def test_setting_read_only_attrs_through_init(self): # Test that we are unable to set readonly attrs through __init__ for readonly_key in Task.read_only_fields: @@ -413,6 +458,93 @@ class TaskTest(TasklibTest): self.assertRaises(RuntimeError, lambda: t.__setitem__(readonly_key, 'value')) + def test_saving_unmodified_task(self): + t = Task(self.tw, description="test task") + t.save() + t.save() + + def test_adding_tag_by_appending(self): + t = Task(self.tw, description="test task", tags=['test1']) + t.save() + t['tags'].append('test2') + t.save() + self.assertEqual(t['tags'], ['test1', 'test2']) + + def test_adding_tag_by_appending_empty(self): + t = Task(self.tw, description="test task") + t.save() + t['tags'].append('test') + t.save() + self.assertEqual(t['tags'], ['test']) + + def test_serializers_returning_empty_string_for_none(self): + # Test that any serializer returns '' when passed None + t = Task(self.tw) + serializers = [getattr(t, serializer_name) for serializer_name in + filter(lambda x: x.startswith('serialize_'), dir(t))] + for serializer in serializers: + self.assertEqual(serializer(None), '') + + def test_deserializer_returning_empty_value_for_empty_string(self): + # Test that any deserializer returns empty value when passed '' + t = Task(self.tw) + deserializers = [getattr(t, deserializer_name) for deserializer_name in + filter(lambda x: x.startswith('deserialize_'), dir(t))] + for deserializer in deserializers: + self.assertTrue(deserializer('') in (None, [], set())) + + + +class TaskFromHookTest(TasklibTest): + + input_add_data = six.StringIO( + '{"description":"Buy some milk",' + '"entry":"20141118T050231Z",' + '"status":"pending",' + '"uuid":"a360fc44-315c-4366-b70c-ea7e7520b749"}') + + input_modify_data = six.StringIO(input_add_data.getvalue() + '\n' + + '{"description":"Buy some milk finally",' + '"entry":"20141118T050231Z",' + '"status":"completed",' + '"uuid":"a360fc44-315c-4366-b70c-ea7e7520b749"}') + + exported_raw_data = ( + '{"project":"Home",' + '"due":"20150101T232323Z",' + '"description":"test task"}') + + def test_setting_up_from_add_hook_input(self): + t = Task.from_input(input_file=self.input_add_data) + self.assertEqual(t['description'], "Buy some milk") + self.assertEqual(t.pending, True) + + def test_setting_up_from_modified_hook_input(self): + t = Task.from_input(input_file=self.input_modify_data, modify=True) + self.assertEqual(t['description'], "Buy some milk finally") + self.assertEqual(t.pending, False) + self.assertEqual(t.completed, True) + + self.assertEqual(t._original_data['status'], "pending") + self.assertEqual(t._original_data['description'], "Buy some milk") + self.assertEqual(set(t._modified_fields), + set(['status', 'description'])) + + def test_export_data(self): + t = Task(self.tw, description="test task", + project="Home", due=datetime.datetime(2015,1,1,23,23,23)) + + # Check that the output is a permutation of: + # {"project":"Home","description":"test task","due":"20150101232323Z"} + allowed_segments = self.exported_raw_data[1:-1].split(',') + allowed_output = [ + '{' + ','.join(segments) + '}' + for segments in itertools.permutations(allowed_segments) + ] + + self.assertTrue(any(t.export_data() == expected + for expected in allowed_output)) + class AnnotationTest(TasklibTest): @@ -447,6 +579,14 @@ class AnnotationTest(TasklibTest): task.remove_annotation(ann) self.assertEqual(len(task['annotations']), 0) + def test_annotation_after_modification(self): + task = self.tw.tasks.get() + task['project'] = 'test' + task.add_annotation('I should really do this task') + self.assertEqual(task['project'], 'test') + task.save() + self.assertEqual(task['project'], 'test') + class UnicodeTest(TasklibTest):