ipymuvue 0.7.0__py3-none-any.whl

ipymuvue/.gitignore

@@ -0,0 +1,4 @@
+# Compiled javascript
+/labextensions/
+
+

ipymuvue/__init__.py

@@ -0,0 +1,36 @@
+# ******************************************************************************
+# Copyright (c) 2022 Julian Rüth <julian.rueth@fsfe.org>
+#
+# ipymuvue is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ipymuvue is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with ipymuvue. If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+
+from ipymuvue.version import version_info, __version__
+
+__all__ = ["version_info", "__version__"]
+
+
+def _jupyter_labextension_paths():
+    r"""
+    Called by JupyterLab to find out which JavaScript assets need to be copied.
+    """
+    # The command `jupyter labextension build` creates a package in
+    # labextensions/ipymuvue/, see jupyterlab.outputDir in ts/package.json
+    # These files are copied to extensions/ipymuvue/ in
+    # JupyterLab when this package is pip-installed.
+    return [
+        {
+            "src": "labextensions/ipymuvue",
+            "dest": "ipymuvue",
+        }
+    ]

ipymuvue/pyodide/proxies/__init__.py

@@ -0,0 +1,9 @@
+from ipymuvue.pyodide.proxies.conversion import (
+    vue_compatible,
+    python_compatible,
+    owner,
+    create_proxy,
+)
+
+
+__all__ = ["vue_compatible", "python_compatible", "owner", "create_proxy"]

ipymuvue/pyodide/proxies/array_wrapper.py

@@ -0,0 +1,93 @@
+r"""
+Wrappers for JavaScript arrays.
+
+pyodide wraps JavaScript arrays in a way that is very convenient to
+use from Python. However, we want to wrap the entries of that array
+with our own object wrapper, see
+:module:`ipymuvue.pyodide.proxies.object_wrapper` so we need to
+intercept some of the operations on an array.
+"""
+# ******************************************************************************
+# Copyright (c) 2022 Julian Rüth <julian.rueth@fsfe.org>
+#
+# ipymuvue is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ipymuvue is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with ipymuvue. If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+
+from collections.abc import MutableSequence
+from ipymuvue.pyodide.proxies import python_compatible, vue_compatible
+from ipymuvue.pyodide.types import is_vue_proxy
+
+
+class ArrayWrapper(MutableSequence):
+    r"""
+    Wraps a JavaScript Array with a Python list interface.
+    """
+
+    def __init__(self, array):
+        import js
+
+        if not js.Array.isArray(array):
+            raise TypeError("array must be a JavaScript array")
+
+        self._array = array
+
+    def _vue_compatible(self, object):
+        return vue_compatible(object)
+
+    def insert(self, index, object):
+        if index < 0:
+            index = 0
+        if index >= len(self):
+            index = len(self)
+        self._array.splice(index, 0, self._vue_compatible(object))
+
+    def __getitem__(self, index):
+        return python_compatible(self._array[index])
+
+    def __setitem__(self, index, value):
+        if index < 0:
+            index = len(self) + index
+        if index < 0:
+            raise IndexError("assignment index out of range")
+        if index >= len(self):
+            raise IndexError("assignment index out of range")
+
+        self._array[index] = self._vue_compatible(object)
+
+    def __delitem__(self, index):
+        if index < 0:
+            index = len(self) + index
+        if index < 0:
+            raise IndexError("deletion index out of range")
+        if index >= len(self):
+            raise IndexError("deletion index out of range")
+
+        self._array.splice(index, 1)
+
+    def __len__(self):
+        return self._array.length
+
+
+class ProxyList(ArrayWrapper):
+    r"""
+    Wraps a Vue proxy with a Python list interface.
+    """
+
+    def __init__(self, proxy):
+        if not is_vue_proxy(proxy):
+            raise TypeError("proxy must be a Vue proxy")
+        super().__init__(proxy)
+
+    def _vue_compatible(self, object):
+        return vue_compatible(object, reference=False)

ipymuvue/pyodide/proxies/conversion.py

@@ -0,0 +1,267 @@
+r"""
+Generic conversion between JavaScript and Python.
+
+pyodide wraps JavaScript objects in a PyProxy and Python objects in a
+JSProxy when the cross the boundary between JavaScript and Python and
+vice versa.
+
+However, this proxying causes trouble, see
+:module:`ipymuvue.pyodide.vue`. In short, Python programmers expect a
+Python dict interface and Vue gets confused by installing its own
+proxy on top of the JsProxy.
+
+Here, we provide some cenversions that seem to work better to enable
+communication between Python and Vue.js JavaScript API.
+"""
+# ******************************************************************************
+# Copyright (c) 2022 Julian Rüth <julian.rueth@fsfe.org>
+#
+# ipymuvue is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ipymuvue is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with ipymuvue. If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+
+import js
+from contextvars import ContextVar
+from contextlib import contextmanager
+from ipymuvue.pyodide.types import is_vue_ref, is_vue_proxy
+
+
+def python_compatible(x):
+    r"""
+    Wrap ``x`` that came out of a Vue API for use in Python.
+    """
+    import pyodide.ffi
+
+    from ipymuvue.pyodide.proxies.object_wrapper import ObjectWrapper, ProxyDict
+    from ipymuvue.pyodide.proxies.array_wrapper import ArrayWrapper, ProxyList
+    from ipymuvue.pyodide.proxies.proxy_ref import ProxyRef
+
+    # Some elementary types are converted automatically by pyodide.
+    if type(x) in [int, str, float, bool, type(None)]:
+        return x
+
+    if callable(x):
+        assert isinstance(x, pyodide.ffi.JsProxy), (
+            "received a function from Vue that is not defined in JavaScript"
+        )
+        raise NotImplementedError("cannot properly wrap functions from the Vue API yet")
+
+    if is_vue_ref(x):
+        return ProxyRef(x)
+
+    if js.Array.isArray(x):
+        if is_vue_proxy(x):
+            return ProxyList(x)
+        return ArrayWrapper(x)
+
+    if x.typeof == "object":
+        if is_vue_proxy(x):
+            return ProxyDict(x)
+        return ObjectWrapper(x)
+
+    raise Exception(f"not implemented, wrapping a proxy {x.typeof}")
+
+
+def vue_compatible(x, reference=True, shallow=False, owner=None):
+    r"""
+    Return ``x`` as a native JavaScript object that can be safely consumed by
+    the Vue API.
+
+    If ``x`` is a primitive value such as a number or a string, return it
+    unchanged.
+
+    If ``reference`` is ``True``, returns a value that behaves like a reference
+    of ``x``. Changes to ``x`` are reflected in the returned
+    value and vice versa. If ``shallow`` is not set, verify that values nested
+    in ``x`` are also compatible with Vue's JavaScript API. (That last part is
+    sometimes not actually verified yet.)
+
+    If ``reference`` is ``False``, return clone of ``x``; the clone is deep
+    unless ``shallow`` is set.
+
+    If ``reference`` is ``None``, return whatever is chepest to accomplish.
+
+    If a proxy of a callable gets created, its lifetime is tied to ``owner``,
+    see :meth:`owner` for details.
+    """
+    import pyodide.ffi
+
+    from ipymuvue.pyodide.proxies.object_wrapper import ObjectWrapper
+    from ipymuvue.pyodide.proxies.array_wrapper import ArrayWrapper
+    from ipymuvue.pyodide.proxies.proxy_ref import ProxyRef
+
+    if type(x) in [int, str, float, bool, type(None)]:
+        return x
+
+    if callable(x):
+        if isinstance(x, pyodide.ffi.JsProxy):
+            return x
+
+        import asyncio
+
+        if asyncio.iscoroutine(x):
+            raise NotImplementedError(
+                "coroutines cannot be export by setup() yet, see "
+            )
+
+        # Load helper implemented in TypeScript in ipymuvue_js.ts
+        from ipymuvue_js import asVueCompatibleFunction
+
+        return asVueCompatibleFunction(
+            create_proxy(x, owner),
+            python_compatible_js,
+            vue_compatible_js,
+        )
+
+    if isinstance(x, pyodide.ffi.JsProxy):
+        if reference is not False:
+            # Note that we are not yet checking whether the insides of this
+            # object contain no PyProxy instances.
+            return x
+        else:
+            # Load helper implemented in TypeScript in ipymuvue_js.ts
+            from ipymuvue_js import clone, cloneDeep
+
+            return clone(x) if shallow else cloneDeep(x)
+
+    if isinstance(x, ProxyRef):
+        assert is_vue_ref(x._ref)
+        return vue_compatible(x._ref, reference=reference, shallow=shallow)
+
+    if isinstance(x, ObjectWrapper):
+        return vue_compatible(x._object, reference=reference, shallow=shallow)
+
+    if isinstance(x, ArrayWrapper):
+        return vue_compatible(x._array, reference=reference, shallow=shallow)
+
+    from collections.abc import Sequence
+
+    if isinstance(x, Sequence):
+        if reference is True:
+            raise TypeError(
+                "cannot call Vue API with this Python sequence; use vue_compatible(..., reference=False) to create a deep clone that can be consumed by thue Vue API"
+            )
+        else:
+            y = js.Array.new()
+            for item in x:
+                y.push(vue_compatible(item, reference=None, shallow=shallow))
+            return y
+
+    from collections.abc import Mapping
+
+    if isinstance(x, Mapping):
+        if reference is True:
+            raise TypeError(
+                "cannot call Vue API with this Python mapping; use vue_compatible(..., reference=False) to create a deep clone that can be consumed by the Vue API"
+            )
+        else:
+            o = js.Object.new()
+            for key in x.keys():
+                if not isinstance(key, (str, int)):
+                    raise TypeError(f"key must be str or int but was {type(key)}")
+                strkey = str(key)
+                if hasattr(o, strkey):
+                    raise ValueError("duplicate key in dict after conversion to str")
+                setattr(
+                    o, strkey, vue_compatible(x[key], reference=None, shallow=shallow)
+                )
+
+            return o
+
+    raise NotImplementedError(f"cannot wrap this {type(x)} yet")
+
+
+_owner = ContextVar("owner", default=None)
+
+
+@contextmanager
+def owner(owner):
+    r"""
+    Tie the lifetime of any proxies created during this context to ``owner``.
+
+    If no owner has been set when creating a proxy (of a callable) a warning is
+    emitted and we are never going to release the proxy (and leak memory).
+
+    If ``owner`` is a callable, it gets called with the proxy once created to
+    register its own lifetime handling (or just silence the warning.)
+
+    If ``owner`` is any other JavaScript object, we register it with a
+    ``FinalizationRegistry`` in JavaScript.
+    """
+    import pyodide.ffi
+
+    if owner is None:
+        pass
+    elif callable(owner):
+        pass
+    elif isinstance(owner, pyodide.ffi.JsProxy):
+        pass
+    else:
+        raise TypeError("owner must be None, a callable, or a JsProxy")
+
+    token = _owner.set(owner)
+    try:
+        yield None
+    finally:
+        _owner.reset(token)
+
+
+def create_proxy(x, owner=None):
+    r"""
+    Create a JavaScript JsProxy proxy of ``x`` (typically a callable.) This
+    wraps pyodide's ``create_proxy`` to get better control over the lifetime of
+    ``x``.
+
+    If ``owner`` is ``None``, we try to deduce the ownership from a context
+    variable. See :meth:`owner` for details.
+    """
+    import pyodide.ffi
+
+    proxy = pyodide.ffi.create_proxy(x)
+
+    if owner is None:
+        owner = _owner.get()
+
+    if owner is None:
+        js.console.warn(
+            f"No owner set when creating proxy of {x}. Memory will be leaked. Wrap your code in a `with ipymuvue.pyodide.proxies.owner(...)` context to avoid this warning."
+        )
+
+    elif callable(owner):
+        owner(proxy)
+    elif isinstance(owner, pyodide.ffi.JsProxy):
+        _registry.register(owner, proxy)
+    else:
+        raise NotImplementedError("cannot handle this kind of owner yet")
+
+    # Enable to understand memory leaks.
+    # print("created proxy for", x, "owner by", owner)
+
+    return proxy
+
+
+def release_proxy(proxy):
+    # Enable to understand memory leaks.
+    # print("releasing proxy", proxy)
+
+    import pyodide.ffi
+
+    pyodide.ffi.destroy_proxies(js.Array.new([proxy]))
+
+
+# Singleton proxies of these conversion functions with infinite lifetime
+python_compatible_js = create_proxy(python_compatible, owner=lambda proxy: None)
+vue_compatible_js = create_proxy(vue_compatible, owner=lambda proxy: None)
+release_proxy_js = create_proxy(release_proxy, owner=lambda proxy: None)
+
+_registry = js.FinalizationRegistry.new(release_proxy_js)

ipymuvue/pyodide/proxies/object_wrapper.py

@@ -0,0 +1,98 @@
+r"""
+Wrappers for JavaScript objects.
+
+pyodide wraps JavaScript objects with a PyProxy. However, that proxy does not
+provide them with a Python dict like interface that most Python programmers
+expect. Here we provide such a wrapper :class:`ObjectWrapper` and a specialized
+version, :class:`ProxyDict` that makes sure that no actual Python objects end
+up in a Vue proxy without converting them to native JavaScript objects first.
+"""
+# ******************************************************************************
+# Copyright (c) 2022 Julian Rüth <julian.rueth@fsfe.org>
+#
+# ipymuvue is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ipymuvue is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with ipymuvue. If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+
+from collections.abc import MutableMapping
+
+
+class ObjectWrapper(MutableMapping):
+    r"""
+    Wraps a JavaScript object with a Python dict interface.
+    """
+
+    def __init__(self, object):
+        if not object.typeof == "object":
+            raise TypeError("object must be a JavaScript object")
+
+        super().__setattr__("_object", object)
+
+    def _vue_compatible(self, object):
+        from ipymuvue.pyodide.proxies import vue_compatible
+
+        return vue_compatible(object)
+
+    def __delitem__(self, key):
+        raise Exception("not implemented __delitem__")
+
+    def __getattr__(self, key):
+        if not isinstance(key, (int, str)):
+            raise TypeError(f"key must be int or str but was {type(key)}")
+
+        from ipymuvue.pyodide.proxies import python_compatible
+
+        return python_compatible(getattr(self._object, str(key)))
+
+    def __setattr__(self, key, value):
+        if not isinstance(key, (int, str)):
+            raise TypeError(f"key must be int or str but was {type(key)}")
+
+        setattr(self._object, str(key), self._vue_compatible(value))
+
+    def __setitem__(self, key, value):
+        self.__setattr__(key, value)
+
+    def __iter__(self):
+        import js
+
+        for key in js.Object.keys(self._object):
+            yield key
+
+    def __len__(self):
+        return len(self._object)
+
+    def __getitem__(self, key):
+        try:
+            return self.__getattr__(key)
+        except AttributeError:
+            raise KeyError(key) from None
+
+
+class ProxyDict(ObjectWrapper):
+    r"""
+    Wraps a Vue proxy with a Python dict interface.
+    """
+
+    def __init__(self, proxy):
+        from ipymuvue.pyodide.types import is_vue_proxy
+
+        if not is_vue_proxy(proxy):
+            raise TypeError("proxy must be a Vue proxy")
+
+        super().__init__(proxy)
+
+    def _vue_compatible(self, object):
+        from ipymuvue.pyodide.proxies import vue_compatible
+
+        return vue_compatible(object, reference=False)

ipymuvue/pyodide/proxies/proxy_ref.py

@@ -0,0 +1,53 @@
+r"""
+Wrapper for a Vue.js Ref.
+
+We provide a Vue.js Ref with a more convenient interface from Python
+and make sure that no Python objects that Vue.js cannot understand
+enter the Vue.js API.
+"""
+# ******************************************************************************
+# Copyright (c) 2022 Julian Rüth <julian.rueth@fsfe.org>
+#
+# ipymuvue is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ipymuvue is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with ipymuvue. If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+
+
+class ProxyRef:
+    r"""
+    Wraps a Vue ref object with a Python property interface.
+    """
+
+    def __init__(self, ref):
+        from ipymuvue.pyodide.types import is_vue_ref
+
+        if not is_vue_ref(ref):
+            raise TypeError("ref must be a Vue ref")
+        self._ref = ref
+
+    @property
+    def value(self):
+        # For a readonly ref, Python does not see its .value attribute so we
+        # run the .value in JavaScript.
+        from ipymuvue.pyodide.proxies import python_compatible
+
+        # Load Vue from ipymuvue_js.ts implemented in TypeScript
+        from ipymuvue_js import Vue
+
+        return python_compatible(Vue.unref(self._ref))
+
+    @value.setter
+    def value(self, value):
+        from ipymuvue.pyodide.proxies import vue_compatible
+
+        self._ref.value = vue_compatible(value, reference=False)

ipymuvue/pyodide/types.py

@@ -0,0 +1,53 @@
+r"""
+Type checks for objects coming out of the Vue.js API.
+"""
+# ******************************************************************************
+# Copyright (c) 2022 Julian Rüth <julian.rueth@fsfe.org>
+#
+# ipymuvue is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ipymuvue is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with ipymuvue. If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+
+# The interface to JavaScript, only available when running in pyodide.
+import js
+
+
+def is_vue_proxy(x):
+    r"""
+    Return whether ``x`` is a un unwrapped reactive Vue Proxy.
+    """
+    import pyodide.ffi
+    from ipymuvue_js import Vue
+
+    return isinstance(x, pyodide.ffi.JsProxy) and Vue.isProxy(x)
+
+
+def is_vue_ref(x):
+    r"""
+    Return whether ``x`` is a un unwrapped reactive Vue Ref.
+    """
+    import pyodide.ffi
+    from ipymuvue_js import Vue
+
+    return isinstance(x, pyodide.ffi.JsProxy) and Vue.isRef(x)
+
+
+# Types for Runtime Type Checks of props
+String = js.String
+Number = js.Number
+Boolean = js.Boolean
+Array = js.Array
+Object = js.Object
+Date = js.Date
+Function = js.Function
+Symbol = js.Symbol