TaskWarrior: Output whole stderr content as TaskWarriorException on failure

[etc/taskwarrior.git] / docs / index.rst

diff --git a/docs/index.rst b/docs/index.rst
index 90cd94ba7c36abb9014e49baa43dc7d55468bcb8..6b9a6c3dc6bc1243875147f8b4dbf4651f6144b2 100644 (file)
--- 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
 ---------------------------
 
@@ -312,7 +333,7 @@ are set in the same timezone:
     >>> t['due']
     datetime.datetime(2015, 2, 1, 19, 44, 4, 770001, tzinfo=<DstTzInfo 'Europe/Berlin' CET+1:00:00 STD>)
     >>> now.astimezone(pytz.utc)
-    datetime.datetime(2015, 2, 1, 18, 44, 4, 770001, tzinfo=<DstTzInfo 'Europe/Berlin' CET+1:00:00 STD>)
+    datetime.datetime(2015, 2, 1, 18, 44, 4, 770001, tzinfo=<UTC>)
     >>> t['due'] == now.astimezone(pytz.utc)
     True
 
@@ -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
 -----------------