Report the type of change observed in FileWatcher

Previously, the FileWatcher only provided information of the
path of the changed file, without indicating whether the change
was a creation, modification, or deletion. This commit improves the
functionality of the FileWatcher by adding the ability to report
the type of change observed. This additional information can be
useful when tracking changes to files and understanding the
context of the change.

Signed-off-by: Daniel Zullo <[email protected]>

Author: daniel-zullo-frequenz

RELEASE_NOTES.md

@@ -53,12 +53,19 @@ This release adds support to pass `None` values via channels and revamps the `Ti
 
   Therefore, you should now check a file receiving an event really exist before trying to operate on it.
 
+* `FileWatcher` reports the type of event observed in addition to the file path.
+
+  Previously, only the file path was reported. With this update, users can now determine if a file change is a creation, modification, or deletion.
+  Note that this change may require updates to your existing code that relies on `FileWatcher` as the new interface returns a `FileWatcher.Event` instead of just the file path.
+
 ## New Features
 
 * `util.Timer` was replaced by a more generic implementation that allows for customizable policies to handle missed ticks.
 
 * Passing `None` values via channels is now supported.
 
+* `FileWatcher.Event` was added to notify events when a file is created, modified, or deleted.
+
 ## Bug Fixes
 
 * `util.Select` / `util.Merge` / `util.MergeNamed`: Cancel pending tasks in `__del__` methods only if possible (the loop is not already closed).

src/frequenz/channels/util/_file_watcher.py

@@ -7,6 +7,7 @@
 
 import asyncio
 import pathlib
+from dataclasses import dataclass
 from enum import Enum
 
 from watchfiles import Change, awatch
@@ -16,7 +17,7 @@
 from .._exceptions import ReceiverStoppedError
 
 
-class FileWatcher(Receiver[pathlib.Path]):
+class FileWatcher(Receiver["FileWatcher.Event"]):
     """A channel receiver that watches for file events."""
 
     class EventType(Enum):
@@ -26,6 +27,15 @@ class EventType(Enum):
         MODIFY = Change.modified
         DELETE = Change.deleted
 
+    @dataclass(frozen=True)
+    class Event:
+        """A file change event."""
+
+        type: FileWatcher.EventType
+        """The type of change that was observed."""
+        path: pathlib.Path
+        """The path where the change was observed."""
+
     def __init__(
         self,
         paths: list[pathlib.Path | str],
@@ -104,11 +114,11 @@ async def ready(self) -> bool:
 
         return True
 
-    def consume(self) -> pathlib.Path:
-        """Return the latest change once `ready` is complete.
+    def consume(self) -> Event:
+        """Return the latest event once `ready` is complete.
 
         Returns:
-            The next change that was received.
+            The next event that was received.
 
         Raises:
             ReceiverStoppedError: if there is some problem with the receiver.
@@ -117,8 +127,8 @@ def consume(self) -> pathlib.Path:
             raise ReceiverStoppedError(self) from self._awatch_stopped_exc
 
         assert self._changes, "`consume()` must be preceeded by a call to `ready()`"
-        change = self._changes.pop()
         # Tuple of (Change, path) returned by watchfiles
-        _, path_str = change
-        path = pathlib.Path(path_str)
-        return path
+        change, path_str = self._changes.pop()
+        return FileWatcher.Event(
+            type=FileWatcher.EventType(change), path=pathlib.Path(path_str)
+        )

tests/utils/test_file_watcher.py

@@ -71,7 +71,9 @@ async def test_file_watcher_receive_updates(
 
     for change in changes:
         recv_changes = await file_watcher.receive()
-        assert recv_changes == pathlib.Path(change[1])
+        event_type = FileWatcher.EventType(change[0])
+        path = pathlib.Path(change[1])
+        assert recv_changes == FileWatcher.Event(type=event_type, path=path)
 
 
 @hypothesis.given(event_types=st.sets(st.sampled_from(FileWatcher.EventType)))

tests/utils/test_integration.py

@@ -36,7 +36,12 @@ async def test_file_watcher(tmp_path: pathlib.Path) -> None:
         if msg := select.timer:
             filename.write_text(f"{msg.inner}")
         elif msg := select.file_watcher:
-            assert msg.inner == filename
+            event_type = (
+                FileWatcher.EventType.CREATE
+                if number_of_writes == 0
+                else FileWatcher.EventType.MODIFY
+            )
+            assert msg.inner == FileWatcher.Event(type=event_type, path=filename)
             number_of_writes += 1
             # After receiving a write 3 times, unsubscribe from the writes channel
             if number_of_writes == expected_number_of_writes: