A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
fix: handle private imports (#9704)
Dylan Madisettif08787ac0149
diff --git a/docs/guides/reactivity.md b/docs/guides/reactivity.mdindex 4cea874e47..49c23775b9 100644--- a/docs/guides/reactivity.md+++ b/docs/guides/reactivity.md@@ -168,6 +168,13 @@ Variables prefixed with an underscore (_e.g._, `_x`) are "local" to acell: they can't be read by other cells. Multiple cells can reuse the samelocal variables names.+!!! note "Underscore-prefixed imports"+ Imported names are also variables, so an import bound to an+ underscore-prefixed name (`import numpy as _np`, or `from ibis import _`)+ is local to the cell that imports it. When the imported symbol itself+ starts with an underscore and you want to use it across cells, alias it+ to a name without a leading underscore: `from ibis import _ as d`.+#### Encapsulating code in functionsIf you want most or all the variables in a cell to be temporary, prefixing eachdiff --git a/marimo/_ast/visitor.py b/marimo/_ast/visitor.pyindex a98b8f37e0..bd5efa01f9 100644--- a/marimo/_ast/visitor.py+++ b/marimo/_ast/visitor.py@@ -1021,16 +1021,21 @@ class ScopedVisitor(ast.NodeVisitor):)for block in reversed(self.block_stack):if block == self.block_stack[0]:- # At top-level scope: mangle only if the mangled name is- # already defined. When called from a nested scope- # (len > 1), also mangle even if the top-level block- # doesn't define it yet — this handles recursive calls to- # underscore-prefixed functions, where the function name- # isn't registered in the top-level block until after its- # body is visited.- if (- block.is_defined(mangled_name)- or len(self.block_stack) > 1+ # A local (underscore-prefixed) reference resolves+ # against the top-level block. Leave it raw only when+ # the raw name is a top-level definition, which happens+ # solely for no-alias underscore imports (`from pkg+ # import _c` — the user has no control over the+ # package's symbol name, so it is deliberately not+ # mangled). Everything else is mangled: names whose+ # mangled def exists, forward references (e.g. the body+ # of a recursive underscore-prefixed function, visited+ # before its name is registered), and references to+ # names this cell never defines — the latter guarantees+ # one cell's raw import can never leak into another+ # cell through the shared globals.+ if block.is_defined(mangled_name) or not block.is_defined(+ node.id):node.id = mangled_nameelif block.is_defined(node.id):diff --git a/marimo/_runtime/executor/executor.py b/marimo/_runtime/executor/executor.pyindex a75285feee..de47a2fbe9 100644--- a/marimo/_runtime/executor/executor.py+++ b/marimo/_runtime/executor/executor.py@@ -7,6 +7,7 @@ import asynciofrom typing import TYPE_CHECKING, Any, Protocolfrom marimo._ast.cell import _is_coroutine+from marimo._ast.variables import demangle_locals_in_textfrom marimo._runtime.exceptions import MarimoRuntimeExceptionfrom marimo._types.globals import MutableGlobals@@ -14,6 +15,21 @@ if TYPE_CHECKING:from marimo._ast.cell import CellImpl+def _demangle_name_error(e: BaseException) -> None:+ """Rewrite a NameError's message to use the name the user wrote.++ Cell-local (underscore-prefixed) references are compiled to mangled+ names (`_cell_<id>_x`); when one is undefined, CPython's message+ exposes the mangled form. The `name` attribute is left untouched for+ downstream consumers that resolve it structurally.+ """+ if isinstance(e, NameError) and e.args:+ e.args = tuple(+ demangle_locals_in_text(arg) if isinstance(arg, str) else arg+ for arg in e.args+ )++def _strip_frame(e: BaseException, count: int = 1) -> None:"""Drop the top `count` frames from `e.__traceback__`.@@ -61,6 +77,7 @@ class DefaultExecutor:except BaseException as e:# Strip our own frame so user-facing tracebacks start at user code._strip_frame(e)+ _demangle_name_error(e)raise MarimoRuntimeException from easync def execute_cell_async(@@ -81,4 +98,5 @@ class DefaultExecutor:raiseexcept BaseException as e:_strip_frame(e)+ _demangle_name_error(e)raise MarimoRuntimeException from ediff --git a/marimo/_runtime/runner/cell_runner.py b/marimo/_runtime/runner/cell_runner.pyindex 66c33daaf7..45295ae860 100644--- a/marimo/_runtime/runner/cell_runner.py+++ b/marimo/_runtime/runner/cell_runner.py@@ -1,6 +1,7 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations+import astimport asyncioimport ioimport traceback@@ -8,7 +9,11 @@ from pathlib import Pathfrom types import TracebackTypefrom typing import TYPE_CHECKING, Any-from marimo._ast.variables import unmangle_local+from marimo._ast.variables import (+ if_local_then_mangle,+ is_local,+ unmangle_local,+)from marimo._config.config import ExecutionType, MarimoConfig, OnCellChangeTypefrom marimo._dependencies.dependencies import DependencyManagerfrom marimo._dependencies.errors import ManyModulesNotFoundError@@ -61,6 +66,31 @@ if TYPE_CHECKING:from marimo._runtime.state import State+def _find_aliased_import(code: str, name: str) -> str | None:+ """If `code` imports `name`, return that import re-aliased publicly.++ Builds the suggestion statement for the cell-local NameError hint,+ e.g. `from ibis import _` -> "from ibis import _ as lib". Returns+ None when `code` doesn't parse or doesn't import `name`.+ """+ try:+ tree = ast.parse(code)+ except SyntaxError:+ return None+ alias_name = name.lstrip("_") or "lib"+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom):+ for alias in node.names:+ if (alias.asname or alias.name) == name:+ module = "." * node.level + (node.module or "")+ return f"from {module} import {alias.name} as {alias_name}"+ elif isinstance(node, ast.Import):+ for alias in node.names:+ if (alias.asname or alias.name.split(".")[0]) == name:+ return f"import {alias.name} as {alias_name}"+ return None++def _should_broadcast_data() -> bool:"""Whether data (variables, datasets, etc.) should be broadcast.@@ -393,6 +423,61 @@ class Runner:# Default to regular error for self reference in relaxed# mode.exception = unwrapped_exception+ elif (+ isinstance(unwrapped_exception, NameError)+ and (local_name := getattr(unwrapped_exception, "name", None))+ is not None+ and is_local(local_name)+ ):+ # A cell-local (underscore-prefixed) name that never resolved.+ # Such names are not graph definitions, so the MissingRef path+ # above cannot blame a cell; find one that defines it as a+ # temporary — either raw (no-alias underscore imports, which+ # are deliberately left unmangled) or mangled (every other+ # private). The failing reference may itself be mangled+ # (`_cell_<id>_x`); unmangle so the message and the search use+ # the name the user wrote. Prefer an import definition for the+ # blame: `_` in particular is commonly both an imported API+ # (`from ibis import _`) and a throwaway assignment in+ # unrelated cells.+ local_name, _ = unmangle_local(local_name)+ defining_cell: CellId_t | None = None+ aliased_import: str | None = None+ for cid, other in self.graph.cells.items():+ if cid == cell_id:+ continue+ if (+ local_name in other.temporaries+ or if_local_then_mangle(local_name, cid)+ in other.temporaries+ ):+ stmt = _find_aliased_import(other.code, local_name)+ if defining_cell is None or stmt is not None:+ defining_cell = cid+ aliased_import = stmt+ if stmt is not None:+ break+ if defining_cell is not None:+ if aliased_import is not None:+ remedy = (+ "To use it across cells, alias the import to a "+ "name without a leading underscore: "+ f"`{aliased_import}`."+ )+ else:+ remedy = (+ "To use it across cells, remove the leading "+ "underscore."+ )+ output = MarimoExceptionRaisedError(+ f"Name `{local_name}` is not defined. Names prefixed "+ "with an underscore are local to the cell that "+ f"defines them. {remedy} `{local_name}` is defined "+ "as a cell-local name in ",+ "NameError",+ defining_cell,+ )+ exception = output# Handle other special runtime errors.elif isinstance(unwrapped_exception,diff --git a/marimo/_save/hash.py b/marimo/_save/hash.pyindex cf433fc555..2ad2b9b13d 100644--- a/marimo/_save/hash.py+++ b/marimo/_save/hash.py@@ -690,7 +690,22 @@ class BlockHasher:imports = get_imports(scope)for local_ref in sorted(refs):ref = if_local_then_mangle(local_ref, self.cell_id)- if ref in imports:+ # An underscore import (e.g. `import marimo as _private`) is+ # mangled in the cell, but a cached function that references+ # it can surface the raw, unmangled name as a ref (its body+ # is hashed in the function scope). Depending on the path the+ # import may therefore appear in `imports` under either the+ # mangled `ref` or the raw `local_ref`. Accept either so the+ # module is treated as an import (and not pickled, which+ # would raise `cannot pickle 'module' object`).+ import_key: Name | None = (+ ref+ if ref in imports+ else local_ref+ if local_ref in imports+ else None+ )+ if import_key is not None:# TODO: There may be a way to tie this in with module watching.# e.g. module watcher could mutate the version number based# last updated timestamp.@@ -699,15 +714,18 @@ class BlockHasher:if self.pin_modules:# Fall back to the in-scope value (which may be a module# stub) so its replayed `__version__` reproduces the pinned- # hash.- module = sys.modules.get(imports[ref].module) or scope.get(- local_ref+ # hash. The scope may hold the module under either the+ # mangled or the raw name, mirroring `import_key`.+ module = (+ sys.modules.get(imports[import_key].module)+ or scope.get(ref)+ or scope.get(local_ref))version = getattr(module, "__version__", "") or ""if not version:module = sys.modules.get(- imports[ref].namespace- ) or scope.get(imports[ref].namespace)+ imports[import_key].namespace+ ) or scope.get(imports[import_key].namespace)version = getattr(module, "__version__", "") or ""content_serialization[ref] = type_sign(diff --git a/tests/_ast/test_visitor.py b/tests/_ast/test_visitor.pyindex 63a5c8c78d..f7ea1632ee 100644--- a/tests/_ast/test_visitor.py+++ b/tests/_ast/test_visitor.py@@ -2,6 +2,7 @@from __future__ import annotationsimport ast+import refrom inspect import cleandocfrom textwrap import dedent@@ -985,6 +986,109 @@ def test_relative_from_import() -> None:]+def test_underscore_as_imports_are_cell_local() -> None:+ # An underscore-prefixed `as` alias is mangled, i.e. it is treated as+ # a cell-local (private) name. This preserves the documented contract+ # that underscore-prefixed names are private and may be redefined+ # across cells: two cells may each `import numpy as _np` without a+ # MultipleDefinitionError. References to the alias within the cell+ # (including in a nested decorator/body scope) resolve to the mangled+ # name.+ prefix = "_cell_test_"+ cases = [+ ("import marimo as _mo", {f"{prefix}mo"}),+ ("import a.b as _c", {f"{prefix}c"}),+ ("from a.b import _c as _d", {f"{prefix}d"}),+ (+ "import marimo as _private\n"+ "@_private.cache\n"+ "def f(x):\n"+ " return _private.md('x')\n",+ {f"{prefix}private", "f"},+ ),+ # `from x import y as _p` referenced in nested scopes (class base,+ # decorator, function body) must mangle the references too, so the+ # cell-local definition and its uses stay consistent.+ (+ "from a.b import c as _private\nclass C(_private.X):\n pass\n",+ {f"{prefix}private", "C"},+ ),+ (+ "from a.b import c as _also_private\n"+ "@_also_private.deco\n"+ "def f(x):\n"+ " return _also_private.g(x)\n",+ {f"{prefix}also_private", "f"},+ ),+ ]+ for source, expected_defs in cases:+ v = visitor.ScopedVisitor(mangle_prefix="cell_test")+ mod = ast.parse(source)+ v.visit(mod)+ assert v.defs == expected_defs, source+ unparsed = ast.unparse(mod)+ # The alias is rewritten to its mangled, cell-local form.+ assert prefix in unparsed, (+ f"alias was not mangled in {source!r}: {unparsed!r}"+ )+ # No reference to the raw alias survives unmangled: every mangled+ # def has its raw counterpart fully rewritten (def *and* uses).+ for mangled in expected_defs:+ if not mangled.startswith(prefix):+ continue+ raw = "_" + mangled[len(prefix) :]+ assert re.search(rf"\b{re.escape(raw)}\b", unparsed) is None, (+ f"raw alias {raw!r} leaked unmangled in {source!r}: "+ f"{unparsed!r}"+ )+++def test_no_alias_underscore_import_refs_not_mangled() -> None:+ # Regression for #9151: a no-alias underscore import (e.g.+ # `from pkg import _camera`) defines the *raw* name, because the user+ # can't control the package's module name. References to it inside a+ # nested scope (class base, decorator, function body) must therefore+ # stay raw too, otherwise they resolve to an undefined mangled name+ # (`NameError: name '_cell_<id>_camera' is not defined`).+ prefix = "_cell_test_"+ cases = [+ # (source, expected_defs)+ ("from a.b import _c", {"_c"}),+ ("from a.b import _c, _d", {"_c", "_d"}),+ ("import _foo", {"_foo"}),+ # A dotted import with an underscore root has no resolvable local+ # name to mangle (`_private.submodule` is reached through the raw+ # root binding) — the case that ruled out mangling imports+ # wholesale.+ (+ "import _private.submodule\ny = _private.submodule.thing\n",+ {"_private", "y"},+ ),+ (+ "from a.b import _camera\nclass C(_camera.Observer):\n pass\n",+ {"_camera", "C"},+ ),+ (+ "from a.b import _camera\n"+ "@_camera.deco\n"+ "def f(x):\n"+ " return _camera.g(x)\n",+ {"_camera", "f"},+ ),+ ]+ for source, expected_defs in cases:+ v = visitor.ScopedVisitor(mangle_prefix="cell_test")+ mod = ast.parse(source)+ v.visit(mod)+ assert v.defs == expected_defs, source+ unparsed = ast.unparse(mod)+ # The raw import name is never mangled, neither at the definition+ # nor at any (possibly nested) reference.+ assert prefix not in unparsed, (+ f"no-alias import was mangled in {source!r}: {unparsed!r}"+ )++def test_from_import_star() -> None:expr = "from a.b.c import *"v = visitor.ScopedVisitor()diff --git a/tests/_runtime/test_runtime.py b/tests/_runtime/test_runtime.pyindex 1c392e0dd2..59bc726d06 100644--- a/tests/_runtime/test_runtime.py+++ b/tests/_runtime/test_runtime.py@@ -872,6 +872,127 @@ except NameError:assert "_sys" not in k.globalsassert k.globals["msize"] == sys.maxsize+ async def test_underscore_prefixed_import_in_cell(+ self, any_kernel: Kernel+ ) -> None:+ # An underscore-prefixed `as` alias is cell-local (mangled), but+ # must still resolve when used within the same cell, including in+ # a nested decorator/body scope.+ k = any_kernel+ await k.run(+ [+ ExecuteCellCommand(+ cell_id="0",+ code=(+ "import marimo as _mo\n"+ "@_mo.cache\n"+ "def f(x):\n"+ " return _mo.md(str(x))\n"+ "msg = f(1)"+ ),+ ),+ ]+ )+ assert not k.errors, k.errors+ # The alias is cell-local, so it never leaks into globals.+ assert "_mo" not in k.globals+ assert "1" in k.globals["msg"].text++ async def test_underscore_prefixed_import_across_cells_no_conflict(+ self, k: Kernel+ ) -> None:+ # Underscore-prefixed `as` aliases are cell-local/private: two+ # cells may each `import sys as _sys` without triggering a+ # MultipleDefinitionError. Each cell sees its own mangled binding.+ await k.run(+ [+ ExecuteCellCommand(+ cell_id="0",+ code="import sys as _sys; a = _sys.maxsize",+ ),+ ExecuteCellCommand(+ cell_id="1",+ code="import sys as _sys; b = _sys.maxsize",+ ),+ ]+ )+ assert not k.errors, k.errors+ assert k.globals["a"] == sys.maxsize+ assert k.globals["b"] == sys.maxsize+ # The private alias is not promoted to a graph def.+ assert "_sys" not in k.globals++ async def test_no_alias_underscore_import_nested_scope(+ self, any_kernel: Kernel+ ) -> None:+ # Regression for #9151 (MO-5835): a no-alias underscore import+ # (`from pkg import _name`) keeps its raw name — the user cannot+ # control the package's symbol name — so references to it in+ # nested scopes (function bodies, decorators, class bases) must+ # stay raw as well, not be mangled to `_cell_<id>_name`.+ k = any_kernel+ await k.run(+ [+ ExecuteCellCommand(+ cell_id="0",+ code=(+ "from marimo import _ast\n"+ "top = _ast.__name__\n"+ "def g():\n"+ " return _ast.__name__\n"+ "nested = g()"+ ),+ ),+ ]+ )+ assert not k.errors, k.errors+ assert k.globals["top"] == "marimo._ast"+ assert k.globals["nested"] == "marimo._ast"++ async def test_no_alias_underscore_import_is_cell_local(+ self, k: Kernel+ ) -> None:+ # MO-5949: a no-alias underscore import keeps its raw name but is+ # still cell-local — it never becomes a graph definition, so other+ # cells cannot read it.+ await k.run(+ [+ ExecuteCellCommand(+ cell_id="0",+ code="from marimo import _ast\na = _ast.__name__",+ ),+ ExecuteCellCommand(+ cell_id="1",+ code="b = _ast.__name__",+ ),+ ]+ )+ assert k.globals["a"] == "marimo._ast"+ # The import is not shared: the other cell fails with a NameError.+ assert "b" not in k.globals++ async def test_underscore_import_public_alias_is_shared(+ self, k: Kernel+ ) -> None:+ # MO-5949: aliasing an underscore-prefixed import to a name+ # without a leading underscore makes it a regular, shared+ # definition usable across cells.+ await k.run(+ [+ ExecuteCellCommand(+ cell_id="0",+ code="from marimo import _ast as ast_mod",+ ),+ ExecuteCellCommand(+ cell_id="1",+ code="c = ast_mod.__name__",+ ),+ ]+ )+ assert not k.errors, k.errors+ assert k.globals["c"] == "marimo._ast"+ assert "ast_mod" in k.globals+async def test_cell_transitioned_to_error_is_not_stale(self, lazy_kernel: Kernel) -> None:@@ -3825,6 +3946,66 @@ class TestErrorHandling:if sys.version_info >= (3, 13):assert "Did you mean: 'aaa'?" in errors[0].msg+ async def test_name_error_private_import_hint(+ self, mocked_kernel: MockedKernel, exec_req: ExecReqProvider+ ) -> None:+ # MO-6804 / #10223: referencing another cell's underscore import+ # (`from ibis import _`) fails because such names are cell-local.+ # The bare Python NameError is misleading; marimo should explain+ # the privacy rule and suggest aliasing the import.+ k = mocked_kernel.k+ await k.run(+ [+ exec_req.get(+ "import sys, types\n"+ "_mod = types.ModuleType('fakelib')\n"+ "_mod._ = 42\n"+ "sys.modules['fakelib'] = _mod\n"+ "ready = True"+ ),+ exec_req.get("ready\nfrom fakelib import _"),+ exec_req.get("res = _ + 1"),+ ]+ )+ assert "res" not in k.globals+ cell_notifications = mocked_kernel.stream.cell_notifications+ error_cell_notification = _filter_to_error_ops(cell_notifications)+ assert len(error_cell_notification) == 1+ errors = _parse_error_output(error_cell_notification[0])+ assert len(errors) == 1+ assert isinstance(errors[0], MarimoExceptionRaisedError)+ assert errors[0].exception_type == "NameError"+ assert "local to the cell" in errors[0].msg+ assert "`from fakelib import _ as lib`" in errors[0].msg+ # Blames the importing cell.+ assert errors[0].raising_cell is not None++ async def test_name_error_private_variable_hint(+ self, mocked_kernel: MockedKernel, exec_req: ExecReqProvider+ ) -> None:+ # Referencing another cell's private (underscore-prefixed)+ # variable produces a hint about the privacy rule rather than a+ # bare NameError with a mangled name.+ k = mocked_kernel.k+ await k.run(+ [+ exec_req.get("_x = 1"),+ exec_req.get("y = _x"),+ ]+ )+ assert "y" not in k.globals+ cell_notifications = mocked_kernel.stream.cell_notifications+ error_cell_notification = _filter_to_error_ops(cell_notifications)+ assert len(error_cell_notification) == 1+ errors = _parse_error_output(error_cell_notification[0])+ assert len(errors) == 1+ assert isinstance(errors[0], MarimoExceptionRaisedError)+ assert errors[0].exception_type == "NameError"+ # The message shows the name as written, not the mangled form.+ assert "Name `_x` is not defined" in errors[0].msg+ assert "remove the leading underscore" in errors[0].msg+ assert errors[0].raising_cell is not None+async def test_error_handling_in_run_mode_stop(self, run_mode_kernel: MockedKernel, exec_req: ExecReqProvider) -> None:diff --git a/tests/_save/test_cache.py b/tests/_save/test_cache.pyindex 853b69ea51..3958ba757d 100644--- a/tests/_save/test_cache.py+++ b/tests/_save/test_cache.py@@ -1111,6 +1111,62 @@ class TestCacheDecorator:assert k.stdout.messages.count("ran") == 1assert k.globals["foo"].hits == 3+ async def test_lru_cache_underscore_alias(+ self, k: Kernel, exec_req: ExecReqProvider+ ) -> None:+ # Regression: `import marimo as _private` (underscore alias) used to+ # blow up cache hashing because mangled scope keys (`_cell_<id>__private`)+ # don't match the unmangled-ref lookup used during the cache attempt.+ await k.run(+ [+ exec_req.get(+ """+ import marimo as _private++ @_private.lru_cache(maxsize=128)+ def f(x):+ return x * 2++ a = f(1)+ b = f(1)+ c = f(2)+ """+ ),+ ]+ )++ assert not k.stderr.messages, k.stderr+ assert k.globals["a"] == 2+ assert k.globals["b"] == 2+ assert k.globals["c"] == 4+ # Second `f(1)` should hit the cache.+ assert k.globals["f"].hits == 1++ async def test_cache_underscore_alias(+ self, k: Kernel, exec_req: ExecReqProvider+ ) -> None:+ await k.run(+ [+ exec_req.get(+ """+ import marimo as _private++ @_private.cache+ def f(x):+ return x * 3++ a = f(1)+ b = f(1)+ """+ ),+ ]+ )++ assert not k.stderr.messages, k.stderr+ assert k.globals["a"] == 3+ assert k.globals["b"] == 3+ assert k.globals["f"].hits == 1+async def test_persistent_cache(self, k: Kernel, exec_req: ExecReqProvider) -> None: