Add FileWatcher API (#529)

Author: davidbrochart

docs/plugins/contents.md

@@ -1 +1 @@
-`fps-contents` implements the `contents` API, i.e. everything related to reading/writing files, for the local file system. It also provides notifications for file changes using [watchfiles](https://github.com/samuelcolvin/watchfiles).
+`fps-contents` implements the `contents` API, i.e. everything related to reading/writing files, for the local file system.

jupyverse_api/jupyverse_api/file_watcher/__init__.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from enum import IntEnum
+from pathlib import Path
+
+from anyio import Event
+
+
+class Change(IntEnum):
+    added = 1
+    modified = 2
+    deleted = 3
+
+
+FileChange = tuple[Change, str]
+
+
+class FileWatcher(ABC):
+    @abstractmethod
+    async def watch(
+        self,
+        path: Path | str,
+        stop_event: Event | None = None,
+    ) -> AsyncGenerator[set[FileChange], None]: ...

plugins/file_id/fps_file_id/file_id.py

@@ -1,19 +1,16 @@
 from __future__ import annotations
 
-import logging
 import sqlite3
 from uuid import uuid4
 
 import structlog
 from anyio import Event, Lock, Path
 from sqlite_anyio import connect
-from watchfiles import Change, awatch
 
 from jupyverse_api.file_id import FileId
+from jupyverse_api.file_watcher import Change, FileWatcher
 
 logger = structlog.get_logger()
-watchfiles_logger = logging.getLogger("watchfiles")
-watchfiles_logger.setLevel(logging.WARNING)
 
 
 class Watcher:
@@ -40,7 +37,8 @@ class _FileId(FileId):
     watchers: dict[str, list[Watcher]]
     lock: Lock
 
-    def __init__(self, db_path: str = ".fileid.db"):
+    def __init__(self, file_watcher: FileWatcher, db_path: str = ".fileid.db"):
+        self.file_watcher = file_watcher
         self.db_path = db_path
         self.initialized = Event()
         self.watchers = {}
@@ -116,14 +114,15 @@ async def watch_files(self):
             await self._db.commit()
             self.initialized.set()
 
-        async for changes in awatch(".", stop_event=self.stop_event):
+        here = await Path().absolute()
+        async for changes in self.file_watcher.watch(here, stop_event=self.stop_event):
             async with self.lock:
                 deleted_paths = set()
                 added_paths = set()
                 cursor = await self._db.cursor()
                 for change, changed_path in changes:
                     # get relative path
-                    changed_path = Path(changed_path).relative_to(await Path().absolute())
+                    changed_path = Path(changed_path).relative_to(here)
                     changed_path_str = str(changed_path)
 
                     if change == Change.deleted:

plugins/file_id/fps_file_id/main.py

@@ -2,13 +2,15 @@
 from fps import Module
 
 from jupyverse_api.file_id import FileId
+from jupyverse_api.file_watcher import FileWatcher
 
 from .file_id import _FileId
 
 
 class FileIdModule(Module):
     async def prepare(self) -> None:
-        self.file_id = _FileId()
+        file_watcher = await self.get(FileWatcher)  # type: ignore[type-abstract]
+        self.file_id = _FileId(file_watcher)
 
         async with create_task_group() as tg:
             tg.start_soon(self.file_id.start)

plugins/file_id/pyproject.toml

@@ -9,7 +9,6 @@ description = "An FPS plugin for the file ID API"
 keywords = ["jupyter", "server", "fastapi", "plugins"]
 requires-python = ">=3.9"
 dependencies = [
-    "watchfiles >=1.0.4,<2",
     "sqlite-anyio >=0.2.0,<0.3.0",
     "anyio>=3.6.2,<5",
     "jupyverse-api >=0.11.0,<0.12.0",

plugins/file_watcher/COPYING.md

@@ -0,0 +1,59 @@
+# Licensing terms
+
+This project is licensed under the terms of the Modified BSD License
+(also known as New or Revised or 3-Clause BSD), as follows:
+
+- Copyright (c) 2025-, Jupyter Development Team
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this
+list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+Neither the name of the Jupyter Development Team nor the names of its
+contributors may be used to endorse or promote products derived from this
+software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## About the Jupyter Development Team
+
+The Jupyter Development Team is the set of all contributors to the Jupyter project.
+This includes all of the Jupyter subprojects.
+
+The core team that coordinates development on GitHub can be found here:
+https://github.com/jupyter/.
+
+## Our Copyright Policy
+
+Jupyter uses a shared copyright model. Each contributor maintains copyright
+over their contributions to Jupyter. But, it is important to note that these
+contributions are typically only changes to the repositories. Thus, the Jupyter
+source code, in its entirety is not the copyright of any single person or
+institution. Instead, it is the collective copyright of the entire Jupyter
+Development Team. If individual contributors want to maintain a record of what
+changes/contributions they have specific copyright on, they should indicate
+their copyright in the commit message of the change, when they commit the
+change to one of the Jupyter repositories.
+
+With this in mind, the following banner should be used in any source code file
+to indicate the copyright and license terms:
+
+    # Copyright (c) Jupyter Development Team.
+    # Distributed under the terms of the Modified BSD License.

plugins/file_watcher/README.md

@@ -0,0 +1,3 @@
+# fps-file-watcher
+
+An FPS plugin for the file watcher API.

plugins/file_watcher/fps_file_watcher/__init__.py

@@ -0,0 +1,6 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("fps_file_watcher")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "unknown"

plugins/file_watcher/fps_file_watcher/file_watcher.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncGenerator
+from pathlib import Path
+
+import structlog
+from anyio import Event
+from watchfiles import awatch
+
+from jupyverse_api.file_watcher import FileChange, FileWatcher
+
+logger = structlog.get_logger()
+watchfiles_logger = logging.getLogger("watchfiles")
+watchfiles_logger.setLevel(logging.WARNING)
+
+
+class _FileWatcher(FileWatcher):
+    async def watch(  # type: ignore[override]
+        self,
+        path: Path | str,
+        stop_event: Event | None = None,
+    ) -> AsyncGenerator[set[FileChange], None]:
+        async for changes in awatch(path, stop_event=stop_event):
+            yield changes  # type: ignore[misc]

plugins/file_watcher/fps_file_watcher/main.py

@@ -0,0 +1,11 @@
+from fps import Module
+
+from jupyverse_api.file_watcher import FileWatcher
+
+from .file_watcher import _FileWatcher
+
+
+class FileWatcherModule(Module):
+    async def prepare(self) -> None:
+        file_watcher = _FileWatcher()
+        self.put(file_watcher, FileWatcher)