moops 0.2.0__tar.gz → 0.3.0__tar.gz

{moops-0.2.0 → moops-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moops
-Version: 0.2.0
+Version: 0.3.0
 Summary: Write Marimo notebooks that also work as CLI scripts, with unified UI controls
 Keywords: marimo,notebooks,cli,testing
 Author: Yair Chuchem
@@ -100,6 +100,16 @@ those controls from the URL. Query keys use the same names as `moops.run`
 keyword arguments. For subgroups, use dot-separated names such as
 `?casing.style=camel_case`.
 
+## Presets
+
+Presets save and restore named groups of control values from a JSON file stored
+next to the calling notebook as `<notebook>_presets.json`.
+
+```python
+get_preset, set_preset = mo.state(None)
+args = moops.Group(presets=moops.Presets(get_preset, set_preset))
+```
+
 ## Custom notebook controls
 
 Use `args.custom()` when the notebook needs an interactive control that moops

{moops-0.2.0 → moops-0.3.0}/README.md

@@ -77,6 +77,16 @@ those controls from the URL. Query keys use the same names as `moops.run`
 keyword arguments. For subgroups, use dot-separated names such as
 `?casing.style=camel_case`.
 
+## Presets
+
+Presets save and restore named groups of control values from a JSON file stored
+next to the calling notebook as `<notebook>_presets.json`.
+
+```python
+get_preset, set_preset = mo.state(None)
+args = moops.Group(presets=moops.Presets(get_preset, set_preset))
+```
+
 ## Custom notebook controls
 
 Use `args.custom()` when the notebook needs an interactive control that moops

{moops-0.2.0 → moops-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "moops"
-version = "0.2.0"
+version = "0.3.0"
 description = "Write Marimo notebooks that also work as CLI scripts, with unified UI controls"
 license = "MIT"
 readme = "README.md"

{moops-0.2.0 → moops-0.3.0}/src/moops/_input_map.py

@@ -11,8 +11,15 @@ class InputMap:
         self._registered: weakref.WeakValueDictionary[str, _options.InputControl] = (
             weakref.WeakValueDictionary()
         )
+        self._ui_id_options: dict[typing.Any, str] = {}
 
     def register(self, control: typing.Any, cli: _options.InputControl) -> typing.Any:
+        ui_id = getattr(control, "_id", None)
+        if ui_id is not None:
+            old_option = self._ui_id_options.get(ui_id)
+            if old_option is not None and old_option != cli.option:
+                self._registered.pop(old_option, None)
+            self._ui_id_options[ui_id] = cli.option
         self._registered[cli.option] = cli
         control._moops_input = cli
         return control

moops-0.3.0/src/moops/_markdown.py

@@ -0,0 +1,47 @@
+def demote_markdown_headings(text: str, levels: int) -> str:
+    if levels <= 0:
+        return text
+
+    fence: tuple[str, int] | None = None
+    lines: list[str] = []
+    for line in text.splitlines(keepends=True):
+        content = line.rstrip("\r\n")
+        newline = line[len(content) :]
+        fence = _update_markdown_fence(content, fence)
+        lines.append(
+            content if fence is not None else _demote_markdown_heading(content, levels)
+        )
+        lines[-1] += newline
+    return "".join(lines)
+
+
+def _update_markdown_fence(
+    line: str, fence: tuple[str, int] | None
+) -> tuple[str, int] | None:
+    stripped = line.lstrip(" ")
+    if len(line) - len(stripped) > 3 or not stripped:
+        return fence
+    marker = stripped[0]
+    if marker not in "`~":
+        return fence
+    count = len(stripped) - len(stripped.lstrip(marker))
+    if count < 3:
+        return fence
+    if fence is None:
+        return (marker, count)
+    if marker == fence[0] and count >= fence[1] and not stripped[count:].strip():
+        return None
+    return fence
+
+
+def _demote_markdown_heading(line: str, levels: int) -> str:
+    stripped = line.lstrip(" ")
+    indent = len(line) - len(stripped)
+    if indent > 3:
+        return line
+    count = len(stripped) - len(stripped.lstrip("#"))
+    if not 1 <= count <= 6:
+        return line
+    if len(stripped) > count and not stripped[count].isspace():
+        return line
+    return f"{line[:indent]}{'#' * min(6, count + levels)}{stripped[count:]}"

{moops-0.2.0 → moops-0.3.0}/src/moops/_options.py

@@ -1,5 +1,6 @@
 import abc
 import dataclasses
+import json
 import math
 import pathlib
 import shlex
@@ -41,6 +42,10 @@ class InputControl(abc.ABC):
         """Flags for this control."""
         return set()
 
+    def allows_repeated_values(self) -> bool:
+        """Whether this control accepts repeated CLI values for the same option."""
+        return False
+
     @abc.abstractmethod
     def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
         """Parse from CLI args. Returns value, ParseError, or None if not provided."""
@@ -49,7 +54,7 @@ class InputControl(abc.ABC):
         """Parse a value supplied by a URL query parameter."""
 
         result = self.parse(
-            _parse.ParsedArgs(options={self.option: value}, unexpected=[])
+            _parse.ParsedArgs(options={self.option: [value]}, unexpected=[])
         )
         if result is None:
             raise RuntimeError(
@@ -82,7 +87,7 @@ class InputControl(abc.ABC):
     def prompt_interactive(
         self, effective_default: typing.Any = _UNSET
     ) -> dict[str, str | None]:
-        """Prompt the user for a value. Returns entries to inject into args.options.
+        """Prompt the user for a value. Returns option values to inject into args.
 
         effective_default overrides self.default for display when the caller
         has a better default (e.g. from a preset).
@@ -97,7 +102,7 @@ class FlagControl(InputControl):
         return {self.option}
 
     def parse(self, args: _parse.ParsedArgs) -> ParseResult | None:
-        return ParseResult(not self.default) if self.option in args.options else None
+        return ParseResult(not self.default) if args.has(self.option) else None
 
     def parse_query_value(self, value: str) -> ParseResult | ParseError:
         match value.lower():
@@ -164,7 +169,7 @@ class TextControl(ValueControl):
     default: str
 
     def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
-        res = args.options.get(self.option)
+        res = args.value_for(self.option)
         return None if res is None else ParseResult(res)
 
     def strategy(self) -> st.SearchStrategy:
@@ -217,6 +222,98 @@ class FileControl(TextControl):
             return result
 
 
+@dataclasses.dataclass
+class MultiFileControl(ValueControl):
+    default: list[str]
+
+    def allows_repeated_values(self) -> bool:
+        return True
+
+    def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
+        values = args.values_for(self.option)
+        if not values:
+            return None
+        flattened = [
+            part
+            for value in values
+            for part in (
+                value.splitlines()
+                if isinstance(value, str) and "\n" in value
+                else [value]
+            )
+            if part or part is None
+        ]
+        paths: list[str] = []
+        for value in flattened:
+            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}")
+            paths.append(value)
+        return ParseResult(paths)
+
+    def parse_query_value(self, value: str) -> ParseResult | ParseError:
+        try:
+            raw: typing.Any = json.loads(value)
+        except json.JSONDecodeError:
+            raw = [value] if value else []
+        if not isinstance(raw, list):
+            return ParseError(
+                f"Query parameter for {self.option} must be a JSON list of paths"
+            )
+        paths: list[str] = []
+        for item in typing.cast(list[typing.Any], raw):
+            if not isinstance(item, str):
+                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}")
+            paths.append(item)
+        return ParseResult(paths)
+
+    def strategy(self) -> st.SearchStrategy:
+        return st.lists(st.text())
+
+    def format_usage_parts(self) -> list[str]:
+        return [f"[{self.option} {self.metavar} ...]"]
+
+    def format_help_lines(self) -> list[str]:
+        line = f"  {self.option} {self.metavar}: {self.help_text}"
+        if self.default:
+            line += f" (default: {', '.join(self.default)})"
+        line += f" (repeat {self.option} to select multiple files)"
+        return [line]
+
+    def format_value(self, value: typing.Any) -> list[str]:
+        values = list(value)
+        if values == self.default:
+            return []
+        return [f"{self.option} {shlex.quote(v)}" for v in values]
+
+    def format_query_value(self, value: typing.Any) -> str | None:
+        values = list(value)
+        return None if values == self.default else json.dumps(values)
+
+    def prompt_interactive(
+        self, effective_default: typing.Any = _UNSET
+    ) -> dict[str, str | None]:
+        d = self.default if effective_default is _UNSET else effective_default
+        default_display = f" [{', '.join(d)}]" if d else ""
+        while True:
+            response = input(
+                f"{self.help_text} (comma-separated paths){default_display}: "
+            )
+            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}")
+                continue
+            return {self.option: "\n".join(paths)}
+
+
 @dataclasses.dataclass
 class TextAreaControl(ValueControl):
     default: str
@@ -229,15 +326,15 @@ class TextAreaControl(ValueControl):
         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:
+        if not mo.running_in_notebook() and args.has(self._stdin_flag):
+            if args.value_for(self._stdin_flag) is not None:
                 return None
-            if self.option in args.options:
+            if args.has(self.option):
                 return ParseError(
                     f"Cannot use both {self.option} and {self._stdin_flag}"
                 )
             return ParseResult(sys.stdin.read())
-        res = args.options.get(self.option)
+        res = args.value_for(self.option)
         return None if res is None else ParseResult(res)
 
     def strategy(self) -> st.SearchStrategy:
@@ -273,7 +370,7 @@ class NumberControl(ValueControl):
     default: Numeric | None
 
     def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
-        value = args.options.get(self.option)
+        value = args.value_for(self.option)
         return None if value is None else _parse_number(self.option, value)
 
     def strategy(self) -> st.SearchStrategy:
@@ -340,7 +437,7 @@ class RangeControl(ValueControl):
         )
 
     def parse(self, args: _parse.ParsedArgs) -> ParseResult | ParseError | None:
-        raw = args.options.get(self.option)
+        raw = args.value_for(self.option)
         if raw is None:
             return None
         values = raw.split(",")
@@ -460,11 +557,11 @@ class DropdownControl(InputControl):
 
     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:
+        if no_flag and args.has(no_flag):
+            if args.has(self.option):
                 return ParseError(f"Cannot use both {self.option} and {no_flag}")
             return ParseResult(None)
-        raw = args.options.get(self.option)
+        raw = args.value_for(self.option)
         if raw is None:
             return None
         if raw not in self.allowed_values:

{moops-0.2.0 → moops-0.3.0}/src/moops/_parse.py

@@ -9,22 +9,35 @@ interactive_flag = "--interactive"
 
 @dataclasses.dataclass
 class ParsedArgs:
-    options: dict[str, str | None]
+    options: dict[str, list[str | None]]
     unexpected: list[str]
 
+    def values_for(self, option: str) -> list[str | None]:
+        return self.options.get(option, [])
+
+    def value_for(self, option: str) -> str | None:
+        values = self.values_for(option)
+        return values[-1] if values else None
+
+    def has(self, option: str) -> bool:
+        return option in self.options
+
+    def set_value(self, option: str, value: str | None) -> None:
+        self.options[option] = [value]
+
     @property
     def is_help(self) -> bool:
-        return any(x in self.options for x in help_flags)
+        return any(self.has(x) for x in help_flags)
 
     @property
     def is_interactive(self) -> bool:
-        return interactive_flag in self.options
+        return self.has(interactive_flag)
 
     @classmethod
     def from_options(cls, args: list[str]) -> "ParsedArgs":
         """Parse a pre-tokenized list of options (no command name)."""
 
-        options: dict[str, str | None] = {}
+        options: dict[str, list[str | None]] = {}
         unexpected: list[str] = []
         prev = None
         for arg in args:
@@ -32,13 +45,13 @@ class ParsedArgs:
             if arg.startswith("-") and not (prev is not None and is_negative_num):
                 if "=" in arg:
                     key, value = arg.split("=", 1)
-                    options[key] = value
+                    options.setdefault(key, []).append(value)
                     prev = None
                 else:
-                    options[arg] = None
+                    options.setdefault(arg, []).append(None)
                     prev = arg
             elif prev is not None and prev.startswith("-"):
-                options[prev] = arg
+                options[prev][-1] = arg
                 prev = None
             else:
                 unexpected.append(arg)

{moops-0.2.0 → moops-0.3.0}/src/moops/group.py

@@ -10,7 +10,7 @@ import weakref
 
 import marimo as mo
 
-from . import _input_map, _naming, _options, _parse, _query_params, interface
+from . import _input_map, _markdown, _naming, _options, _parse, _query_params, interface
 from .interface import FileBrowserWithInitialSelection
 from .presets import Presets
 
@@ -43,6 +43,7 @@ class Group:
         self._default_preset_state = self._build_default_preset_state()
         self._active_preset = self._build_active_preset()
         self._parent_group: Group | None = None
+        self._markdown_heading_offset = 0
         self._subgroup_interfaces: dict[
             str, weakref.ReferenceType[interface.Interface]
         ] = {}
@@ -58,6 +59,7 @@ class Group:
         prefix: str,
         overrides: dict[str, typing.Any] | None = None,
         presets: Presets | None = None,
+        markdown_heading_offset: int = 1,
     ) -> Group:
         """Create a child Group that prefixes all its option names with '{prefix}-'.
 
@@ -67,11 +69,20 @@ class Group:
 
         Pass `presets=` to give the subgroup its own preset selector; otherwise
         it inherits the parent's preset state.
+
+        Markdown headings emitted by the subgroup are demoted by one level by
+        default. Pass `markdown_heading_offset=` to customize how many levels
+        this subgroup adds relative to its parent.
         """
+        if markdown_heading_offset < 0:
+            raise ValueError("markdown_heading_offset must be non-negative")
         child = type(self)([prefix])
         child._state = self._state
         child._cli_map = _input_map.InputMap()
         child._parent_group = self
+        child._markdown_heading_offset = (
+            self._markdown_heading_offset + markdown_heading_offset
+        )
         child._overrides = {**self._overrides.get(prefix, {}), **(overrides or {})}
         child.option = f"{self.option}-{prefix}" if self.option else f"--{prefix}"
         child._presets = presets
@@ -193,9 +204,12 @@ class Group:
         self._subgroup_interfaces = live_refs
         return missing
 
-    def md(self, text: str) -> mo.Html | None:
+    def md(self, text: str, *, notebook_only: bool = False) -> mo.Html | None:
         """Display markdown in notebooks or plain text in CLI."""
 
+        if notebook_only and not mo.running_in_notebook():
+            return None
+        text = _markdown.demote_markdown_headings(text, self._markdown_heading_offset)
         if mo.running_in_notebook():
             return mo.md(text)
         if self._state.args.is_help:
@@ -332,39 +346,44 @@ class Group:
         help_text: str,
         label: str | None = None,
         multiple: bool = True,
-        on_change: typing.Callable[[str], None] | None = None,
+        on_change: typing.Callable[[typing.Any], None] | None = None,
         **kwargs: typing.Any,
     ) -> FileBrowserWithInitialSelection | mo.ui.file_browser:
         """Create a file browser UI element that maps to a CLI path option."""
-        if multiple:
-            raise NotImplementedError("multiple=True is not yet supported")
-
         opt = self._make_opt(label=label, option=option)
         initial_path = str(initial_path)
-        cli = _options.FileControl(
-            option=opt.option,
-            metavar="PATH",
-            help_text=help_text,
-            default=initial_path,
-        )
-        value = self._get_value(cli, initial_path)
+        ctrl_opts = {
+            "option": opt.option,
+            "metavar": "PATH",
+            "help_text": help_text,
+        }
+        if multiple:
+            default: str | list[str] = [initial_path] if initial_path else []
+            cli = _options.MultiFileControl(default=default, **ctrl_opts)
+        else:
+            default = initial_path
+            cli = _options.FileControl(default=default, **ctrl_opts)
+        value = self._get_value(cli, default)
         raw_on_change = self._query_on_change(cli, on_change)
 
         def _on_change(infos: typing.Sequence[interface.FileBrowserFileInfo]) -> None:
             if raw_on_change is not None:
-                raw_on_change(str(infos[0].path) if infos else "")
+                paths = [str(info.path) for info in infos]
+                raw_on_change(paths if multiple else (paths[0] if paths else ""))
 
-        p = pathlib.Path(value) if value else None
+        paths = list(value) if multiple else ([value] if value else [])
+        first = paths[0] if paths else ""
+        p = pathlib.Path(first) if first else None
         browser_kwargs: dict[str, typing.Any] = dict(
-            initial_path=str(p.parent) if (p and p.is_file()) else (value or ""),
+            initial_path=str(p.parent) if (p and p.is_file()) else first,
             label=opt.label_with_tooltip(help_text),
             multiple=multiple,
             on_change=_on_change,
             **kwargs,
         )
         return self._cli_map.register(
-            FileBrowserWithInitialSelection(default=value, **browser_kwargs)
-            if value
+            FileBrowserWithInitialSelection(default=paths, **browser_kwargs)
+            if paths
             else mo.ui.file_browser(**browser_kwargs),
             cli,
         )
@@ -603,12 +622,12 @@ class Group:
                             case _:
                                 pass
                     try:
-                        self._state.args.options.update(
-                            control.prompt_interactive(effective_default)
-                        )
+                        prompted = control.prompt_interactive(effective_default)
                     except KeyboardInterrupt:
                         print("\nAborted.")
                         sys.exit(1)
+                    for option, value in prompted.items():
+                        self._state.args.set_value(option, value)
                     match control.parse(self._state.args):
                         case _options.ParseResult(value=v):
                             return v

{moops-0.2.0 → moops-0.3.0}/src/moops/interface.py

@@ -53,22 +53,27 @@ class Interface:
 
     def validate(self, state: _parse.ParseState) -> typing.Iterator[str]:
         flags: set[str] = set()
-        value_options: set[str] = set()
+        value_options: dict[str, _options.InputControl] = {}
         for cli in self._all_input_controls():
             flags.update(cli.flags())
-            value_options.update(cli.options())
-        rendered = flags | value_options
+            for option in cli.options():
+                value_options[option] = cli
+        rendered = flags | set(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():
+        for k, values 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}"
+                for v in values:
+                    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"
+                if len(values) > 1 and not value_options[k].allows_repeated_values():
+                    yield f"{k} was provided multiple times"
+                for v in values:
+                    if v is None:
+                        yield f"Option {k} requires a value"
             elif k not in _parse.help_flags and k != _parse.interactive_flag:
                 yield f"{unexp_text}{k}"
 
@@ -332,19 +337,22 @@ class _PresetsUI:
 class FileBrowserWithInitialSelection(mo.ui.file_browser):
     """Extends mo.ui.file_browser with a CLI path fallback when no file is selected."""
 
-    def __init__(self, default: str, **kwargs: typing.Any) -> None:
-        self._default = default
+    def __init__(
+        self, default: str | typing.Sequence[str], **kwargs: typing.Any
+    ) -> None:
+        self._default = [default] if isinstance(default, str) else list(default)
         super().__init__(**kwargs)
 
     @property
     def value(self) -> list[FileBrowserFileInfo]:  # type: ignore[override]
         if browser_value := list(super().value):
             return browser_value
-        p = pathlib.Path(self._default)
         return [
             FileBrowserFileInfo(
-                id=self._default, path=p, name=p.name, is_directory=p.is_dir()
+                id=default, path=p, name=p.name, is_directory=p.is_dir()
             )
+            for default in self._default
+            for p in [pathlib.Path(default)]
         ]
 
     @value.setter
@@ -353,13 +361,17 @@ class FileBrowserWithInitialSelection(mo.ui.file_browser):
         raise RuntimeError("Setting the value of a UIElement is not allowed.")
 
     def _mime_(self) -> tuple[str, str]:  # type: ignore[override]
+        files = "\n".join({f"- `{p}`" for p in self._default})
         return mo.vstack(
             [
                 mo.Html(super()._mime_()[1]),
                 mo.callout(
                     mo.md(
-                        "marimo's file browser does not support "
-                        f"an initial selection — falling back to `{self._default}`"
+                        "marimo's file browser "
+                        "[does not yet support an initial selection]"
+                        "(https://github.com/marimo-team/marimo/issues/7468). "
+                        "Falling back to:\n\n"
+                        f"{files}"
                     ),
                     kind="info",
                 ),
@@ -404,6 +416,9 @@ class CustomControl(UIElement[typing.Any, typing.Any]):
 
 def _ctrl_value(ctrl: typing.Any) -> typing.Any:
     if isinstance(ctrl, mo.ui.file_browser):
+        multiple = getattr(ctrl, "_component_args", {}).get("multiple", True)
+        if multiple:
+            return [str(info.path) for info in ctrl.value]
         p = ctrl.path()
         return str(p) if p is not None else ""
     return ctrl._selected_key if hasattr(ctrl, "_selected_key") else ctrl.value

{moops-0.2.0 → moops-0.3.0}/src/moops/presets.py

@@ -1,3 +1,4 @@
+import inspect
 import json
 import pathlib
 import typing
@@ -8,11 +9,14 @@ class Presets:
 
     def __init__(
         self,
-        filename: str | pathlib.Path,
         get_selected_preset: typing.Callable[[], str | None],
         set_selected_preset: typing.Callable[[str | None], None],
+        *,
+        filename: str | pathlib.Path | None = None,
     ) -> None:
-        self._filename = pathlib.Path(filename)
+        self._filename = (
+            pathlib.Path(filename) if filename is not None else _infer_filename()
+        )
         self.get_current = get_selected_preset
         self.select = set_selected_preset
         if self._filename.exists():
@@ -64,3 +68,32 @@ class Presets:
     def _write(self) -> None:
         with self._filename.open("w") as f:
             json.dump({"presets": self._data}, f, indent=2)
+
+
+def _infer_filename() -> pathlib.Path:
+    caller = _marimo_notebook_filename() or _stack_filename()
+    return caller.with_name(f"{caller.stem}_presets.json")
+
+
+def _marimo_notebook_filename() -> pathlib.Path | None:
+    try:
+        from marimo._runtime.context import ContextNotInitializedError, get_context
+    except ImportError:
+        return None
+
+    try:
+        filename = get_context().filename
+    except ContextNotInitializedError:
+        return None
+    if filename is None:
+        return None
+
+    path = pathlib.Path(filename)
+    return None if path.name.startswith("<") else path
+
+
+def _stack_filename() -> pathlib.Path:
+    caller = pathlib.Path(inspect.stack()[2].filename)
+    if caller.name.startswith("<"):
+        raise ValueError("Presets filename could not be inferred; pass a filename")
+    return caller