Improve Python API (#122)

* Improve YNotebook Python API

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Call observer's callback with the name of the changed Y object

* Update YBaseDoc.observe callback signature

* Remove unneeded pass statement

* Make external ydoc optional

* Add YUTF8 and YBytes

* Replace YBytes with YBlob, YUTF8 with YText

* Replace YText with YUnicode

* Update README

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: davidbrochart

README.md

@@ -7,17 +7,23 @@
 
 `jupyter_ydoc` provides [Ypy](https://github.com/y-crdt/ypy)-based data structures for various
 documents used in the Jupyter ecosystem. Built-in documents include:
-- `YFile`: a generic text document.
+- `YBlob`: a generic immutable binary document.
+- `YUnicode`: a generic UTF8-encoded text document (`YFile` is an alias to `YUnicode`).
 - `YNotebook`: a Jupyter notebook document.
 
-These documents are registered via an entry point under the `"jupyter_ydoc"` group as `"file"` and
-`"notebook"`, respectively. You can access them as follows:
+These documents are registered via an entry point under the `"jupyter_ydoc"` group as `"blob"`,
+`"unicode"` (or `"file"`), and `"notebook"`, respectively. You can access them as follows:
 
 ```py
 from jupyter_ydoc import ydocs
 
 print(ydocs)
-# {'file': <class 'jupyter_ydoc.ydoc.YFile'>, 'notebook': <class 'jupyter_ydoc.ydoc.YNotebook'>}
+# {
+#     'blob': <class 'jupyter_ydoc.ydoc.YBlob'>,
+#     'file': <class 'jupyter_ydoc.ydoc.YFile'>,
+#     'notebook': <class 'jupyter_ydoc.ydoc.YNotebook'>,
+#     'unicode': <class 'jupyter_ydoc.ydoc.YUnicode'>
+# }
 ```
 
 Which is just a shortcut to:
@@ -30,14 +36,13 @@ ydocs = {ep.name: ep.load() for ep in pkg_resources.iter_entry_points(group="jup
 
 Or directly import them:
 ```py
-from jupyter_ydoc import YFile, YNotebook
+from jupyter_ydoc import YBlob, YUnicode, YNotebook
 ```
 
 The `"jupyter_ydoc"` entry point group can be populated with your own documents, e.g. by adding the
-following to your package's `setup.cfg`:
+following to your package's `pyproject.toml`:
 
 ```
-[options.entry_points]
-jupyter_ydoc =
-    my_document = my_package.my_file:MyDocumentClass
+[project.entry-points.jupyter_ydoc]
+my_dodument = "my_package.my_file:MyDocumentClass"
 ```

jupyter_ydoc/ydoc.py

@@ -1,9 +1,11 @@
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 
+import base64
 import copy
 from abc import ABC, abstractmethod
-from typing import Any, Callable, Dict, Optional
+from functools import partial
+from typing import Any, Callable, Dict, Optional, Union
 from uuid import uuid4
 
 import y_py as Y
@@ -24,14 +26,17 @@ class YBaseDoc(ABC):
     subscribe to changes in the document.
     """
 
-    def __init__(self, ydoc: Y.YDoc):
+    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.
-        :type ydoc: :class:`y_py.YDoc`
+        :param ydoc: The :class:`y_py.YDoc` that will hold the data of the document, if provided.
+        :type ydoc: :class:`y_py.YDoc`, optional.
         """
-        self._ydoc = ydoc
+        if ydoc is None:
+            self._ydoc = Y.YDoc()
+        else:
+            self._ydoc = ydoc
         self._ystate = self._ydoc.get_map("state")
         self._subscriptions = {}
 
@@ -125,7 +130,6 @@ def get(self) -> Any:
         :return: Document's content.
         :rtype: Any
         """
-        pass
 
     @abstractmethod
     def set(self, value: Any) -> None:
@@ -135,17 +139,15 @@ def set(self, value: Any) -> None:
         :param value: The content of the document.
         :type value: Any
         """
-        pass
 
     @abstractmethod
-    def observe(self, callback: Callable[[Any], None]) -> None:
+    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[[Any], None]
+        :type callback: Callable[[str, Any], None]
         """
-        pass
 
     def unobserve(self) -> None:
         """
@@ -158,9 +160,9 @@ def unobserve(self) -> None:
         self._subscriptions = {}
 
 
-class YFile(YBaseDoc):
+class YUnicode(YBaseDoc):
     """
-    Extends :class:`YBaseDoc`, and represents a plain text document.
+    Extends :class:`YBaseDoc`, and represents a plain text document, encoded as UTF-8.
 
     Schema:
 
@@ -172,12 +174,12 @@ class YFile(YBaseDoc):
         }
     """
 
-    def __init__(self, ydoc: Y.YDoc):
+    def __init__(self, ydoc: Optional[Y.YDoc] = None):
         """
-        Constructs a YFile.
+        Constructs a YUnicode.
 
-        :param ydoc: The :class:`y_py.YDoc` that will hold the data of the document.
-        :type ydoc: :class:`y_py.YDoc`
+        :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_text("source")
@@ -207,16 +209,81 @@ def set(self, value: str) -> None:
             if value:
                 self._ysource.extend(t, value)
 
-    def observe(self, callback: Callable[[Any], None]) -> None:
+    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[[Any], None]
+        :type callback: Callable[[str, Any], None]
         """
         self.unobserve()
-        self._subscriptions[self._ystate] = self._ystate.observe(callback)
-        self._subscriptions[self._ysource] = self._ysource.observe(callback)
+        self._subscriptions[self._ystate] = self._ystate.observe(partial(callback, "state"))
+        self._subscriptions[self._ysource] = self._ysource.observe(partial(callback, "source"))
+
+
+class YFile(YUnicode):  # for backwards-compatibility
+    pass
+
+
+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"))
 
 
 class YNotebook(YBaseDoc):
@@ -248,17 +315,27 @@ class YNotebook(YBaseDoc):
         }
     """
 
-    def __init__(self, ydoc: Y.YDoc):
+    def __init__(self, ydoc: Optional[Y.YDoc] = None):
         """
         Constructs a YNotebook.
 
-        :param ydoc: The :class:`y_py.YDoc` that will hold the data of the document.
-        :type ydoc: :class:`y_py.YDoc`
+        :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._ymeta = self._ydoc.get_map("meta")
         self._ycells = self._ydoc.get_array("cells")
 
+    @property
+    def cell_number(self) -> int:
+        """
+        Returns the number of cells in the notebook.
+
+        :return: The cell number.
+        :rtype: int
+        """
+        return len(self._ycells)
+
     def get_cell(self, index: int) -> Dict[str, Any]:
         """
         Returns a cell.
@@ -438,14 +515,14 @@ def set(self, value: Dict) -> None:
 
             self._ymeta.set(t, "metadata", Y.YMap(metadata))
 
-    def observe(self, callback: Callable[[Any], None]) -> None:
+    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[[Any], None]
+        :type callback: Callable[[str, Any], None]
         """
         self.unobserve()
-        self._subscriptions[self._ystate] = self._ystate.observe(callback)
-        self._subscriptions[self._ymeta] = self._ymeta.observe_deep(callback)
-        self._subscriptions[self._ycells] = self._ycells.observe_deep(callback)
+        self._subscriptions[self._ystate] = self._ystate.observe(partial(callback, "state"))
+        self._subscriptions[self._ymeta] = self._ymeta.observe_deep(partial(callback, "meta"))
+        self._subscriptions[self._ycells] = self._ycells.observe_deep(partial(callback, "cells"))

pyproject.toml

@@ -40,7 +40,9 @@ docs = [
 ]
 
 [project.entry-points.jupyter_ydoc]
+blob = "jupyter_ydoc.ydoc:YBlob"
 file = "jupyter_ydoc.ydoc:YFile"
+unicode = "jupyter_ydoc.ydoc:YUnicode"
 notebook = "jupyter_ydoc.ydoc:YNotebook"
 
 [project.readme]