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
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
import sys
import pytest
from marimo._ast import toplevel
from marimo._ast.app import App, InternalApp
from marimo._ast.toplevel import (
TopLevelExtraction,
TopLevelStatus,
TopLevelType,
)
from marimo._ast.variables import BUILTINS
from marimo._dependencies.dependencies import DependencyManager
HAS_DUCKDB = DependencyManager.duckdb.has()
class TestTopLevelStatus:
@staticmethod
def test_expression_ignored(app) -> None:
@app.cell
def cell():
def add(a: int, b: int) -> int:
return a + b
_ = 1 # Needed for tests
status = TopLevelStatus.from_cell(cell._cell, BUILTINS)
assert status.type == TopLevelType.CELL
assert status.hint == toplevel.HINT_NOT_SINGLE
@staticmethod
def test_function_converted(app) -> None:
@app.cell
def cell():
def add(a: int, b: int) -> int:
return a + b
status = TopLevelStatus.from_cell(cell._cell, BUILTINS)
assert status.type == TopLevelType.TOPLEVEL
@staticmethod
def test_function_uses_top(app) -> None:
with app.setup:
c = 1e-16
@app.cell
def cell():
def add(a: int, b: int, offset: float = c) -> float:
return a + b + offset
status = TopLevelStatus.from_cell(cell._cell, BUILTINS | {"c"})
assert status.type == TopLevelType.TOPLEVEL
@staticmethod
def test_function_uses_top_fn(app) -> None:
@app.cell
def _():
def c() -> float:
return 1e-16
@app.cell
def cell(c):
def add(a: int, b: int, offset: float = c()) -> float:
return a + b + offset
status = TopLevelStatus.from_cell(cell._cell, BUILTINS | {"c"})
assert status.type == TopLevelType.TOPLEVEL
@staticmethod
def test_function_uses_top_fn_bad_order(app) -> None:
@app.cell
def cell(c):
def add(a: int, b: int, offset: float = c()) -> float:
return a + b + offset
@app.cell
def _():
def c() -> float:
return 1e-16
status = TopLevelStatus.from_cell(cell._cell, BUILTINS)
status.update(BUILTINS, set(), {"c"})
assert status.type == TopLevelType.CELL
assert status.hint == toplevel.HINT_ORDER_DEPENDENT.format({"c"})
@staticmethod
def test_function_not_top(app) -> None:
@app.cell
def _():
c = 1e-16
return c
@app.cell
def cell(c):
def add(a: int, b: int, offset: float = c) -> float:
return a + b + offset
status = TopLevelStatus.from_cell(cell._cell, BUILTINS)
assert status.type == TopLevelType.CELL
assert status.hint == toplevel.HINT_HAS_REFS.format({"c"})
@staticmethod
def test_injection_name_ignored(app) -> None:
@app.cell
def app():
def app(a: int, b: int) -> int:
return a + b
status = TopLevelStatus.from_cell(app._cell, BUILTINS)
assert status.type == TopLevelType.CELL
assert status.hint == toplevel.HINT_BAD_NAME
@staticmethod
def test_function_recursion(app) -> None:
@app.cell
def cell():
def fib(n: int) -> int:
if n <= 1:
return 1
return fib(n - 1) + fib(n - 2)
@app.cell
def _(fib):
assert fib(6) == 13
status = TopLevelStatus.from_cell(cell._cell, BUILTINS)
assert status.type == TopLevelType.TOPLEVEL
class TestTopLevelExtraction:
@staticmethod
def test_function_uses_top(app) -> None:
with app.setup:
c = 1e-16
@app.cell
def cell():
def add(a: int, b: int, offset: float = c) -> float:
return a + b + offset
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.TOPLEVEL] == [s.type for s in extraction]
@staticmethod
def test_decorator_reversed(app) -> None:
with app.setup:
from collections.abc import Callable # noqa: TC003
@app.cell
def second(wrap):
@wrap
def c() -> float:
return 1 + 1
@app.cell
def first():
def wrap(fn: Callable[[], float]) -> float:
return lambda: fn() + 1
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.CELL, TopLevelType.TOPLEVEL] == [
s.type for s in extraction
], [s.hint for s in extraction]
@staticmethod
def test_decorator(app) -> None:
with app.setup:
from collections.abc import Callable # noqa: TC003
@app.cell
def first():
def wrap(fn: Callable[[], float]) -> float:
return lambda: fn() + 1
@app.cell
def second(wrap):
@wrap
def c() -> float:
return 1 + 1
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.TOPLEVEL, TopLevelType.TOPLEVEL] == [
s.type for s in extraction
], [s.hint for s in extraction]
@staticmethod
def test_function_trailing_comment(app) -> None:
@app.cell
def cell():
def add(a: int, b: int) -> float:
return a + b
# Comment
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.CELL] == [s.type for s in extraction]
assert extraction.statuses[0].hint == toplevel.HINT_HAS_COMMENT
@staticmethod
def test_function_trailing_comment_ok(app) -> None:
@app.cell
def cell():
def add(a: int, b: int) -> float:
return a + b
# Comment
@app.cell
def tricky_cell():
def md() -> float:
return """
#"""
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.TOPLEVEL, TopLevelType.TOPLEVEL] == [
s.type for s in extraction
]
@staticmethod
def test_function_uses_top_fn_unresolved(app) -> None:
@app.cell
def cell(c):
def add(a: int, b: int) -> int:
return a + b + c()
@app.cell
def _():
def c() -> float:
return 1e-16
status = TopLevelStatus.from_cell(cell._cell, BUILTINS)
status.update(BUILTINS, set(), {"c"})
assert status.type == TopLevelType.UNRESOLVED
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.TOPLEVEL, TopLevelType.TOPLEVEL] == [
s.type for s in extraction
], [s.hint for s in extraction]
@staticmethod
def test_function_uses_top_fn_unresolved_path(app) -> None:
@app.cell
def cell(A, Z):
def a() -> float:
return A() + Z()
@app.cell
def _(B):
def A() -> float:
return B()
@app.cell
def _():
def B() -> float:
return 1.0
@app.cell
def _():
def Y() -> float:
return 1.0
@app.cell
def _(Y):
def Z() -> float:
return Y()
status = TopLevelStatus.from_cell(cell._cell, BUILTINS)
status.update(BUILTINS, set(), {"A", "B", "Y", "Z"})
assert status.type == TopLevelType.UNRESOLVED
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.TOPLEVEL,
] * 5 == [s.type for s in extraction], [s.hint for s in extraction]
@staticmethod
def test_function_uses_top_fn_unresolved_path_fails(app) -> None:
@app.cell
def cell(A, Z):
def a() -> float:
return A() + Z()
@app.cell
def _(B):
def A() -> float:
return B()
@app.cell
def _():
def B() -> float:
return 1.0
@app.cell
def _():
def Y() -> float:
return 1.0
# to make it a cell
@app.cell
def _(Y):
def Z() -> float:
return Y()
status = TopLevelStatus.from_cell(cell._cell, BUILTINS)
status.update(BUILTINS, set(), {"A", "B", "Y", "Z"})
assert status.type == TopLevelType.UNRESOLVED
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.CELL,
TopLevelType.TOPLEVEL,
TopLevelType.TOPLEVEL,
TopLevelType.CELL,
TopLevelType.CELL,
] == [s.type for s in extraction], [s.hint for s in extraction]
assert extraction.statuses[
0
].hint == toplevel.HINT_HAS_CLOSE_REFS.format({"Z"})
@staticmethod
def test_indirect_recursion() -> None:
app = App()
# Needed for consistent stack trace paths.
app._anonymous_file = True
# Renders, but fails in runtime (which is fine).
@app.cell
def first(c):
def add(a: int, b: int) -> int:
return a + b + c()
@app.cell
def second(add):
def c() -> float:
return add(1, 1)
status = TopLevelStatus.from_cell(first._cell, BUILTINS)
status.update(BUILTINS, set(), {"c", "add"})
assert status.type == TopLevelType.UNRESOLVED
status = TopLevelStatus.from_cell(second._cell, BUILTINS)
status.update(BUILTINS, {"add"}, {"c", "add"})
assert status.type == TopLevelType.UNRESOLVED
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.TOPLEVEL, TopLevelType.TOPLEVEL] == [
s.type for s in extraction
], [s.hint for s in extraction]
@staticmethod
def test_name_is_not_propagated(app) -> None:
@app.cell
def cell():
value = 1
@app.function
def to_be_demoted():
return value + 1 # type: ignore # noqa: F821
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.CELL,
TopLevelType.CELL,
] == [s.type for s in extraction], [s.hint for s in extraction]
assert ["cell", "_"] == [s.name for s in extraction], [
s.hint for s in extraction
]
@staticmethod
def test_variables_extracted(app) -> None:
with app.setup:
CONSTANT: int = 42
@app.cell
def _():
x: int = 2
# No typing
z = CONSTANT
return (x, z)
@app.cell
def _():
y: float = 2.0
return (y,)
extraction = TopLevelExtraction.from_app(InternalApp(app))
from marimo._ast.visitor import AnnotationData, VariableData
assert extraction.variables == {
"x": VariableData(
kind="variable",
required_refs={
"int",
},
unbounded_refs=set(),
annotation_data=AnnotationData(
repr="int",
refs={
"int",
},
),
import_data=None,
),
"y": VariableData(
kind="variable",
required_refs={
"float",
},
unbounded_refs=set(),
annotation_data=AnnotationData(
repr="float",
refs={
"float",
},
),
import_data=None,
),
"z": VariableData(
kind="variable",
required_refs={
"CONSTANT",
},
unbounded_refs=set(),
annotation_data=None,
import_data=None,
),
}
class TestTopLevelClasses:
@staticmethod
def test_class_converted(app) -> None:
@app.cell
def cell():
class Example: ...
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.TOPLEVEL,
] == [s.type for s in extraction], [s.hint for s in extraction]
@staticmethod
def test_subclassing_order(app) -> None:
@app.cell
def Example():
class Example: ...
@app.cell
def SubExample(Example):
class SubExample(Example): ...
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.TOPLEVEL,
TopLevelType.TOPLEVEL,
] == [s.type for s in extraction], [s.hint for s in extraction]
@staticmethod
def test_subclassing_scoped_vars(app) -> None:
@app.cell
def Example():
class Example: ...
@app.cell
def SubExample(A, Example):
class SubExample(Example):
def __init__(self):
self.a = A()
@app.cell
def _():
def A() -> float:
return 1.0
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.TOPLEVEL,
TopLevelType.TOPLEVEL,
TopLevelType.TOPLEVEL,
] == [s.type for s in extraction], [s.hint for s in extraction]
@staticmethod
def test_subclassing_order_vars(app) -> None:
@app.cell
def Example(A):
class Example:
a = A()
@app.cell
def _():
def A() -> float:
return 1.0
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.CELL,
TopLevelType.TOPLEVEL,
] == [s.type for s in extraction], [s.hint for s in extraction]
@staticmethod
def test_subclassing_order_vars_recursion(app) -> None:
@app.cell
def Example(A):
class Example:
class SubExample:
a = A()
@app.cell
def _():
def A() -> float:
return 1.0
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.CELL,
TopLevelType.TOPLEVEL,
] == [s.type for s in extraction], [s.hint for s in extraction]
@staticmethod
def test_subclassing_order_breaks(app) -> None:
@app.cell
def cell(Example):
class SubExample(Example): ...
@app.cell
def _():
class Example: ...
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.CELL,
TopLevelType.TOPLEVEL,
] == [s.type for s in extraction], [s.hint for s in extraction]
@staticmethod
def test_class_properties(app) -> None:
@app.class_definition
class Example:
@property
def prop(self) -> int:
return 1
@prop.setter
def prop(self, value: int) -> None:
pass
@app.function
def f():
return Example()
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.TOPLEVEL,
TopLevelType.TOPLEVEL,
] == [s.type for s in extraction], [s.hint for s in extraction]
@staticmethod
def test_class_invocation(app) -> None:
@app.class_definition
class Example: ...
@app.function
def f():
return Example()
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [
TopLevelType.TOPLEVEL,
TopLevelType.TOPLEVEL,
] == [s.type for s in extraction], [s.hint for s in extraction]
@staticmethod
def test_private_var(app) -> None:
@app.cell
def cell():
def _private():
return 1
status = TopLevelStatus.from_cell(cell._cell, BUILTINS)
assert status.type == TopLevelType.CELL, status.hint
assert status.hint == toplevel.HINT_NO_PRIVATES
@staticmethod
@pytest.mark.skipif(
sys.version_info < (3, 12),
reason="Requires Python 3.12+ for generic type parameter syntax",
)
def test_class_generic_type_parameter() -> None:
from marimo._ast.compiler import compile_cell
code = """\
class GenericTypeParameter[T]:
def __init__(self, value: T):
self.value = value
"""
cell = compile_cell(code, cell_id="test")
status = TopLevelStatus.from_cell(cell, BUILTINS)
assert status.type == TopLevelType.TOPLEVEL, status.hint
class TestTopLevelHook:
@staticmethod
def test_toplevel_hook(app) -> None:
@app.class_definition
class Example: ...
@app.cell()
def f():
def f():
return Example()
extraction = TopLevelExtraction.from_graph(
InternalApp(app).graph,
cell=f._cell,
)
assert [
TopLevelType.TOPLEVEL,
TopLevelType.TOPLEVEL,
] == [s.type for s in extraction], [s.hint for s in extraction]
@staticmethod
def test_class_builtin_ignored(app) -> None:
@app.cell
def cell():
class Example:
@staticmethod
def method() -> None:
print(__class__)
status = TopLevelStatus.from_cell(cell._cell, BUILTINS)
assert status.type == TopLevelType.TOPLEVEL
class TestTopLevelSQL:
@staticmethod
@pytest.mark.skipif(not HAS_DUCKDB, reason="Requires duckdb")
def test_sql_self_contained_two_calls(app) -> None:
"""Two separate duckdb.sql() calls (create then use) — should be TOPLEVEL."""
@app.function
def create_and_query():
import duckdb
duckdb.sql("CREATE TABLE t AS SELECT 1 AS id")
return duckdb.sql("SELECT * FROM t").df()
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.TOPLEVEL] == [s.type for s in extraction], [
s.hint for s in extraction
]
@staticmethod
@pytest.mark.skipif(not HAS_DUCKDB, reason="Requires duckdb")
def test_sql_self_contained_single_call(app) -> None:
"""Single duckdb.sql() with multiple statements (create then use) — should be TOPLEVEL."""
@app.function
def create_and_query():
import duckdb
return duckdb.sql(
"CREATE TABLE t AS SELECT 1 AS id; SELECT * FROM t"
).df()
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.TOPLEVEL] == [s.type for s in extraction], [
s.hint for s in extraction
]
@staticmethod
@pytest.mark.skipif(not HAS_DUCKDB, reason="Requires duckdb")
def test_sql_attach_detach_self_contained(app) -> None:
"""ATTACH/DETACH pattern — db alias defined in same function — should be TOPLEVEL."""
@app.function
def attach_and_query():
import duckdb
duckdb.sql(
"DETACH DATABASE IF EXISTS mydb; ATTACH DATABASE 'mydb.duckdb' AS mydb"
)
return duckdb.sql("SELECT * FROM mydb.users").df()
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.TOPLEVEL] == [s.type for s in extraction], [
s.hint for s in extraction
]
@staticmethod
@pytest.mark.skipif(not HAS_DUCKDB, reason="Requires duckdb")
def test_sql_external_refs_toplevel(app) -> None:
"""@app.function referencing external SQL tables — still TOPLEVEL.
SQL table references are runtime dependencies, not definition-time
dependencies, so they don't prevent a function from being top-level.
"""
@app.function
def query_external():
import duckdb
return duckdb.sql("SELECT * FROM some_external_table").df()
extraction = TopLevelExtraction.from_app(InternalApp(app))
assert [TopLevelType.TOPLEVEL] == [s.type for s in extraction], [
s.hint for s in extraction
]