moops 0.1.0__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moops
-Version: 0.1.0
+Version: 0.2.0
 Summary: Write Marimo notebooks that also work as CLI scripts, with unified UI controls
 Keywords: marimo,notebooks,cli,testing
 Author: Yair Chuchem
@@ -23,6 +23,9 @@ Description-Content-Type: text/markdown
 
 # moops
 
+[![PyPI](https://img.shields.io/pypi/v/moops.svg)](https://pypi.org/project/moops/)
+[![Open in molab](https://marimo.io/molab-shield.svg)](https://molab.marimo.io/github/yairchu/moops/blob/main/examples/notebook.py)
+
 Easily write Marimo notebooks that work as CLI scripts (and more!) with minimal boilerplate.
 
 Marimo supports notebooks running as CLI scripts,
@@ -76,6 +79,52 @@ 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.
 
+## URL query parameters
+
+In browser notebooks, `Group()` lets URL query parameters initialize controls
+and keeps later control changes reflected in the URL.
+
+```python
+args = moops.Group()
+input_text = args.text(value="", help_text="Input text")
+style = args.dropdown(
+    ["snake_case", "camel_case"],
+    value="snake_case",
+    help_text="Output style",
+    allow_select_none=False,
+)
+```
+
+Opening the notebook with `?input_text=Hello&style=camel_case` initializes
+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`.
+
+## Custom notebook controls
+
+Use `args.custom()` when the notebook needs an interactive control that moops
+does not wrap directly, while the CLI should use a supported fallback control.
+The fallback supplies the CLI parser, help text, defaults, and query-parameter
+format.
+
+```python
+plot_selection = mo.ui.matplotlib(ax)
+fallback_slider = args.range_slider(
+    start=0,
+    stop=100,
+    value=[10, 50],
+    option="--x-range",
+    help_text="X axis range",
+)
+x_range = args.custom(
+    plot_selection,
+    fallback_slider,
+    value=lambda plot:
+        [plot.value.x_min, plot.value.x_max]
+        if plot.value else fallback_slider.value,
+)
+```
+
 ## 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.
@@ -99,6 +148,7 @@ From the project root:
 
 ```sh
 uv run examples/notebook.py
+uv run --with matplotlib --with numpy examples/custom_control.py --x-range 30,70
 ```
 
 Or `uv run marimo edit` to run as notebooks.

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

@@ -1,5 +1,8 @@
 # moops
 
+[![PyPI](https://img.shields.io/pypi/v/moops.svg)](https://pypi.org/project/moops/)
+[![Open in molab](https://marimo.io/molab-shield.svg)](https://molab.marimo.io/github/yairchu/moops/blob/main/examples/notebook.py)
+
 Easily write Marimo notebooks that work as CLI scripts (and more!) with minimal boilerplate.
 
 Marimo supports notebooks running as CLI scripts,
@@ -53,6 +56,52 @@ 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.
 
+## URL query parameters
+
+In browser notebooks, `Group()` lets URL query parameters initialize controls
+and keeps later control changes reflected in the URL.
+
+```python
+args = moops.Group()
+input_text = args.text(value="", help_text="Input text")
+style = args.dropdown(
+    ["snake_case", "camel_case"],
+    value="snake_case",
+    help_text="Output style",
+    allow_select_none=False,
+)
+```
+
+Opening the notebook with `?input_text=Hello&style=camel_case` initializes
+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`.
+
+## Custom notebook controls
+
+Use `args.custom()` when the notebook needs an interactive control that moops
+does not wrap directly, while the CLI should use a supported fallback control.
+The fallback supplies the CLI parser, help text, defaults, and query-parameter
+format.
+
+```python
+plot_selection = mo.ui.matplotlib(ax)
+fallback_slider = args.range_slider(
+    start=0,
+    stop=100,
+    value=[10, 50],
+    option="--x-range",
+    help_text="X axis range",
+)
+x_range = args.custom(
+    plot_selection,
+    fallback_slider,
+    value=lambda plot:
+        [plot.value.x_min, plot.value.x_max]
+        if plot.value else fallback_slider.value,
+)
+```
+
 ## 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.
@@ -76,6 +125,7 @@ From the project root:
 
 ```sh
 uv run examples/notebook.py
+uv run --with matplotlib --with numpy examples/custom_control.py --x-range 30,70
 ```
 
 Or `uv run marimo edit` to run as notebooks.

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "moops"
-version = "0.1.0"
+version = "0.2.0"
 description = "Write Marimo notebooks that also work as CLI scripts, with unified UI controls"
 license = "MIT"
 readme = "README.md"
@@ -39,6 +39,7 @@ dev-dependencies = [
     "pyright>=1.1.409",
     "pytest>=9.0.3",
     "vulture>=2.16",
+    "pymarkdownlnt>=0.9.37",
 ]
 
 [tool.pytest.ini_options]

moops-0.2.0/src/moops/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import version
+
+from ._run import run
+from .group import Group
+from .interface import Interface
+from .presets import Presets
+
+__version__ = version("moops")
+
+__all__ = ["Group", "Interface", "Presets", "__version__", "run"]

moops-0.2.0/src/moops/_input_map.py

@@ -0,0 +1,24 @@
+import typing
+import weakref
+
+from . import _options
+
+
+class InputMap:
+    """Maps UI controls to their input-channel counterparts."""
+
+    def __init__(self) -> None:
+        self._registered: weakref.WeakValueDictionary[str, _options.InputControl] = (
+            weakref.WeakValueDictionary()
+        )
+
+    def register(self, control: typing.Any, cli: _options.InputControl) -> typing.Any:
+        self._registered[cli.option] = cli
+        control._moops_input = cli
+        return control
+
+    def get(self, control: typing.Any) -> _options.InputControl | None:
+        return getattr(control, "_moops_input", None)
+
+    def registered_options(self) -> typing.Iterator[_options.InputControl]:
+        yield from self._registered.values()

{moops-0.1.0 → moops-0.2.0}/src/moops/_naming.py

@@ -1,4 +1,5 @@
 import dataclasses
+import html
 
 
 @dataclasses.dataclass
@@ -25,3 +26,9 @@ class OptionLabel:
             if label is None:
                 label = option.lstrip("-").replace("-", " ")
         return OptionLabel(label=label, option=option)
+
+    def label_with_tooltip(self, help_text: str) -> str:
+        return (
+            f'<span title="{html.escape(help_text, quote=True)} ({self.option})">'
+            f"{self.label}</span>"
+        )