Add file system change notifier

jupyter_server/services/contents/filemanager.py

@@ -35,6 +35,8 @@
 
 class FileContentsManager(FileManagerMixin, ContentsManager):
 
+    import watchfiles
+
     root_dir = Unicode(config=True)
 
     @default("root_dir")
@@ -546,6 +548,9 @@ def get_kernel_path(self, path, model=None):
 
 
 class AsyncFileContentsManager(FileContentsManager, AsyncFileManagerMixin, AsyncContentsManager):
+
+    import watchfiles
+
     @default("checkpoints_class")
     def _checkpoints_class_default(self):
         return AsyncFileCheckpoints

jupyter_server/services/contents/manager.py

@@ -34,6 +34,13 @@
 copy_pat = re.compile(r"\-Copy\d*\.")
 
 
+class NoWatchfilesAPI:
+    pass
+
+
+NOWATCHFILESAPI = NoWatchfilesAPI()
+
+
 class ContentsManager(LoggingConfigurable):
     """Base class for serving files and directories.
 
@@ -409,6 +416,20 @@ def rename_file(self, old_path, new_path):
     # ContentsManager API part 2: methods that have useable default
     # implementations, but can be overridden in subclasses.
 
+    @property
+    def watchfiles(self):
+        """File system change notifyer
+
+        Override this method in subclasses if the file system supports change notifications.
+
+        Returns
+        -------
+        api : class
+            The supported API for file system change notifications. Loosely follows the API of the
+            watchfiles Python package (can be a subset of it).
+        """
+        return NOWATCHFILESAPI
+
     def delete(self, path):
         """Delete a file/directory and any associated checkpoints."""
         path = path.strip("/")

setup.cfg

@@ -53,6 +53,7 @@ install_requires =
     terminado>=0.8.3
     tornado>=6.1.0
     traitlets>=5.1
+    watchfiles>=0.13
     websocket-client
 
 [options.extras_require]

tests/services/contents/test_largefilemanager.py

@@ -1,3 +1,5 @@
+import asyncio
+
 import pytest
 import tornado
 
@@ -110,3 +112,29 @@ async def test_save_in_subdirectory(jp_large_contents_manager, tmp_path):
     assert "path" in model
     assert model["name"] == "Untitled.ipynb"
     assert model["path"] == "foo/Untitled.ipynb"
+
+
+async def test_watch_directory(tmp_path):
+    cm = AsyncLargeFileManager(root_dir=str(tmp_path))
+    file_path = tmp_path / "file.txt"
+    stop_event = asyncio.Event()
+
+    async def change_dir():
+        # let the watcher start
+        await asyncio.sleep(0.1)
+        # add file to directory
+        file_path.write_text("foo")
+
+    async def timeout():
+        await asyncio.sleep(10)
+        stop_event.set()
+
+    asyncio.create_task(change_dir())
+    asyncio.create_task(timeout())
+    test_ok = False
+    async for change in cm.watchfiles.awatch(tmp_path, stop_event=stop_event):
+        if (cm.watchfiles.Change.added, str(file_path)) in change:
+            test_ok = True
+            break
+
+    assert test_ok