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
[pre-commit.ci] pre-commit autoupdate (#10707)
pre-commit-ci[bot]b700da3457b1
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex d60b351721..ab9b229db8 100644--- a/.pre-commit-config.yaml+++ b/.pre-commit-config.yaml@@ -39,7 +39,7 @@ repos:types: [python]- repo: https://github.com/astral-sh/ruff-pre-commit- rev: v0.16.4+ rev: v0.16.7hooks:# Run the linter- id: ruff-check@@ -56,7 +56,7 @@ repos:# files: ^(frontend/src/|packages/)- repo: https://github.com/oxc-project/mirrors-oxfmt- rev: v0.65.0+ rev: v0.67.0hooks:- id: oxfmtargs: [--write, --config, .oxfmtrc.json]diff --git a/development_docs/adding_backend_and_mcp_tools.md b/development_docs/adding_backend_and_mcp_tools.mdindex 8e604fb5dd..dba0d9737b 100644--- a/development_docs/adding_backend_and_mcp_tools.md+++ b/development_docs/adding_backend_and_mcp_tools.md@@ -34,6 +34,7 @@ from marimo._types.ids import SessionId@dataclassclass YourToolArgs:"""Arguments for your tool."""+session_id: SessionId# Add other required parametersoptional_param: str = "default_value"@@ -42,6 +43,7 @@ class YourToolArgs:@dataclassclass YourToolOutput(SuccessResult):"""Output from your tool."""+# Add your output fieldsdata: dict = field(default_factory=dict)count: int = 0@@ -82,6 +84,7 @@ if TYPE_CHECKING:@dataclassclass YourToolArgs:"""Arguments for your tool."""+session_id: SessionId# Add parameters here@@ -89,6 +92,7 @@ class YourToolArgs:@dataclassclass YourToolOutput(SuccessResult):"""Output from your tool."""+# Add output fields heresample_dict: dict = field(default_factory=dict)@@ -410,6 +414,7 @@ def test_your_tool_error_handling(mock_context: Mock) -> None:assert exc_info.value.code == "SESSION_NOT_FOUND"+# if necessarydef test_your_tool_with_edge_cases(mock_context: Mock) -> None:"""Test edge cases and boundary conditions."""@@ -528,8 +533,7 @@ def handle(self, args: Args) -> Output:# Good: Using context methodsdef handle(self, args: Args) -> Output:errors = self.context.get_notebook_errors(- args.session_id,- include_stderr=True+ args.session_id, include_stderr=True)```---@@ -590,6 +594,7 @@ def handle(self, args: Args) -> Output:# Bad: Using TypedDict for tool input/outputfrom typing import TypedDict+class YourToolArgs(TypedDict):session_id: strcount: int@@ -603,6 +608,7 @@ class YourToolArgs(TypedDict):# Good: Using dataclasses as requiredfrom dataclasses import dataclass+@dataclassclass YourToolArgs:session_id: SessionIddiff --git a/marimo/AGENTS.md b/marimo/AGENTS.mdindex a52d44b9b2..a698167fe0 100644--- a/marimo/AGENTS.md+++ b/marimo/AGENTS.md@@ -17,11 +17,14 @@ Avoid individual property assertions, opt for full object comparisons.from inline_snapshot import snapshotfrom dirty_equals import IsStr+def test_function():- assert func() == snapshot({- "prop1": IsStr(),- "prop2": "some string",- })+ assert func() == snapshot(+ {+ "prop1": IsStr(),+ "prop2": "some string",+ }+ )```## Code Style@@ -37,5 +40,6 @@ Heavy dependencies must be imported lazily```pythondef get_dataframe():import pandas as pd # altair, duckdb, numpy, polars, pyarrow, sqlglot, etc.+return pd.DataFrame()```diff --git a/marimo/_server/ai/skills/marimo-pair/SKILL.md b/marimo/_server/ai/skills/marimo-pair/SKILL.mdindex 0fedea06bb..40e5496162 100644--- a/marimo/_server/ai/skills/marimo-pair/SKILL.md+++ b/marimo/_server/ai/skills/marimo-pair/SKILL.md@@ -47,6 +47,7 @@ Start every code-mode session with this dedicated `execute_code` call:```pythonimport marimo._code_mode as cm+help(cm)```@@ -180,9 +181,9 @@ and `ctx.graph` is the dataflow view.for cell in ctx.cells:cell # .id, .code, .name, .config, .status, .errors-ctx.cells["setup"] # by name-ctx.cells[0] # by position-list(ctx.cells.keys()) # all IDs, in notebook order+ctx.cells["setup"] # by name+ctx.cells[0] # by position+list(ctx.cells.keys()) # all IDs, in notebook order```Cell IDs are opaque strings which can be queried from the notebook or captured@@ -190,7 +191,7 @@ from `cm` return values:```pythoncid = ctx.create_cell("df = pd.read_csv('data.csv')")-print(cid) # e.g. 'Hbol'+print(cid) # e.g. 'Hbol'```Alternatively, cells can be assigned and referenced by `name`. The graph can be@@ -200,8 +201,8 @@ used to understand its role in the dataflow.for cid, impl in ctx.graph.cells.items():impl # .defs, .refs (sets of public names)-ctx.graph.descendants(cid) # cells that re-run when this one changes-ctx.graph.ancestors(cid) # cells this one depends on+ctx.graph.descendants(cid) # cells that re-run when this one changes+ctx.graph.ancestors(cid) # cells this one depends on```In marimo, deletes are _destructive_ so it can be useful to query thediff --git a/marimo/_server/ai/skills/marimo-pair/references/gotchas.md b/marimo/_server/ai/skills/marimo-pair/references/gotchas.mdindex b072de6a35..4a31e7b472 100644--- a/marimo/_server/ai/skills/marimo-pair/references/gotchas.md+++ b/marimo/_server/ai/skills/marimo-pair/references/gotchas.md@@ -11,10 +11,10 @@ This matters when building notebooks programmatically. A common mistake:```python# Cell A-_df = pd.DataFrame(results) # _df is private to this cell+_df = pd.DataFrame(results) # _df is private to this cell# Cell B — FAILS-mo.ui.table(_df) # NameError: name '_df' is not defined+mo.ui.table(_df) # NameError: name '_df' is not defined```**Fix:** Either merge both into one cell, or use a non-private name (`df`).@@ -30,7 +30,7 @@ incrementally — a second cell reassigns `df`, `results`, `data`, etc.df = pd.read_csv("data.csv")# Cell B — FAILS: df already defined in Cell A-df = df.dropna() # Multiply-defined names: df+df = df.dropna() # Multiply-defined names: df```**Fix — pick one:**@@ -65,6 +65,7 @@ tree = ast.parse(src) # IndentationError: unexpected indent# FIXimport textwrap+src = textwrap.dedent(inspect.getsource(SomeClass.some_method))tree = ast.parse(src)```@@ -87,6 +88,7 @@ persist in the notebook.```pythonimport pyarrow as _paimport polars.dataframe.frame as _frame_mod+_frame_mod.pa = _pa```diff --git a/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md b/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.mdindex c04cc78338..e460a166eb 100644--- a/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md+++ b/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md@@ -38,10 +38,13 @@ one and hoist scattered imports into it. `name="setup"` auto-positions the cellfirst — no `before`/`after` needed:```python-cid = ctx.create_cell('''import polars as pl+cid = ctx.create_cell(+ """import polars as plimport marimo as moimport anywidget-import traitlets''', name="setup")+import traitlets""",+ name="setup",+)ctx.run_cell(cid)```@@ -68,9 +71,11 @@ cell-internal helpers that aren't meant to be reused.objects = pl.read_csv("https://example.com/objects.csv")artists = pl.read_csv("https://example.com/artists.csv")+def top_counts(df, col, n=5):return df.group_by(col).len().sort("len", descending=True).head(n)+result = top_counts(objects.join(artists, on="id"), "category")```@@ -99,6 +104,7 @@ def load_data():artists = pl.read_csv("https://example.com/artists.csv")return objects.join(artists, on="id", how="left")+df = load_data()```diff --git a/marimo/_server/ai/skills/marimo-pair/references/rich-representations.md b/marimo/_server/ai/skills/marimo-pair/references/rich-representations.mdindex 67987ad588..ac0cfc42c4 100644--- a/marimo/_server/ai/skills/marimo-pair/references/rich-representations.md+++ b/marimo/_server/ai/skills/marimo-pair/references/rich-representations.md@@ -62,6 +62,7 @@ When unsure, check in the scratchpad:```pythonimport anywidget+obj = scatter.widget # or whatever accessor the library providesprint(isinstance(obj, anywidget.AnyWidget)) # True = marimo can render it```@@ -155,6 +156,7 @@ export default () => {};"""+class Timer(anywidget.AnyWidget):seconds = traitlets.Int(0).tag(sync=True)running = traitlets.Bool(True).tag(sync=True)@@ -180,7 +182,9 @@ timer # display the widget```python# Cell 2 — reacts to changesseconds = get_seconds()-mo.md(f"Timer is at **{seconds}s** — {'running' if seconds > 0 else 'stopped'}")+mo.md(+ f"Timer is at **{seconds}s** — {'running' if seconds > 0 else 'stopped'}"+)```The common pattern is `mo.state(widget.trait)` for the initial value,@@ -213,11 +217,12 @@ justifies it.```python# Polars (native, no pyarrow needed)-_ipc=df.write_ipc(None).getvalue()+_ipc = df.write_ipc(None).getvalue()# Any __arrow_c_stream__ source (pandas, narwhals, pyarrow, etc.)import io, pyarrow as pa, pyarrow.feather as feather+def to_arrow_ipc(data) -> bytes:table = pa.RecordBatchReader.from_stream(data).read_all()sink = io.BytesIO()@@ -271,8 +276,8 @@ Two strategies for reactive anywidgets. Choose one per widget — don't mix themRead widget state or set UI controls from the scratchpad — no clicking:```python-print(timer.seconds) # read-timer.seconds = 0 # set — frontend updates automatically+print(timer.seconds) # read+timer.seconds = 0 # set — frontend updates automatically````mo.ui.*` elements need `ctx.set_ui_value(...)` from code mode; anywidgets use@@ -290,6 +295,7 @@ Precedence: `_display_()` > built-in formatters > `_mime_()` > IPythonfrom dataclasses import dataclassimport marimo as mo+@dataclassclass ColorSwatch:colors: list[str]diff --git a/tests/_utils/snapshots/docstring_summary.md b/tests/_utils/snapshots/docstring_summary.mdindex fc52f6a989..51606fc17d 100644--- a/tests/_utils/snapshots/docstring_summary.md+++ b/tests/_utils/snapshots/docstring_summary.md@@ -3,7 +3,7 @@ This is the summary.# Examples```python-print('Hello, world!')+print("Hello, world!")print(foo, bar)```diff --git a/tests/_utils/test_docs.py b/tests/_utils/test_docs.pyindex 61c88b3035..744c1e5a06 100644--- a/tests/_utils/test_docs.py+++ b/tests/_utils/test_docs.py@@ -28,7 +28,7 @@ def test_google_docstring_to_markdown_summary():Examples:```python- print('Hello, world!')+ print("Hello, world!")print(foo, bar)```"""@@ -50,7 +50,7 @@ def test_google_docstring_to_markdown_summary():"ValueError","# Examples","```python",- "print('Hello, world!')",+ 'print("Hello, world!")',]:assert substr in md_result