changed Transaction interface and added documentation

Author: forman

tests/fsutil/test_transaction.py

@@ -41,30 +41,34 @@ def _run_transaction_test(self, fail: bool):
         self.assertFalse(test_folder.exists())
         self.assertFalse(test_file_3.exists())
 
-        lock_file = test_root.parent / (test_root.filename + LOCK_EXT)
+        temp_dir = FileObj("memory://temp")
+        transaction = Transaction(test_root, temp_dir)
+
+        self.assertEqual(test_root, transaction.target_dir)
+
+        lock_file = transaction.lock_file
         self.assertFalse(lock_file.exists())
 
-        rollback_dir = FileObj("memory://rollback")
+        rollback_dir = transaction.rollback_dir
         rollback_file = rollback_dir / ROLLBACK_FILE
         self.assertFalse(rollback_file.exists())
 
         def change_test_file_1(rollback_cb: Callable):
             original_data = test_file_1.read()
             test_file_1.write("D-E-F")
-            rollback_cb("replace_file", test_file_1.path, original_data)
+            rollback_cb("replace_file", test_file_1.filename, original_data)
 
         def create_test_file_2(rollback_cb: Callable):
             test_file_2.write("1-2-3")
-            rollback_cb("delete_file", test_file_2.path, None)
+            rollback_cb("delete_file", test_file_2.filename, None)
 
         def create_test_folder(rollback_cb: Callable):
             test_folder.mkdir()
             test_file_3.write("4-5-6")
-            rollback_cb("delete_dir", test_folder.path, None)
+            rollback_cb("delete_dir", test_folder.filename, None)
 
         try:
-            with Transaction(test_root, rollback_dir,
-                             create_rollback_subdir=False) as rollback_cb:
+            with transaction as rollback_cb:
                 self.assertTrue(rollback_file.exists())
                 self.assertTrue(lock_file.exists())
 
@@ -77,9 +81,9 @@ def create_test_folder(rollback_cb: Callable):
                                     for line in rollback_data.split("\n")]
                 self.assertEqual(
                     [
-                        ["replace_file", "/test/file-1.txt"],
-                        ["delete_file", "/test/file-2.txt"],
-                        ["delete_dir", "/test/folder"],
+                        ["replace_file", "file-1.txt"],
+                        ["delete_file", "file-2.txt"],
+                        ["delete_dir", "folder"],
                         []
                     ],
                     rollback_records
@@ -152,35 +156,33 @@ def test_it_raises_if_not_used_with_with(self):
     def test_deletes_lock(self):
         test_root = FileObj("memory://test")
         test_root.mkdir()
-        rollback_dir = FileObj("memory://rollback")
-        rollback_dir.mkdir()
-        transaction = Transaction(test_root, rollback_dir,
-                                  create_rollback_subdir=False)
-        self.assertFalse(transaction._lock_file.exists())
+        temp_dir = FileObj("memory://temp")
+        temp_dir.mkdir()
+        transaction = Transaction(test_root, temp_dir)
+        self.assertFalse(transaction.lock_file.exists())
         with transaction:
-            self.assertTrue(transaction._lock_file.exists())
-        self.assertFalse(transaction._lock_file.exists())
+            self.assertTrue(transaction.lock_file.exists())
+        self.assertFalse(transaction.lock_file.exists())
 
     def test_leaves_lock_behind_when_it_cannot_be_deleted(self):
         test_root = FileObj("memory://test")
         test_root.mkdir()
-        rollback_dir = FileObj("memory://rollback")
-        rollback_dir.mkdir()
-        transaction = Transaction(test_root, rollback_dir,
-                                  create_rollback_subdir=False)
+        temp_dir = FileObj("memory://temp")
+        temp_dir.mkdir()
+        transaction = Transaction(test_root, temp_dir)
         delete_called = False
 
         def _delete():
             nonlocal delete_called
             delete_called = True
             raise OSError("Bam!")
 
-        transaction._lock_file.delete = _delete
-        self.assertFalse(transaction._lock_file.exists())
+        transaction.lock_file.delete = _delete
+        self.assertFalse(transaction.lock_file.exists())
         with transaction:
-            self.assertTrue(transaction._lock_file.exists())
+            self.assertTrue(transaction.lock_file.exists())
         self.assertEqual(True, delete_called)
-        self.assertTrue(transaction._lock_file.exists())
+        self.assertTrue(transaction.lock_file.exists())
 
     # noinspection PyMethodMayBeStatic
     def test_it_raises_on_illegal_callback_calls(self):

zappend/fsutil/transaction.py

@@ -33,24 +33,66 @@ class Transaction:
     """
     A filesystem transaction.
 
-    See https://github.com/zarr-developers/zarr-python/issues/247
+    Its main motivation is implementing transactional Zarr dataset
+    modifications, because this does not exist for Zarr yet (2024-01), see
+    https://github.com/zarr-developers/zarr-python/issues/247.
+
+    The ``Transaction`` class is used to observe changes to a given target
+    directory *target_dir*.
+
+    Changes must be explicitly registered using a "rollback callback"
+    function that is provided as the result of using the
+    transaction instance as a context manager:::
+
+    with Transaction(target_dir, temp_dir) as rollback_cb:
+        # emit rollback actions here
+
+    The following actions are supported:
+
+    * ``rollback_cb("delete_dir", path)`` if a directory has been created.
+    * ``rollback_cb("delete_file", path)`` if a file has been created.
+    * ``rollback_cb("replace_file", path, original_data)`` if a directory has
+        been changed.
+
+    Reported paths must be relative to *target_dir*. The empty path ``""``
+    refers to *target_dir* itself.
+
+    :param target_dir: The target directory that is subject to this
+        transaction. All paths emitted to the rollback callback must be
+        relative to *target_dir*. The directory may or may not exist yet.
+    :param temp_dir: Temporary directory in which a unique subdirectory
+        will be created that will be used to collect
+        rollback data during the transaction. The directory must exist.
     """
 
     def __init__(self,
                  target_dir: FileObj,
-                 rollback_dir: FileObj,
-                 create_rollback_subdir: bool = True):
+                 temp_dir: FileObj):
+        transaction_id = f"zappend-{uuid.uuid4()}"
+        rollback_dir = temp_dir / transaction_id
         lock_file = target_dir.parent / (target_dir.filename + LOCK_EXT)
-        transaction_id = str(uuid.uuid4())
-        if create_rollback_subdir:
-            rollback_dir = rollback_dir / transaction_id
         self._id = transaction_id
         self._rollback_dir = rollback_dir
         self._rollback_file = rollback_dir / ROLLBACK_FILE
         self._target_dir = target_dir
         self._lock_file = lock_file
         self._entered_ctx = False
 
+    @property
+    def target_dir(self) -> FileObj:
+        """Target directory that is subject to this transaction."""
+        return self._target_dir
+
+    @property
+    def lock_file(self) -> FileObj:
+        """Temporary lock file used during the transaction."""
+        return self._lock_file
+
+    @property
+    def rollback_dir(self) -> FileObj:
+        """Temporary directory containing rollback data."""
+        return self._rollback_dir
+
     def __enter__(self):
         if self._entered_ctx:
             raise ValueError("Transaction instance cannot be used"
@@ -62,8 +104,7 @@ def __enter__(self):
             raise IOError(f"Target is locked: {lock_file.uri}")
         lock_file.write(self._rollback_dir.uri)
 
-        if not self._rollback_dir.exists():
-            self._rollback_dir.mkdir()
+        self._rollback_dir.mkdir()
         self._rollback_file.write("")  # touch
 
         return self._add_rollback_action