moops 0.12.0__tar.gz → 0.12.2__tar.gz

{moops-0.12.0 → moops-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moops
-Version: 0.12.0
+Version: 0.12.2
 Summary: Write Marimo notebooks that also work as CLI scripts, with unified UI controls
 Keywords: marimo,notebooks,cli,testing
 Author: Yair Chuchem
@@ -13,11 +13,12 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: marimo>=0.23.1
-Requires-Dist: hypothesis
+Requires-Dist: hypothesis ; extra == 'test'
 Requires-Python: >=3.10
 Project-URL: Homepage, https://github.com/yairchu/moops
 Project-URL: Repository, https://github.com/yairchu/moops
 Project-URL: Issues, https://github.com/yairchu/moops/issues
+Provides-Extra: test
 Description-Content-Type: text/markdown
 
 # moops
@@ -174,6 +175,8 @@ x_range = args.custom(
 
 `moops.interface_of` returns the notebook's `Interface`, from which `.strategy()` generates a [Hypothesis](https://hypothesis.readthedocs.io/) strategy that produces valid `moops.run` kwargs by introspecting the notebook's interface — dropdowns yield their allowed keys, switches yield booleans, and text fields yield arbitrary strings.
 
+Hypothesis is an optional dependency, since it is only needed for `.strategy()`; install it with `pip install moops[test]` (or just `pip install hypothesis`).
+
 ```python
 from examples.composition import name_casing
 

{moops-0.12.0 → moops-0.12.2}/README.md

@@ -152,6 +152,8 @@ x_range = args.custom(
 
 `moops.interface_of` returns the notebook's `Interface`, from which `.strategy()` generates a [Hypothesis](https://hypothesis.readthedocs.io/) strategy that produces valid `moops.run` kwargs by introspecting the notebook's interface — dropdowns yield their allowed keys, switches yield booleans, and text fields yield arbitrary strings.
 
+Hypothesis is an optional dependency, since it is only needed for `.strategy()`; install it with `pip install moops[test]` (or just `pip install hypothesis`).
+
 ```python
 from examples.composition import name_casing
 

{moops-0.12.0 → moops-0.12.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "moops"
-version = "0.12.0"
+version = "0.12.2"
 description = "Write Marimo notebooks that also work as CLI scripts, with unified UI controls"
 license = "MIT"
 readme = "README.md"
@@ -24,9 +24,12 @@ classifiers = [
 ]
 dependencies = [
     "marimo>=0.23.1",
-    "hypothesis",
 ]
 
+[project.optional-dependencies]
+# Interface.strategy() builds a Hypothesis strategy; only needed for testing.
+test = ["hypothesis"]
+
 [project.urls]
 Homepage = "https://github.com/yairchu/moops"
 Repository = "https://github.com/yairchu/moops"
@@ -34,6 +37,7 @@ Issues = "https://github.com/yairchu/moops/issues"
 
 [dependency-groups]
 dev = [
+    "hypothesis",
     "ruff>=0.1.0",
     "pyright>=1.1.409",
     "pytest>=9.0.3",

{moops-0.12.0 → moops-0.12.2}/src/moops/_control_mirroring.py

@@ -80,7 +80,7 @@ class VariantAwareDictionary(mo.ui.dictionary):
         result: dict[str, typing.Any] = {}
         rendered_variant_groups: set[tuple[str, str]] = set()
         for name, element in self.elements.items():
-            sub_iface = _attached_interface(element)
+            sub_iface = interface.attached_interface(element)
             if sub_iface is None or sub_iface.variant_ctx.group_prefix is None:
                 result[name] = element
                 continue
@@ -116,7 +116,7 @@ def _display_element(element: typing.Any) -> typing.Any:
         visible = typing.cast(dict[str, typing.Any], visible_elements())
         return mo.vstack([_display_element(child) for child in visible.values()])
     elements = getattr(element, "elements", None)
-    if isinstance(elements, dict) and _attached_interface(element) is not None:
+    if isinstance(elements, dict) and interface.attached_interface(element) is not None:
         typed_elements = typing.cast(dict[str, typing.Any], elements)
         return mo.vstack([_display_element(child) for child in typed_elements.values()])
     return element
@@ -129,12 +129,12 @@ def _active_variant_element(
 ) -> tuple[str, typing.Any] | None:
     selector_option = variant_iface.variant_ctx.selector_option
     variant_group_prefix = variant_iface.variant_ctx.group_prefix
-    selected = _selected_value_for_option(root_iface, selector_option)
+    selected = interface.selected_value_for_option(root_iface, selector_option)
     if selected is None:
         return None
     selected_key = _variant.key_text(selected)
     for name, element in elements.items():
-        sub_iface = _attached_interface(element)
+        sub_iface = interface.attached_interface(element)
         if (
             sub_iface is not None
             and sub_iface.variant_ctx.selector_option == selector_option
@@ -145,16 +145,6 @@ def _active_variant_element(
     return None
 
 
-def _selected_value_for_option(
-    iface: interface.Interface, selector_option: str | None
-) -> typing.Any:
-    return interface.selected_value_for_option(iface, selector_option)
-
-
-def _attached_interface(ctrl: typing.Any) -> interface.Interface | None:
-    return interface.attached_interface(ctrl)
-
-
 def _apply_mirrored_variant_ctx(
     source: interface.Interface,
     child_group: typing.Any,
@@ -195,20 +185,9 @@ def _create_control(
     group: typing.Any,
     iface: interface.Interface,
     input_control: _options.InputControl,
-) -> typing.Any:
-    return _create_from_input_control(
-        group,
-        input_control,
-        _interface_utils.unprefixed_option(iface, input_control.option),
-    )
-
-
-def _create_from_input_control(
-    group: typing.Any,
-    input_control: _options.InputControl,
-    display_option: str,
 ) -> typing.Any:
     """Create a marimo element from an existing InputControl."""
+    display_option = _interface_utils.unprefixed_option(iface, input_control.option)
     opt = group._make_opt(label=None, option=display_option)
     cloned = input_control.with_option(opt.option)
     return group._register_control(opt, cloned, cloned.help_text, None)

{moops-0.12.0 → moops-0.12.2}/src/moops/_custom_element.py

@@ -6,19 +6,10 @@ from marimo._plugins.ui._core.ui_element import UIElement
 
 from . import _ui_workarounds
 
-
-class CustomValueSource(typing.Protocol):
-    @property
-    def value(self) -> typing.Any: ...
-
-
-CustomValueFn = typing.Callable[[CustomValueSource, CustomValueSource], typing.Any]
+CustomValueFn = typing.Callable[[typing.Any, typing.Any], typing.Any]
 
 
-def _default_custom_value(
-    component: CustomValueSource, fallback: CustomValueSource
-) -> typing.Any:
-    del fallback
+def _default_value_fn(component: typing.Any, _fallback: typing.Any) -> typing.Any:
     return component.value
 
 
@@ -46,7 +37,7 @@ class CustomElement(UIElement[typing.Any, typing.Any]):
             raise TypeError("custom controls must build a marimo UIElement")
         self._component: UIElement[typing.Any, typing.Any] = component
         self._fallback = fallback
-        self._value_fn = value_fn or _default_custom_value
+        self._value_fn = value_fn or _default_value_fn
         # Deliberately skip super().__init__(): we reuse the wrapped component's
         # identity so marimo's reactive DAG treats this as the same element.
         # Calling super().__init__() would register a new element and ID.

{moops-0.12.0 → moops-0.12.2}/src/moops/_embed.py

@@ -99,21 +99,41 @@ async def embed(
     Embed a marimo app, with lean script-mode embeds.
 
     In script mode, only the embedded notebook's ``result`` definition is
-    retained, so intermediate definitions and rendered outputs can be released
-    after the embed completes. Pass additional definition names in ``keep`` to
-    retain them as well (in notebook mode all definitions are exposed and
-    ``keep`` has no effect).
+    retained, so intermediate definitions can be released after the embed
+    completes. Pass additional definition names in ``keep`` to retain them as
+    well (in notebook mode all definitions are exposed and ``keep`` has no
+    effect). The embedded notebook's rendered cell outputs are stacked on the
+    returned object's ``output``, matching notebook-mode embeds.
+
+    When ``args`` is the only overridden definition, the embedded notebook's
+    interface also shows a CLI command that reproduces the embed's current
+    setup standalone.
 
     This also works around marimo nested embed failures in script mode,
     see https://github.com/marimo-team/marimo/issues/9572
     """
     keep = _normalize_keep(keep)
+    _record_extra_overrides(defs)
     if mo.running_in_notebook():
         _raise_if_same_cell_app(app)
         return await app.embed(defs=defs)
     return await asyncio.to_thread(_embed_in_script, app, defs or {}, keep)
 
 
+def _record_extra_overrides(defs: dict[str, typing.Any] | None) -> None:
+    """Stamp on the injected args Group which other defs were overridden.
+
+    The embedded notebook's interface offers a CLI command reproducing the
+    current setup only when ``args`` is the only override: defs injected
+    directly (e.g. a dataframe) cannot be reproduced from the command line.
+    The interface cannot detect overrides itself — marimo merges them into
+    the run's globals without a trace — so embed() records them here.
+    """
+    args = (defs or {}).get("args")
+    if args is not None and hasattr(args, "_embedded_extra_overrides"):
+        args._embedded_extra_overrides = frozenset(defs or ()) - {"args"}
+
+
 def _normalize_keep(keep: typing.Sequence[str]) -> tuple[str, ...]:
     if isinstance(keep, str):
         raise TypeError("keep must be a sequence of definition names, not a string")
@@ -158,7 +178,7 @@ class Passthrough:
         for name in ("result", *keep):
             if name in source_defs:
                 self.defs[name] = source_defs[name]
-        self.output = None
+        self.output: mo.Html | None = None
 
     def _forwarded(self) -> dict[str, typing.Any]:
         return {k: v for k, v in self.defs.items() if k != "interface"}
@@ -207,10 +227,13 @@ class Passthrough:
 
 
 def _embed_in_script(
-    app: _App, defs: dict[str, typing.Any], keep: tuple[str, ...] = ()
+    app: _App,
+    defs: dict[str, typing.Any],
+    keep: tuple[str, ...] = (),
 ) -> typing.Any:
-    _, computed_defs = app.run(defs=defs)
+    output, computed_defs = app.run(defs=defs)
     result = Passthrough(dict(computed_defs), keep=keep)
     if "interface" in computed_defs:
         result.defs["interface"] = computed_defs["interface"]
+    result.output = mo.vstack([x for x in output if x is not None])
     return result

{moops-0.12.0 → moops-0.12.2}/src/moops/_list_options.py

@@ -6,10 +6,12 @@ import json
 import typing
 
 import marimo as mo
-from hypothesis import strategies as st
 
 from . import _options, _parse, _variant
 
+if typing.TYPE_CHECKING:
+    from hypothesis import strategies as st
+
 InputControl = _options.InputControl
 ParseError = _options.ParseError
 ParseResult = _options.ParseResult
@@ -17,30 +19,6 @@ ParseResult = _options.ParseResult
 _UNSET: typing.Any = object()
 
 
-class _ListUIOwner(typing.Protocol):
-    def current_items(self) -> list[typing.Any]: ...
-
-    def default_item(self) -> typing.Any: ...
-
-    def set_items(self, items: list[typing.Any]) -> None: ...
-
-
-@dataclasses.dataclass(frozen=True)
-class _CallbackListUIOwner:
-    value_getter: typing.Callable[[], list[typing.Any]]
-    make_default: typing.Callable[[], typing.Any]
-    on_change: typing.Callable[[typing.Any], None]
-
-    def current_items(self) -> list[typing.Any]:
-        return self.value_getter()
-
-    def default_item(self) -> typing.Any:
-        return self.make_default()
-
-    def set_items(self, items: list[typing.Any]) -> None:
-        self.on_change(items)
-
-
 class _ListUI:
     """Notebook UI wrapper for a list control.
 
@@ -77,7 +55,9 @@ class _ListUI:
 def _build_list_ui(
     elements: list[typing.Any],
     *,
-    owner: _ListUIOwner,
+    current_items: typing.Callable[[], list[typing.Any]],
+    default_item: typing.Callable[[], typing.Any],
+    set_items: typing.Callable[[list[typing.Any]], None],
 ) -> tuple[typing.Any, typing.Any]:
     """Build the notebook list layout with per-item controls.
 
@@ -93,21 +73,21 @@ def _build_list_ui(
     """
 
     def insert_at(idx: int) -> None:
-        current = owner.current_items()
-        owner.set_items([*current[:idx], owner.default_item(), *current[idx:]])
+        current = current_items()
+        set_items([*current[:idx], default_item(), *current[idx:]])
 
     def remove_at(idx: int) -> None:
-        current = owner.current_items()
+        current = current_items()
         if 0 <= idx < len(current):
-            owner.set_items([*current[:idx], *current[idx + 1 :]])
+            set_items([*current[:idx], *current[idx + 1 :]])
 
     def move(idx: int, delta: int) -> None:
-        current = owner.current_items()
+        current = current_items()
         target = idx + delta
         if 0 <= idx < len(current) and 0 <= target < len(current):
             reordered = list(current)
             reordered[idx], reordered[target] = reordered[target], reordered[idx]
-            owner.set_items(reordered)
+            set_items(reordered)
 
     count = len(elements)
     rows: list[typing.Any] = []
@@ -143,7 +123,7 @@ def _build_list_ui(
 
     add_btn = mo.ui.button(
         label="+ Append",
-        on_click=lambda _: insert_at(len(owner.current_items())),
+        on_click=lambda _: insert_at(len(current_items())),
     )
     rows.append(add_btn)
     return mo.vstack(rows), add_btn
@@ -504,21 +484,55 @@ class SubgroupListControl(InputControl):
         return groups
 
     def format_query_value(self, value: typing.Any) -> str | None:
-        try:
-            return json.dumps(value)
-        except TypeError:
-            return None
+        # Serialize each item per leaf, keeping the dict structure but replacing
+        # each leaf value with its own control's query form (a dropdown's key,
+        # str(number), ...). This stays JSON-serializable even when a leaf value
+        # is not — e.g. a dropdown mapped to a class — where a raw json.dumps of
+        # the resolved values would raise TypeError and drop the whole param.
+        # Leaves whose query form is None (at their default) are omitted and
+        # refilled from the item template on parse.
+        items: list[dict[str, typing.Any]] = []
+        for item in value:
+            out: dict[str, typing.Any] = {}
+            for leaf in self.leaves:
+                raw = get_path(item, leaf.value_path, _UNSET)
+                if raw is _UNSET:
+                    continue
+                formatted = leaf.bare_control().format_query_value(raw)
+                if formatted is not None:
+                    _set_path(out, leaf.value_path, formatted)
+            items.append(out)
+        return json.dumps(items)
 
     def parse_query_value(self, value: str) -> ParseResult | ParseError:
         try:
-            raw_items: typing.Any = json.loads(value)
+            raw: typing.Any = json.loads(value)
         except json.JSONDecodeError:
             return ParseError(f"Query parameter for {self.option} must be a JSON list")
-        if not isinstance(raw_items, list):
+        if not isinstance(raw, list):
             return ParseError(f"Query parameter for {self.option} must be a JSON list")
-        return ParseResult(raw_items)
+        result: list[dict[str, typing.Any]] = []
+        for raw_item in typing.cast(list[typing.Any], raw):
+            item = copy.deepcopy(self.item_template_default)
+            if isinstance(raw_item, dict):
+                for leaf in self.leaves:
+                    stored = get_path(raw_item, leaf.value_path, _UNSET)
+                    if stored is _UNSET:
+                        continue
+                    if not isinstance(stored, str):
+                        # Legacy form stored the resolved value directly.
+                        _set_path(item, leaf.value_path, stored)
+                        continue
+                    parsed = leaf.bare_control().parse_query_value(stored)
+                    if isinstance(parsed, ParseError):
+                        return parsed
+                    _set_path(item, leaf.value_path, parsed.value)
+            result.append(item)
+        return ParseResult(result)
 
     def strategy(self) -> st.SearchStrategy:
+        from hypothesis import strategies as st
+
         leaf_strategies = {
             leaf.value_path: leaf.bare_control().strategy() for leaf in self.leaves
         }
@@ -545,18 +559,17 @@ class SubgroupListControl(InputControl):
         items = [copy.deepcopy(item) for item in value]
         elements = [self.item_builder(i, item) for i, item in enumerate(items)]
         if on_change is not None and mo.running_in_notebook():
-            self._attach_item_change_handlers(elements, on_change)
 
             def value_getter() -> list[typing.Any]:
                 return [element.value for element in elements]
 
+            self._attach_item_change_handlers(elements, on_change, value_getter)
+
             display, add_btn = _build_list_ui(
                 elements,
-                owner=_CallbackListUIOwner(
-                    value_getter=value_getter,
-                    make_default=lambda: copy.deepcopy(self.item_template_default),
-                    on_change=on_change,
-                ),
+                current_items=value_getter,
+                default_item=lambda: copy.deepcopy(self.item_template_default),
+                set_items=on_change,
             )
             return _ListUI(
                 _ElementList(elements),
@@ -570,10 +583,8 @@ class SubgroupListControl(InputControl):
         self,
         item_elements: list[typing.Any],
         on_change: typing.Callable[[typing.Any], None],
+        value_getter: typing.Callable[[], list[typing.Any]],
     ) -> None:
-        def value_getter() -> list[typing.Any]:
-            return [element.value for element in item_elements]
-
         for idx, item_element in enumerate(item_elements):
             for leaf in self.leaves:
                 element = _element_at_path(item_element, leaf.value_path)
@@ -773,8 +784,6 @@ class ListControl(InputControl):
 
     def format_query_value(self, value: typing.Any) -> str | None:
         items = list(value)
-        if not items and not self.default:
-            return None
         return json.dumps([self.item_control.format_query_value(v) for v in items])
 
     def parse_query_value(self, value: str) -> ParseResult | ParseError:
@@ -802,6 +811,8 @@ class ListControl(InputControl):
         return [_options.option_value_token(self.item_control.option, query_value)]
 
     def strategy(self) -> st.SearchStrategy:
+        from hypothesis import strategies as st
+
         return st.lists(self.item_control.strategy())
 
     def create_marimo_element(
@@ -826,7 +837,7 @@ class ListControl(InputControl):
             return handler
 
         elements = [
-            self.item_control.create_marimo_element(
+            self.item_control.make_element(
                 v,
                 label=f"{label} [{i + 1}]",
                 disabled=disabled,
@@ -842,11 +853,9 @@ class ListControl(InputControl):
 
             display, add_btn = _build_list_ui(
                 elements,
-                owner=_CallbackListUIOwner(
-                    value_getter=value_getter,
-                    make_default=lambda: copy.deepcopy(self.item_control.default),
-                    on_change=on_change,
-                ),
+                current_items=value_getter,
+                default_item=lambda: copy.deepcopy(self.item_control.default),
+                set_items=on_change,
             )
             return _ListUI(
                 array,

{moops-0.12.0 → moops-0.12.2}/src/moops/_options.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import abc
 import contextlib
 import dataclasses
@@ -9,19 +11,17 @@ import sys
 import typing
 
 import marimo as mo
-from hypothesis import strategies as st
 
 from . import _choice_options, _custom_element, _parse, _ui_workarounds
 
+if typing.TYPE_CHECKING:
+    from hypothesis import strategies as st
+
 Numeric = int | float
 
 _UNSET: typing.Any = object()
 
 
-def _empty_cli_opts() -> dict[str, str]:
-    return {}
-
-
 def option_value_token(option: str, value: str) -> str:
     """Serialize an ``option value`` pair as one CLI token string.
 
@@ -52,8 +52,19 @@ class InputControl(abc.ABC):
     option: str
     help_text: str
     default: typing.Any
-    extra_kwargs: dict[str, typing.Any] = dataclasses.field(  # type: ignore[assignment]
-        default_factory=dict, kw_only=True
+    extra_kwargs: dict[str, typing.Any] = dataclasses.field(
+        default_factory=dict[str, typing.Any], kw_only=True
+    )
+    # Set by Group.custom(): a factory that builds a notebook-only component
+    # from this control's resolved value, and a value_fn mapping
+    # (component, fallback) to the control's value shape. When set, make_element
+    # wraps the control's own element in a CustomElement in notebooks; the
+    # control keeps all its CLI/parse/help behavior as the fallback.
+    custom_build: typing.Callable[[typing.Any], typing.Any] | None = dataclasses.field(
+        default=None, kw_only=True
+    )
+    custom_value_fn: _custom_element.CustomValueFn | None = dataclasses.field(
+        default=None, kw_only=True
     )
 
     def options(self) -> set[str]:
@@ -68,7 +79,7 @@ class InputControl(abc.ABC):
         """Whether this control accepts repeated CLI values for the same option."""
         return False
 
-    def with_option(self, option: str) -> "InputControl":
+    def with_option(self, option: str) -> InputControl:
         """Return a copy of this control with a different option name.
 
         Used by ``controls_from`` to re-prefix a mirrored control. Subclasses
@@ -135,6 +146,31 @@ class InputControl(abc.ABC):
     ) -> typing.Any:
         """Create the marimo UI element for this control."""
 
+    def make_element(
+        self,
+        value: typing.Any,
+        label: str,
+        *,
+        on_change: typing.Callable[[typing.Any], None] | None = None,
+        disabled: bool = False,
+    ) -> typing.Any:
+        """Create this control's element, applying any Group.custom() wrapper.
+
+        Ordinary controls just return ``create_marimo_element``; a control set up
+        by ``Group.custom()`` wraps that element in a ``CustomElement`` (notebook
+        only) so it renders a bespoke component while keeping this control's CLI
+        fallback. Use this instead of ``create_marimo_element`` wherever an
+        element is built from a control that may carry a custom wrapper.
+        """
+        element = self.create_marimo_element(
+            value, label, on_change=on_change, disabled=disabled
+        )
+        if self.custom_build is None or not mo.running_in_notebook():
+            return element
+        return _custom_element.CustomElement(
+            self.custom_build(value), element, self.custom_value_fn
+        )
+
     @abc.abstractmethod
     def prompt_interactive(self, effective_default: typing.Any = _UNSET) -> list[str]:
         """Prompt the user for a value. Returns raw CLI tokens to append to args.
@@ -223,6 +259,8 @@ class FlagControl(InputControl):
                 )
 
     def strategy(self) -> st.SearchStrategy:
+        from hypothesis import strategies as st
+
         return st.booleans()
 
     def format_usage_parts(self) -> list[str]:
@@ -320,6 +358,8 @@ class TextControl(ValueControl):
         return None if res is None else ParseResult(res)
 
     def strategy(self) -> st.SearchStrategy:
+        from hypothesis import strategies as st
+
         return st.text()
 
     def format_help_lines(self) -> list[str]:
@@ -375,6 +415,12 @@ def _decode_json_list(value: str) -> list[typing.Any] | None:
     return typing.cast(list[typing.Any], raw)
 
 
+def _missing_path_error(value: str) -> ParseError | None:
+    if value and not pathlib.Path(value).exists():
+        return ParseError(f"File not found: {value!r}")
+    return None
+
+
 @dataclasses.dataclass
 class FileControl(TextControl):
     def create_marimo_element(
@@ -407,9 +453,8 @@ class FileControl(TextControl):
     def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
         result = super().parse(args)
         match result:
-            case ParseResult(value=v) if v and not pathlib.Path(v).exists():
-                # Empty string means no file selected; skip existence check.
-                return ParseError(f"File not found: {v!r}")
+            case ParseResult(value=v):
+                return _missing_path_error(v) or result
             case _:
                 pass
         return result
@@ -420,8 +465,8 @@ class FileControl(TextControl):
             if not result:
                 return result
             v = result[1]
-            if v and not pathlib.Path(v).exists():
-                print(f"File not found: {v!r}")
+            if err := _missing_path_error(v):
+                print(err.message)
                 continue
             return result
 
@@ -467,8 +512,8 @@ class MultiFileControl(ValueControl):
         for value in values:
             if value is None:
                 return ParseError(f"Option {self.option} requires a value")
-            if value and not pathlib.Path(value).exists():
-                return ParseError(f"File not found: {value!r}")
+            if err := _missing_path_error(value):
+                return err
             paths.append(value)
         return ParseResult(paths)
 
@@ -484,12 +529,14 @@ class MultiFileControl(ValueControl):
                 return ParseError(
                     f"Query parameter for {self.option} must be a JSON list of paths"
                 )
-            if item and not pathlib.Path(item).exists():
-                return ParseError(f"File not found: {item!r}")
+            if err := _missing_path_error(item):
+                return err
             paths.append(item)
         return ParseResult(paths)
 
     def strategy(self) -> st.SearchStrategy:
+        from hypothesis import strategies as st
+
         return st.lists(st.text())
 
     def format_usage_parts(self) -> list[str]:
@@ -522,9 +569,9 @@ class MultiFileControl(ValueControl):
             if not response:
                 return []
             paths = [part.strip() for part in response.split(",") if part.strip()]
-            missing = [path for path in paths if not pathlib.Path(path).exists()]
-            if missing:
-                print(f"File not found: {missing[0]!r}")
+            errors = [err for path in paths if (err := _missing_path_error(path))]
+            if errors:
+                print(errors[0].message)
                 continue
             return [tok for path in paths for tok in (self.option, path)]
 
@@ -569,6 +616,8 @@ class TextAreaControl(ValueControl):
         return None if res is None else ParseResult(res)
 
     def strategy(self) -> st.SearchStrategy:
+        from hypothesis import strategies as st
+
         return st.text()
 
     def format_usage_parts(self) -> list[str]:
@@ -655,6 +704,8 @@ class NumberControl(_NoneFlag, ValueControl):
         return super().parse_query_value(value)
 
     def strategy(self) -> st.SearchStrategy:
+        from hypothesis import strategies as st
+
         numbers = st.integers() | st.floats(allow_nan=False, allow_infinity=False)
         return st.one_of(st.none(), numbers) if self._is_none_capable else numbers
 
@@ -716,7 +767,7 @@ class RangeControl(ValueControl):
         steps: typing.Sequence[Numeric] | None,
         step: Numeric | None = None,
         extra_kwargs: dict[str, typing.Any] | None = None,
-    ) -> "RangeControl":
+    ) -> RangeControl:
         return cls(
             option=option,
             metavar=metavar,
@@ -790,11 +841,15 @@ class RangeControl(ValueControl):
         return ParseResult(parsed)
 
     def strategy(self) -> st.SearchStrategy:
+        from hypothesis import strategies as st
+
         return st.tuples(self._number_strategy(), self._number_strategy()).map(
             lambda pair: sorted(pair)
         )
 
     def _number_strategy(self) -> st.SearchStrategy[Numeric]:
+        from hypothesis import strategies as st
+
         if self.allowed_values is not None:
             return st.sampled_from(self.allowed_values)
         if self.start is not None and self.stop is not None:
@@ -913,6 +968,8 @@ class MultiSelectControl(_NoneFlag, ValueControl):
         return ParseResult([self.select_opts[item] for item in keys])
 
     def strategy(self) -> st.SearchStrategy:
+        from hypothesis import strategies as st
+
         if not self.select_opts:
             return st.just([])
         return st.lists(st.sampled_from(list(self.select_opts.values())), unique=True)
@@ -990,7 +1047,7 @@ class DropdownControl(_NoneFlag, InputControl):
     dropdown_opts: dict[str, typing.Any]
     supports_none: bool
     default: str | None
-    cli_opts: dict[str, str] = dataclasses.field(default_factory=_empty_cli_opts)
+    cli_opts: dict[str, str] = dataclasses.field(default_factory=dict[str, str])
 
     def __post_init__(self) -> None:
         if not self.cli_opts:
@@ -1052,6 +1109,8 @@ class DropdownControl(_NoneFlag, InputControl):
         return ParseResult(key)
 
     def strategy(self) -> st.SearchStrategy:
+        from hypothesis import strategies as st
+
         return st.sampled_from(
             [None, *self.dropdown_opts.keys()]
             if self.supports_none
@@ -1138,102 +1197,6 @@ class DropdownControl(_NoneFlag, InputControl):
         )
 
 
-@dataclasses.dataclass
-class CustomControl(InputControl):
-    """A notebook-only component paired with a CLI-compatible fallback control.
-
-    ``inner`` is the fallback control that supplies all CLI behavior (parsing,
-    help, defaults, query format). ``build`` constructs the notebook component
-    from the fallback's live marimo element; it is only called in notebooks.
-    ``value_fn`` maps ``(component, fallback)`` to the fallback-shaped value.
-
-    Because all CLI behavior lives in ``inner`` and the component is rebuilt by
-    ``create_marimo_element``, ``controls_from`` recreates the component when it
-    mirrors this control into a parent notebook.
-    """
-
-    inner: InputControl
-    build: typing.Callable[[typing.Any], typing.Any]
-    value_fn: _custom_element.CustomValueFn | None = None
-
-    # ``build`` receives the fallback's resolved *value* (a snapshot), not the
-    # live element. controls_from creates the fallback and calls build in one
-    # cell, and marimo forbids reading a UIElement's ``.value`` in the cell that
-    # created it -- so build must not touch the element. ``value_fn`` does
-    # receive the element, but it runs later (when the parent reads the mirror
-    # dictionary's value), in a different cell, where ``.value`` is allowed.
-
-    @classmethod
-    def wrap(
-        cls,
-        inner: InputControl,
-        build: typing.Callable[[typing.Any], typing.Any],
-        value_fn: _custom_element.CustomValueFn | None,
-    ) -> "CustomControl":
-        return cls(
-            option=inner.option,
-            help_text=inner.help_text,
-            default=inner.default,
-            inner=inner,
-            build=build,
-            value_fn=value_fn,
-        )
-
-    def with_option(self, option: str) -> "CustomControl":
-        inner = self.inner.with_option(option)
-        return dataclasses.replace(
-            self, option=option, inner=inner, default=inner.default
-        )
-
-    def options(self) -> set[str]:
-        return self.inner.options()
-
-    def flags(self) -> set[str]:
-        return self.inner.flags()
-
-    def allows_repeated_values(self) -> bool:
-        return self.inner.allows_repeated_values()
-
-    def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
-        return self.inner.parse(args)
-
-    def parse_query_value(self, value: str) -> ParseResult | ParseError:
-        return self.inner.parse_query_value(value)
-
-    def format_query_value(self, value: typing.Any) -> str | None:
-        return self.inner.format_query_value(value)
-
-    def strategy(self) -> st.SearchStrategy:
-        return self.inner.strategy()
-
-    def format_usage_parts(self) -> list[str]:
-        return self.inner.format_usage_parts()
-
-    def format_help_lines(self) -> list[str]:
-        return self.inner.format_help_lines()
-
-    def format_value(self, value: typing.Any) -> list[str]:
-        return self.inner.format_value(value)
-
-    def prompt_interactive(self, effective_default: typing.Any = _UNSET) -> list[str]:
-        return self.inner.prompt_interactive(effective_default)
-
-    def create_marimo_element(
-        self,
-        value: typing.Any,
-        label: str,
-        *,
-        on_change: typing.Callable[[typing.Any], None] | None = None,
-        disabled: bool = False,
-    ) -> typing.Any:
-        fallback = self.inner.create_marimo_element(
-            value, label, on_change=on_change, disabled=disabled
-        )
-        if not mo.running_in_notebook():
-            return fallback
-        return _custom_element.CustomElement(self.build(value), fallback, self.value_fn)
-
-
 def _parse_number(option: str, value: str) -> ParseResult | ParseError:
     # Parse integer-looking strings as int first: routing them through float()
     # would silently lose precision past 2**53 (e.g. "9007199254740993").

{moops-0.12.0 → moops-0.12.2}/src/moops/_query_params.py

@@ -8,21 +8,16 @@ from . import _options
 _MARIMO_RESERVED_PARAMS = frozenset({"file"})
 
 
-class QueryParamStore(typing.Protocol):
-    def __iter__(self) -> typing.Iterator[typing.Any]: ...
-
-    def __setitem__(self, key: str, value: str) -> None: ...
-
-    def get(self, key: str) -> typing.Any: ...
-
-
 def escape_url_key(key: str) -> str:
     return f"{key}_" if key in _MARIMO_RESERVED_PARAMS else key
 
 
 @dataclasses.dataclass
 class QueryParams:
-    params: QueryParamStore | None
+    # marimo's query-params object (mo.query_params()), or None outside a
+    # notebook. Duck-typed: get / __setitem__ / __iter__, plus an optional
+    # remove() used when clearing a key.
+    params: typing.Any
     prefix: str = ""
 
     @classmethod
@@ -100,8 +95,6 @@ class QueryParams:
             if callable(remove):
                 remove(key)
             else:
-                typing.cast(typing.MutableMapping[str, typing.Any], params).pop(
-                    key, None
-                )
+                params.pop(key, None)
         else:
             params[key] = value

{moops-0.12.0 → moops-0.12.2}/src/moops/_terminal_graphics.py

@@ -9,46 +9,36 @@ dependency on a plotting library.
 from __future__ import annotations
 
 import base64
-import enum
 import io
 import os
 import sys
 import typing
 
 
-class Protocol(enum.Enum):
-    """Terminal image protocol detected for the current stdout."""
-
-    KITTY = "kitty"
-    NONE = "none"  # room for ITERM / SIXEL backends later
-
-
 def detect(
     env: typing.Mapping[str, str] | None = None,
     stream: typing.IO[str] | None = None,
-) -> Protocol:
+) -> bool:
     """Best-effort detection of inline-image support for ``stream``.
 
-    Returns ``Protocol.NONE`` whenever stdout is not a terminal (piped or
-    redirected), so escape sequences never leak into captured output. Terminal
-    identification is by environment variable; this covers kitty, Ghostty,
-    WezTerm, and Konsole, all of which speak the Kitty graphics protocol.
+    Returns ``False`` whenever stdout is not a terminal (piped or redirected),
+    so escape sequences never leak into captured output. Terminal identification
+    is by environment variable; this covers kitty, Ghostty, WezTerm, and
+    Konsole, all of which speak the Kitty graphics protocol.
     """
     env = os.environ if env is None else env
     out = sys.stdout if stream is None else stream
     if out is None or not (hasattr(out, "isatty") and out.isatty()):
-        return Protocol.NONE
+        return False
     term = env.get("TERM", "")
-    if (
+    return (
         "KITTY_WINDOW_ID" in env
         or "kitty" in term
         or term == "xterm-ghostty"
         or "GHOSTTY_BIN_DIR" in env
         or env.get("TERM_PROGRAM") == "WezTerm"
         or "KONSOLE_VERSION" in env
-    ):
-        return Protocol.KITTY
-    return Protocol.NONE
+    )
 
 
 def to_png(fig: typing.Any, *, dpi: int | None = None) -> bytes:
@@ -102,7 +92,7 @@ def emit(png: bytes, *, stream: typing.IO[str] | None = None) -> None:
     fallback (e.g. ASCII art) when they want one.
     """
     out = sys.stdout if stream is None else stream
-    if out is not None and detect(stream=out) is Protocol.KITTY:
+    if out is not None and detect(stream=out):
         out.write(kitty_sequence(png) + "\n")
         out.flush()
     else:

{moops-0.12.0 → moops-0.12.2}/src/moops/_ui_workarounds.py

@@ -52,7 +52,6 @@ class LockedMultiselect(UIElement[str, list[str]]):
 
     def __init__(self, value: list[str], label_html: str) -> None:
         self._locked_value = list(value)
-        self._label_html = label_html
         _chips = "".join(
             f'<span style="background:var(--sky-2,#dbeafe);border-radius:4px;'
             f'padding:2px 8px;margin:2px;display:inline-block">{v}</span>'

{moops-0.12.0 → moops-0.12.2}/src/moops/_value_resolution.py

@@ -31,12 +31,19 @@ class ValueResolver:
             return self.overrides[key]
         query_value = self._query_value(control, key)
         if self.preset_state is not None:
+            # Honor live notebook list state over the preset: if the persisted
+            # query matches the value the caller passed (so it reflects the
+            # current edited state rather than a stale param), keep it. Compare
+            # in parsed/canonical form by round-tripping `default` through the
+            # same query (de)serialization — a list's live value holds mapped
+            # objects (e.g. a dropdown's resolved value) that don't compare
+            # equal to the parsed query's key form directly.
             if (
                 _is_list_control(control)
                 and query_value is not _UNSET
-                and query_value == default
+                and query_value == self._normalized_default(control, default)
             ):
-                return query_value
+                return default
             match control.parse(self.preset_state.args):
                 case _options.ParseResult(value=v):
                     self.query_params.sync(control, key, v)
@@ -67,6 +74,26 @@ class ValueResolver:
                     pass
         return default
 
+    def _normalized_default(
+        self,
+        control: _options.InputControl,
+        default: typing.Any,
+    ) -> typing.Any:
+        """``default`` round-tripped through the control's query (de)serialization.
+
+        Returns it in the same parsed form a query value takes, so the two can
+        be compared directly. Returns ``_UNSET`` (which never equals a real
+        query value) when ``default`` cannot be serialized or parsed back.
+        """
+        formatted = control.format_query_value(default)
+        if formatted is None:
+            return _UNSET
+        match control.parse_query_value(formatted):
+            case _options.ParseResult(value=v):
+                return v
+            case _:
+                return _UNSET
+
     def _query_value(
         self,
         control: _options.InputControl,

{moops-0.12.0 → moops-0.12.2}/src/moops/group.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import dataclasses
 import enum
 import inspect
 import pathlib
@@ -46,6 +47,27 @@ class OutputMode(enum.Enum):
     STDOUT = "stdout"  # print text to the terminal
 
 
+def _ensure_nongui_matplotlib() -> None:
+    """Switch matplotlib off GUI backends for CLI figure rendering.
+
+    Imports matplotlib if needed: when an app offloaded to a worker thread is
+    the first to import it, the backend would be resolved in that thread,
+    picking the GUI backend on macOS. A no-op when matplotlib is not
+    installed. Notebook backends are not registered as interactive and are
+    left untouched.
+    """
+    try:
+        import matplotlib
+        from matplotlib.backends.registry import BackendFilter, backend_registry
+    except ImportError:
+        return
+    interactive = backend_registry.list_builtin(  # type: ignore[reportUnknownMemberType]
+        BackendFilter.INTERACTIVE
+    )
+    if matplotlib.get_backend().lower() in {b.lower() for b in interactive}:
+        matplotlib.use("agg")
+
+
 class Group:
     """Unified CLI argument parser and marimo UI element generator."""
 
@@ -74,6 +96,10 @@ class Group:
         self._query_params = _query_params.QueryParams.from_notebook()
         self._preset_state = self._resolve_preset_state()
         self._parent_group: Group | None = None
+        # Set by moops.embed() on the injected args: names of defs other than
+        # "args" overridden for the embed. None means not embedded via
+        # moops.embed (or overrides unknown).
+        self._embedded_extra_overrides: frozenset[str] | None = None
         self._markdown_heading_offset = 0
         self._disabled = False
         self._variant_ctx = _variant.VariantContext()
@@ -258,6 +284,7 @@ class Group:
             extra_missing_options=extra_missing_options,
             disabled=self._disabled,
             variant_ctx=self._variant_ctx,
+            embedded_extra_overrides=self._embedded_extra_overrides,
         )
         if self._parent_group is not None:
             self._parent_group._subgroup_registry.register(iface)
@@ -302,12 +329,21 @@ class Group:
         to a text/ASCII fallback when it is ``False``::
 
             mo.stop(not args.graphics_supported)
+
+        A ``True`` on the CLI also switches matplotlib off GUI backends, so
+        that the plotting it gates works when the app runs in a worker thread
+        (e.g. embedded by another notebook) — GUI backends can only create
+        figures on the main thread, and ``figure`` only rasterizes, never
+        showing GUI windows.
         """
         if self.output_mode is OutputMode.NOTEBOOK:
             return True
         if self.output_mode is None:
             return False
-        return _terminal_graphics.detect() is not _terminal_graphics.Protocol.NONE
+        if not _terminal_graphics.detect():
+            return False
+        _ensure_nongui_matplotlib()
+        return True
 
     def figure(
         self,
@@ -616,7 +652,9 @@ class Group:
         inner = self._input_map.get(fallback)
         if inner is None:
             raise ValueError("fallback must be a control created by this Group")
-        custom_control = _options.CustomControl.wrap(inner, build, value)
+        custom_control = dataclasses.replace(
+            inner, custom_build=build, custom_value_fn=value
+        )
         fallback_value = fallback._value
         element = (
             CustomElement(build(fallback_value), fallback, value)
@@ -896,7 +934,7 @@ class Group:
         on_change: typing.Callable[[typing.Any], None] | None,
     ) -> typing.Any:
         reset_state = self._value_resolver.query_on_change(input_control, on_change)
-        control = input_control.create_marimo_element(
+        control = input_control.make_element(
             self._value_resolver.get_value(input_control, input_control.default),
             label=opt.label_with_tooltip(help_text),
             disabled=self._value_resolver.is_overridden(opt.option) or self._disabled,

{moops-0.12.0 → moops-0.12.2}/src/moops/interface.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import dataclasses
 import html
 import pathlib
@@ -7,7 +9,6 @@ import typing
 import urllib.parse
 
 import marimo as mo
-from hypothesis import strategies as st
 
 from . import (
     _input_map,
@@ -23,6 +24,9 @@ from . import (
 )
 from .presets import Presets
 
+if typing.TYPE_CHECKING:
+    from hypothesis import strategies as st
+
 
 @dataclasses.dataclass
 class Interface:
@@ -47,6 +51,9 @@ class Interface:
     variant_ctx: _variant.VariantContext = dataclasses.field(
         default_factory=_variant.VariantContext
     )
+    # Names of defs other than "args" overridden for the embed this interface
+    # renders inside; None when that is unknown (not embedded via moops.embed).
+    embedded_extra_overrides: frozenset[str] | None = None
 
     def __post_init__(self) -> None:
         seen_ids: set[int] = set()
@@ -250,6 +257,8 @@ class Interface:
         return result
 
     def strategy(self) -> st.SearchStrategy[dict[str, typing.Any]]:
+        from hypothesis import strategies as st
+
         strategies: dict[str, st.SearchStrategy[typing.Any]] = {
             name: ctrl_or_sub.strategy() for name, ctrl_or_sub in self.iter_controls()
         }
@@ -261,8 +270,9 @@ class Interface:
         self,
         *,
         active_only: bool,
-        root: "Interface | None" = None,
+        root: Interface | None = None,
         active_args: _parse.ParsedArgs | None = None,
+        include_overridden: bool = False,
     ) -> typing.Iterator[_options.InputControl]:
         root = self if root is None else root
         if active_only and self._is_inactive(root, active_args=active_args):
@@ -273,15 +283,18 @@ class Interface:
                     active_only=active_only,
                     root=root,
                     active_args=active_args,
+                    include_overridden=include_overridden,
                 )
             else:
                 input_control = self.input_map.get(ctrl)
-                if input_control is not None and not self._is_overridden(input_control):
+                if input_control is not None and (
+                    include_overridden or not self._is_overridden(input_control)
+                ):
                     yield input_control
 
     def _is_inactive(
         self,
-        root: "Interface",
+        root: Interface,
         *,
         active_args: _parse.ParsedArgs | None = None,
     ) -> bool:
@@ -303,7 +316,7 @@ class Interface:
 
     def iter_controls(
         self,
-    ) -> typing.Iterator[tuple[str, "Interface | _options.InputControl"]]:
+    ) -> typing.Iterator[tuple[str, Interface | _options.InputControl]]:
         """Yield one entry per top-level control, preserving subgroup structure.
 
         Yields ``(name, sub_iface)`` for subgroup controls and
@@ -324,14 +337,16 @@ class Interface:
     def _is_overridden(self, input_control: _options.InputControl) -> bool:
         return self._key(input_control) in self.overrides
 
-    def cur_values(self) -> dict[str, typing.Any]:
+    def cur_values(self, *, include_overridden: bool = False) -> dict[str, typing.Any]:
         result: dict[str, typing.Any] = {}
         for ctrl in self.controls:
             if (iface := attached_interface(ctrl)) is not None:
-                result.update(iface.cur_values())
+                result.update(iface.cur_values(include_overridden=include_overridden))
             else:
                 input_control = self.input_map.get(ctrl)
-                if input_control is not None and not self._is_overridden(input_control):
+                if input_control is not None and (
+                    include_overridden or not self._is_overridden(input_control)
+                ):
                     result[input_control.option] = _marimo_controls.ctrl_value(ctrl)
         return result
 
@@ -350,16 +365,42 @@ class Interface:
         wrap per item. Used both for the flat ``_current_args`` string and for
         the line-wrapped command shown in the script callout.
         """
-        values = self.cur_values()
+        return [" ".join(tokens) for tokens in self._token_groups()]
+
+    def _token_groups(self, *, include_overridden: bool = False) -> list[list[str]]:
+        values = self.cur_values(include_overridden=include_overridden)
         return [
-            " ".join(tokens)
-            for input_control in self._input_controls(active_only=True)
+            tokens
+            for input_control in self._input_controls(
+                active_only=True, include_overridden=include_overridden
+            )
             if input_control.option in values
             for tokens in input_control.format_value_groups(
                 values[input_control.option]
             )
         ]
 
+    def _standalone_arg_groups(self) -> list[str]:
+        """Current CLI args spelled for running the notebook standalone.
+
+        Rewrites option tokens to drop this interface's embed prefix. Working
+        at the token level covers every control type uniformly, including
+        list anchors and ``--no-`` aux flags that embed the prefixed name.
+        Overridden controls are included: their values are fixed by the
+        embedding parent, so standalone the CLI must pass them explicitly.
+        """
+        return [
+            " ".join(self._strip_embed_prefix(token) for token in tokens)
+            for tokens in self._token_groups(include_overridden=True)
+        ]
+
+    def _strip_embed_prefix(self, token: str) -> str:
+        stem = self.option_prefix.lstrip("-")
+        for head in ("--", "--no-"):
+            if token.startswith(f"{head}{stem}-"):
+                return f"{head}{token[len(head) + len(stem) + 1 :]}"
+        return token
+
     def missing_options(self) -> list[str]:
         covered = {
             input_control.option
@@ -393,10 +434,21 @@ class Interface:
             return mo.md("Input bundle with no notebook name")
         notebook_name = html.escape(self.notebook_name)
         href = html.escape(self._standalone_url(), quote=True)
-        return mo.md(
+        link = mo.md(
             f'<a href="{href}" target="_blank" rel="noopener">'
             f"An embedded instance of `{notebook_name}`</a>"
         )
+        if self.embedded_extra_overrides != frozenset():
+            # None: embedded outside moops.embed, so overrides are unknown.
+            # Non-empty: the parent injected defs beyond args, so no CLI
+            # command can reproduce this setup.
+            return link
+        command = _text_wrap.wrap_command(
+            self.notebook_file, self._standalone_arg_groups()
+        )
+        return mo.vstack(
+            [link, mo.md(f"To run as a standalone script:\n```\n{command}\n```")]
+        )
 
     def _standalone_url(self) -> str:
         values = self._standalone_query_values()
@@ -414,7 +466,7 @@ class Interface:
                 self._add_query_value(values, ctrl, self.input_map)
         return values
 
-    def _controls_from_query_values(self, sub_iface: "Interface") -> dict[str, str]:
+    def _controls_from_query_values(self, sub_iface: Interface) -> dict[str, str]:
         """Collect standalone query values for a controls_from mirror.
 
         Uses this interface's key scheme (our option_prefix) so the resulting