Split documents into separate files (#135)

Author: davidbrochart

README.md

@@ -19,10 +19,10 @@ from jupyter_ydoc import ydocs
 
 print(ydocs)
 # {
-#     'blob': <class 'jupyter_ydoc.ydoc.YBlob'>,
-#     'file': <class 'jupyter_ydoc.ydoc.YFile'>,
-#     'notebook': <class 'jupyter_ydoc.ydoc.YNotebook'>,
-#     'unicode': <class 'jupyter_ydoc.ydoc.YUnicode'>
+#     'blob': <class 'jupyter_ydoc.yblob.YBlob'>,
+#     'file': <class 'jupyter_ydoc.yfile.YFile'>,
+#     'notebook': <class 'jupyter_ydoc.ynotebook.YNotebook'>,
+#     'unicode': <class 'jupyter_ydoc.yunicode.YUnicode'>
 # }
 ```
 

jupyter_ydoc/__init__.py

@@ -4,7 +4,10 @@
 import sys
 
 from ._version import __version__  # noqa
-from .ydoc import YBlob, YFile, YNotebook, YUnicode  # noqa
+from .yblob import YBlob  # noqa
+from .yfile import YFile  # noqa
+from .ynotebook import YNotebook  # noqa
+from .yunicode import YUnicode  # noqa
 
 # See compatibility note on `group` keyword in
 # https://docs.python.org/3/library/importlib.metadata.html#entry-points

jupyter_ydoc/ybasedoc.py

@@ -0,0 +1,149 @@
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Optional
+
+import y_py as Y
+
+
+class YBaseDoc(ABC):
+    """
+    Base YDoc class.
+    This class, defines the minimum API that any document must provide
+    to be able to get and set the content of the document as well as
+    subscribe to changes in the document.
+    """
+
+    def __init__(self, ydoc: Optional[Y.YDoc] = None):
+        """
+        Constructs a YBaseDoc.
+
+        :param ydoc: The :class:`y_py.YDoc` that will hold the data of the document, if provided.
+        :type ydoc: :class:`y_py.YDoc`, optional.
+        """
+        if ydoc is None:
+            self._ydoc = Y.YDoc()
+        else:
+            self._ydoc = ydoc
+        self._ystate = self._ydoc.get_map("state")
+        self._subscriptions = {}
+
+    @property
+    def ystate(self) -> Y.YMap:
+        """
+        A :class:`y_py.YMap` containing the state of the document.
+
+        :return: The document's state.
+        :rtype: :class:`y_py.YMap`
+        """
+        return self._ystate
+
+    @property
+    def ydoc(self) -> Y.YDoc:
+        """
+        The underlying :class:`y_py.YDoc` that contains the data.
+
+        :return: The document's ydoc.
+        :rtype: :class:`y_py.YDoc`
+        """
+        return self._ydoc
+
+    @property
+    def source(self) -> Any:
+        """
+        Returns the content of the document.
+
+        :return: The content of the document.
+        :rtype: Any
+        """
+        return self.get()
+
+    @source.setter
+    def source(self, value: Any):
+        """
+        Sets the content of the document.
+
+        :param value: The content of the document.
+        :type value: Any
+        """
+        return self.set(value)
+
+    @property
+    def dirty(self) -> Optional[bool]:
+        """
+        Returns whether the document is dirty.
+
+        :return: Whether the document is dirty.
+        :rtype: Optional[bool]
+        """
+        return self._ystate["dirty"]
+
+    @dirty.setter
+    def dirty(self, value: bool) -> None:
+        """
+        Sets the document as clean (all changes committed) or dirty (uncommitted changes).
+
+        :param value: Whether the document is clean or dirty.
+        :type value: bool
+        """
+        with self._ydoc.begin_transaction() as t:
+            self._ystate.set(t, "dirty", value)
+
+    @property
+    def path(self) -> Optional[str]:
+        """
+        Returns document's path.
+
+        :return: Document's path.
+        :rtype: Optional[str]
+        """
+        return self._ystate.get("path")
+
+    @path.setter
+    def path(self, value: str) -> None:
+        """
+        Sets document's path.
+
+        :param value: Document's path.
+        :type value: str
+        """
+        with self._ydoc.begin_transaction() as t:
+            self._ystate.set(t, "path", value)
+
+    @abstractmethod
+    def get(self) -> Any:
+        """
+        Returns the content of the document.
+
+        :return: Document's content.
+        :rtype: Any
+        """
+
+    @abstractmethod
+    def set(self, value: Any) -> None:
+        """
+        Sets the content of the document.
+
+        :param value: The content of the document.
+        :type value: Any
+        """
+
+    @abstractmethod
+    def observe(self, callback: Callable[[str, Any], None]) -> None:
+        """
+        Subscribes to document changes.
+
+        :param callback: Callback that will be called when the document changes.
+        :type callback: Callable[[str, Any], None]
+        """
+
+    def unobserve(self) -> None:
+        """
+        Unsubscribes to document changes.
+
+        This method removes all the callbacks.
+        """
+        for k, v in self._subscriptions.items():
+            k.unobserve(v)
+        self._subscriptions = {}

jupyter_ydoc/yblob.py

@@ -0,0 +1,71 @@
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import base64
+from functools import partial
+from typing import Any, Callable, Optional, Union
+
+import y_py as Y
+
+from .ybasedoc import YBaseDoc
+
+
+class YBlob(YBaseDoc):
+    """
+    Extends :class:`YBaseDoc`, and represents a blob document.
+    It is currently encoded as base64 because of:
+    https://github.com/y-crdt/ypy/issues/108#issuecomment-1377055465
+    The Y document can be set from bytes or from str, in which case it is assumed to be encoded as
+    base64.
+
+    Schema:
+
+    .. code-block:: json
+
+        {
+            "state": YMap,
+            "source": YMap
+        }
+    """
+
+    def __init__(self, ydoc: Optional[Y.YDoc] = None):
+        """
+        Constructs a YBlob.
+
+        :param ydoc: The :class:`y_py.YDoc` that will hold the data of the document, if provided.
+        :type ydoc: :class:`y_py.YDoc`, optional.
+        """
+        super().__init__(ydoc)
+        self._ysource = self._ydoc.get_map("source")
+
+    def get(self) -> bytes:
+        """
+        Returns the content of the document.
+
+        :return: Document's content.
+        :rtype: bytes
+        """
+        return base64.b64decode(self._ysource.get("base64", "").encode())
+
+    def set(self, value: Union[bytes, str]) -> None:
+        """
+        Sets the content of the document.
+
+        :param value: The content of the document.
+        :type value: Union[bytes, str]
+        """
+        if isinstance(value, bytes):
+            value = base64.b64encode(value).decode()
+        with self._ydoc.begin_transaction() as t:
+            self._ysource.set(t, "base64", value)
+
+    def observe(self, callback: Callable[[str, Any], None]) -> None:
+        """
+        Subscribes to document changes.
+
+        :param callback: Callback that will be called when the document changes.
+        :type callback: Callable[[str, Any], None]
+        """
+        self.unobserve()
+        self._subscriptions[self._ystate] = self._ystate.observe(partial(callback, "state"))
+        self._subscriptions[self._ysource] = self._ysource.observe(partial(callback, "source"))

jupyter_ydoc/yfile.py

@@ -0,0 +1,8 @@
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+from .yunicode import YUnicode
+
+
+class YFile(YUnicode):  # for backwards-compatibility
+    pass