trame-dataclass 1.0.0__tar.gz

trame_dataclass-1.0.0/.gitignore

@@ -0,0 +1,26 @@
+.DS_Store
+node_modules
+.venv
+
+# local env files
+.env.local
+.env.*.local
+
+# Log files
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+__pycache__
+*egg-info
+*pyc

trame_dataclass-1.0.0/LICENSE

@@ -0,0 +1,15 @@
+Apache Software License 2.0
+
+Copyright (c) 2025, Kitware Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

trame_dataclass-1.0.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: trame-dataclass
+Version: 1.0.0
+Summary: Dataclass for trame UI binding
+Author: Kitware Inc.
+License: Apache Software License
+License-File: LICENSE
+Keywords: Application,Framework,Interactive,Python,Web
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: trame-client>=3.10
+Provides-Extra: app
+Requires-Dist: pywebview; extra == 'app'
+Provides-Extra: dev
+Requires-Dist: nox; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov>=3; extra == 'dev'
+Requires-Dist: pytest>=6; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: jupyter
+Requires-Dist: jupyterlab; extra == 'jupyter'
+Description-Content-Type: text/x-rst
+
+trame-dataclass
+----------------------------------------
+
+Dataclass for trame UI binding
+
+License
+----------------------------------------
+
+This library is OpenSource and follow the Apache Software License
+
+Installation
+----------------------------------------
+
+Install the application/library
+
+.. code-block:: console
+
+    pip install trame-dataclass
+
+
+Development setup
+----------------------------------------
+
+We recommend using uv for setting up and managing a virtual environment for your development.
+
+.. code-block:: console
+
+    # Create venv and install all dependencies
+    uv sync --all-extras --dev
+
+    # Activate environment
+    source .venv/bin/activate
+
+    # Install commit analysis
+    pre-commit install
+    pre-commit install --hook-type commit-msg
+
+    # Allow live code edit
+    uv pip install -e .
+
+
+Build and install the Vue components
+
+.. code-block:: console
+
+    cd vue-components
+    npm i
+    npm run build
+    cd -
+
+For running tests and checks, you can run ``nox``.
+
+.. code-block:: console
+
+    # run all
+    nox
+
+    # lint
+    nox -s lint
+
+    # tests
+    nox -s tests
+
+Professional Support
+----------------------------------------
+
+* `Training <https://www.kitware.com/courses/trame/>`_: Learn how to confidently use trame from the expert developers at Kitware.
+* `Support <https://www.kitware.com/trame/support/>`_: Our experts can assist your team as you build your web application and establish in-house expertise.
+* `Custom Development <https://www.kitware.com/trame/support/>`_: Leverage Kitware’s 25+ years of experience to quickly build your web application.

trame_dataclass-1.0.0/README.rst

@@ -0,0 +1,69 @@
+trame-dataclass
+----------------------------------------
+
+Dataclass for trame UI binding
+
+License
+----------------------------------------
+
+This library is OpenSource and follow the Apache Software License
+
+Installation
+----------------------------------------
+
+Install the application/library
+
+.. code-block:: console
+
+    pip install trame-dataclass
+
+
+Development setup
+----------------------------------------
+
+We recommend using uv for setting up and managing a virtual environment for your development.
+
+.. code-block:: console
+
+    # Create venv and install all dependencies
+    uv sync --all-extras --dev
+
+    # Activate environment
+    source .venv/bin/activate
+
+    # Install commit analysis
+    pre-commit install
+    pre-commit install --hook-type commit-msg
+
+    # Allow live code edit
+    uv pip install -e .
+
+
+Build and install the Vue components
+
+.. code-block:: console
+
+    cd vue-components
+    npm i
+    npm run build
+    cd -
+
+For running tests and checks, you can run ``nox``.
+
+.. code-block:: console
+
+    # run all
+    nox
+
+    # lint
+    nox -s lint
+
+    # tests
+    nox -s tests
+
+Professional Support
+----------------------------------------
+
+* `Training <https://www.kitware.com/courses/trame/>`_: Learn how to confidently use trame from the expert developers at Kitware.
+* `Support <https://www.kitware.com/trame/support/>`_: Our experts can assist your team as you build your web application and establish in-house expertise.
+* `Custom Development <https://www.kitware.com/trame/support/>`_: Leverage Kitware’s 25+ years of experience to quickly build your web application.

trame_dataclass-1.0.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "trame-dataclass"
+version = "1.0.0"
+description = "Dataclass for trame UI binding"
+authors = [{ name = "Kitware Inc." }]
+dependencies = ["trame_client>=3.10"]
+requires-python = ">=3.9"
+readme = "README.rst"
+license = { text = "Apache Software License" }
+keywords = ["Python", "Interactive", "Web", "Application", "Framework"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "License :: OSI Approved :: Apache Software License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.optional-dependencies]
+app = ["pywebview"]
+jupyter = ["jupyterlab"]
+dev = [
+    "pre-commit",
+    "ruff",
+    "pytest >=6",
+    "pytest-asyncio",
+    "pytest-cov >=3",
+    "nox",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.hatch.build]
+include = [
+    "/src/trame/**/*.py",
+    "/src/trame_dataclass/**/*.py",
+    "/src/trame_dataclass/**/*.js",
+    "/src/trame_dataclass/**/*.css",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/trame", "src/trame_dataclass"]
+
+[tool.ruff]
+
+[tool.ruff.lint]
+extend-select = [
+    "ARG", # flake8-unused-arguments
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "EM",  # flake8-errmsg
+    "EXE", # flake8-executable
+    "G",   # flake8-logging-format
+    "I",   # isort
+    "ICN", # flake8-import-conventions
+    "NPY", # NumPy specific rules
+    "PD",  # pandas-vet
+    "PGH", # pygrep-hooks
+    "PIE", # flake8-pie
+    "PL",  # pylint
+    "PT",  # flake8-pytest-style
+    "PTH", # flake8-use-pathlib
+    "RET", # flake8-return
+    "RUF", # Ruff-specific
+    "SIM", # flake8-simplify
+    "T20", # flake8-print
+    "UP",  # pyupgrade
+    "YTT", # flake8-2020
+]
+ignore = [
+    "T201",    # tmp during dev
+    "PLR09",   # Too many <...>
+    "PLR2004", # Magic value used in comparison
+    "ISC001",  # Conflicts with formatter
+    "SIM117",  # nested with for UI in examples
+]
+isort.required-imports = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["T20"]
+"noxfile.py" = ["T20"]
+"src/**" = ["SIM117"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/trame_dataclass/__init__.py:__version__"]
+build_command = "pip install uv && uv build"

trame_dataclass-1.0.0/src/trame/modules/dataclass.py

@@ -0,0 +1 @@
+from trame_dataclass.module import *  # noqa: F403

trame_dataclass-1.0.0/src/trame/widgets/dataclass.py

@@ -0,0 +1,7 @@
+from trame_dataclass.widgets.dataclass import *  # noqa: F403
+
+
+def initialize(server):
+    from trame_dataclass import module
+
+    server.enable_module(module)

trame_dataclass-1.0.0/src/trame_dataclass/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

trame_dataclass-1.0.0/src/trame_dataclass/core.py

@@ -0,0 +1,775 @@
+import asyncio
+import inspect
+import os
+import string
+import types
+import warnings
+import weakref
+from collections.abc import Awaitable
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Any, Callable, TypeVar
+
+from trame_common.obj.component import TrameComponent
+
+from trame_dataclass import module as dataclass_module
+
+# -----------------------------------------------------------------------------
+# internal field names
+# -----------------------------------------------------------------------------
+_FIELDS = "__trame_dataclass_fields__"
+
+# -----------------------------------------------------------------------------
+# Id generator
+# -----------------------------------------------------------------------------
+INSTANCES = weakref.WeakValueDictionary()
+_INSTANCE_COUNT = 0
+_INSTANCE_ID_CHARS = string.digits + string.ascii_letters
+
+
+def _next_id():
+    global _INSTANCE_COUNT  # noqa: PLW0603
+    _INSTANCE_COUNT += 1
+
+    result = []
+    value = _INSTANCE_COUNT
+    size = len(_INSTANCE_ID_CHARS)
+    while value > 0:
+        remainder = value % size
+        result.append(_INSTANCE_ID_CHARS[remainder])
+        value //= size
+
+    return "".join(result[::-1])
+
+
+# -----------------------------------------------------------------------------
+# Compatibles Types
+# -----------------------------------------------------------------------------
+
+_JSON_TYPES = frozenset(
+    {
+        # Common JSON Serializable types
+        types.NoneType,
+        bool,
+        int,
+        float,
+        str,
+    }
+)
+
+_COMPOSITE_TYPES = frozenset(
+    {
+        set,
+        list,
+        dict,
+    }
+)
+
+# -----------------------------------------------------------------------------
+# Internal type definition
+# -----------------------------------------------------------------------------
+
+T = TypeVar("T")
+SerializableCoreType = None | str | bool | int | float
+SerializableType = (
+    SerializableCoreType | list[SerializableCoreType] | dict[str, SerializableCoreType]
+)
+Encoder = Callable[[T], SerializableType]
+Decoder = Callable[[SerializableType], T]
+WatcherCallback = Callable[[Any], None | Awaitable[None]]
+
+# -----------------------------------------------------------------------------
+# Custom Exception
+# -----------------------------------------------------------------------------
+
+
+class NonSerializableType(ValueError):
+    pass
+
+
+class InvalidDefaultForType(ValueError):
+    pass
+
+
+class NoServerLinked(ValueError):
+    pass
+
+
+class WatcherExecution(Exception):
+    pass
+
+
+# -----------------------------------------------------------------------------
+# Internal classes
+# -----------------------------------------------------------------------------
+
+
+class ContainerFactory:
+    def __init__(self, cls):
+        self._cls = cls
+
+    def __call__(self, *args, **kwargs):
+        return self._cls(*args, **kwargs)
+
+
+@dataclass
+class Watcher:
+    id: int
+    args: tuple[str]
+    dependency: set[str]
+    callback: WatcherCallback
+    sync: bool
+
+    def trigger(
+        self,
+        obj,
+        dirty: set[str] | None = None,
+        sync: bool = False,
+        eager: bool = False,
+    ):
+        if self.sync != sync and not eager:
+            return
+
+        if dirty is None or self.dependency & dirty:
+            args = [getattr(obj, name) for name in self.args]
+            coroutine = self.callback(*args)
+            if inspect.isawaitable(coroutine):
+                bg_task = asyncio.create_task(coroutine)
+                bg_task.add_done_callback(handle_task_result)
+
+
+def handle_task_result(task: asyncio.Task) -> None:
+    try:
+        task.result()
+    except asyncio.CancelledError:
+        pass  # Task cancellation should not be logged as an error.
+    except Exception as e:  # pylint: disable=broad-except
+        raise WatcherExecution() from e
+
+
+def check_loop_status():
+    try:
+        asyncio.get_running_loop()
+        return True
+    except RuntimeError:
+        return False
+
+
+# -----------------------------------------------------------------------------
+# Method to add to trame_dataclass
+# -----------------------------------------------------------------------------
+
+
+def _create_methods(fields, server, client, sync, valid_keys):
+    methods_to_register = {}
+
+    def __init__(self, trame_server=None, **kwargs):
+        self.__id = _next_id()
+        self.__trame_server = trame_server
+
+        # Register all instances
+        INSTANCES[self.__id] = self
+
+        self._dirty_set = set()
+        self._sync = sync
+        self._watchers = []
+        self._next_watcher_id = 1
+        self._pending_task = None
+        self._flush_impl = None
+
+        if server:
+            self._server_state = {}
+
+        if client:
+            self._client_state = {}
+
+        # set default values
+        for f in fields:
+            f.setup_instance(self)
+
+        # initialize fields from kwargs
+        self.update(**kwargs)
+
+        # register to server
+        if self.server is not None:
+            self.server.enable_module(dataclass_module)
+            if self.server.running:
+                # register protocol directly
+                self._register_server()
+            else:
+                # wait for server to be ready
+                self.server.controller.on_server_ready.add(self._register_server)
+
+    def _register_server(self, **_):
+        self.server.protocol_call("trame.dataclass.register", self)
+
+    def register_flush_implementation(self, push_function):
+        self._flush_impl = push_function
+
+    def update(self, **kwargs):
+        for key in valid_keys & set(kwargs.keys()):
+            setattr(self, key, kwargs[key])
+
+    def __repr__(self):
+        max_size = max(len(f.name) for f in fields)
+        fields_info = [
+            f"{f.name:<{max_size}} [{f.mode} | enc({'custom' if f.encoder and f.decoder else 'json'}) | {_repr_type(f.type_annotation)}: {_repr_default(f.default)} ]: {_repr_value(getattr(self, f.name))}"
+            for f in fields
+        ]
+        return f"{self.__class__.__name__} ({self._id}) - {self._dirty_set if len(self._dirty_set) else 'Synched'}{os.linesep} - {f'{os.linesep} - '.join(fields_info)}"
+
+    def _on_dirty(self):
+        dirty_copy = set(self._dirty_set)
+
+        self._notify_watcher(dirty_copy, sync=True)
+        if self._pending_task is None and check_loop_status():
+            self._pending_task = asyncio.create_task(self._async_update(dirty_copy))
+            self._pending_task.add_done_callback(handle_task_result)
+
+            # only clear if you know that the dirty copy will be processed
+            # otherwise wait for completion to pickup the dirty left over.
+            self._dirty_set.clear()
+
+        if not check_loop_status():
+            # need to clear dirty if async is out of the picture
+            self._dirty_set.clear()
+
+    def _notify_watcher(self, dirty_set: set[str] | None = None, sync=False):
+        if dirty_set is None:
+            dirty_set = set(self._dirty_set)
+
+        for w in self._watchers:
+            w.trigger(self, dirty_set, sync=sync)
+
+    async def _async_update(self, dirty_set: set[str]):
+        self._notify_watcher(dirty_set, sync=False)
+        if sync:
+            self.flush(dirty_set)
+
+        self._pending_task = None
+
+        # reschedule ourself if remaining dirty
+        if self._dirty_set and check_loop_status():
+            dirty_set = set(self._dirty_set)
+            self._dirty_set.clear()
+
+            self._pending_task = asyncio.create_task(self._async_update(dirty_set))
+            self._pending_task.add_done_callback(handle_task_result)
+
+    def clear_watchers(self):
+        self._watchers.clear()
+
+    def clone(self):
+        other = self.__class__()
+        state = getattr(self, "_server_state", getattr(self, "_client_state", {}))
+        other.update(**state)
+        return other
+
+    methods_to_register["__init__"] = __init__
+    methods_to_register["update"] = update
+    methods_to_register["clone"] = clone
+    methods_to_register["__repr__"] = __repr__
+    methods_to_register["_on_dirty"] = _on_dirty
+    methods_to_register["_notify_watcher"] = _notify_watcher
+    methods_to_register["_async_update"] = _async_update
+    methods_to_register["_register_server"] = _register_server
+    methods_to_register["clear_watchers"] = clear_watchers
+    methods_to_register["register_flush_implementation"] = register_flush_implementation
+
+    # Optionally add flush method
+    if sync:
+
+        def flush(self, dirty_set: set[str] | None = None):
+            """Flush the data to the client."""
+            if self._flush_impl is None:
+                return
+
+            if dirty_set is None:
+                dirty_set = set(self._dirty_set)
+                self._dirty_set.clear()
+            else:
+                for name in dirty_set:
+                    self._dirty_set.discard(name)
+
+            fields = getattr(self.__class__, _FIELDS)
+            for name in dirty_set:
+                _save_field(fields.get(name), self, self._client_state)
+
+            # Send data over the network
+            msg = {
+                "id": self._id,
+                "state": {k: self._client_state[k] for k in dirty_set},
+            }
+            self._flush_impl(msg)
+
+        methods_to_register["flush"] = flush
+
+    return methods_to_register
+
+
+def _m_get_id(self):
+    return self.__id
+
+
+def _m_get_server(self):
+    return self.__trame_server
+
+
+def _m_set_server(self, v):
+    if self.__trame_server != v:
+        self.__trame_server = v
+        if v:
+            v.enable_module(dataclass_module)
+            self._register_server()
+
+
+def _save_field(field, src, dst):
+    if field.encoder:
+        dst[field.name] = field.encoder(getattr(src, field.name))
+    else:
+        value = getattr(src, field.name)
+        if is_trame_dataclass(value):
+            value.flush()
+            value = f"_dataclass: {value._id}"
+        dst[field.name] = value
+
+
+def _m_get_client_state(self):
+    # Make sure the client_state is fully filled
+    fields = getattr(self.__class__, _FIELDS).values()
+    dirty = set(self._dirty_set)
+    for field in fields:
+        if field.name in dirty or field.name not in self._client_state:
+            _save_field(field, self, self._client_state)
+
+    return self._client_state
+
+
+def _m_watch(
+    self,
+    field_names: tuple[str],
+    callback_func: WatcherCallback,
+    sync: bool = False,
+    eager: bool = False,
+) -> Callable:
+    """Register a callback to be called when one or more fields change.
+
+    Args:
+        field_names (list[str]): Name(s) of the field(s) to watch.
+        callback_func (callable): Callback function to be called when the field(s) change.
+        sync (bool): Whether to execute the callback synchronously. By default this get triggered asynchronously.
+        eager (bool): Whether to execute the callback immediately after registration.
+
+    Returns:
+        callable: Unwatch function to unregister the callback.
+    """
+    watcher = Watcher(
+        self._next_watcher_id, field_names, set(field_names), callback_func, sync
+    )
+    self._next_watcher_id += 1
+    self._watchers.append(watcher)
+
+    def unwatch():
+        self._watchers.remove(watcher)
+
+    if eager:
+        watcher.trigger(self, eager=eager)
+
+    return unwatch
+
+
+def _m_Provider(
+    self, name: str = "data", instance: str | None = None
+) -> TrameComponent:
+    """Register a data provider to be used by the client.
+
+    Args:
+        name (str): Name of the data variable that will be available within the nested scope.
+        instance (str): Id of the trame_dataclass instance to use for filling the data. This behave like any other Widget property, so you can make it dynamic to switch at runtime the delivered data.
+
+    Returns:
+        widget: instance of the widget to put within your UI definition."""
+    from trame_dataclass.widgets.dataclass import Provider
+
+    if instance is None:
+        instance = (f"'{self._id}'",)
+
+    return Provider(name=name, instance=instance)
+
+
+# -----------------------------------------------------------------------------
+# Representation helper functions
+# -----------------------------------------------------------------------------
+
+
+def _repr_type(annotation_type):
+    if isinstance(annotation_type, types.UnionType):
+        return f"({annotation_type})"
+
+    if is_trame_dataclass(annotation_type):
+        return annotation_type.__name__
+
+    if isinstance(annotation_type, type):
+        return annotation_type.__name__
+
+    return str(annotation_type)
+
+
+def _repr_default(value):
+    if isinstance(value, ContainerFactory):
+        return "-"
+    return _repr_value(value)
+
+
+def _repr_value(value):
+    if is_trame_dataclass(value):
+        return "\n      ".join(str(value).split("\n"))
+    if isinstance(value, str):
+        return f'"{value}"'
+    return str(value)
+
+
+# -----------------------------------------------------------------------------
+# Type annotation analysis helper functions
+# -----------------------------------------------------------------------------
+
+
+def _type_compatibility(annotation_type):
+    if annotation_type in _JSON_TYPES:
+        return True
+
+    if isinstance(annotation_type, types.UnionType):
+        return all(map(_type_compatibility, annotation_type.__args__))
+
+    if is_trame_dataclass(annotation_type):
+        return True
+
+    if annotation_type in _COMPOSITE_TYPES:
+        warnings.warn("Composite type is not templated.", stacklevel=2)
+        return True
+
+    if (
+        hasattr(annotation_type, "__origin__")
+        and annotation_type.__origin__ in _COMPOSITE_TYPES
+    ):
+        return all(map(_type_compatibility, annotation_type.__args__))
+
+    return False
+
+
+def _type_is_composite(annotation_type):
+    if annotation_type in _COMPOSITE_TYPES:
+        return True
+
+    return (
+        hasattr(annotation_type, "__origin__")
+        and annotation_type.__origin__ in _COMPOSITE_TYPES
+    )
+
+
+def _type_can_be_none(annotation_type):
+    if isinstance(annotation_type, types.UnionType):
+        return types.NoneType in annotation_type.__args__
+
+    return False
+
+
+def _type_is_dataclass(annotation_type):
+    if is_trame_dataclass(annotation_type):
+        return True
+
+    if isinstance(annotation_type, types.UnionType):
+        for t in annotation_type.__args__:
+            if is_trame_dataclass(t):
+                return True
+
+    return False
+
+
+def _type_default(annotation_type):
+    if _type_can_be_none(annotation_type):
+        return None
+
+    if annotation_type is int:
+        return 0
+
+    if annotation_type is float:
+        return 0.0
+
+    if annotation_type is bool:
+        return False
+
+    if annotation_type is str:
+        return ""
+
+    if _type_is_composite(annotation_type):
+        container_type = (
+            annotation_type.__origin__
+            if hasattr(annotation_type, "__origin__")
+            else annotation_type
+        )
+        if container_type is list:
+            return ContainerFactory(list)
+        if container_type is set:
+            return ContainerFactory(set)
+        if container_type is dict:
+            return ContainerFactory(dict)
+        raise InvalidDefaultForType(annotation_type)
+
+    if isinstance(annotation_type, types.GenericAlias):
+        return _type_default(annotation_type.__origin__)
+
+    if is_trame_dataclass(annotation_type):
+        return ContainerFactory(annotation_type)
+
+    raise InvalidDefaultForType(annotation_type)
+
+
+# -----------------------------------------------------------------------------
+# Dataclass builder
+# -----------------------------------------------------------------------------
+
+
+def _process_class(cls):
+    cls_annotations = cls.__dict__.get("__annotations__", {})
+    cls_fields = []
+    for name, type in cls_annotations.items():
+        initial_value = cls.__dict__.get(name, None)
+        if initial_value is not None and isinstance(initial_value, Field):
+            initial_value.setup_annotation(name, type)
+            cls_fields.append(initial_value)
+        else:
+            if not _type_compatibility(type):
+                msg = f"{type} is not supported"
+                raise NonSerializableType(msg)
+
+            field = Field(default=initial_value)
+            field.setup_annotation(name, type)
+            cls_fields.append(field)
+
+    # add class metadata
+    setattr(cls, _FIELDS, {f.name: f for f in cls_fields})
+    for f in cls_fields:
+        f.setup_class(cls)
+
+    # Extract field meta summary
+    server = any(f.mode.has_server_state for f in cls_fields)
+    client = any(f.mode.has_client_state for f in cls_fields)
+    sync = any(f.mode.need_sync for f in cls_fields)
+    valid_keys = {f.name for f in cls_fields}
+
+    # add default getter properties
+    cls._id = property(_m_get_id)
+    cls.server = property(_m_get_server, _m_set_server)
+    if sync:
+        cls.client_state = property(_m_get_client_state)
+
+    # Add default methods
+    for name, fn in _create_methods(
+        cls_fields, server, client, sync, valid_keys
+    ).items():
+        setattr(cls, name, fn)
+    cls.watch = _m_watch
+    cls.Provider = _m_Provider
+
+    # return decorated class
+    return cls
+
+
+# -----------------------------------------------------------------------------
+# Generic encoder/decoder
+# -----------------------------------------------------------------------------
+
+
+def encode_dataclass_item(item):
+    if item is None:
+        return None
+    return item._id
+
+
+def decode_dataclass_item(item):
+    # print("decode_dataclass_item", item)
+    if item is None:
+        return None
+    return get_instance(item)
+
+
+def encode_dataclass_list(items):
+    return [item._id for item in items]
+
+
+def decode_dataclass_list(items):
+    # print("decode_dataclass_list", items)
+    return list(map(get_instance, items))
+
+
+def encode_dataclass_dict(data):
+    return {k: v._id for k, v in data.items()}
+
+
+def decode_dataclass_dict(data):
+    # print("decode_dataclass_dict", data)
+    return {k: get_instance(v) for k, v in data.items()}
+
+
+# -----------------------------------------------------------------------------
+# Public API
+# -----------------------------------------------------------------------------
+__all__ = [
+    "Field",
+    "FieldMode",
+    "get_instance",
+    "is_trame_dataclass",
+    "trame_dataclass",
+]
+
+
+def get_instance(instance_id: str):
+    # print(f"get_instance({instance_id})")
+    # print(" => ", INSTANCES[instance_id])
+    return INSTANCES[instance_id]
+
+
+def trame_dataclass(cls=None, **_):
+    """Annotation for state based dataclass"""
+
+    def wrap(cls):
+        return _process_class(cls)
+
+    if cls is None:
+        return wrap
+
+    return wrap(cls)
+
+
+def is_trame_dataclass(obj):
+    """Returns True if obj is a trame_dataclass or an instance of a
+    trame_dataclass."""
+    cls = (
+        obj
+        if isinstance(obj, type) and not isinstance(obj, types.GenericAlias)
+        else type(obj)
+    )
+    return hasattr(cls, _FIELDS)
+
+
+class FieldMode(Enum):
+    CLIENT_ONLY = (False, False, True)
+    READ_ONLY = (True, False, True)
+    PUSH_ONLY = (False, True, True)
+    SERVER_ONLY = (True, True, False)
+    DEFAULT = (True, True, True)
+
+    def __init__(self, server_get, server_set, client):
+        self._value_ = auto()
+        self._get = server_get
+        self._set = server_set
+        self._client = client
+
+    @property
+    def has_get(self):
+        return self._get or self._set
+
+    @property
+    def has_set(self):
+        return self._set
+
+    @property
+    def has_server_state(self):
+        return self._get or self._set
+
+    @property
+    def has_client_state(self):
+        return self._client
+
+    @property
+    def need_sync(self):
+        return self.has_server_state and self.has_client_state
+
+
+# -----------------------------------------------------------------------------
+
+
+class Field:
+    def __init__(
+        self,
+        mode: FieldMode = FieldMode.DEFAULT,
+        default: Any = None,
+        encoder: Encoder | None = None,
+        decoder: Decoder | None = None,
+    ):
+        self.name = None
+        self.type_annotation = None
+        self.mode = mode
+        self.default = default
+        self.encoder = encoder
+        self.decoder = decoder
+        self.dataclass_container = False
+
+    def setup_annotation(self, name, type_annotation):
+        self.name = name
+        self.type_annotation = type_annotation
+        if self.default is None:
+            self.default = _type_default(type_annotation)
+
+        if _type_is_composite(type_annotation):
+            if hasattr(type_annotation, "__origin__"):
+                # properly typed
+                if type_annotation.__origin__ is list and is_trame_dataclass(
+                    type_annotation.__args__[0]
+                ):
+                    # print("Use custom list[dataclass] encoder/decoder")
+                    assert self.encoder is None, (
+                        "DataClass encoder get managed automatically. Should not override an existing one!"
+                    )
+                    self.encoder = encode_dataclass_list
+                    self.decoder = decode_dataclass_list
+                    self.dataclass_container = True
+                elif type_annotation.__origin__ is dict and is_trame_dataclass(
+                    type_annotation.__args__[1]
+                ):
+                    assert type_annotation.__args__[0] is str, (
+                        "Dict with dataclass must use str as key"
+                    )
+                    assert self.encoder is None, (
+                        "DataClass encoder get managed automatically. Should not override an existing one!"
+                    )
+                    # print("Use custom dict[str, dataclass] encoder/decoder")
+                    self.encoder = encode_dataclass_dict
+                    self.decoder = decode_dataclass_dict
+                    self.dataclass_container = True
+        elif _type_is_dataclass(type_annotation):
+            assert self.encoder is None, (
+                "DataClass encoder get managed automatically. Should not override an existing one!"
+            )
+            self.encoder = encode_dataclass_item
+            self.decoder = decode_dataclass_item
+            self.dataclass_container = True
+
+    def setup_class(self, cls):
+        """Patch class with methods to add"""
+        name = self.name
+
+        def _set(self, value):
+            if name in self._server_state and self._server_state[name] == value:
+                return
+
+            self._dirty_set.add(name)
+            self._server_state[name] = value
+            self._on_dirty()
+
+        def _get(self):
+            return self._server_state[name]
+
+        if self.mode.has_get and self.mode.has_set:
+            setattr(cls, name, property(_get, _set))
+        elif self.mode.has_get:
+            setattr(cls, name, property(_get))
+
+    def setup_instance(self, obj):
+        # Assign value
+        value = self.default() if callable(self.default) else self.default
+        if self.mode.has_set:
+            setattr(obj, self.name, value)
+        elif self.mode.has_client_state:
+            obj._client_state[self.name] = value

trame_dataclass-1.0.0/src/trame_dataclass/module/__init__.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+# Compute local path to serve
+serve_path = str(Path(__file__).with_name("serve").resolve())
+
+# Serve directory for JS/CSS files
+serve = {"__trame_dataclass": serve_path}
+
+# List of JS files to load (usually from the serve path above)
+scripts = ["__trame_dataclass/trame_dataclass.umd.js"]
+
+# List of CSS files to load (usually from the serve path above)
+if (Path(serve_path) / "style.css").exists():
+    styles = ["__trame_dataclass/style.css"]
+
+# List of Vue plugins to install/load
+vue_use = ["trame_dataclass"]
+
+
+# Optional if you want to execute custom initialization at module load
+def setup(server, **_):
+    """Method called at initialization with possibly some custom keyword arguments"""
+    server.add_protocol_to_configure(configure_protocol)
+
+
+def configure_protocol(protocol):
+    from trame_dataclass.module.protocol import TrameDataclassProtocol
+
+    protocol.registerLinkProtocol(TrameDataclassProtocol())

trame_dataclass-1.0.0/src/trame_dataclass/module/protocol.py

@@ -0,0 +1,94 @@
+from wslink import register as export_rpc
+from wslink.websocket import LinkProtocol
+
+from trame_dataclass.core import get_instance, is_trame_dataclass
+
+
+def compute_definition(trame_dataclass_class):
+    return {
+        "name": trame_dataclass_class.__name__,
+        "dataclass_containers": [
+            f.name
+            for f in trame_dataclass_class.__trame_dataclass_fields__.values()
+            if f.dataclass_container
+        ],
+    }
+
+
+class TrameDataclassProtocol(LinkProtocol):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        self.class_definitions = {}
+        self.next_class_definition_id = 1
+
+    @export_rpc("trame.dataclass.register")
+    def register_instance(self, trame_dataclass):
+        if is_trame_dataclass(trame_dataclass):
+            self.register_definition(trame_dataclass.__class__)
+            trame_dataclass.register_flush_implementation(self.push_delta)
+
+    def register_definition(self, trame_dataclass_class):
+        if not is_trame_dataclass(trame_dataclass_class):
+            return None
+
+        if trame_dataclass_class in self.class_definitions:
+            return self.class_definitions[trame_dataclass_class]
+
+        definition_id = self.next_class_definition_id
+        self.next_class_definition_id += 1
+
+        definition = {
+            "id": definition_id,
+            **compute_definition(trame_dataclass_class),
+        }
+        self.class_definitions[trame_dataclass_class] = definition
+
+        return definition
+
+    @export_rpc("trame.dataclass.definition.get")
+    def get_definition(self, class_id):
+        for definition in self.class_definitions.values():
+            if definition["id"] == class_id:
+                return definition
+        return None
+
+    @export_rpc("trame.dataclass.state.get")
+    def get_state(self, instance_id):
+        """
+        {
+            id: instance_id,
+            definition: class_id,
+            state: {},
+        }
+        """
+        obj = get_instance(instance_id)
+        if obj is None:
+            return {
+                "id": instance_id,
+                "state": None,
+            }
+
+        return {
+            "id": instance_id,
+            "definition": self.class_definitions[obj.__class__]["id"],
+            "state": obj.client_state,
+        }
+
+    @export_rpc("trame.dataclass.state.update")
+    def update_state(self, msg):
+        # print("update_state", msg)
+        for dc_id, state in msg.items():
+            obj = get_instance(dc_id)
+            fields = obj.__class__.__trame_dataclass_fields__
+            if obj is not None:
+                for k, v in state.items():
+                    field = fields.get(k)
+                    if field.decoder:
+                        setattr(obj, k, field.decoder(v))
+                    else:
+                        setattr(obj, k, v)
+
+    def push_delta(self, msg):
+        # print("publish", msg)
+        self.publish("trame.dataclass.publish", msg)

trame_dataclass-1.0.0/src/trame_dataclass/module/serve/trame_dataclass.umd.js

@@ -0,0 +1 @@
+(function(r,c){typeof exports=="object"&&typeof module<"u"?c(exports,require("vue")):typeof define=="function"&&define.amd?define(["exports","vue"],c):(r=typeof globalThis<"u"?globalThis:r||self,c(r.trame_dataclass={},r.Vue))})(this,function(r,c){"use strict";function f(h,t,e){if(e.data._id!==h){e.data._id=h;const s=Object.keys(e.data);for(let i of s)delete e.data[i]}Object.assign(e.data,t.refs)}class d{constructor(){this.client=null,this.subscription=null,this.dataStates={},this.dataTypes={},this.typeDefinitions={},this.vueComponents={},this.internalReactiveObjects={},this.dataToVue={},this.pendingClientServerQueue=[],this.pendingFlushRequest=0}connect(t){this.client||!t||(this.client=t,this.subscription=t.getConnection().getSession().subscribe("trame.dataclass.publish",async([e])=>{const{id:s,state:i}=e;Object.assign(this.dataStates[s].server,i);for(const[n,a]of Object.entries(i))this.isDataClass(s,n)?await this.handleNestedDataClass(s,n,a):this.dataStates[s].refs[n].value=a}))}updateServer(t,e,s){this.pendingClientServerQueue.push([t,e,s]),this.flushToServer()}async flushToServer(){if(this.pendingFlushRequest)return;this.pendingFlushRequest++;const t={};let e=0;for(;this.pendingClientServerQueue.length;){const[s,i,n]=this.pendingClientServerQueue.shift();let a=n;if(n!==null&&this.isDataClass(s,i))if(Array.isArray(n))a=n.map(o=>o._id);else if(n._id)a=n._id;else{a={};for(const[o,v]in Object.entries(n))a[o]=v._id}JSON.stringify(this.dataStates[s].server[i])!==JSON.stringify(a)&&(t[s]||(t[s]={}),t[s][i]=a,e++)}if(e)try{await this.client.getConnection().getSession().call("trame.dataclass.state.update",[t])}catch(s){console.error("Network error when pushing client state",s)}this.pendingFlushRequest--,this.pendingClientServerQueue.length&&this.flushToServer()}isDataClass(t,e){return this.typeDefinitions[this.dataTypes[t]].dataclass_containers.includes(e)}async handleNestedDataClass(t,e,s){if(s===null)this.dataStates[t].refs[e].value=null;else if(Array.isArray(s)){const i=[];for(let n=0;n<s.length;n++){const a=s[n];let o=!1;this.internalReactiveObjects[a]||(this.internalReactiveObjects[a]=c.reactive({}),o=!0),i.push(this.internalReactiveObjects[a]),this.dataStates[a]||(o=!1,await this.fetchState(a)),o&&Object.assign(this.internalReactiveObjects[a],this.dataStates[a].refs)}this.dataStates[t].refs[e].value=i}else if(typeof s=="string"){const i=s;this.internalReactiveObjects[i]||(this.internalReactiveObjects[i]=c.reactive({})),this.dataStates[i]?Object.assign(this.internalReactiveObjects[i],this.dataStates[i].refs):await this.fetchState(i)}else{const i=c.reactive({});for(const[n,a]of Object.entries(s))this.internalReactiveObjects[a]||(this.internalReactiveObjects[a]=c.reactive({})),i[n]=this.internalReactiveObjects[a],this.dataStates[a]?Object.assign(this.internalReactiveObjects[a],this.dataStates[a].refs):await this.fetchState(a);this.dataStates[t].refs[e].value=i}}async fetchState(t){const e={_id:t},s=await this.client.getConnection().getSession().call("trame.dataclass.state.get",[t]);this.dataTypes[t]=s.definition,this.dataStates[t]={refs:e,server:s.state},this.typeDefinitions[s.definition]||await this.fetchDefinition(s.definition);for(const[i,n]of Object.entries(s.state))this.isDataClass(t,i)?(e[i]=c.ref(null),await this.handleNestedDataClass(t,i,n)):e[i]=c.ref(n),c.watch(()=>e[i].value,a=>this.updateServer(t,i,a));return this.dataToVue[t]&&this.dataToVue[t].forEach(i=>{f(t,this.dataStates[t],this.vueComponents[i])}),this.internalReactiveObjects[t]&&Object.assign(this.internalReactiveObjects[t],this.dataStates[t].refs),this.dataStates[t]}async fetchDefinition(t){const e=await this.client.getConnection().getSession().call("trame.dataclass.definition.get",[t]);this.typeDefinitions[t]=e}unlink(t,e){this.dataToVue[t]&&(this.dataToVue[t]=this.dataToVue[t].filter(s=>s!==e))}link(t,e){this.dataToVue[t]?this.dataToVue[t].push(e):this.dataToVue[t]=[e],this.dataStates[t]?f(t,this.dataStates[t],this.vueComponents[e]):this.fetchState(t)}connectVueComponent(t,e){var n;const s=(n=this.vueComponents[t])==null?void 0:n.id,i=e.id;this.unlink(s,t),this.vueComponents[t]=e,this.link(i,t)}disconnectVueComponent(t){var s;const e=(s=this.vueComponents[t])==null?void 0:s.id;delete this.vueComponents[t],this.unlink(e,t)}}const l=new d;let p=1;const u={TrameDataclass:{props:["instance"],setup(h){const t=c.inject("trame"),e=c.reactive({}),s={serverPush:!1},i=`vueDataClass${p++}`;return l.connect(t.client),c.watchEffect(()=>{l.connectVueComponent(i,{id:h.instance,data:e,guards:s})}),c.onBeforeUnmount(()=>{l.disconnectVueComponent(i)}),{data:e}},template:'<slot :dataclass="data"></slot>'}};function S(h){Object.keys(u).forEach(t=>{h.component(t,u[t])})}r.install=S,Object.defineProperty(r,Symbol.toStringTag,{value:"Module"})});

trame_dataclass-1.0.0/src/trame_dataclass/widgets/dataclass.py

@@ -0,0 +1,26 @@
+from trame_client.widgets.core import AbstractElement
+
+from .. import module
+
+
+class HtmlElement(AbstractElement):
+    def __init__(self, _elem_name, children=None, **kwargs):
+        super().__init__(_elem_name, children, **kwargs)
+        if self.server:
+            self.server.enable_module(module)
+
+
+__all__ = [
+    "Provider",
+]
+
+
+# Expose your vue component(s)
+class Provider(HtmlElement):
+    def __init__(self, name, **kwargs):
+        super().__init__(
+            "trame-dataclass",
+            **kwargs,
+        )
+        self._attr_names += ["instance"]
+        self._attributes["slot"] = f'v-slot="{{ dataclass: {name} }}"'