fps_yrooms 0.1.0__tar.gz

fps_yrooms-0.1.0/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) 2026-, 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.

fps_yrooms-0.1.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: fps_yrooms
+Version: 0.1.0
+Summary: An FPS plugin for YRooms
+Keywords: jupyter,server,fastapi,plugins
+Author: Jupyter Development Team
+Author-email: Jupyter Development Team <jupyter@googlegroups.com>
+License-Expression: BSD-3-Clause
+License-File: COPYING.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Dist: jupyverse-api>=0.13.0,<0.14.0
+Requires-Dist: jupyter-ydoc>=3.3.5,<4.0.0
+Requires-Dist: pycrdt>=0.12.0,<0.13.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://jupyter.org
+Description-Content-Type: text/markdown
+
+# fps-yrooms
+
+An FPS plugin for YRooms.

fps_yrooms-0.1.0/README.md

@@ -0,0 +1,3 @@
+# fps-yrooms
+
+An FPS plugin for YRooms.

fps_yrooms-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[project]
+name = "fps_yrooms"
+version = "0.1.0"
+description = "An FPS plugin for YRooms"
+keywords = [ "jupyter", "server", "fastapi", "plugins" ]
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: BSD License",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = [
+  "jupyverse-api >=0.13.0,<0.14.0",
+  "jupyter-ydoc >=3.3.5,<4.0.0",
+  "pycrdt >=0.12.0,<0.13.0",
+]
+license = "BSD-3-Clause"
+license-files = ["COPYING.md"]
+
+[[project.authors]]
+name = "Jupyter Development Team"
+email = "jupyter@googlegroups.com"
+
+[project.readme]
+file = "README.md"
+content-type = "text/markdown"
+
+[project.urls]
+Homepage = "https://jupyter.org"
+
+[project.entry-points]
+"fps.modules" = {yrooms = "fps_yrooms.main:YRoomsModule"}
+"jupyverse.modules" = {yrooms = "fps_yrooms.main:YRoomsModule"}

fps_yrooms-0.1.0/src/fps_yrooms/__init__.py

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

fps_yrooms-0.1.0/src/fps_yrooms/config.py

@@ -0,0 +1,19 @@
+from pydantic import Field
+
+from jupyverse_api import Config
+
+
+class YRoomsConfig(Config):
+    document_cleanup_delay: float = Field(
+        description=(
+            "The time to wait (in seconds) after the last client has leaved "
+            "before closing the room."
+        ),
+        default=60,
+    )
+    document_save_delay: float = Field(
+        description=(
+            "The time to wait (in seconds) after the last change before saving a document to disk."
+        ),
+        default=1,
+    )

fps_yrooms-0.1.0/src/fps_yrooms/main.py

@@ -0,0 +1,30 @@
+from functools import partial
+from typing import Any
+
+from fps import Module
+from jupyverse_api.contents import Contents
+from jupyverse_api.file_id import FileId
+from jupyverse_api.yrooms import YRoomFactory, YRooms
+from jupyverse_api.ystore import YStoreFactory
+
+from .config import YRoomsConfig
+from .yrooms import _YRoom, _YRooms
+
+
+class YRoomsModule(Module):
+    def __init__(self, name: str, **kwargs: Any):
+        super().__init__(name)
+        self.config = YRoomsConfig(**kwargs)
+
+    async def prepare(self) -> None:
+        contents = await self.get(Contents)  # type: ignore[type-abstract]
+        file_id = await self.get(FileId)  # type: ignore[type-abstract]
+        ystore_factory = await self.get(YStoreFactory)
+        yroom_factory = YRoomFactory(
+            partial(_YRoom, contents, file_id, ystore_factory, self.config)  # type: ignore[arg-type]
+        )
+        async with _YRooms(yroom_factory) as yrooms:
+            self.put(yrooms, YRooms)
+            self.done()
+            await self.started.wait()
+            await self.freed(yrooms)

fps_yrooms-0.1.0/src/fps_yrooms/yrooms.py

@@ -0,0 +1,229 @@
+from datetime import datetime
+
+import structlog
+from anyio import (
+    CancelScope,
+    sleep,
+)
+from anyio.abc import TaskStatus
+from jupyter_ydoc import ydocs as YDOCS
+from jupyverse_api.contents import Contents
+from jupyverse_api.file_id import FileId
+from jupyverse_api.yrooms import AsyncChannel, YRoom, YRooms
+from jupyverse_api.ystore import YDocNotFound, YStoreFactory
+from pycrdt import (
+    Doc,
+    YMessageType,
+    YSyncMessageType,
+    handle_sync_message,
+)
+
+from .config import YRoomsConfig
+
+logger = structlog.get_logger()
+YFILE = YDOCS["file"]
+
+
+class _YRoom(YRoom):
+    def __init__(
+        self,
+        contents: Contents,
+        file_id: FileId,
+        ystore_factory: YStoreFactory,
+        config: YRoomsConfig,
+        id: str,
+        sync: bool = True,
+        doc: Doc | None = None,
+        permissions: dict[str, list[str]] | None = None,
+    ) -> None:
+        super().__init__(id, sync, doc=doc)
+        self._contents = contents
+        self._file_id = file_id
+        self._ystore_factory = ystore_factory
+        self._config = config
+        self._close_room_cancel_scope: CancelScope | None = None
+        self._write_to_file_cancel_scope: CancelScope | None = None
+        self._id_of_file: str | None = None
+        self._can_write = permissions is None or "write" in permissions.get("yjs", [])
+
+    async def serve(self, client: AsyncChannel) -> None:
+        # cancel the closing of the room if it was scheduled:
+        if self._close_room_cancel_scope is not None:
+            self._close_room_cancel_scope.cancel()
+            self._close_room_cancel_scope = None
+        kwargs = {"id": self.id}
+        if self._id_of_file is not None:
+            file_path = await self._get_file_path(self._id_of_file)
+            assert file_path is not None
+            kwargs["file_path"] = file_path
+        logger.info("Client connected", **kwargs)
+        await super().serve(client)
+        logger.info("Client disconnected", **kwargs)
+
+    async def run(self, *, task_status: TaskStatus[None]) -> None:
+        kwargs = {"id": self.id}
+        if self.id.count(":") >= 2:
+            # it is a stored document (e.g. a notebook)
+            self._file_format, self._file_type, self._id_of_file = self.id.split(":", 2)
+            self._jupyter_ydoc = YDOCS.get(self._file_type, YFILE)(self.doc)
+            self._jupyter_ydoc.ystate["file_id"] = self._id_of_file
+            file_path = await self._get_file_path(self._id_of_file)
+            assert file_path is not None
+            kwargs["file_path"] = file_path
+            logger.info("Opening collaboration room", **kwargs)
+            model = await self._contents.read_content(file_path, True, self._file_format)
+            assert model.last_modified is not None
+            self._last_modified = to_datetime(model.last_modified)
+            updates_file_path = f".{self._file_type}:{self._id_of_file}.y"
+            async with self._ystore_factory(path=updates_file_path) as self._ystore:
+                # try to apply Y updates from the YStore for this document
+                try:
+                    await self._ystore.apply_updates(self.doc)
+                    read_from_source = False
+                except YDocNotFound:
+                    # YDoc not found in the YStore, create the document from
+                    # the source file (no change history)
+                    read_from_source = True
+                    logger.info("Document not found in YStore", file_path=file_path, id=self.id)
+                if not read_from_source:
+                    # if YStore updates and source file are out-of-sync, resync updates
+                    # with source
+                    if self._jupyter_ydoc.source != model.content:
+                        read_from_source = True
+                        logger.info(
+                            "Document in YStore differs from file content",
+                            file_path=file_path,
+                            id=self.id,
+                        )
+                await self.task_group.start(self._write_to_ystore)
+                await self.task_group.start(self._write_to_file)
+                await self.task_group.start(self._watch_file)
+                if read_from_source:
+                    self._jupyter_ydoc.source = model.content
+                    await self._ystore.encode_state_as_update(self.doc)
+                    logger.info("Document read from file", file_path=file_path, id=self.id)
+                else:
+                    logger.info("Document read from YStore", file_path=file_path, id=self.id)
+
+                self._jupyter_ydoc.dirty = False
+                await super().run(task_status=task_status)
+        else:
+            logger.info("Opening collaboration room", **kwargs)
+            await super().run(task_status=task_status)
+
+    async def _write_to_ystore(self, *, task_status: TaskStatus[None]) -> None:
+        async with self.doc.events() as events:
+            task_status.started()
+            async for event in events:
+                await self._ystore.write(event.update)
+
+    async def _write_to_file(self, *, task_status: TaskStatus[None]) -> None:
+        async with self.doc.events() as events:
+            task_status.started()
+            async for event in events:
+                if self._write_to_file_cancel_scope is not None:
+                    self._write_to_file_cancel_scope.cancel()
+                    self._write_to_file_cancel_scope = None
+                self.task_group.start_soon(self._write_to_file_later)
+
+    async def _write_to_file_later(self) -> None:
+        with CancelScope() as self._write_to_file_cancel_scope:
+            await sleep(self._config.document_save_delay)
+            assert self._id_of_file is not None
+            file_path = await self._get_file_path(self._id_of_file)
+            assert file_path is not None
+            model = await self._contents.read_content(file_path, True, self._file_format)
+            if model.content != self._jupyter_ydoc.source:
+                # don't save if not needed
+                # this also prevents the dirty flag from bouncing between windows of
+                # the same document opened as different types (e.g. notebook/text editor)
+                content = {
+                    "content": self._jupyter_ydoc.source,
+                    "format": self._file_format,
+                    "path": file_path,
+                    "type": self._file_type,
+                }
+                with CancelScope(shield=True):
+                    logger.info("Saving document", file_path=file_path, id=self.id)
+                    await self._contents.write_content(content)
+                    model = await self._contents.read_content(file_path, False)
+                    assert model.last_modified is not None
+                    self._last_modified = to_datetime(model.last_modified)
+                self._jupyter_ydoc.dirty = False
+
+    async def _watch_file(self, *, task_status: TaskStatus[None]) -> None:
+        assert self._id_of_file is not None
+        file_path = await self._get_file_path(self._id_of_file)
+        assert file_path is not None
+        logger.info("Watching file", path=file_path)
+        watcher = self._file_id.watch(file_path)
+        task_status.started()
+        async for changes in watcher:
+            new_file_path = await self._get_file_path(self._id_of_file)
+            assert new_file_path is not None
+            if new_file_path is None:
+                continue
+            if new_file_path != file_path:
+                # file was renamed
+                self._file_id.unwatch(file_path, watcher)
+                file_path = new_file_path
+                # break
+            await self._read_file(new_file_path)
+
+    async def _read_file(self, file_path: str) -> None:
+        model = await self._contents.read_content(file_path, False)
+        assert model.last_modified is not None
+        # do nothing if the file was saved by us
+        if self._last_modified < to_datetime(model.last_modified):
+            # the file was not saved by us, update the shared document
+            model = await self._contents.read_content(file_path, True, self._file_format)
+            assert model.last_modified is not None
+            self._jupyter_ydoc.source = model.content
+            self._jupyter_ydoc.dirty = False
+            logger.info("Document read from file", file_path=file_path, id=self.id)
+            await self._ystore.encode_state_as_update(self._doc)
+            self._last_modified = to_datetime(model.last_modified)
+
+    async def _get_file_path(self, id_of_file: str) -> str | None:
+        file_path = await self._file_id.get_path(id_of_file)
+        if file_path is None:
+            return None
+        if file_path != self._jupyter_ydoc.path:
+            self._jupyter_ydoc.path = file_path
+        return file_path
+
+    async def handle_message(self, message: bytes, client: AsyncChannel) -> None:
+        match message[0]:
+            case YMessageType.SYNC:
+                _message = message[1:]
+                if self._can_write or _message[0] not in {
+                    YSyncMessageType.SYNC_UPDATE,
+                    YSyncMessageType.SYNC_STEP2,
+                }:
+                    reply = handle_sync_message(_message, self._doc)
+                    if reply is not None:
+                        await client.send(reply)
+            case YMessageType.AWARENESS:
+                for client in self.clients:
+                    await client.send(message)
+
+    async def close(self) -> None:
+        with CancelScope() as self._close_room_cancel_scope:
+            kwargs = {"id": self.id}
+            if self._id_of_file is not None:
+                file_path = await self._get_file_path(self._id_of_file)
+                assert file_path is not None
+                kwargs["file_path"] = file_path
+                await sleep(self._config.document_cleanup_delay)
+            await super().close()
+            logger.info("Closed collaboration room", **kwargs)
+
+
+class _YRooms(YRooms):
+    async def serve(self, websocket: AsyncChannel, permissions: dict[str, list[str]]) -> None:
+        room = await self.get_room(websocket.id, permissions=permissions)
+        await room.serve(websocket)
+
+
+def to_datetime(iso_date: str) -> datetime:
+    return datetime.fromisoformat(iso_date.rstrip("Z"))