From 8ad57d84e608417867885cee2afe898e968ce3f3 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Thu, 8 Jan 2015 07:11:42 +0100 Subject: [PATCH 01/16] Setup: Add pytz as dependency --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 30b2187..a8efa08 100644 --- a/setup.py +++ b/setup.py @@ -15,7 +15,7 @@ setup( packages=find_packages(), include_package_data=True, test_suite='tasklib.tests', - install_requires=['six==1.5.2'], + install_requires=['six==1.5.2', 'pytz'], classifiers=[ 'Development Status :: 4 - Beta', 'Programming Language :: Python', -- 2.39.5 From 11b50d11a86a461740d217dbebb896d119c955bc Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Fri, 6 Feb 2015 20:20:35 +0100 Subject: [PATCH 02/16] Add documentation for localized timezones --- docs/index.rst | 82 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 80 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 5c8b387..90cd94b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -84,7 +84,7 @@ Attributes of task objects are accessible through indices, like so:: >>> task['id'] 15 >>> task['due'] - datetime.datetime(2013, 12, 5, 0, 0) + datetime.datetime(2015, 2, 5, 0, 0, tzinfo=) >>> task['tags'] ['work', 'servers'] @@ -239,6 +239,84 @@ same Python object:: >>> task3 == task1 True +Dealing with dates and time +--------------------------- + +Any timestamp-like attributes of the tasks are converted to timezone-aware +datetime objects. To achieve this, Tasklib leverages ``pytz`` Python module, +which brings the Olsen timezone databaze to Python. + +This shields you from annoying details of Daylight Saving Time shifts +or conversion between different timezones. For example, to list all the +tasks which are due midnight if you're currently in Berlin: + + >>> myzone = pytz.timezone('Europe/Berlin') + >>> midnight = myzone.localize(datetime(2015,2,2,0,0,0)) + >>> tw.tasks.filter(due__before=midnight) + +However, this is still a little bit tedious. That's why TaskWarrior object +is capable of automatic timezone detection, using the ``tzlocal`` Python +module. If your system timezone is set to 'Europe/Berlin', following example +will work the same way as the previous one: + + >>> tw.tasks.filter(due__before=datetime(2015,2,2,0,0,0)) + +You can also use simple dates when filtering: + + >>> tw.tasks.filter(due__before=date(2015,2,2)) + +In such case, a 00:00:00 is used as the time component. + +Of course, you can use datetime naive objects when initializing Task object +or assigning values to datetime atrributes: + + >>> t = Task(tw, description="Buy new shoes", due=date(2015,2,5)) + >>> t['due'] + datetime.datetime(2015, 2, 5, 0, 0, tzinfo=) + >>> t['due'] = date(2015,2,6,15,15,15) + >>> t['due'] + datetime.datetime(2015, 2, 6, 15, 15, 15, tzinfo=) + +However, since timezone-aware and timezone-naive datetimes are not comparable +in Python, this can cause some unexpected behaviour: + + >>> from datetime import datetime + >>> now = datetime.now() + >>> t = Task(tw, description="take out the trash now") + >>> t['due'] = now + >>> now + datetime.datetime(2015, 2, 1, 19, 44, 4, 770001) + >>> t['due'] + datetime.datetime(2015, 2, 1, 19, 44, 4, 770001, tzinfo=) + >>> t['due'] == now + Traceback (most recent call last): + File "", line 1, in + TypeError: can't compare offset-naive and offset-aware datetimes + +If you want to compare datetime aware value with datetime naive value, you need +to localize the naive value first: + + >>> from datetime import datetime + >>> from tasklib.task import local_zone + >>> now = local_zone.localize(datetime.now()) + >>> t['due'] = now + >>> now + datetime.datetime(2015, 2, 1, 19, 44, 4, 770001, tzinfo=) + >>> t['due'] == now + True + +Also, note that it does not matter whether the timezone aware datetime objects +are set in the same timezone: + + >>> import pytz + >>> t['due'] + datetime.datetime(2015, 2, 1, 19, 44, 4, 770001, tzinfo=) + >>> now.astimezone(pytz.utc) + datetime.datetime(2015, 2, 1, 18, 44, 4, 770001, tzinfo=) + >>> t['due'] == now.astimezone(pytz.utc) + True + + Working with annotations ------------------------ @@ -253,7 +331,7 @@ Annotations have only defined ``entry`` and ``description`` values:: >>> annotation = annotated_task['annotations'][0] >>> annotation['entry'] - datetime.datetime(2015, 1, 3, 21, 13, 55) + datetime.datetime(2015, 1, 3, 21, 13, 55, tzinfo=) >>> annotation['description'] u'Yeah, I am annotated!' -- 2.39.5 From 5fe9dbdc944f57eacd1041f518a6703057f6e5f5 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Fri, 6 Feb 2015 20:44:11 +0100 Subject: [PATCH 03/16] Task: Leverage normalizers for localized datetime objects --- tasklib/task.py | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/tasklib/task.py b/tasklib/task.py index ca21b2b..73280b0 100644 --- a/tasklib/task.py +++ b/tasklib/task.py @@ -93,36 +93,54 @@ class SerializingObject(object): def deserialize_entry(self, value): return self.timestamp_deserializer(value) + def normalize_entry(self, value): + return self.datetime_normalizer(value) + def serialize_modified(self, value): return self.timestamp_serializer(value) def deserialize_modified(self, value): return self.timestamp_deserializer(value) + def normalize_modified(self, value): + return self.datetime_normalizer(value) + def serialize_due(self, value): return self.timestamp_serializer(value) def deserialize_due(self, value): return self.timestamp_deserializer(value) + def normalize_due(self, value): + return self.datetime_normalizer(value) + def serialize_scheduled(self, value): return self.timestamp_serializer(value) def deserialize_scheduled(self, value): return self.timestamp_deserializer(value) + def normalize_scheduled(self, value): + return self.datetime_normalizer(value) + def serialize_until(self, value): return self.timestamp_serializer(value) def deserialize_until(self, value): return self.timestamp_deserializer(value) + def normalize_until(self, value): + return self.datetime_normalizer(value) + def serialize_wait(self, value): return self.timestamp_serializer(value) def deserialize_wait(self, value): return self.timestamp_deserializer(value) + def normalize_wait(self, value): + return self.datetime_normalizer(value) + def serialize_annotations(self, value): value = value if value is not None else [] @@ -153,7 +171,7 @@ class SerializingObject(object): uuids = raw_uuids.split(',') return set(self.warrior.tasks.get(uuid=uuid) for uuid in uuids if uuid) - def normalize_datetime(self, value): + def datetime_normalizer(self, value): """ Normalizes date/datetime value (considered to come from user input) to localized datetime value. Following conversions happen: @@ -221,11 +239,8 @@ class TaskResource(SerializingObject): if key in self.read_only_fields: raise RuntimeError('Field \'%s\' is read-only' % key) - # Localize any naive date/datetime to the detected timezone - if (isinstance(value, datetime.datetime) or - isinstance(value, datetime.date)): - value = self.normalize_datetime(value) - + # Normalize the user input before saving it + value = self._normalize(key, value) self._data[key] = value def __str__(self): @@ -593,12 +608,8 @@ class TaskFilter(SerializingObject): # convention in TW for empty values attribute_key = key.split('.')[0] - # Since this is user input, we need to normalize datetime - # objects - if (isinstance(value, datetime.datetime) or - isinstance(value, datetime.date)): - value = self.normalize_datetime(value) - + # Since this is user input, we need to normalize before we serialize + value = self._normalize(key, value) value = self._serialize(attribute_key, value) # If we are filtering by uuid:, do not use uuid keyword -- 2.39.5 From aa96b5703ca8df1df113ac165b0d756c03517435 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Fri, 6 Feb 2015 20:55:57 +0100 Subject: [PATCH 04/16] Tests: Update tests for localized timestamps --- tasklib/tests.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tasklib/tests.py b/tasklib/tests.py index 3a3f25d..eb19948 100644 --- a/tasklib/tests.py +++ b/tasklib/tests.py @@ -3,6 +3,7 @@ import datetime import itertools import json +import pytz import six import shutil import tempfile @@ -532,7 +533,8 @@ class TaskFromHookTest(TasklibTest): def test_export_data(self): t = Task(self.tw, description="test task", - project="Home", due=datetime.datetime(2015,1,1,23,23,23)) + project="Home", + due=pytz.utc.localize(datetime.datetime(2015,1,1,23,23,23))) # Check that the output is a permutation of: # {"project":"Home","description":"test task","due":"20150101232323Z"} -- 2.39.5 From 33c9f69e01349c7339cb669e252a4d98a08351c1 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Fri, 6 Feb 2015 22:50:06 +0100 Subject: [PATCH 05/16] Tests: Add tests for timezone aware datetimes --- tasklib/tests.py | 79 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 78 insertions(+), 1 deletion(-) diff --git a/tasklib/tests.py b/tasklib/tests.py index eb19948..f7b9a27 100644 --- a/tasklib/tests.py +++ b/tasklib/tests.py @@ -9,7 +9,7 @@ import shutil import tempfile import unittest -from .task import TaskWarrior, Task +from .task import TaskWarrior, Task, local_zone, DATE_FORMAT # http://taskwarrior.org/docs/design/task.html , Section: The Attributes TASK_STANDARD_ATTRS = ( @@ -495,6 +495,14 @@ class TaskTest(TasklibTest): for deserializer in deserializers: self.assertTrue(deserializer('') in (None, [], set())) + def test_normalizers_returning_empty_string_for_none(self): + # Test that any normalizer can handle None as a valid value + t = Task(self.tw) + normalizers = [getattr(t, normalizer_name) for normalizer_name in + filter(lambda x: x.startswith('normalize_'), dir(t))] + for normalizer in normalizers: + normalizer(None) + class TaskFromHookTest(TasklibTest): @@ -547,6 +555,75 @@ class TaskFromHookTest(TasklibTest): self.assertTrue(any(t.export_data() == expected for expected in allowed_output)) +class TimezoneAwareDatetimeTest(TasklibTest): + + def setUp(self): + super(TimezoneAwareDatetimeTest, self).setUp() + self.zone = local_zone + self.localdate_naive = datetime.datetime(2015,2,2) + self.localtime_naive = datetime.datetime(2015,2,2,0,0,0) + self.localtime_aware = self.zone.localize(self.localtime_naive) + self.utctime_aware = self.localtime_aware.astimezone(pytz.utc) + + def test_timezone_naive_datetime_setitem(self): + t = Task(self.tw, description="test task") + t['due'] = self.localtime_naive + self.assertEqual(t['due'], self.localtime_aware) + + def test_timezone_naive_datetime_using_init(self): + t = Task(self.tw, description="test task", due=self.localtime_naive) + self.assertEqual(t['due'], self.localtime_aware) + + def test_filter_by_naive_datetime(self): + t = Task(self.tw, description="task1", due=self.localtime_naive) + t.save() + matching_tasks = self.tw.tasks.filter(due=self.localtime_naive) + self.assertEqual(len(matching_tasks), 1) + + def test_serialize_naive_datetime(self): + t = Task(self.tw, description="task1", due=self.localtime_naive) + self.assertEqual(json.loads(t.export_data())['due'], + self.utctime_aware.strftime(DATE_FORMAT)) + + def test_timezone_naive_date_setitem(self): + t = Task(self.tw, description="test task") + t['due'] = self.localdate_naive + self.assertEqual(t['due'], self.localtime_aware) + + def test_timezone_naive_date_using_init(self): + t = Task(self.tw, description="test task", due=self.localdate_naive) + self.assertEqual(t['due'], self.localtime_aware) + + def test_filter_by_naive_date(self): + t = Task(self.tw, description="task1", due=self.localdate_naive) + t.save() + matching_tasks = self.tw.tasks.filter(due=self.localdate_naive) + self.assertEqual(len(matching_tasks), 1) + + def test_serialize_naive_date(self): + t = Task(self.tw, description="task1", due=self.localdate_naive) + self.assertEqual(json.loads(t.export_data())['due'], + self.utctime_aware.strftime(DATE_FORMAT)) + + def test_timezone_aware_datetime_setitem(self): + t = Task(self.tw, description="test task") + t['due'] = self.localtime_aware + self.assertEqual(t['due'], self.localtime_aware) + + def test_timezone_aware_datetime_using_init(self): + t = Task(self.tw, description="test task", due=self.localtime_aware) + self.assertEqual(t['due'], self.localtime_aware) + + def test_filter_by_aware_datetime(self): + t = Task(self.tw, description="task1", due=self.localtime_aware) + t.save() + matching_tasks = self.tw.tasks.filter(due=self.localtime_aware) + self.assertEqual(len(matching_tasks), 1) + + def test_serialize_aware_datetime(self): + t = Task(self.tw, description="task1", due=self.localtime_aware) + self.assertEqual(json.loads(t.export_data())['due'], + self.utctime_aware.strftime(DATE_FORMAT)) class AnnotationTest(TasklibTest): -- 2.39.5 From 843561147d85899271c128015d1e098c8484c81e Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Fri, 6 Feb 2015 23:29:30 +0100 Subject: [PATCH 06/16] Setup: Add tzlocal to required packages --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index a8efa08..d5f45f5 100644 --- a/setup.py +++ b/setup.py @@ -15,7 +15,7 @@ setup( packages=find_packages(), include_package_data=True, test_suite='tasklib.tests', - install_requires=['six==1.5.2', 'pytz'], + install_requires=['six==1.5.2', 'pytz', 'tzlocal'], classifiers=[ 'Development Status :: 4 - Beta', 'Programming Language :: Python', -- 2.39.5 From 2ef4751c25fbbced996deed6e17bd5bae7a5fdd7 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sat, 7 Feb 2015 12:18:59 +0100 Subject: [PATCH 07/16] TaskWarrior: Add keyword argument to supress failure in execute_command --- tasklib/task.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tasklib/task.py b/tasklib/task.py index 73280b0..2a51b35 100644 --- a/tasklib/task.py +++ b/tasklib/task.py @@ -777,14 +777,14 @@ class TaskWarrior(object): stdout, stderr = [x.decode('utf-8') for x in p.communicate()] return stdout.strip('\n') - def execute_command(self, args, config_override={}): + def execute_command(self, args, config_override={}, allow_failure=True): command_args = self._get_command_args( args, config_override=config_override) logger.debug(' '.join(command_args)) p = subprocess.Popen(command_args, stdout=subprocess.PIPE, stderr=subprocess.PIPE) stdout, stderr = [x.decode('utf-8') for x in p.communicate()] - if p.returncode: + if p.returncode and allow_failure: if stderr.strip(): error_msg = stderr.strip().splitlines()[-1] else: -- 2.39.5 From 22d4f890a914e0687af63d11b20772d6bf949151 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sat, 7 Feb 2015 12:19:41 +0100 Subject: [PATCH 08/16] TaskWarrior: Enforce recurrent tasks upon each evaluation of filter --- tasklib/task.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tasklib/task.py b/tasklib/task.py index 2a51b35..51c97d3 100644 --- a/tasklib/task.py +++ b/tasklib/task.py @@ -792,7 +792,15 @@ class TaskWarrior(object): raise TaskWarriorException(error_msg) return stdout.strip().split('\n') + def enforce_recurrence(self): + # Run arbitrary report command which will trigger generation + # of recurrent tasks. + # TODO: Make a version dependant enforcement once + # TW-1531 is handled + self.execute_command(['next'], allow_failure=False) + def filter_tasks(self, filter_obj): + self.enforce_recurrence() args = ['export', '--'] + filter_obj.get_filter_params() tasks = [] for line in self.execute_command(args): -- 2.39.5 From 27f93e251029f1d93c92d8e1ac6a254bdb70ecdd Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sat, 7 Feb 2015 12:19:55 +0100 Subject: [PATCH 09/16] Tests: Test generation of recurrent tasks --- tasklib/tests.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/tasklib/tests.py b/tasklib/tests.py index f7b9a27..3ff1ebf 100644 --- a/tasklib/tests.py +++ b/tasklib/tests.py @@ -503,6 +503,12 @@ class TaskTest(TasklibTest): for normalizer in normalizers: normalizer(None) + def test_recurrent_task_generation(self): + today = datetime.date.today() + t = Task(self.tw, description="brush teeth", + due=today, recur="daily") + t.save() + self.assertEqual(len(self.tw.tasks.pending()), 2) class TaskFromHookTest(TasklibTest): -- 2.39.5 From 0110af91cb5bf3804efc35cb50c8430419af4313 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sat, 7 Feb 2015 12:35:31 +0100 Subject: [PATCH 10/16] SerializingObject: Make sure UUID is properly validated --- tasklib/task.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/tasklib/task.py b/tasklib/task.py index 51c97d3..138ea7c 100644 --- a/tasklib/task.py +++ b/tasklib/task.py @@ -195,7 +195,13 @@ class SerializingObject(object): localized = value return localized - + + def normalize_uuid(self, value): + # Enforce sane UUID + if not isinstance(value, six.text_type) or value == '': + raise ValueError("UUID must be a valid non-empty string.") + + return value class TaskResource(SerializingObject): -- 2.39.5 From 4da9b8fa085b6089c35573c6638fa137c131c30d Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sat, 7 Feb 2015 12:35:47 +0100 Subject: [PATCH 11/16] Tests: Add test for filtering with empty UUID --- tasklib/tests.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/tasklib/tests.py b/tasklib/tests.py index 3ff1ebf..2aebdcb 100644 --- a/tasklib/tests.py +++ b/tasklib/tests.py @@ -125,6 +125,8 @@ class TaskFilterTest(TasklibTest): filtered_task = self.tw.tasks.get(project="random") self.assertEqual(filtered_task['project'], "random") + def test_filter_with_empty_uuid(self): + self.assertRaises(ValueError, lambda: self.tw.tasks.get(uuid='')) class TaskTest(TasklibTest): @@ -495,11 +497,17 @@ class TaskTest(TasklibTest): for deserializer in deserializers: self.assertTrue(deserializer('') in (None, [], set())) - def test_normalizers_returning_empty_string_for_none(self): + def test_normalizers_handling_none(self): # Test that any normalizer can handle None as a valid value t = Task(self.tw) + + # These normalizers are not supposed to handle None + exempt_normalizers = ('normalize_uuid', ) + normalizers = [getattr(t, normalizer_name) for normalizer_name in - filter(lambda x: x.startswith('normalize_'), dir(t))] + filter(lambda x: x.startswith('normalize_'), dir(t)) + if normalizer_name not in exempt_normalizers] + for normalizer in normalizers: normalizer(None) -- 2.39.5 From 628b2d244b841be6494b87a14c3f78f0aa1cfc0e Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sat, 7 Feb 2015 13:49:29 +0100 Subject: [PATCH 12/16] ReadOnlyDictView: Add ReadOnlyDictView which allows read-only access to a given dict --- tasklib/task.py | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/tasklib/task.py b/tasklib/task.py index 138ea7c..dc27460 100644 --- a/tasklib/task.py +++ b/tasklib/task.py @@ -28,6 +28,40 @@ class TaskWarriorException(Exception): pass +class ReadOnlyDictView(object): + """ + Provides simplified read-only view upon dict object. + """ + + def __init__(self, viewed_dict): + self.viewed_dict = viewed_dict + + def __getitem__(self, key): + return copy.deepcopy(self.viewed_dict.__getitem__(key)) + + def __contains__(self, k): + return self.viewed_dict.__contains__(k) + + def __iter__(self): + for value in self.viewed_dict: + yield copy.deepcopy(value) + + def __len__(self): + return len(self.viewed_dict) + + def get(self, key, default=None): + return copy.deepcopy(self.viewed_dict.get(key, default)) + + def has_key(self, key): + return self.viewed_dict.has_key(key) + + def items(self): + return [copy.deepcopy(v) for v in self.viewed_dict.items()] + + def values(self): + return [copy.deepcopy(v) for v in self.viewed_dict.values()] + + class SerializingObject(object): """ Common ancestor for TaskResource & TaskFilter, since they both -- 2.39.5 From 6220d716c07a841b77fba60d50d1e2b57851af84 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sat, 7 Feb 2015 13:50:08 +0100 Subject: [PATCH 13/16] TaskResource: Provide read-only view on _original_data via original attribute --- tasklib/task.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tasklib/task.py b/tasklib/task.py index dc27460..17af8d4 100644 --- a/tasklib/task.py +++ b/tasklib/task.py @@ -424,6 +424,9 @@ class Task(TaskResource): for (key, value) in six.iteritems(kwargs)) self._original_data = copy.deepcopy(self._data) + # Provide read only access to the original data + self.original = ReadOnlyDictView(self._original_data) + def __unicode__(self): return self['description'] -- 2.39.5 From 96cd505ef5e22acc9707b3497449a9dfdf6dfc5e Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sat, 7 Feb 2015 13:50:33 +0100 Subject: [PATCH 14/16] SerializingObject: Document purpose of normalizing methods --- tasklib/task.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/tasklib/task.py b/tasklib/task.py index 17af8d4..537c792 100644 --- a/tasklib/task.py +++ b/tasklib/task.py @@ -78,6 +78,15 @@ class SerializingObject(object): 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. + + Normalizing methods should hold the following contract: + - They are used to validate and normalize the user input. + Any attribute value that comes from the user (during Task + initialization, assignign values to Task attributes, or + filtering by user-provided values of attributes) is first + validated and normalized using the normalize_{key} method. + - If validation or normalization fails, normalizer is expected + to raise ValueError. """ def _deserialize(self, key, value): -- 2.39.5 From dbf7ac142540916c427153dce16bba790c605d74 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sat, 7 Feb 2015 13:50:53 +0100 Subject: [PATCH 15/16] Tests: Add tests for ReadOnlyDictView --- tasklib/tests.py | 83 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 82 insertions(+), 1 deletion(-) diff --git a/tasklib/tests.py b/tasklib/tests.py index 2aebdcb..0dae79e 100644 --- a/tasklib/tests.py +++ b/tasklib/tests.py @@ -1,5 +1,6 @@ # coding=utf-8 +import copy import datetime import itertools import json @@ -9,7 +10,7 @@ import shutil import tempfile import unittest -from .task import TaskWarrior, Task, local_zone, DATE_FORMAT +from .task import TaskWarrior, Task, ReadOnlyDictView, local_zone, DATE_FORMAT # http://taskwarrior.org/docs/design/task.html , Section: The Attributes TASK_STANDARD_ATTRS = ( @@ -707,3 +708,83 @@ class UnicodeTest(TasklibTest): def test_non_unicode_task(self): Task(self.tw, description="test task").save() self.tw.tasks.get() + +class ReadOnlyDictViewTest(unittest.TestCase): + + def setUp(self): + self.sample = dict(l=[1,2,3], d={'k':'v'}) + self.original_sample = copy.deepcopy(self.sample) + self.view = ReadOnlyDictView(self.sample) + + def test_readonlydictview_getitem(self): + l = self.view['l'] + self.assertEqual(l, self.sample['l']) + + # Assert that modification changed only copied value + l.append(4) + self.assertNotEqual(l, self.sample['l']) + + # Assert that viewed dict is not changed + self.assertEqual(self.sample, self.original_sample) + + def test_readonlydictview_contains(self): + self.assertEqual('l' in self.view, 'l' in self.sample) + self.assertEqual('d' in self.view, 'd' in self.sample) + self.assertEqual('k' in self.view, 'k' in self.sample) + + # Assert that viewed dict is not changed + self.assertEqual(self.sample, self.original_sample) + + def test_readonlydictview_iter(self): + self.assertEqual(list(k for k in self.view), + list(k for k in self.sample)) + + # Assert the view is correct after modification + self.sample['new'] = 'value' + self.assertEqual(list(k for k in self.view), + list(k for k in self.sample)) + + def test_readonlydictview_len(self): + self.assertEqual(len(self.view), len(self.sample)) + + # Assert the view is correct after modification + self.sample['new'] = 'value' + self.assertEqual(len(self.view), len(self.sample)) + + def test_readonlydictview_get(self): + l = self.view.get('l') + self.assertEqual(l, self.sample.get('l')) + + # Assert that modification changed only copied value + l.append(4) + self.assertNotEqual(l, self.sample.get('l')) + + # Assert that viewed dict is not changed + self.assertEqual(self.sample, self.original_sample) + + def test_readonlydictview_contains(self): + self.assertEqual(self.view.has_key('l'), self.sample.has_key('l')) + self.assertEqual(self.view.has_key('k'), self.sample.has_key('k')) + self.assertEqual(self.view.has_key('d'), self.sample.has_key('d')) + + # Assert that viewed dict is not changed + self.assertEqual(self.sample, self.original_sample) + + def test_readonlydict_items(self): + view_items = self.view.items() + sample_items = self.sample.items() + self.assertEqual(view_items, sample_items) + + view_items.append('newkey') + self.assertNotEqual(view_items, sample_items) + self.assertEqual(self.sample, self.original_sample) + + def test_readonlydict_values(self): + view_values = self.view.values() + sample_values = self.sample.values() + self.assertEqual(view_values, sample_values) + + view_list_item = filter(lambda x: type(x) is list, view_values)[0] + view_list_item.append(4) + self.assertNotEqual(view_values, sample_values) + self.assertEqual(self.sample, self.original_sample) -- 2.39.5 From 80230e4e58118eaec09b0a83459b8543fbf78260 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sat, 7 Feb 2015 13:59:38 +0100 Subject: [PATCH 16/16] Docs: Document the original attribute access to the task object --- docs/index.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index 90cd94b..83e476e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -239,6 +239,27 @@ same Python object:: >>> task3 == task1 True +Accessing original values +------------------------- + +To access the saved state of the Task, use dict-like access using the +``original`` attribute: + + >>> t = Task(tw, description="tidy up") + >>> t.save() + >>> t['description'] = "tidy up the kitchen and bathroom" + >>> t['description'] + "tidy up the kitchen and bathroom" + >>> t.original['description'] + "tidy up" + +When you save the task, original values are refreshed to reflect the +saved state of the task: + + >>> t.save() + >>> t.original['description'] + "tidy up the kitchen and bathroom" + Dealing with dates and time --------------------------- @@ -424,6 +445,15 @@ Consenquently, you can create just one hook file for both ``on-add`` and This removes the need for maintaining two copies of the same code base and/or boilerplate code. +In ``on-modify`` events, tasklib loads both the original version and the modified +version of the task to the returned ``Task`` object. To access the original data +(in read-only manner), use ``original`` dict-like attribute: + + >>> t = Task.from_input() + >>> t['description'] + "Modified description" + >>> t.original['description'] + "Original description" Working with UDAs ----------------- -- 2.39.5