Accept a covariant Mapping of elements in ui.dictionary and .batch by winklemad · Pull Request #10653 · marimo-team/marimo

winklemad · 2026-08-25T10:57:18Z

This pull request was authored by a coding agent.

📝 Summary

dict is invariant, so typing the elements parameter as dict[str, UIElement[Any, Any]] makes static type checkers (mypy, Pyright/Pylance) reject valid subclass dictionaries — e.g. dict[str, mo.ui.checkbox] — even though they are perfectly fine at runtime. Users have to work around it with cast(dict[str, Any], elements).

Reproduction under mypy (marimo's CI type checker) on main:

import marimo as mo

checks: dict[str, mo.ui.checkbox] = {"a": mo.ui.checkbox()}
mo.ui.dictionary(checks)
# error: Argument 1 to "dictionary" has incompatible type
#        "dict[str, checkbox]"; expected "dict[str, UIElement[Any, Any]]"  [arg-type]
# note: "Dict" is invariant

Fix

The affected constructors only read elements — they immediately clone it into a fresh dict via validate_and_clone — so the parameter can be a read-only, covariant Mapping. Widened in:

ui.dictionary.__init__
the internal batch element __init__
validate_and_clone (the shared helper, per the maintainer's note on the issue)

validate_and_clone still returns a dict, and the internal _batch_base (which stores and mutates the mapping) keeps its dict type since it always receives the cloned dict. ui.array already uses the covariant Sequence, so it needs no change. Runtime behaviour is unchanged.

Verification

The mypy reproduction above goes from erroring to clean after the change.
mypy marimo reports no new errors in the changed files.
New regression tests build a ui.dictionary and call validate_and_clone from a read-only MappingProxyType (a non-dict Mapping), which fails if the parameter is ever narrowed back to dict.
test_dictionary.py + test_batch.py pass (11 tests); ruff format/ruff check clean.

📋 Pre-Review Checklist

For large changes, or changes that affect the public API: this change was discussed or approved through an issue — Typing: ui.dictionary.__init__ uses invariant dict[str, UIElement] and rejects dict[str, ui.checkbox] #10631 (labelled bug, contribution invited by a maintainer).
Any AI generated code has been reviewed line-by-line by the human PR author, who stands by it.
Video or media evidence is provided for any visual changes (optional).

✅ Merge Checklist

I have read the contributor guidelines.
Documentation has been updated where applicable, including docstrings for API changes.
Tests have been added for the changes made.

winklemad · 2026-08-25T10:57:20Z

I have read the CLA Document and I hereby sign the CLA

vercel · 2026-08-25T10:57:24Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview	Aug 28, 2026 3:56am

github-actions · 2026-08-25T10:57:32Z

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

Copilot

Pull request overview

This PR addresses a static typing limitation in marimo’s UI container APIs by widening elements inputs from invariant dict[...] to covariant Mapping[...], allowing type checkers to accept dictionaries of UIElement subclasses (e.g. dict[str, ui.checkbox]) without casts, while preserving existing runtime behavior by cloning into a fresh dict.

Changes:

Widened elements parameter types to Mapping[...] in ui.dictionary, ui.batch, and the shared validate_and_clone helper (still returning a concrete dict).
Added regression tests ensuring read-only mappings (e.g. MappingProxyType) are accepted and cloned correctly.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
tests/_plugins/ui/_impl/test_dictionary.py	Adds coverage that `ui.dictionary` accepts and clones a read-only `Mapping`.
tests/_plugins/ui/_impl/test_batch.py	Adds coverage that `validate_and_clone` accepts and clones a read-only `Mapping`.
marimo/_plugins/ui/_impl/dictionary.py	Widens `dictionary.__init__` `elements` typing to `Mapping[...]`.
marimo/_plugins/ui/_impl/batch.py	Widens `validate_and_clone` and `batch.__init__` `elements` typing to `Mapping[...]`.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

        self,
-        elements: dict[str, UIElement[Any, Any]],
+        elements: Mapping[str, UIElement[Any, Any]],
        *,
        label: str = "",
        on_change: Callable[[dict[str, object]], None] | None = None,


    def __init__(
        self,
        html: Html,
-        elements: dict[str, UIElement[Any, Any]],
+        elements: Mapping[str, UIElement[Any, Any]],
        on_change: Callable[[dict[str, object]], None] | None = None,


kirangadhave

Thanks @winklemad, I have a few change requests below. Also please rebase the branch from origin/main

kirangadhave · 2026-08-27T18:21:14Z

        md("Example {thing}").batch(thing={"key": "value"})  # type: ignore


+def test_validate_and_clone_accepts_readonly_mapping() -> None:


this test will run without any changes to batch.py because Python doesn't enforce annotations on runtime.

Typing only change requires a type-level test. See tests/_ast/test_app_typing.py for reference.

kirangadhave · 2026-08-27T18:21:30Z

    assert dictionary.value == {"a": 2, "b": "goodbye", "c": 1}


+def test_dictionary_accepts_readonly_mapping() -> None:


Same as: https://github.com/marimo-team/marimo/pull/10653/changes#r3874653890

kirangadhave · 2026-08-27T18:22:03Z

docstring still refers to dict

Suggested change

elements (Mapping): A dict of the batched elements (clones of the originals).

kirangadhave · 2026-08-27T18:22:22Z

docstring still refers to dict

Suggested change

elements (Mapping): A dict of the wrapped elements (clones of the originals).

kirangadhave · 2026-08-27T18:23:55Z

+def test_dictionary_accepts_readonly_mapping() -> None:
+    # `elements` is typed as a covariant Mapping, so any read-only mapping of
+    # UI elements (not just a plain dict) must be accepted and cloned.
+    from types import MappingProxyType


import at module level similar to other imports

kirangadhave · 2026-08-27T18:24:09Z

+    from types import MappingProxyType
+
+    from marimo._plugins.ui._impl.batch import validate_and_clone


import at module level similar to other imports

kirangadhave · 2026-08-27T18:24:44Z

        md("Example {thing}").batch(thing={"key": "value"})  # type: ignore


+def test_validate_and_clone_accepts_readonly_mapping() -> None:


nit: move the test to bottom. it separates two similar tests.

`dict` is invariant, so annotating the `elements` parameter as `dict[str, UIElement[Any, Any]]` made type checkers reject valid subclass dictionaries such as `dict[str, mo.ui.checkbox]`, forcing users to add casts. The constructors only read `elements` (they clone it into a fresh dict via `validate_and_clone`), so widen the parameter to a read-only `Mapping` in `ui.dictionary`, the internal `batch` element, and `validate_and_clone`. Runtime behaviour is unchanged. Add regression tests that build from a read-only `MappingProxyType`.

- Add basedpyright type-level tests (TestDictionaryTyping) that fail on the old invariant dict[...] param and pass on the covariant Mapping[...] one, so the typing change is actually guarded (runtime tests can't enforce annotations) - Update the batch/dictionary docstrings that still referred to dict - Hoist the MappingProxyType / validate_and_clone imports to module scope - Move the validate_and_clone test next to the other batch tests

winklemad · 2026-08-28T03:55:18Z

Thanks @kirangadhave — addressed all of these in ca31563:

Type-level test (the load-bearing one): added TestDictionaryTyping in tests/_ast/test_app_typing.py, following the existing _check_pyright pattern. The two snippets error on the old invariant dict[...] param and pass on the covariant Mapping[...], so the typing change is now genuinely guarded — basedpyright even suggests "switching from dict to Mapping which is covariant" on the old signature. (You're right that the runtime tests pass either way.)
Docstrings: updated the elements entries in batch.py / dictionary.py that still said dict.
Imports: hoisted MappingProxyType and validate_and_clone to module scope in both test files.
Nit: moved the validate_and_clone test down next to the other batch tests.
Rebased on origin/main.

Let me know if you'd like anything else.

…arimo-team#10653)

vercel Bot deployed to Preview August 25, 2026 10:58

View deployment

kirangadhave requested review from dmadisetti and kirangadhave and a lite review from Copilot and removed request for dmadisetti August 25, 2026 15:45

Copilot started reviewing on behalf of kirangadhave August 25, 2026 15:45

View session

Copilot AI reviewed Aug 25, 2026

View reviewed changes

kirangadhave mentioned this pull request Aug 26, 2026

fix: accept Mapping instead of dict for ui.dictionary/ui.batch elements #10667

Closed

4 tasks done

kirangadhave requested changes Aug 27, 2026

View reviewed changes

kirangadhave marked this pull request as ready for review August 27, 2026 18:25

winklemad added 2 commits August 28, 2026 09:24

winklemad force-pushed the fix/dictionary-batch-mapping-elements branch from 1d71f14 to ca31563 Compare August 28, 2026 03:55

vercel Bot deployed to Preview August 28, 2026 03:56

View deployment

kirangadhave approved these changes Aug 28, 2026

View reviewed changes

kirangadhave added the bug Something isn't working label Aug 31, 2026

kirangadhave merged commit 07921bd into marimo-team:main Aug 31, 2026
40 of 41 checks passed

kirangadhave mentioned this pull request Sep 1, 2026

fix: accept a covariant Mapping in tabs, accordion, and routes #10712

Merged

williambdean pushed a commit to williambdean/marimo that referenced this pull request Sep 6, 2026

Accept a covariant Mapping of elements in ui.dictionary and .batch (m…

26fa9aa

…arimo-team#10653)

		md("Example {thing}").batch(thing={"key": "value"}) # type: ignore


		def test_validate_and_clone_accepts_readonly_mapping() -> None:

		assert dictionary.value == {"a": 2, "b": "goodbye", "c": 1}


		def test_dictionary_accepts_readonly_mapping() -> None:


	elements (Mapping): A dict of the batched elements (clones of the originals).


	elements (Mapping): A dict of the wrapped elements (clones of the originals).

		from types import MappingProxyType

		from marimo._plugins.ui._impl.batch import validate_and_clone

Conversation

winklemad commented Aug 25, 2026

📝 Summary

Fix

Verification

📋 Pre-Review Checklist

✅ Merge Checklist

Uh oh!

winklemad commented Aug 25, 2026

Uh oh!

vercel Bot commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 25, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

kirangadhave left a comment

Choose a reason for hiding this comment

Uh oh!

kirangadhave Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

kirangadhave Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

kirangadhave Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

kirangadhave Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

kirangadhave Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

kirangadhave Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

kirangadhave Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

winklemad commented Aug 28, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented Aug 25, 2026 •

edited

Loading