composeui 0.1.0__py3-none-any.whl

composeui/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from composeui.core.application import LOGGER
+from composeui.core.signal import LOGGER as SIGNAL_LOGGER
+
+__all__ = ["LOGGER", "SIGNAL_LOGGER", "__version__"]
+
+#: the version of the installed package, from its tag (setuptools-scm)
+__version__ = version("composeui")

composeui/core/application.py

@@ -0,0 +1,368 @@
+"""The app: it builds the main view, wires its signals and runs it on a backend (`run`)."""
+
+from __future__ import annotations
+
+import argparse
+import functools
+import importlib
+import importlib.util
+import inspect
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Generic, Protocol, TypeVar, cast
+
+from typing_extensions import TypedDict, TypeVarTuple, Unpack, overload, override
+
+from composeui.core.registry import RendererType
+from composeui.core.signal import LOGGER as SIGNAL_LOGGER
+from composeui.core.signal import Signal
+from composeui.core.study import open_study
+from composeui.core.view import set_references
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from composeui.core.model import Model
+    from composeui.core.signal import _BoundCallback, _MainViewCallback, _ModelCallback
+    from composeui.core.view import MainView, View
+
+__all__ = ["Application", "ModelApplication", "run"]
+
+
+LOGGER = logging.getLogger("COMPOSEUI")
+_STREAM_HANDLER = logging.StreamHandler(sys.stdout)
+_STREAM_HANDLER.setFormatter(logging.Formatter("%(asctime)s: %(message)s", "%Y-%m-%d %H:%M:%S"))
+LOGGER.addHandler(_STREAM_HANDLER)
+
+# T = TypeVar("T", bound=MainView)
+Ts = TypeVarTuple("Ts")
+
+_ViewT_contra = TypeVar("_ViewT_contra", contravariant=True)
+_MainViewT_contra = TypeVar("_MainViewT_contra", contravariant=True)
+_ModelT_contra = TypeVar("_ModelT_contra", contravariant=True)
+ViewT = TypeVar("ViewT", bound="View")
+MainViewT = TypeVar("MainViewT", bound="MainView")
+ModelT = TypeVar("ModelT", bound="Model")
+
+
+_ViewTD = TypeVar("_ViewTD")
+_MainViewTD = TypeVar("_MainViewTD")
+_ModelTD = TypeVar("_ModelTD")
+_TsD = TypeVarTuple("_TsD")
+
+
+class AvailableBounds(TypedDict, Generic[_ViewT_contra, _MainViewT_contra]):
+    """The arguments `Application.connect` can give a callback by name."""
+
+    view: _ViewT_contra
+    main_view: _MainViewT_contra
+
+
+class AvailableModelBounds(TypedDict, Generic[_ViewT_contra, _MainViewT_contra, _ModelT_contra]):
+    """The arguments `ModelApplication.connect` can give a callback by name."""
+
+    view: _ViewT_contra
+    main_view: _MainViewT_contra
+    model: _ModelT_contra
+
+
+class _ViewOnlyCallback(Protocol[_ViewT_contra, Unpack[Ts]]):
+    def __call__(self, *args: Unpack[Ts], view: _ViewT_contra) -> None: ...
+
+
+class _ViewMainCallback(Protocol[_ViewT_contra, _MainViewT_contra, Unpack[Ts]]):
+    def __call__(
+        self, *args: Unpack[Ts], view: _ViewT_contra, main_view: _MainViewT_contra
+    ) -> None: ...
+
+
+class _ViewModelCallback(Protocol[_ViewT_contra, _ModelT_contra, Unpack[Ts]]):
+    def __call__(self, *args: Unpack[Ts], view: _ViewT_contra, model: _ModelT_contra) -> None: ...
+
+
+class _ViewMainModelCallback(
+    Protocol[_ViewT_contra, _MainViewT_contra, _ModelT_contra, Unpack[Ts]]
+):
+    def __call__(
+        self,
+        *args: Unpack[Ts],
+        view: _ViewT_contra,
+        main_view: _MainViewT_contra,
+        model: _ModelT_contra,
+    ) -> None: ...
+
+
+class _ConnectDecorator(Protocol[_ViewTD, _MainViewTD, Unpack[_TsD]]):
+    @overload
+    def __call__(
+        self, callback: Callable[[Unpack[_TsD]], None]
+    ) -> Callable[[Unpack[_TsD]], None]: ...
+    @overload
+    def __call__(
+        self, callback: _MainViewCallback[_MainViewTD, Unpack[_TsD]]
+    ) -> _MainViewCallback[_MainViewTD, Unpack[_TsD]]: ...
+    @overload
+    def __call__(
+        self, callback: _ViewOnlyCallback[_ViewTD, Unpack[_TsD]]
+    ) -> _ViewOnlyCallback[_ViewTD, Unpack[_TsD]]: ...
+    @overload
+    def __call__(
+        self, callback: _ViewMainCallback[_ViewTD, _MainViewTD, Unpack[_TsD]]
+    ) -> _ViewMainCallback[_ViewTD, _MainViewTD, Unpack[_TsD]]: ...
+
+
+class _ConnectModelDecorator(Protocol[_ViewTD, _MainViewTD, _ModelTD, Unpack[_TsD]]):
+    @overload
+    def __call__(
+        self, callback: Callable[[Unpack[_TsD]], None]
+    ) -> Callable[[Unpack[_TsD]], None]: ...
+    @overload
+    def __call__(
+        self, callback: _MainViewCallback[_MainViewTD, Unpack[_TsD]]
+    ) -> _MainViewCallback[_MainViewTD, Unpack[_TsD]]: ...
+    @overload
+    def __call__(
+        self, callback: _ModelCallback[_ModelTD, Unpack[_TsD]]
+    ) -> _ModelCallback[_ModelTD, Unpack[_TsD]]: ...
+    @overload
+    def __call__(
+        self, callback: _BoundCallback[_MainViewTD, _ModelTD, Unpack[_TsD]]
+    ) -> _BoundCallback[_MainViewTD, _ModelTD, Unpack[_TsD]]: ...
+    @overload
+    def __call__(
+        self, callback: _ViewOnlyCallback[_ViewTD, Unpack[_TsD]]
+    ) -> _ViewOnlyCallback[_ViewTD, Unpack[_TsD]]: ...
+    @overload
+    def __call__(
+        self, callback: _ViewMainCallback[_ViewTD, _MainViewTD, Unpack[_TsD]]
+    ) -> _ViewMainCallback[_ViewTD, _MainViewTD, Unpack[_TsD]]: ...
+    @overload
+    def __call__(
+        self, callback: _ViewModelCallback[_ViewTD, _ModelTD, Unpack[_TsD]]
+    ) -> _ViewModelCallback[_ViewTD, _ModelTD, Unpack[_TsD]]: ...
+    @overload
+    def __call__(
+        self, callback: _ViewMainModelCallback[_ViewTD, _MainViewTD, _ModelTD, Unpack[_TsD]]
+    ) -> _ViewMainModelCallback[_ViewTD, _MainViewTD, _ModelTD, Unpack[_TsD]]: ...
+
+
+def _add_reference_to_signals(main_view: MainView, model: Model | None) -> None:
+    set_references(main_view, main_view, model)
+    if model is not None:
+        main_view.jobs.set_model(model)
+        for signal in model.signals:
+            signal.set_main_view(main_view)
+            signal.set_model(model)
+
+
+class Application(Generic[MainViewT]):
+    """An app showing the main view `build_main_view` builds; each backend has its own.
+
+    The app builds its main view itself, so every backend takes the same arguments: a web
+    app builds one per browser session.
+    """
+
+    def __init__(self, *, build_main_view: Callable[[], MainViewT]) -> None:
+        self._main_view = build_main_view()
+        self._args: argparse.Namespace | None = None
+        self._parser = argparse.ArgumentParser()
+        self._parser.add_argument("--debug", help="Run the app in debug mode", action="store_true")
+        self._parser.add_argument(
+            "-f", metavar="FILE", help="Open the app with the FILE study", type=Path
+        )
+        self._parser.add_argument("--log", help="Display the debug Log.", action="store_true")
+        self._parser.add_argument(
+            "--log-signals", help="Log all the emitted signals.", action="store_true"
+        )
+        self._parser.add_argument(
+            "--language", metavar="LANGUAGE", help="Show the app in LANGUAGE, e.g. fr."
+        )
+        self._add_reference_to_signals()
+
+    def _add_reference_to_signals(self) -> None:
+        _add_reference_to_signals(self._main_view, None)
+
+    @property
+    def main_view(self) -> MainViewT:
+        return self._main_view
+
+    def connect(
+        self, *, view: ViewT, signals: Sequence[Signal[Unpack[Ts]]]
+    ) -> _ConnectDecorator[ViewT, MainViewT, Unpack[Ts]]:
+        def wrapper(callback: Callable[..., None]) -> Callable[..., None]:
+            available_bounds: AvailableBounds[ViewT, MainViewT] = {
+                "view": view,
+                "main_view": self._main_view,
+            }
+            requested_bounds = self._requested_kwargs(callback, tuple(available_bounds))
+            bound = functools.partial(
+                callback, **{k: v for k, v in available_bounds.items() if k in requested_bounds}
+            )
+            new_callback = cast("Callable[[Unpack[Ts]], None]", bound)
+            for s in signals:
+                s.connect(new_callback)
+            return callback
+
+        return cast("_ConnectDecorator[ViewT, MainViewT, Unpack[Ts]]", wrapper)
+
+    def render(self, renderer_type: RendererType) -> None:
+        self._main_view.is_visible = True
+        self._main_view.render(renderer_type)
+
+    def run(self) -> None:
+        self._args = self._parse_arguments()
+        if self._args.log or self._args.debug:
+            LOGGER.setLevel(level=logging.DEBUG)
+        else:
+            LOGGER.setLevel(level=logging.INFO)
+        if self._args.log_signals or self._args.debug:
+            SIGNAL_LOGGER.setLevel(level=logging.DEBUG)
+        else:
+            SIGNAL_LOGGER.setLevel(level=logging.INFO)
+        if self._args.language is not None:
+            self.main_view.set_language(self._args.language)
+        if self._args.f is not None:
+            open_study(self.main_view, self._study_model(), self._args.f)
+        self.main_view.apply_arguments(self._args)
+
+    def _study_model(self) -> Model | None:
+        """Get the model opened, saved and started over with the views: none here."""
+        return None
+
+    def _parse_arguments(self) -> argparse.Namespace:
+        # last: after the backend's own, which a subclass adds once built
+        type(self.main_view).add_arguments(self._parser)
+        args = self._parser.parse_args()
+        if (
+            args.f is not None
+            and isinstance(args.f, Path)
+            and args.f.is_file()
+            and args.f.suffix != self.main_view.extension
+        ):
+            msg = (
+                f"Invalid file extension: '{args.f.suffix}'. "
+                f"Expected extension: '{self.main_view.extension}'. "
+                "Please provide a file with the correct extension."
+            )
+            raise ValueError(msg)
+        return args
+
+    @staticmethod
+    def _requested_kwargs(callback: object, names: tuple[str, ...]) -> frozenset[str]:
+        try:
+            params = inspect.signature(callback).parameters  # type: ignore[arg-type]
+        except (TypeError, ValueError):
+            return frozenset()
+        return frozenset(name for name in names if name in params)
+
+
+class ModelApplication(Application[MainViewT], Generic[MainViewT, ModelT]):
+    """An app with a model beside its main view, given to the callbacks asking for `model`.
+
+    `setup_model` wires them once both are built, e.g. to refresh views when the model
+    changes.
+    """
+
+    def __init__(
+        self,
+        *,
+        build_main_view: Callable[[], MainViewT],
+        build_model: Callable[[], ModelT],
+        setup_model: Callable[[MainViewT, ModelT], None] | None = None,
+    ) -> None:
+        # first: the base class gives it to the signals
+        self._model = build_model()
+        super().__init__(build_main_view=build_main_view)
+        if setup_model is not None:
+            setup_model(self._main_view, self._model)
+
+    @override
+    def _add_reference_to_signals(self) -> None:
+        _add_reference_to_signals(self._main_view, self._model)
+
+    @property
+    def model(self) -> ModelT:
+        return self._model
+
+    @override
+    def _study_model(self) -> ModelT:
+        return self._model
+
+    def connect(
+        self, *, view: ViewT, signals: Sequence[Signal[Unpack[Ts]]]
+    ) -> _ConnectModelDecorator[ViewT, MainViewT, ModelT, Unpack[Ts]]:
+        def wrapper(callback: Callable[..., None]) -> Callable[..., None]:
+            available_bounds: AvailableModelBounds[ViewT, MainViewT, ModelT] = {
+                "view": view,
+                "main_view": self._main_view,
+                "model": self._model,
+            }
+            requested_bounds = self._requested_kwargs(callback, tuple(available_bounds))
+            bound = functools.partial(
+                callback, **{k: v for k, v in available_bounds.items() if k in requested_bounds}
+            )
+            new_callback = cast("Callable[[Unpack[Ts]], None]", bound)
+            for s in signals:
+                s.connect(new_callback)
+            return callback
+
+        return cast("_ConnectModelDecorator[ViewT, MainViewT, ModelT, Unpack[Ts]]", wrapper)
+
+
+#: environment variable naming the backend `run` started: a process the app starts again,
+#: e.g. the web's ``--reload`` server, gets the command line without ``--backend``
+BACKEND_VARIABLE = "COMPOSEUI_BACKEND"
+
+
+def run(
+    build_main_view: Callable[[], MainViewT],
+    *,
+    build_model: Callable[[], ModelT] | None = None,
+    setup_model: Callable[[MainViewT, ModelT], None] | None = None,
+    default_backend: RendererType = RendererType.WEB,
+) -> None:
+    """Run the app on the backend the command line names, e.g. ``--backend qt``.
+
+    Without ``--backend``, on the one `BACKEND_VARIABLE` names, else on `default_backend`.
+    The rest of the command line goes to the backend's app (``-f``, ``--language``,
+    ``--port``, ``--help``...). Only that backend is imported, so the others' extras
+    needn't be installed; without its own, it stops and names the extra. With `build_model`,
+    the app has a model, wired to its main view by `setup_model`: once, or per session on the
+    web.
+    """
+    if build_model is None and setup_model is not None:
+        msg = "setup_model needs a model: pass build_model too"
+        raise ValueError(msg)
+    backends = {backend.name.lower(): backend for backend in RendererType}
+    parser = argparse.ArgumentParser(add_help=False)
+    default = os.environ.get(BACKEND_VARIABLE, "")
+    if default not in backends:
+        default = default_backend.name.lower()
+    parser.add_argument("--backend", choices=backends, default=default)
+    args, rest = parser.parse_known_args()
+    # the app parses the command line itself when it runs; a process it starts again
+    # inherits its environment, and so the backend
+    sys.argv = [sys.argv[0], *rest]
+    os.environ[BACKEND_VARIABLE] = args.backend
+    backend = backends[args.backend].value
+    try:
+        module = importlib.import_module(backend.applications)
+    except ImportError:
+        # only the extra not installed: another import error is a bug, shown as it is
+        missing = [name for name in backend.packages if importlib.util.find_spec(name) is None]
+        if not missing:
+            raise
+        parser.error(
+            f"the {args.backend} backend needs {', '.join(missing)}, from the "
+            f'{backend.extra} extra: pip install "composeui[{backend.extra}]"'
+        )
+    app: Application[MainViewT]
+    if build_model is None:
+        app = module.APPLICATION(build_main_view=build_main_view)
+    else:
+        app = module.MODEL_APPLICATION(
+            build_main_view=build_main_view, build_model=build_model, setup_model=setup_model
+        )
+    app.run()

composeui/core/chartcolors.py

@@ -0,0 +1,23 @@
+"""The series colors of the backends drawing charts without a palette of their own."""
+
+#: categorical hues, in order, told apart with color blindness too, for a light and for a
+#: dark background (each stepped for its background); past them, around again dashed
+from __future__ import annotations
+
+__all__ = []
+
+SERIES_COLORS = {
+    False: ("#2a78d6", "#eb6834", "#1baf7a", "#eda100", "#e87ba4", "#008300", "#6250d6", "#e34948"),
+    True: ("#3987e5", "#d95926", "#199e70", "#c98500", "#d55181", "#008300", "#9085e9", "#e66767"),
+}
+
+
+def series_color(index: int, *, is_dark: bool) -> str:
+    """Get the color of the chart's series at `index`, as ``#rrggbb``."""
+    colors = SERIES_COLORS[is_dark]
+    return colors[index % len(colors)]
+
+
+def is_dashed(index: int) -> bool:
+    """Tell whether the series at `index` is dashed: the colors went around once already."""
+    return index >= len(SERIES_COLORS[False])