moutils 0.4.4

No project description provided

moutils

Utility functions used in marimo.

[!NOTE] This is a community led effort and not actively prioritized by the core marimo team.

Installation

pip install moutils

or with uv:

uv add moutils

Widgets

Widget	Description
URLHash	Get and set the URL hash
URLPath	Get and set the URL path
URLInfo	Read all URL components
DOMQuery	Query DOM elements with CSS selectors
CookieManager	Get, set, and monitor browser cookies
StorageItem	Read/write localStorage or sessionStorage
Slot	Render HTML with DOM event handlers
CopyToClipboard	Copy text to clipboard with a button
ShellWidget	Run terminal commands with live output
ColorScheme	Detect dark/light mode preference
ViewportSize	Detect window dimensions
OnlineStatus	Detect network connectivity
PageVisibility	Detect if the browser tab is active
Geolocation	Get the user's geographic coordinates
CameraCapture	Capture a still image from the webcam
Notification	Send browser notifications
KeyboardShortcut	Listen for global keyboard shortcuts
thread_map process_map interpreter_map	Thread/Process/Interpreter mapping
PrintPageButton	Button to open the browser print dialog
print_page()	Programmatically trigger the browser print dialog
ScreenshotButton	Button to capture a DOM element as PNG
screenshot()	Programmatically screenshot a DOM element

---

URLHash

Get and set the hash portion of the URL.

from moutils import URLHash
h = URLHash()
h.hash  # e.g. "#section-1"

URLPath

Get and set the current URL path.

from moutils import URLPath
p = URLPath()
p.path  # e.g. "/notebooks/demo"

URLInfo

Read all URL components (protocol, hostname, port, pathname, search, hash, etc.).

from moutils import URLInfo
info = URLInfo()
info.hostname  # e.g. "localhost"

DOMQuery

Query DOM elements using CSS selectors.

from moutils import DOMQuery
q = DOMQuery(selector=".my-class")
q.result  # list of matched element data

CookieManager

Get, set, and monitor browser cookies.

from moutils import CookieManager
cm = CookieManager()
cm.cookies  # dict of current cookies

StorageItem

Read and write data in the browser's localStorage or sessionStorage.

from moutils import StorageItem
s = StorageItem(key="my-key", storage_type="local")
s.data  # stored value

Slot

Render HTML content and handle DOM events (mouse, keyboard, form, drag, touch, pointer, scroll, clipboard, animation).

from moutils import Slot
s = Slot(children="<button>Click me</button>", on_dblclick=lambda e: print(e))

CopyToClipboard

Copy text to the clipboard with a button and success feedback.

from moutils import CopyToClipboard
c = CopyToClipboard(text="hello world")

ShellWidget

Run terminal commands in notebooks with real-time output streaming.

from moutils import shell

shell("ls -la")
shell("npm install", working_directory="./frontend")

ColorScheme

Detect the user's preferred color scheme (light or dark). Automatically updates when the preference changes.

from moutils import ColorScheme
cs = ColorScheme()
cs.scheme       # "light" or "dark"
cs.prefers_dark # True or False

ViewportSize

Detect the browser window dimensions. Updates on resize (debounced).

from moutils import ViewportSize
vs = ViewportSize()
vs.width   # e.g. 1920
vs.height  # e.g. 1080

OnlineStatus

Detect whether the browser has network connectivity.

from moutils import OnlineStatus
os_ = OnlineStatus()
os_.online  # True or False

PageVisibility

Detect whether the browser tab is currently active or hidden.

from moutils import PageVisibility
pv = PageVisibility()
pv.visible  # True or False
pv.state    # "visible" or "hidden"

Geolocation

Get the user's geographic coordinates. Opt-in — set enabled=True to request permission.

from moutils import Geolocation
geo = Geolocation(enabled=True)
geo.latitude   # e.g. 37.7749
geo.longitude  # e.g. -122.4194
geo.accuracy   # meters
geo.error      # error message, if any

CameraCapture

Capture a still image from the webcam. Opt-in — set enabled=True to request camera access.

from moutils import CameraCapture
cam = CameraCapture(enabled=True, width=640, height=480)
cam.image_data  # base64 data URL of the captured image

Notification

Send browser notifications. Automatically requests permission when needed.

from moutils import Notification
n = Notification(title="Done!", body="Your computation finished.")
n.send = True   # fires the notification
n.permission    # "default", "granted", or "denied"

KeyboardShortcut

Listen for global keyboard shortcuts with modifier key support.

from moutils import KeyboardShortcut
ks = KeyboardShortcut(shortcut="ctrl+k")
ks.pressed  # True when the shortcut is pressed
ks.event    # dict with key event details

thread_map, process_map, interpreter_map

Equivalent to list(map(fn, *iterables)) driven by ThreadPoolExecutor, ProcessPoolExecutor, or InterpreterPoolExecutor (python >= 3.14) from concurrent.futures, respectively, with a Marimo progress bar or spinner.

A spinner is used if the length cannot be automatically determined.

Inspired by https://tqdm.github.io/docs/contrib.concurrent/.

from moutils.concurrent import thread_map, process_map, interpreter_map

def add_one(x):
    return x + 1

results: list[int] = thread_map(add_one, range(1000))
# Can specify title, max_workers, etc.
results = process_map(add_one, range(1000), title="Process map", max_workers=2)
results = interpreter_map(add_one, range(1000)) # Only available for Python >=3.14

PrintPageButton

Button that opens the browser print dialog when clicked.

from moutils import PrintPageButton
btn = PrintPageButton()

print_page()

Programmatically trigger the browser print dialog.

import moutils
moutils.print_page()

ScreenshotButton

Button that captures a DOM element as a PNG and downloads it.

from moutils import ScreenshotButton
btn = ScreenshotButton(locator="#my-chart", filename="chart.png")

screenshot()

Programmatically screenshot a DOM element and download as PNG.

import moutils
moutils.screenshot(locator="#my-chart", filename="chart.png")

Development

We use uv for development.

Specific notebook

uv run marimo edit notebooks/example.py

Workspace

uv run --active marimo edit --port 2718

Installing pre-commit

uv tool install pre-commit
pre-commit

Testing

To run all tests:

pytest -v tests/