nova-trame 0.8.0__py3-none-any.whl

nova/trame/__init__.py

@@ -0,0 +1,3 @@
+from .view.theme import ThemedApp
+
+__all__ = ["ThemedApp"]

nova/trame/model/remote_file_input.py

@@ -0,0 +1,98 @@
+"""Model state for RemoteFileInput."""
+
+import os
+from typing import Any, Union
+
+
+class RemoteFileInputModel:
+    """Manages interactions between RemoteFileInput and the file system."""
+
+    def __init__(self, allow_files: bool, allow_folders: bool, base_paths: list[str], extensions: list[str]) -> None:
+        """Creates a new RemoteFileInputModel."""
+        self.allow_files = allow_files
+        self.allow_folders = allow_folders
+        self.base_paths = base_paths
+        self.extensions = extensions
+
+    def get_base_paths(self) -> list[dict[str, Any]]:
+        return [{"path": base_path, "directory": True} for base_path in self.base_paths]
+
+    def scan_current_path(self, current_path: str, showing_all_files: bool) -> tuple[list[dict[str, Any]], bool]:
+        failed = False
+
+        try:
+            if current_path and (not self.valid_subpath(current_path) or not os.path.exists(current_path)):
+                raise FileNotFoundError
+
+            files = [{"path": "..", "directory": True}]
+
+            if os.path.isdir(current_path):
+                scan_path = current_path
+            else:
+                scan_path = os.path.dirname(current_path)
+
+            for entry in os.scandir(scan_path):
+                if self.valid_entry(entry, showing_all_files):
+                    files.append({"path": entry.name, "directory": entry.is_dir()})
+        except OSError:
+            files = self.get_base_paths()
+            failed = True
+
+        sorted_files = sorted(files, key=lambda entry: str(entry["path"]).lower())
+
+        return (sorted_files, failed)
+
+    def select_file(self, file: Union[dict[str, str], str], old_path: str, showing_base_paths: bool) -> str:
+        if file == "":
+            return ""
+
+        if isinstance(file, dict):
+            file = file["path"]
+
+        if not os.path.isdir(old_path):
+            # If the previous selection is a file, then we need to append to its parent directory
+            old_path = os.path.dirname(old_path)
+
+        if not showing_base_paths and file != "..":
+            return os.path.join(old_path, file)
+        elif not showing_base_paths:
+            if old_path in self.base_paths:
+                return ""
+            else:
+                return os.path.dirname(old_path)
+        else:
+            return file
+
+    def valid_entry(self, entry: os.DirEntry, showing_all_files: bool) -> bool:
+        if entry.is_dir():
+            return True
+
+        if not self.allow_files:
+            return False
+
+        return showing_all_files or not self.extensions or any(entry.name.endswith(ext) for ext in self.extensions)
+
+    def valid_selection(self, selection: str) -> bool:
+        if self.valid_subpath(selection):
+            if os.path.isdir(selection) and self.allow_folders:
+                return True
+
+            if os.path.isfile(selection) and self.allow_files:
+                return True
+
+        return False
+
+    def valid_subpath(self, subpath: str) -> bool:
+        if subpath == "":
+            return False
+
+        try:
+            real_path = os.path.realpath(subpath)
+        except TypeError:
+            return False
+
+        for base_path in self.base_paths:
+            if real_path.startswith(base_path):
+                return True
+
+        return False

nova/trame/view/components/__init__.py

@@ -0,0 +1,4 @@
+from .input_field import InputField
+from .remote_file_input import RemoteFileInput
+
+__all__ = ["InputField", "RemoteFileInput"]

nova/trame/view/components/input_field.py

@@ -0,0 +1,273 @@
+"""View Implementation for InputField."""
+
+import logging
+import re
+from typing import Any, Dict
+
+from mvvm_lib.pydantic_utils import get_field_info
+from trame.app import get_server
+from trame.widgets import client
+from trame.widgets import vuetify3 as vuetify
+from trame_client.widgets.core import AbstractElement
+from trame_server.controller import Controller
+from trame_server.state import State
+
+logger = logging.getLogger(__name__)
+
+
+class InputField:
+    """Factory class for generating Vuetify input components."""
+
+    @staticmethod
+    def create_boilerplate_properties(v_model: str | None) -> dict:
+        if not v_model:
+            return {}
+        object_name_in_state = v_model.split(".")[0]
+        field_info = None
+        try:
+            field_name = ".".join(v_model.split(".")[1:])
+            if "[" in field_name:
+                index_field_name = re.sub(r"\[.*?\]", "[0]", field_name)
+                field_info = get_field_info(index_field_name)
+                if "[" in field_name and "[index]" not in field_name:
+                    field_info = None
+                    logger.warning(
+                        f"{v_model}: validation ignored. We currently only "
+                        f"support single loop with index variable that should be called 'index'"
+                    )
+            else:
+                field_info = get_field_info(field_name)
+        except Exception as _:
+            pass
+        label = ""
+        help_dict: dict = {}
+        placeholder = None
+        if field_info:
+            label = field_info.title
+            if field_info.examples and len(field_info.examples) > 0:
+                placeholder = field_info.examples[0]
+            help_dict = {"hint": field_info.description, "placeholder": placeholder}
+
+        args: Dict[str, Any] = {}
+        if v_model:
+            args |= {
+                "v_model": v_model,
+                "label": label,
+                "help": help_dict,
+                "update_modelValue": f"flushState('{object_name_in_state}')",
+            }
+            if field_info:
+                args |= {
+                    "rules": (f"[(v) => trigger('validate_pydantic_field', ['{field_name}', v, index])]",),
+                }
+        return args
+
+    def __new__(
+        cls, v_model: str | None = None, required: bool = False, type: str = "text", **kwargs: Any
+    ) -> AbstractElement:
+        """Constructor for InputField.
+
+        Parameters
+        ----------
+        required : bool
+            If true, the input will be visually marked as required and a required rule will be added to the end of the
+            rules list.
+        type : str
+            The type of input to create. This can be any of the following:
+
+            - autocomplete
+            - autoscroll (produces a textarea that automatically scrolls to the bottom as new content is added)
+            - checkbox
+            - combobox
+            - file
+            - input
+            - otp
+            - radio
+            - range-slider
+            - select
+            - slider
+            - switch
+            - textarea
+
+            Any other value will produce a text field with your type used as an HTML input type attribute.
+
+        Returns
+        -------
+        `trame_client.widgets.core.AbstractElement <https://trame.readthedocs.io/en/latest/core.widget.html#trame_client.widgets.core.AbstractElement>`_
+            The Vuetify input component.
+        """
+        server = get_server(None, client_type="vue3")
+
+        kwargs = {**cls.create_boilerplate_properties(v_model), **kwargs}
+
+        if "__events" not in kwargs or kwargs["__events"] is None:
+            kwargs["__events"] = []
+
+        # This must be present before each input is created or change events won't be triggered.
+        if isinstance(kwargs["__events"], list):
+            if "change" not in kwargs["__events"]:
+                kwargs["__events"].append("change")
+            if "scroll" not in kwargs["__events"]:
+                kwargs["__events"].append("scroll")
+
+        match type:
+            case "autocomplete":
+                input = vuetify.VAutocomplete(**kwargs)
+            case "autoscroll":
+                input = vuetify.VTextarea(**kwargs)
+                cls._setup_autoscroll(server.state, input)
+            case "checkbox":
+                input = vuetify.VCheckbox(**kwargs)
+            case "combobox":
+                input = vuetify.VCombobox(**kwargs)
+            case "file":
+                input = vuetify.VFileInput(**kwargs)
+            case "input":
+                input = vuetify.VInput(**kwargs)
+            case "otp":
+                input = vuetify.VOtpInput(**kwargs)
+            case "radio":
+                input = vuetify.VRadioGroup(**kwargs)
+            case "range-slider":
+                input = vuetify.VRangeSlider(**kwargs)
+            case "select":
+                items = kwargs.pop("items", None)
+                if isinstance(items, str):
+                    items = (items,)
+
+                input = vuetify.VSelect(items=items, **kwargs)
+            case "slider":
+                input = vuetify.VSlider(**kwargs)
+            case "switch":
+                input = vuetify.VSwitch(**kwargs)
+            case "textarea":
+                input = vuetify.VTextarea(**kwargs)
+            case _:
+                input = vuetify.VTextField(type=type, **kwargs)
+
+        cls._setup_help(input, **kwargs)
+
+        cls._check_rules(input)
+        if required:
+            cls._setup_required_label(input)
+            cls._setup_required_rule(input)
+
+        cls._setup_ref(input)
+        cls._setup_change_listener(server.controller, input)
+
+        return input
+
+    @staticmethod
+    def _check_rules(input: AbstractElement) -> None:
+        if "rules" in input._py_attr and input.rules and not isinstance(input.rules, tuple):
+            raise ValueError(f"Rules for '{input.label}' must be a tuple")
+
+    @staticmethod
+    def _setup_autoscroll(state: State, input: AbstractElement) -> None:
+        if input.v_model:
+            if "id" not in input._py_attr or input.id is None:
+                input.id = f"nova__{input._id}"
+                input.scroll = f"window.nova__autoscroll('{input.id}');"
+
+            with state:
+                if state["nova_scroll_position"] is None:
+                    state["nova_scroll_position"] = {}
+                state.nova_scroll_position[input.id] = 0
+
+            autoscroll = client.JSEval(
+                exec=(
+                    "if (window.nova__autoscroll !== undefined) {"
+                    # If the autoscroll function already exists, call it.
+                    "  window.nova__autoscroll($event);"
+                    "} else {"
+                    # Save the JS so it can be called from outside of this script (ie during a scroll event).
+                    "  window.nova__autoscroll = function(id) {"
+                    # Get the element in the browser by ID
+                    "    const element = window.document.querySelector(`#${id}`);"
+                    # If the user is at the bottom of the textarea, then we should autoscroll.
+                    "    if (element.scrollTop === window.trame.state.state.nova_scroll_position[id]) {"
+                    # Scroll to the bottom
+                    "      element.scrollTop = element.scrollHeight;"
+                    # Save the new scroll position
+                    "      window.trame.state.state.nova_scroll_position[id] = element.scrollTop;"
+                    "      flushState('nova_scroll_position');"
+                    # If the user has scrolled back to the bottom, then we should reenable scrolling.
+                    "    } else if (element.scrollTop === element.scrollHeight - element.clientHeight) {"
+                    # Save the new scroll position
+                    "      window.trame.state.state.nova_scroll_position[id] = element.scrollTop;"
+                    "      flushState('nova_scroll_position');"
+                    "    }"
+                    "  };"
+                    "  window.nova__autoscroll($event);"
+                    "}"
+                )
+            ).exec
+
+            @state.change(input.v_model)
+            def _autoscroll(**kwargs: Any) -> None:
+                autoscroll(input.id)
+
+    @staticmethod
+    def _setup_help(_input: AbstractElement, **kwargs: Any) -> None:
+        help = kwargs.get("help", None)
+        if help and isinstance(help, dict):
+            _input.hint = help.get("hint", None)
+            _input.placeholder = help.get("placeholder", None)
+
+    @staticmethod
+    def _setup_required_label(input: AbstractElement) -> None:
+        if input.label:
+            input.label = f"{input.label}*"
+        else:
+            input.label = "*"
+
+    @staticmethod
+    def _setup_ref(input: AbstractElement) -> None:
+        if "ref" not in input._py_attr or input.ref is None:
+            input.ref = f"nova__{input._id}"
+
+    @staticmethod
+    def _setup_required_rule(input: AbstractElement) -> None:
+        required_rule = "(value) => value?.length > 0 || 'Field is required'"
+        if "rules" in input._py_attr and input.rules:
+            # Existing rules will be in format ("[rule1, rule2]",) and we need to append to this list
+            rule_end_index = input.rules[0].rindex("]")
+            input.rules = (f"{input.rules[0][:rule_end_index]}, {required_rule}{input.rules[0][rule_end_index:]}",)
+        else:
+            input.rules = (f"[{required_rule}]",)
+
+    @staticmethod
+    def _setup_change_listener(ctrl: Controller, input: AbstractElement) -> None:
+        base_handler = None
+        if "change" in input._py_attr and input.change is not None:
+            base_handler = input.change
+
+        # Iterate over all saved refs and perform validation if there is a value that can be validated.
+        change_handler = (
+            "Object.values(window.trame.refs).map("
+            "  (ref) => typeof ref.validate === 'function' && ref.value ? ref.validate() : null"
+            ");"
+        )
+
+        # We need to coerce the developer's change handler, which could be a string, callable, or tuple containing a
+        # callable, to a single string to be compatible with our change handler.
+        if callable(base_handler):
+            base_handler = (base_handler,)
+        if isinstance(base_handler, tuple):
+
+            @ctrl.trigger(f"{input.ref}__trigger")
+            def _(*args: str, **kwargs: Any) -> None:
+                base_handler[0](*args, **kwargs)
+
+            change_handler = (
+                "trigger("
+                f"'{input.ref}__trigger', "
+                f"{base_handler[1] if len(base_handler) > 1 else []}, "
+                f"{base_handler[2] if len(base_handler) > 2 else {} }"
+                f"); {change_handler}"
+            )  # Call the developer's provided change method via a trigger, then call ours.
+        elif isinstance(base_handler, str):
+            # Call the developer's provided change JS expression, then call ours.
+            change_handler = f"{base_handler}; {change_handler}"
+
+        input.change = change_handler

nova/trame/view/components/remote_file_input.py

@@ -0,0 +1,193 @@
+"""View implementation for RemoteFileInput."""
+
+from functools import partial
+from typing import Any, Optional, cast
+
+from mvvm_lib.trame_binding import TrameBinding
+from trame.app import get_server
+from trame.widgets import client, html
+from trame.widgets import vuetify3 as vuetify
+from trame_client.widgets.core import AbstractElement
+
+from nova.trame.model.remote_file_input import RemoteFileInputModel
+from nova.trame.view.components import InputField
+from nova.trame.view_model.remote_file_input import RemoteFileInputViewModel
+
+
+class RemoteFileInput:
+    """Generates a file selection dialog for picking files off of the server.
+
+    You cannot use typical Trame :code:`with` syntax to add children to this.
+    """
+
+    def __init__(
+        self,
+        v_model: Optional[str] = None,
+        allow_files: bool = True,
+        allow_folders: bool = False,
+        allow_nonexistent_path: bool = False,
+        base_paths: Optional[list[str]] = None,
+        dialog_props: Optional[dict[str, Any]] = None,
+        extensions: Optional[list[str]] = None,
+        input_props: Optional[dict[str, Any]] = None,
+        label: str = "",
+    ) -> None:
+        """Constructor for RemoteFileInput.
+
+        Parameters
+        ----------
+        v_model : str
+            The v-model for the input field.
+        allow_files : bool
+            If true, the user can save a file selection.
+        allow_folders : bool
+            If true, the user can save a folder selection.
+        allow_nonexistent_path : bool
+            If false, the user will be warned when they've selected a non-existent path on the filesystem.
+        base_paths : list[str], optional
+            Only files under these paths will be shown.
+        dialog_props : dict[str, typing.Any], optional
+            Props to be passed to VDialog.
+        extensions : list[str], optional
+            Only files with these extensions will be shown by default. The user can still choose to view all files.
+        input_props : dict[str, typing.Any], optional
+            Props to be passed to InputField. Must not include label prop, use the top-level label parameter instead.
+        label : str
+            Label shown in the input field and the dialog title.
+
+        Raises
+        ------
+        ValueError
+            If v_model is None.
+
+        Returns
+        -------
+        None
+        """
+        if v_model is None:
+            raise ValueError("RemoteFileInput must have a v_model attribute.")
+
+        self.v_model = v_model
+        self.allow_files = allow_files
+        self.allow_folders = allow_folders
+        self.allow_nonexistent_path = allow_nonexistent_path
+        self.base_paths = base_paths if base_paths else ["/"]
+        self.dialog_props = dict(dialog_props) if dialog_props else {}
+        self.extensions = extensions if extensions else []
+        self.input_props = dict(input_props) if input_props else {}
+        self.label = label
+
+        if "__events" not in self.input_props:
+            self.input_props["__events"] = []
+        self.input_props["__events"].append("change")
+
+        if "width" not in self.dialog_props:
+            self.dialog_props["width"] = 600
+
+        self.create_model()
+        self.create_viewmodel()
+        self.create_ui()
+
+    def create_ui(self) -> None:
+        with cast(
+            AbstractElement,
+            InputField(
+                v_model=self.v_model,
+                label=self.label,
+                change=(self.vm.select_file, "[$event.target.value]"),
+                **self.input_props,
+            ),
+        ):
+            self.vm.init_view()
+
+            with vuetify.Template(v_slot_append=True):
+                with vuetify.VBtn(icon=True, size="small", click=self.vm.open_dialog):
+                    vuetify.VIcon("mdi-folder-open")
+
+                    with vuetify.VDialog(
+                        v_model=self.vm.get_dialog_state_name(),
+                        activator="parent",
+                        persistent=True,
+                        **self.dialog_props,
+                    ):
+                        with vuetify.VCard(classes="pa-4"):
+                            vuetify.VCardTitle(self.label)
+                            vuetify.VTextField(
+                                v_model=self.v_model,
+                                classes="mb-4 px-4",
+                                label="Current Selection",
+                                __events=["change"],
+                                change=(self.vm.select_file, "[$event.target.value]"),
+                            )
+
+                            if self.allow_files and self.extensions:
+                                with html.Div(v_if=(f"{self.vm.get_showing_all_state_name()}",)):
+                                    vuetify.VListSubheader("All Available Files")
+                                    vuetify.VBtn(
+                                        "Don't show all",
+                                        classes="mb-4",
+                                        size="small",
+                                        click=self.vm.toggle_showing_all_files,
+                                    )
+                                with html.Div(v_else=True):
+                                    vuetify.VListSubheader(
+                                        f"Available Files with Extensions: {', '.join(self.extensions)}"
+                                    )
+                                    vuetify.VBtn(
+                                        "Show all",
+                                        classes="mb-4",
+                                        size="small",
+                                        click=self.vm.toggle_showing_all_files,
+                                    )
+                            elif self.allow_files:
+                                vuetify.VListSubheader("Available Files")
+                            else:
+                                vuetify.VListSubheader("Available Folders")
+
+                            with vuetify.VList(classes="mb-4"):
+                                self.vm.populate_file_list()
+
+                                vuetify.VListItem(
+                                    "{{ file.path }}",
+                                    v_for=f"file, index in {self.vm.get_file_list_state_name()}",
+                                    classes=(
+                                        f"index < {self.vm.get_file_list_state_name()}.length - 1 "
+                                        "? 'border-b-thin' "
+                                        ": ''",
+                                    ),
+                                    prepend_icon=("file.directory ? 'mdi-folder' : 'mdi-file'",),
+                                    click=(self.vm.select_file, "[file]"),
+                                )
+
+                            with html.Div(classes="text-center"):
+                                vuetify.VBtn(
+                                    "OK",
+                                    classes="mr-4",
+                                    disabled=(f"!{self.vm.get_valid_selection_state_name()}",),
+                                    click=self.vm.close_dialog,
+                                )
+                                vuetify.VBtn(
+                                    "Cancel",
+                                    color="lightgrey",
+                                    click=partial(self.vm.close_dialog, cancel=True),
+                                )
+
+    def create_model(self) -> None:
+        self.model = RemoteFileInputModel(self.allow_files, self.allow_folders, self.base_paths, self.extensions)
+
+    def create_viewmodel(self) -> None:
+        server = get_server(None, client_type="vue3")
+        binding = TrameBinding(server.state)
+
+        self.vm = RemoteFileInputViewModel(self.model, binding)
+
+        self.vm.dialog_bind.connect(self.vm.get_dialog_state_name())
+        self.vm.file_list_bind.connect(self.vm.get_file_list_state_name())
+        self.vm.on_close_bind.connect(client.JSEval(exec=f"{self.vm.get_dialog_state_name()} = false;").exec)
+        self.vm.on_update_bind.connect(
+            client.JSEval(
+                exec=f"{self.v_model} = $event; flushState('{self.v_model.split('.')[0].split('[')[0]}');"
+            ).exec
+        )
+        self.vm.showing_all_bind.connect(self.vm.get_showing_all_state_name())
+        self.vm.valid_selection_bind.connect(self.vm.get_valid_selection_state_name())

nova/trame/view/components/visualization/__init__.py

@@ -0,0 +1,3 @@
+from .interactive_2d_plot import Interactive2DPlot
+
+__all__ = ["Interactive2DPlot"]

nova/trame/view/components/visualization/interactive_2d_plot.py

@@ -0,0 +1,85 @@
+"""View implementation for Interactive2DPlot."""
+
+from typing import Any, Optional
+
+from altair import Chart
+from trame.widgets import client, vega
+
+
+class Interactive2DPlot(vega.Figure):
+    """Creates an interactive 2D plot in Trame using Vega.
+
+    Trame provides two primary mechanisms for composing 2D plots: `Plotly <https://github.com/Kitware/trame-plotly>`_
+    and `Vega-Lite/Altair <https://github.com/Kitware/trame-vega>`_. If you only need static plots or basic browser
+    event handling, then please use these libraries directly.
+
+    If you need to capture complex front-end interactions, then you can
+    use our provided Interactive2DPlot widget that is based on Vega-Lite. This uses the same API as Trame's vega.Figure,
+    except that it will automatically sync Vega's signal states as the user interacts with the plot.
+
+    The following allows the user to select a region of the plot and tracks the selected region in Python:
+
+    .. literalinclude:: ../tests/test_interactive_2d_plot.py
+        :start-after: setup 2d plot
+        :end-before: setup 2d plot complete
+        :dedent:
+    """
+
+    def __init__(self, figure: Optional[Chart] = None, **kwargs: Any) -> None:
+        """Constructor for Interactive2DPlot.
+
+        Parameters
+        ----------
+        figure : `altair.Chart <https://altair-viz.github.io/user_guide/generated/toplevel/altair.Chart.html#altair.Chart>`_
+            Altair chart object
+        kwargs
+            Arguments to be passed to `AbstractElement <https://trame.readthedocs.io/en/latest/core.widget.html#trame_client.widgets.core.AbstractElement>`_
+
+        Returns
+        -------
+        None
+        """
+        self._initialized = False
+
+        super().__init__(figure=figure, **kwargs)
+        self.ref = f"nova__vega_{self._id}"
+        self.server.state[self.ref] = {}
+        self._start_update_handlers = client.JSEval(
+            exec=(
+                "async () => {"
+                f" let ref = window.trame.refs['{self.ref}'];"
+                "  await ref.mountVis();"  # wait for the new  visualization to be rendered in the front-end
+                "  if (ref.viz === undefined) { return; }"  # If the component is not mounted, do nothing
+                "  for (const [key, value] of Object.entries(ref.viz.view._signals)) {"
+                "    if (key === 'unit') { continue; }"  # this causes a JSError for some reason if not skipped
+                "    ref.viz.view.addSignalListener(key, (name, value) => {"
+                f"     window.trame.state.state['{self.ref}'][name] = value;"  # sync front-end state
+                f"     flushState('{self.ref}');"  # sync back-end state
+                "    })"
+                "  }"
+                "}"
+            )
+        ).exec
+
+        client.ClientTriggers(mounted=self.update)
+
+    def get_signal_state(self, name: str) -> Any:
+        """Retrieves a Vega signal's state by name.
+
+        Parameters
+        ----------
+        name : str
+            The name of the signal to retrieve.
+
+        Returns
+        -------
+        typing.Any
+            The current value of the Vega signal.
+        """
+        return self.server.state[self.ref].get(name, None)
+
+    def update(self, figure: Optional[Chart] = None, **kwargs: Any) -> None:
+        super().update(figure=figure, **kwargs)
+
+        if hasattr(self, "_start_update_handlers"):
+            self._start_update_handlers()

nova/trame/view/layouts/__init__.py

@@ -0,0 +1,5 @@
+from .grid import GridLayout
+from .hbox import HBoxLayout
+from .vbox import VBoxLayout
+
+__all__ = ["GridLayout", "HBoxLayout", "VBoxLayout"]