moops 0.1.0__tar.gz

moops-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: moops
+Version: 0.1.0
+Summary: Write Marimo notebooks that also work as CLI scripts, with unified UI controls
+Keywords: marimo,notebooks,cli,testing
+Author: Yair Chuchem
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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-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
+Description-Content-Type: text/markdown
+
+# moops
+
+Easily write Marimo notebooks that work as CLI scripts (and more!) with minimal boilerplate.
+
+Marimo supports notebooks running as CLI scripts,
+but until now this required maintaining matching input handling implementations.
+
+Using `moops`, both implementations are merged into one.
+
+## Installation
+
+`uv add` (or `pip install`) `moops`
+
+## Transition guide
+
+* Create your argument group: `args = moops.Group()`
+* Replace your `mo.ui` usages with using methods of `args`
+* Add `args.interface` call, preferably as the top cell, and provide the UI elements to it. This makes the notebook works as a script and adds info about it in the notebook.
+
+Now your notebook doubles as a CLI script
+
+## Running notebooks from Python
+
+Notebooks can also be called from Python with `moops.run`.
+This is useful for testing notebook logic without launching Marimo,
+and for reusing notebook logic from other code.
+
+Expose a variable named `result` from the notebook:
+
+```python
+@app.cell
+def _(input_text, mode_dropdown):
+    result = mode_dropdown.value(input_text.value)
+    return (result,)
+```
+
+Then call the notebook module directly:
+
+```python
+import moops
+from examples import name_casing
+
+result = moops.run(
+    name_casing,
+    text="Hello World",
+    style="snake_case",
+)
+
+assert result == "hello_world"
+```
+
+Keyword arguments override `moops.Group` inputs by their option names,
+with leading dashes removed and dashes converted to underscores.
+If no overrides are provided, `moops.run` uses the notebook defaults.
+
+## Property-based testing
+
+`moops.testing.notebook_interface` 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.
+
+```python
+from examples import name_casing
+
+_name_casing_interface = moops.testing.notebook_interface(name_casing)
+_name_casing_defaults = _name_casing_interface.default
+
+@hypothesis.given(_name_casing_interface.strategy())
+def test_name_casing_preserves_alphanumeric_count(kwargs):
+    result = moops.run(name_casing, **kwargs)
+    input_text = kwargs.get("input_text", _name_casing_defaults["input_text"])
+    assert sum(c.isalnum() for c in result) == sum(c.isalnum() for c in input_text)
+```
+
+## Running the examples
+
+From the project root:
+
+```sh
+uv run examples/notebook.py
+```
+
+Or `uv run marimo edit` to run as notebooks.
+
+## Feedback welcome
+
+This is an early release — issues, ideas, and pull requests are very welcome on [GitHub](https://github.com/yairchu/moops).

moops-0.1.0/README.md

@@ -0,0 +1,85 @@
+# moops
+
+Easily write Marimo notebooks that work as CLI scripts (and more!) with minimal boilerplate.
+
+Marimo supports notebooks running as CLI scripts,
+but until now this required maintaining matching input handling implementations.
+
+Using `moops`, both implementations are merged into one.
+
+## Installation
+
+`uv add` (or `pip install`) `moops`
+
+## Transition guide
+
+* Create your argument group: `args = moops.Group()`
+* Replace your `mo.ui` usages with using methods of `args`
+* Add `args.interface` call, preferably as the top cell, and provide the UI elements to it. This makes the notebook works as a script and adds info about it in the notebook.
+
+Now your notebook doubles as a CLI script
+
+## Running notebooks from Python
+
+Notebooks can also be called from Python with `moops.run`.
+This is useful for testing notebook logic without launching Marimo,
+and for reusing notebook logic from other code.
+
+Expose a variable named `result` from the notebook:
+
+```python
+@app.cell
+def _(input_text, mode_dropdown):
+    result = mode_dropdown.value(input_text.value)
+    return (result,)
+```
+
+Then call the notebook module directly:
+
+```python
+import moops
+from examples import name_casing
+
+result = moops.run(
+    name_casing,
+    text="Hello World",
+    style="snake_case",
+)
+
+assert result == "hello_world"
+```
+
+Keyword arguments override `moops.Group` inputs by their option names,
+with leading dashes removed and dashes converted to underscores.
+If no overrides are provided, `moops.run` uses the notebook defaults.
+
+## Property-based testing
+
+`moops.testing.notebook_interface` 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.
+
+```python
+from examples import name_casing
+
+_name_casing_interface = moops.testing.notebook_interface(name_casing)
+_name_casing_defaults = _name_casing_interface.default
+
+@hypothesis.given(_name_casing_interface.strategy())
+def test_name_casing_preserves_alphanumeric_count(kwargs):
+    result = moops.run(name_casing, **kwargs)
+    input_text = kwargs.get("input_text", _name_casing_defaults["input_text"])
+    assert sum(c.isalnum() for c in result) == sum(c.isalnum() for c in input_text)
+```
+
+## Running the examples
+
+From the project root:
+
+```sh
+uv run examples/notebook.py
+```
+
+Or `uv run marimo edit` to run as notebooks.
+
+## Feedback welcome
+
+This is an early release — issues, ideas, and pull requests are very welcome on [GitHub](https://github.com/yairchu/moops).

moops-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["uv_build>=0.6"]
+build-backend = "uv_build"
+
+[project]
+name = "moops"
+version = "0.1.0"
+description = "Write Marimo notebooks that also work as CLI scripts, with unified UI controls"
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "Yair Chuchem" },
+]
+keywords = ["marimo", "notebooks", "cli", "testing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "marimo>=0.23.1",
+    "hypothesis",
+]
+
+[project.urls]
+Homepage = "https://github.com/yairchu/moops"
+Repository = "https://github.com/yairchu/moops"
+Issues = "https://github.com/yairchu/moops/issues"
+
+[tool.uv]
+dev-dependencies = [
+    "ruff>=0.1.0",
+    "pyright>=1.1.409",
+    "pytest>=9.0.3",
+    "vulture>=2.16",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "."]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+include = ["src", "tests"]
+extraPaths = ["src", ".", "examples"]
+
+[tool.uv.sources]
+moops = { workspace = true }
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "RUF", "C4", "SIM", "N", "Q", "TID", "UP", "PT", "RET"]
+
+[tool.ruff.lint.per-file-ignores]
+"examples/*.py" = ["F401", "F841", "B018"]

moops-0.1.0/src/moops/__init__.py

@@ -0,0 +1,6 @@
+from ._run import run
+from .group import Group
+from .interface import Interface
+from .presets import Presets
+
+__all__ = ["Group", "Interface", "Presets", "run"]

moops-0.1.0/src/moops/_cli_map.py

@@ -0,0 +1,28 @@
+import typing
+import weakref
+
+from . import _options
+
+
+class CliMap:
+    """Maps UI controls to their CLI counterparts."""
+
+    def __init__(self) -> None:
+        self._lookup: dict[int, _options.CliControl] = {}
+
+    def register(self, control: typing.Any, cli: _options.CliControl) -> typing.Any:
+        ctrl_id = id(control)
+        self._lookup[ctrl_id] = cli
+
+        # WeakKeyDictionary would be cleaner but requires hashable keys; marimo
+        # controls (e.g. dropdown) define __eq__ without __hash__, so we use
+        # finalize() to remove the entry when the control is GC'd instead.
+        weakref.finalize(control, self._lookup.pop, ctrl_id, None)
+
+        return control
+
+    def get(self, control: typing.Any) -> _options.CliControl | None:
+        return self._lookup.get(id(control))
+
+    def items(self) -> typing.Iterator[tuple[int, _options.CliControl]]:
+        yield from self._lookup.items()

moops-0.1.0/src/moops/_naming.py

@@ -0,0 +1,27 @@
+import dataclasses
+
+
+@dataclasses.dataclass
+class OptionLabel:
+    """Maps between UI labels and CLI option names."""
+
+    label: str
+    option: str
+
+    @staticmethod
+    def make(
+        label: str | None, option: str | None, prefix: str | None = None
+    ) -> "OptionLabel":
+        """Generate OptionLabel from label or option name."""
+
+        if option is None:
+            assert label is not None, "Either label or option must be provided"
+            option = f"--{prefix or ''}{label.lower().replace(' ', '-')}"
+        else:
+            assert option.startswith("-"), f"Option must start with dash: {option}"
+            assert prefix is None or option.startswith(f"--{prefix}"), (
+                f"Option {option} must start with --{prefix}"
+            )
+            if label is None:
+                label = option.lstrip("-").replace("-", " ")
+        return OptionLabel(label=label, option=option)

moops-0.1.0/src/moops/_options.py

@@ -0,0 +1,252 @@
+import abc
+import dataclasses
+import math
+import shlex
+import sys
+import typing
+
+import marimo as mo
+from hypothesis import strategies as st
+
+from . import _parse
+
+
+@dataclasses.dataclass
+class ParseError:
+    message: str
+
+
+@dataclasses.dataclass
+class ParseResult:
+    value: typing.Any
+
+
+@dataclasses.dataclass
+class CliControl(abc.ABC):
+    """CLI interface for a single UI control."""
+
+    option: str
+    help_text: str
+
+    def options(self) -> set[str]:
+        """Value options for this control."""
+        return set()
+
+    def flags(self) -> set[str]:
+        """Flags for this control."""
+        return set()
+
+    @abc.abstractmethod
+    def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
+        """Parse from CLI args. Returns value, ParseError, or None if not provided."""
+
+    @abc.abstractmethod
+    def strategy(self) -> st.SearchStrategy:
+        """Hypothesis strategy for generating override values."""
+
+    @abc.abstractmethod
+    def format_usage_parts(self) -> list[str]:
+        """Usage tokens for this control, e.g. ['[--flag]'] or ['[--name NAME]']."""
+
+    @abc.abstractmethod
+    def format_help_lines(self) -> list[str]:
+        """Help lines for this control and any aux flags."""
+
+    @abc.abstractmethod
+    def format_value(self, value: typing.Any) -> list[str]:
+        """Format the command line arguments for a given value."""
+
+
+@dataclasses.dataclass
+class FlagControl(CliControl):
+    default: bool = False
+
+    def flags(self) -> set[str]:
+        return {self.option}
+
+    def parse(self, args: _parse.ParsedArgs) -> ParseResult | None:
+        return ParseResult(not self.default) if self.option in args.options else None
+
+    def strategy(self) -> st.SearchStrategy:
+        return st.booleans()
+
+    def format_usage_parts(self) -> list[str]:
+        return [f"[{self.option}]"]
+
+    def format_help_lines(self) -> list[str]:
+        return [f"  {self.option}: {self.help_text}"]
+
+    def format_value(self, value: typing.Any) -> list[str]:
+        return [] if value == self.default else [self.option]
+
+
+@dataclasses.dataclass
+class ValueControl(CliControl):
+    """Base class for controls that take a value, like text or dropdowns."""
+
+    metavar: str
+
+    def options(self) -> set[str]:
+        return {self.option}
+
+    def format_usage_parts(self) -> list[str]:
+        return [f"[{self.option} {self.metavar}]"]
+
+
+@dataclasses.dataclass
+class TextControl(ValueControl):
+    default: str
+
+    def parse(self, args: _parse.ParsedArgs) -> ParseResult | None:
+        res = args.options.get(self.option)
+        return None if res is None else ParseResult(res)
+
+    def strategy(self) -> st.SearchStrategy:
+        return st.text()
+
+    def format_help_lines(self) -> list[str]:
+        line = f"  {self.option} {self.metavar}: {self.help_text}"
+        if self.default:
+            line += f" (default: {self.default})"
+        return [line]
+
+    def format_value(self, value: typing.Any) -> list[str]:
+        return [] if value == self.default else [f"{self.option} {shlex.quote(value)}"]
+
+
+@dataclasses.dataclass
+class TextAreaControl(ValueControl):
+    default: str
+
+    @property
+    def _stdin_flag(self) -> str:
+        return f"{self.option}-from-stdin"
+
+    def flags(self) -> set[str]:
+        return {self._stdin_flag}
+
+    def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
+        if not mo.running_in_notebook() and self._stdin_flag in args.options:
+            if args.options[self._stdin_flag] is not None:
+                return None
+            if self.option in args.options:
+                return ParseError(
+                    f"Cannot use both {self.option} and {self._stdin_flag}"
+                )
+            return ParseResult(sys.stdin.read())
+        res = args.options.get(self.option)
+        return None if res is None else ParseResult(res)
+
+    def strategy(self) -> st.SearchStrategy:
+        return st.text()
+
+    def format_usage_parts(self) -> list[str]:
+        return [f"[{self.option} {self.metavar}]", f"[{self._stdin_flag}]"]
+
+    def format_help_lines(self) -> list[str]:
+        line = f"  {self.option} {self.metavar}: {self.help_text}"
+        if self.default:
+            line += f" (default: {self.default})"
+        return [line, f"  {self._stdin_flag}: Read {self.option} from stdin"]
+
+    def format_value(self, value: typing.Any) -> list[str]:
+        return [] if value == self.default else [f"{self.option} {shlex.quote(value)}"]
+
+
+@dataclasses.dataclass
+class NumberControl(ValueControl):
+    default: float | int | None
+
+    def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
+        value = args.options.get(self.option)
+        if value is None:
+            return None
+        try:
+            num = float(value)
+        except ValueError:
+            return ParseError(f"Option {self.option} expects a number, got: {value!r}")
+        return ParseResult(int(num) if math.isfinite(num) and num == int(num) else num)
+
+    def strategy(self) -> st.SearchStrategy:
+        return st.one_of(
+            st.none(),
+            st.integers() | st.floats(allow_nan=False, allow_infinity=False),
+        )
+
+    def format_help_lines(self) -> list[str]:
+        line = f"  {self.option} {self.metavar}: {self.help_text}"
+        if self.default is not None:
+            line += f" (default: {self.default})"
+        return [line]
+
+    def format_value(self, value: typing.Any) -> list[str]:
+        return [] if value == self.default else [f"{self.option} {value}"]
+
+
+@dataclasses.dataclass
+class DropdownControl(CliControl):
+    allowed_values: list[str]
+    supports_none: bool
+    default: str | None
+
+    def options(self) -> set[str]:
+        return {self.option}
+
+    @property
+    def has_no_flag(self) -> bool:
+        return self.supports_none and self.default is not None
+
+    @property
+    def _no_flag(self) -> str | None:
+        return f"--no-{self.option.lstrip('-')}" if self.has_no_flag else None
+
+    def flags(self) -> set[str]:
+        no_flag = self._no_flag
+        return {no_flag} if no_flag else set()
+
+    def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
+        no_flag = self._no_flag
+        if no_flag and no_flag in args.options:
+            if self.option in args.options:
+                return ParseError(f"Cannot use both {self.option} and {no_flag}")
+            return ParseResult(None)
+        raw = args.options.get(self.option)
+        if raw is None:
+            return None
+        if raw not in self.allowed_values:
+            return ParseError(
+                f"Option {self.option} must be one of"
+                f" {self.allowed_values!r}, got: {raw!r}"
+            )
+        return ParseResult(raw)
+
+    def strategy(self) -> st.SearchStrategy:
+        return st.sampled_from(
+            [None, *self.allowed_values] if self.supports_none else self.allowed_values
+        )
+
+    def format_usage_parts(self) -> list[str]:
+        parts = [f"[{self.option} {self._values_text()}]"]
+        if self._no_flag:
+            parts.append(f"[{self._no_flag}]")
+        return parts
+
+    def _values_text(self) -> str:
+        return "{" + "|".join(self.allowed_values) + "}"
+
+    def format_help_lines(self) -> list[str]:
+        line = f"  {self.option} {self._values_text()}: {self.help_text}"
+        if self.default is not None:
+            line += f" (default: {self.default})"
+        lines = [line]
+        if self._no_flag:
+            lines.append(f"  {self._no_flag}: Set {self.option} to none")
+        return lines
+
+    def format_value(self, value: typing.Any) -> list[str]:
+        if value == self.default:
+            return []
+        if value is None:
+            assert self._no_flag
+            return [self._no_flag]
+        return [f"{self.option} {shlex.quote(value)}"]

moops-0.1.0/src/moops/_parse.py

@@ -0,0 +1,62 @@
+import dataclasses
+import sys
+
+import marimo as mo
+
+help_flags = ["--help", "-h"]
+
+
+@dataclasses.dataclass
+class ParsedArgs:
+    options: dict[str, str | None]
+    unexpected: list[str]
+
+    @property
+    def is_help(self) -> bool:
+        return any(x in self.options for x in help_flags)
+
+    @classmethod
+    def from_options(cls, args: list[str]) -> "ParsedArgs":
+        """Parse a pre-tokenized list of options (no command name)."""
+
+        options: dict[str, str | None] = {}
+        unexpected: list[str] = []
+        prev = None
+        for arg in args:
+            is_negative_num = len(arg) > 1 and arg[0] == "-" and arg[1].isdigit()
+            if arg.startswith("-") and not (prev is not None and is_negative_num):
+                if "=" in arg:
+                    key, value = arg.split("=", 1)
+                    options[key] = value
+                    prev = None
+                else:
+                    options[arg] = None
+                    prev = arg
+            elif prev is not None and prev.startswith("-"):
+                options[prev] = arg
+                prev = None
+            else:
+                unexpected.append(arg)
+        return cls(options=options, unexpected=unexpected)
+
+
+@dataclasses.dataclass
+class ParseState:
+    """Shared mutable state between a Group and all its subgroups."""
+
+    args: ParsedArgs
+    validation_errors: dict[str, str] = dataclasses.field(
+        default_factory=dict[str, str]
+    )
+
+
+def split_argv(args: list[str] | None) -> tuple[str, list[str]]:
+    """Split argv-shaped input into (command, options)."""
+    if args is None:
+        args = sys.argv
+        if mo.running_in_notebook():
+            # When notebooks embed other notebooks,
+            # the outer notebook is the last argument in sys.argv
+            args = args[-1:]
+    cmd, *rest = args
+    return cmd, rest

moops-0.1.0/src/moops/_run.py

@@ -0,0 +1,23 @@
+import types
+import typing
+
+from . import group
+
+
+def run(module: types.ModuleType, **kwargs: typing.Any) -> typing.Any:
+    """Run a notebook as a function, returning its `result` variable.
+
+    Keyword arguments override control values by option name
+    (leading dashes removed and dashes replaced with underscores). For example,
+    a text area with option "--input-text" is overridden with input_text="...".
+    All controls are overridable, including those not passed to interface.
+    """
+    args = group.Group.with_overrides(kwargs)
+
+    _, defs = module.app.run(defs={"args": args})
+    if "result" not in defs:
+        raise RuntimeError(
+            f"moops.run() expected {module.__name__} to expose a variable named "
+            "'result'"
+        )
+    return defs["result"]

moops-0.1.0/src/moops/group.py

@@ -0,0 +1,359 @@
+import html
+import inspect
+import pathlib
+import shlex
+import typing
+import warnings
+
+import marimo as mo
+
+from . import _cli_map, _naming, _options, _parse, interface
+from .presets import Presets
+
+
+class Group:
+    """Unified CLI argument parser and marimo UI element generator."""
+
+    def __init__(
+        self,
+        cli_args: list[str] | None = None,
+        presets: Presets | None = None,
+    ) -> None:
+        """Initialize with command line arguments (defaults to sys.argv)."""
+
+        self.option: str = ""
+        command, rest = _parse.split_argv(cli_args)
+        self._command = command
+        self._state = _parse.ParseState(args=_parse.ParsedArgs.from_options(rest))
+        self._cli_map = _cli_map.CliMap()
+        self._overrides: dict[str, typing.Any] = {}
+        self._presets = presets
+        self._preset_state = self._build_preset_state()
+
+    @classmethod
+    def with_overrides(cls, overrides: dict[str, typing.Any]) -> "Group":
+        instance = cls(["run"])
+        instance._overrides = overrides
+        return instance
+
+    def subgroup(
+        self,
+        prefix: str,
+        overrides: dict[str, typing.Any] | None = None,
+        presets: Presets | None = None,
+    ) -> "Group":
+        """Create a child Group that prefixes all its option names with '{prefix}-'.
+
+        Pass a nested dict under the same key to moops.run() to override controls
+        in this subgroup: moops.run(notebook, casing={"style": "snake_case"}).
+        Explicit overrides take precedence over those passed via moops.run().
+
+        Pass `presets=` to give the subgroup its own preset selector; otherwise
+        it inherits the parent's preset state.
+        """
+        child = type(self)([prefix])
+        child._state = self._state
+        child._cli_map = _cli_map.CliMap()
+        child._overrides = {**self._overrides.get(prefix, {}), **(overrides or {})}
+        child.option = f"{self.option}-{prefix}" if self.option else f"--{prefix}"
+        child._presets = presets
+        child._preset_state = (
+            child._build_preset_state() if presets else self._preset_state
+        )
+        return child
+
+    def _build_preset_state(self) -> _parse.ParseState | None:
+        if self._presets is None or self._presets.selected_args is None:
+            return None
+        args = _parse.ParsedArgs.from_options(shlex.split(self._presets.selected_args))
+        return _parse.ParseState(args=args)
+
+    def interface(self, *controls: typing.Any) -> interface.Interface:
+        """
+        group.interface() serves two purposes:
+        * Display help text based on the defined flags and options.
+        * Verify the arguments passed to the script.
+
+        Pass all controls created by this group so that the registry stays in
+        sync with what is actually live (handles cell reruns and deletions).
+        """
+
+        iface = interface.Interface(
+            controls,
+            cli_map=self._cli_map,
+            overrides=self._overrides,
+            notebook_name=pathlib.Path(inspect.stack()[1].filename).name,
+            option_prefix=self.option,
+            presets=self._presets,
+            command=self._command,
+        )
+        if self.option or not mo.running_in_notebook():
+            missing_options = iface.missing_options()
+            if missing_options:
+                warnings.warn(
+                    f"Controls registered with this Group "
+                    f"but not passed to interface(): {', '.join(missing_options)}",
+                    stacklevel=2,
+                )
+        if not self.option and not mo.running_in_notebook():
+            iface.validate_or_exit(self._state)
+        return iface
+
+    def md(self, text: str) -> mo.Html | None:
+        """Display markdown in notebooks or plain text in CLI."""
+
+        if mo.running_in_notebook():
+            return mo.md(text)
+        if self._state.args.is_help:
+            return None
+        text = text.strip()
+        if text.startswith("```\n") and text.endswith("\n```"):
+            text = text[4:-4]
+        elif text.startswith("`") and text.endswith("`"):
+            text = text[1:-1]
+        print(f"{text}\n")
+        return None
+
+    def switch(
+        self,
+        value: bool = False,
+        flag: str | None = None,
+        *,
+        help_text: str,
+        label: str | None = None,
+        **kwargs: typing.Any,
+    ) -> mo.ui.switch:
+        """Create a switch UI element that maps to a CLI flag."""
+
+        opt = self._make_opt(label=label, option=flag, prefix="no-" if value else None)
+        cli = _options.FlagControl(
+            option=opt.option, help_text=help_text, default=value
+        )
+        return self._cli_map.register(
+            mo.ui.switch(
+                value=self._get_value(cli, value),
+                label=_label_with_help(opt.label, help_text),
+                disabled=self._is_overridden(opt.option),
+                **kwargs,
+            ),
+            cli,
+        )
+
+    def text(
+        self,
+        value: str = "",
+        placeholder: str = "",
+        option: str | None = None,
+        *,
+        help_text: str,
+        label: str | None = None,
+        **kwargs: typing.Any,
+    ) -> mo.ui.text:
+        """Create a text input UI element that maps to a CLI option."""
+
+        opt = self._make_opt(label=label, option=option)
+        cli = _options.TextControl(
+            option=opt.option,
+            metavar=placeholder or opt.label.upper().replace(" ", "_"),
+            help_text=help_text,
+            default=value,
+        )
+        return self._cli_map.register(
+            mo.ui.text(
+                value=self._get_value(cli, value),
+                label=_label_with_help(opt.label, help_text),
+                disabled=self._is_overridden(opt.option),
+                **kwargs,
+            ),
+            cli,
+        )
+
+    def text_area(
+        self,
+        value: str = "",
+        placeholder: str = "",
+        option: str | None = None,
+        *,
+        help_text: str,
+        label: str | None = None,
+        **kwargs: typing.Any,
+    ) -> mo.ui.text_area:
+        """Create a text area UI element that maps to a CLI option."""
+
+        opt = self._make_opt(label=label, option=option)
+        cli = _options.TextAreaControl(
+            option=opt.option,
+            metavar=placeholder or opt.label.upper().replace(" ", "_"),
+            help_text=help_text,
+            default=value,
+        )
+        return self._cli_map.register(
+            mo.ui.text_area(
+                value=self._get_value(cli, value),
+                label=_label_with_help(opt.label, help_text),
+                disabled=self._is_overridden(opt.option),
+                **kwargs,
+            ),
+            cli,
+        )
+
+    def number(
+        self,
+        start: float | None = None,
+        value: float | None = None,
+        option: str | None = None,
+        *,
+        help_text: str,
+        label: str | None = None,
+        **kwargs: typing.Any,
+    ) -> mo.ui.number:
+        """Create a number input UI element that maps to a CLI option."""
+
+        opt, cli, value = self._numeric_cli(start, value, option, help_text, label)
+        return self._cli_map.register(
+            mo.ui.number(
+                start=start,
+                value=value,
+                label=_label_with_help(opt.label, help_text),
+                disabled=self._is_overridden(opt.option),
+                **kwargs,
+            ),
+            cli,
+        )
+
+    def slider(
+        self,
+        start: float | None = None,
+        value: float | None = None,
+        option: str | None = None,
+        *,
+        help_text: str,
+        label: str | None = None,
+        **kwargs: typing.Any,
+    ) -> mo.ui.slider:
+        """Create a slider UI element that maps to a CLI option."""
+
+        opt, cli, value = self._numeric_cli(start, value, option, help_text, label)
+        return self._cli_map.register(
+            mo.ui.slider(
+                start=start,
+                value=value,
+                label=_label_with_help(opt.label, help_text),
+                disabled=self._is_overridden(opt.option),
+                **kwargs,
+            ),
+            cli,
+        )
+
+    def _numeric_cli(
+        self,
+        start: float | None,
+        value: float | None,
+        option: str | None,
+        help_text: str,
+        label: str | None,
+    ) -> tuple[_naming.OptionLabel, _options.NumberControl, float | None]:
+        if value is None:
+            value = start
+        opt = self._make_opt(label=label, option=option)
+        cli = _options.NumberControl(
+            option=opt.option,
+            metavar=opt.label.upper().replace(" ", "_"),
+            help_text=help_text,
+            default=value,
+        )
+        return opt, cli, self._get_value(cli, value)
+
+    def dropdown(
+        self,
+        options: list[str] | dict[str, typing.Any],
+        value: str | None = None,
+        option: str | None = None,
+        *,
+        help_text: str,
+        label: str | None = None,
+        allow_select_none: bool = True,
+        **kwargs: typing.Any,
+    ) -> mo.ui.dropdown:
+        """Create a dropdown UI element that maps to a CLI option."""
+
+        assert len(options) > 0, "Dropdown options cannot be empty"
+        opt = self._make_opt(label=label, option=option)
+        keys = list(options)
+        if value is None and not allow_select_none:
+            value, *_ = keys
+        cli = _options.DropdownControl(
+            option=opt.option,
+            allowed_values=keys,
+            supports_none=allow_select_none,
+            default=value,
+            help_text=help_text,
+        )
+        if self._is_overridden(opt.option):
+            # mo.ui.dropdown doesn't support disabled; filter to one option as a
+            # workaround so the user can't change the value. Remove once marimo adds
+            # disabled support for dropdowns.
+            override = self._overrides[self._override_key(opt.option)]
+            options = (
+                {override: None if override is None else options[override]}
+                if isinstance(options, dict)
+                else [override]
+            )
+        return self._cli_map.register(
+            mo.ui.dropdown(
+                options=options,
+                value=self._get_value(cli, value),
+                label=_label_with_help(opt.label, help_text),
+                allow_select_none=allow_select_none,
+                **kwargs,
+            ),
+            cli,
+        )
+
+    def _override_key(self, option: str) -> str:
+        option = option[len(self.option) :].lstrip("-")
+        if option.startswith("no-"):
+            option = option[3:]
+        return option.replace("-", "_")
+
+    def _get_value(
+        self,
+        control: _options.CliControl,
+        default: typing.Any,
+    ) -> typing.Any:
+        key = self._override_key(control.option)
+        if key in self._overrides:
+            return self._overrides[key]
+        if self._preset_state is not None:
+            match control.parse(self._preset_state.args):
+                case _options.ParseResult(value=v):
+                    return v
+                case _:
+                    pass
+        val = default
+        match control.parse(self._state.args):
+            case _options.ParseError(message=msg):
+                self._state.validation_errors[control.option] = msg
+            case _options.ParseResult(value=v):
+                val = v
+            case None:
+                pass
+        return val
+
+    def _is_overridden(self, option: str) -> bool:
+        return self._override_key(option) in self._overrides
+
+    def _make_opt(
+        self, label: str | None, option: str | None, prefix: str | None = None
+    ) -> _naming.OptionLabel:
+        opt = _naming.OptionLabel.make(label=label, option=option, prefix=prefix)
+        if self.option:
+            opt = _naming.OptionLabel(
+                label=opt.label,
+                option=f"{self.option}-{opt.option.lstrip('-')}",
+            )
+        return opt
+
+
+def _label_with_help(label: str, help_text: str) -> str:
+    return f'<span title="{html.escape(help_text, quote=True)}">{label}</span>'

moops-0.1.0/src/moops/interface.py

@@ -0,0 +1,226 @@
+import dataclasses
+import sys
+import typing
+
+import marimo as mo
+from hypothesis import strategies as st
+
+from . import _cli_map, _options, _parse
+from .presets import Presets
+
+
+@dataclasses.dataclass
+class Interface:
+    """Controls registered by a subgroup's interface, for passing to the parent."""
+
+    controls: tuple[typing.Any]
+    cli_map: _cli_map.CliMap = dataclasses.field(default_factory=_cli_map.CliMap)
+    overrides: dict[str, typing.Any] = dataclasses.field(default_factory=lambda: {})
+    notebook_name: str = ""
+    option_prefix: str = ""
+    presets: Presets | None = None
+    command: str = ""
+
+    def __post_init__(self) -> None:
+        seen_ids: set[int] = set()
+        for ctrl in self.controls:
+            if not isinstance(ctrl, Interface) and id(ctrl) in seen_ids:
+                raise ValueError("Duplicate control passed to interface")
+            seen_ids.add(id(ctrl))
+
+    def validate(self, state: _parse.ParseState) -> typing.Iterator[str]:
+        flags: set[str] = set()
+        value_options: set[str] = set()
+        for cli in self._all_cli_controls():
+            flags.update(cli.flags())
+            value_options.update(cli.options())
+        rendered = flags | value_options
+        yield from (v for k, v in state.validation_errors.items() if k in rendered)
+        unexp_text = "Unexpected argument: "
+        for x in state.args.unexpected:
+            yield f"{unexp_text}{x}"
+        for k, v in state.args.options.items():
+            if k in flags:
+                if v is not None:
+                    yield f"{k} does not take a value, but was given: {v}"
+            elif k in value_options:
+                if v is None:
+                    yield f"Option {k} requires a value"
+            elif k not in _parse.help_flags:
+                yield f"{unexp_text}{k}"
+
+    def help(self) -> str:
+        usage_parts = [
+            p for cli in self._all_cli_controls() for p in cli.format_usage_parts()
+        ]
+        usage_parts.append("[-h/--help]")
+        name = self.command.rsplit("/", 1)[-1]
+        segments = [f"Usage: {name} {' '.join(usage_parts)}"]
+        help_lines = [
+            line for cli in self._all_cli_controls() for line in cli.format_help_lines()
+        ]
+        if help_lines:
+            segments.append("\n".join(help_lines))
+        return "\n\n".join(segments)
+
+    @property
+    def default(self) -> dict[str, typing.Any]:
+        result: dict[str, typing.Any] = {}
+        for ctrl in self.controls:
+            if isinstance(ctrl, Interface):
+                prefix = ctrl.option_prefix.lstrip("-")
+                result[prefix] = ctrl.default
+            else:
+                cli = self.cli_map.get(ctrl)
+                if (
+                    cli is not None
+                    and not self._is_overridden(cli)
+                    and hasattr(cli, "default")
+                ):
+                    result[self._key(cli)] = cli.default  # type: ignore
+        return result
+
+    def strategy(self) -> st.SearchStrategy[dict[str, typing.Any]]:
+        strategies: dict[str, st.SearchStrategy[typing.Any]] = {}
+        for ctrl in self.controls:
+            if isinstance(ctrl, Interface):
+                prefix = ctrl.option_prefix.lstrip("-")
+                strategies[prefix] = ctrl.strategy()
+            else:
+                cli = self.cli_map.get(ctrl)
+                if cli is not None and not self._is_overridden(cli):
+                    strategies[self._key(cli)] = cli.strategy()
+        return st.fixed_dictionaries(strategies).map(
+            lambda d: {k: v for k, v in d.items() if v is not None}
+        )
+
+    def _all_cli_controls(self) -> typing.Iterator[_options.CliControl]:
+        for ctrl in self.controls:
+            if isinstance(ctrl, Interface):
+                yield from ctrl._all_cli_controls()
+            else:
+                cli = self.cli_map.get(ctrl)
+                if cli is not None and not self._is_overridden(cli):
+                    yield cli
+
+    def _key(self, cli: _options.CliControl) -> str:
+        option = cli.option[len(self.option_prefix) :].lstrip("-")
+        if option.startswith("no-"):
+            option = option[3:]
+        return option.replace("-", "_")
+
+    def _is_overridden(self, cli: _options.CliControl) -> bool:
+        return self._key(cli) in self.overrides
+
+    def cur_values(self) -> dict[str, typing.Any]:
+        result: dict[str, typing.Any] = {}
+        for ctrl in self.controls:
+            if isinstance(ctrl, Interface):
+                result.update(ctrl.cur_values())
+            else:
+                cli = self.cli_map.get(ctrl)
+                if cli is not None and not self._is_overridden(cli):
+                    result[cli.option] = _ctrl_value(ctrl)
+        return result
+
+    def _current_args(self) -> str:
+        values = self.cur_values()
+        return " ".join(
+            arg
+            for cli in self._all_cli_controls()
+            if cli.option in values
+            for arg in cli.format_value(values[cli.option])
+        )
+
+    def format_current_command(self) -> str:
+        args = self._current_args()
+        name = self.command.rsplit("/", 1)[-1]
+        return f"{name} {args}" if args else name
+
+    def missing_options(self) -> list[str]:
+        interface_ids = {id(ctrl) for ctrl in self.controls}
+        return [
+            cli.option
+            for ctrl_id, cli in self.cli_map.items()
+            if ctrl_id not in interface_ids
+        ]
+
+    def validate_or_exit(self, state: _parse.ParseState) -> None:
+        issues = list(self.validate(state))
+        if issues:
+            print("Argument errors:\n" + "\n".join(f"- {x}" for x in issues))
+            print()
+        if state.args.is_help or issues:
+            print(self.help())
+            sys.exit(1 if issues else 0)
+
+    def _mime_(self) -> tuple[str, str]:
+        if self.option_prefix:
+            return self._subgroup_summary()._mime_()  # type: ignore
+        return self._root_panel()._mime_()  # type: ignore
+
+    def _subgroup_summary(self) -> mo.Html:
+        if not self.notebook_name:
+            return mo.md("Cli bundle with no notebook name")
+        has_exposed = any(
+            not ctrl._component_args.get("disabled", False)
+            for ctrl in self._flatten()
+            if hasattr(ctrl, "_component_args")
+        )
+        prefix_note = (
+            f" (configured by the `{self.option_prefix}` options)"
+            if has_exposed
+            else ""
+        )
+        return mo.md(f"An embedded instance of `{self.notebook_name}`{prefix_note}.")
+
+    def _root_panel(self) -> mo.Html:
+        info = mo.md(
+            f"This notebook also works as a script:\n```\n{self.help()}\n```\n\n"
+            "To run the script with the current values in the notebook use:\n"
+            f"```\n{self.format_current_command()}\n```"
+        )
+        items: list[typing.Any] = [info]
+        if self.presets is not None:
+            current_args = self._current_args()
+            modified = current_args != (self.presets.selected_args or "")
+            name_input = mo.ui.text(
+                placeholder="preset name",
+                disabled=not modified,
+            )
+            save_btn = mo.ui.button(
+                label="Save preset",
+                on_click=lambda _: self.presets.save(  # type: ignore
+                    name_input.value, current_args
+                ),
+                disabled=not modified,
+            )
+            items.append(
+                mo.hstack(
+                    [self.presets, name_input, save_btn],
+                    justify="start",
+                )
+            )
+        missing_options = self.missing_options()
+        if missing_options:
+            items.append(
+                mo.callout(
+                    mo.md(
+                        "Missing options: "
+                        f"{', '.join(f'`{opt}`' for opt in missing_options)}"
+                    ),
+                    "warn",
+                )
+            )
+        return mo.vstack(items)
+
+    def _flatten(self) -> typing.Iterator[typing.Any]:
+        for ctrl in self.controls:
+            if isinstance(ctrl, Interface):
+                yield from ctrl._flatten()
+            else:
+                yield ctrl
+
+
+def _ctrl_value(ctrl: typing.Any) -> typing.Any:
+    return ctrl._selected_key if hasattr(ctrl, "_selected_key") else ctrl.value

moops-0.1.0/src/moops/presets.py

@@ -0,0 +1,32 @@
+import json
+import pathlib
+
+import marimo as mo
+
+
+class Presets(mo.ui.dropdown):
+    """Preset selector backed by a JSON file. Subclass of mo.ui.dropdown so it
+    drives marimo reactivity: cells that reference a Presets re-run when the
+    selection changes."""
+
+    def __init__(self, filename: str | pathlib.Path) -> None:
+        self._filename = pathlib.Path(filename)
+        self._data: dict[str, str] = {}
+        if self._filename.exists():
+            self._data = json.loads(self._filename.read_text()).get("presets", {})
+        super().__init__(
+            options=list(self._data),
+            value=None,
+            label="Preset",
+            allow_select_none=True,
+        )
+
+    @property
+    def selected_args(self) -> str | None:
+        return self._data.get(self.value) if self.value else None
+
+    def save(self, name: str, args: str) -> None:
+        if not name:
+            return
+        self._data[name] = args
+        self._filename.write_text(json.dumps({"presets": self._data}, indent=2))

moops-0.1.0/src/moops/testing.py

@@ -0,0 +1,8 @@
+import types
+
+from . import group, interface
+
+
+def notebook_interface(module: types.ModuleType) -> interface.Interface:
+    _, defs = module.app.run(defs={"args": group.Group.with_overrides({})})
+    return defs["interface"]