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
Update `marimo config describe` output to use new config struct (#11373)
Martha Cryan97fd84a1b3c3
diff --git a/marimo/_cli/config/commands.py b/marimo/_cli/config/commands.pyindex 5c66b50dc0..46f8878651 100644--- a/marimo/_cli/config/commands.py+++ b/marimo/_cli/config/commands.py@@ -5,7 +5,10 @@ import osimport click-from marimo._cli.config.utils import highlight_toml_headers+from marimo._cli.config.utils import (+ format_config_docs,+ highlight_toml_headers,+)from marimo._cli.help_formatter import ColoredCommand, ColoredGroupfrom marimo._cli.print import echo, greenfrom marimo._config.manager import (@@ -57,74 +60,9 @@ def show() -> None:@click.command(cls=ColoredCommand, help="""Describe the marimo config.""")def describe() -> None:"""Print documentation for all config options."""- import inspect- from textwrap import indent-- import marimo._config.config as marimo_config- from marimo._cli.print import echo, green, muted, yellow-- def format_type_docs(cls: type, indent_level: int = 0) -> str:- """Recursively format type documentation."""- output: list[str] = []- # Get annotations and docs from the class- annotations = (- cls.__annotations__ if hasattr(cls, "__annotations__") else {}- )+ from marimo._config.config_schema import MarimoConfig- # Get the docstring- doc = inspect.getdoc(cls)- if doc and indent_level == 0:- output.append(muted(f"# {doc}\n"))-- for key, type_hint in annotations.items():- # Get field documentation if available- if hasattr(type_hint, "__forward_arg__"):- type_hint = type_hint.__forward_arg__- # Import from marimo._config.config- # If NotRequired, we need to get the type from the NotRequired- if str(type_hint).startswith("NotRequired["):- type_hint = type_hint[12:-1]-- if type_hint in marimo_config.__dict__ and "TypedDict" in str(- type(marimo_config.__dict__[type_hint])- ):- config = marimo_config.__dict__[type_hint]- field_output = f"[{green(key)}]"- output.append(indent(field_output, " " * indent_level))- # Get the docstring for the nested TypedDict- nested_doc = inspect.getdoc(config)- if nested_doc:- output.append(- indent(- muted(f"# {nested_doc}"),- " " * (indent_level + 1),- )- )- output.append("")- output.append(- indent(- format_type_docs(config, indent_level + 1),- " " * indent_level,- )- )- elif indent_level == 0:- output.append(f"[{green(key)}]")- output.append(muted(f"# {type_hint}"))- output.append("")- else:- output.append(- indent(- f"{yellow(key)}: {type_hint}", " " * indent_level- )- )- output.append("")- else:- field_output = f"{yellow(key)}: {type_hint}"- output.append(indent(field_output, " " * indent_level))-- return "\n".join(output)-- echo(format_type_docs(marimo_config.MarimoConfig))+ echo(format_config_docs(MarimoConfig))config.add_command(show)diff --git a/marimo/_cli/config/utils.py b/marimo/_cli/config/utils.pyindex 36516050b9..cfc84f4b6e 100644--- a/marimo/_cli/config/utils.py+++ b/marimo/_cli/config/utils.py@@ -1,7 +1,15 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from marimo._cli.print import orange+import inspect+import types+from typing import Annotated, Any, Literal, Union, get_args, get_origin++from msgspec import NODEFAULT, UNSET, Meta, UnsetType+from msgspec.structs import fields++from marimo._cli.print import cyan, green, muted, orange, yellow+from marimo._config.schema_utils import Configdef highlight_toml_headers(toml_string: str) -> str:@@ -16,3 +24,112 @@ def highlight_toml_headers(toml_string: str) -> str:highlighted_lines.append(line)return "\n".join(highlighted_lines)+++def _format_type(annotation: Any) -> str:+ origin = get_origin(annotation)+ args = get_args(annotation)+ if origin is Annotated:+ return _format_type(args[0])+ if origin in (Union, types.UnionType):+ return " | ".join(+ _format_type(arg) for arg in args if arg is not UnsetType+ )+ if origin is Literal:+ return "Literal[" + ", ".join(repr(arg) for arg in args) + "]"+ if origin is not None:+ return f"{origin.__name__}[{', '.join(_format_type(arg) for arg in args)}]"+ if annotation is type(None):+ return "None"+ return getattr(annotation, "__name__", str(annotation))+++def format_config_docs(cls: type[Config]) -> str:+ """Describe schema fields without loading config or dynamic defaults."""+ output: list[str] = []+ if doc := inspect.getdoc(cls):+ output.extend([doc, ""])++ def format_fields(+ cls: type[Config], path: str, level: int, experimental: bool = False+ ) -> None:+ prefix = " " * level+ for item in fields(cls):+ annotation = item.type+ metadata = Meta()+ if get_origin(annotation) is Annotated:+ annotation, *extras = get_args(annotation)+ metadata = next(+ (extra for extra in extras if isinstance(extra, Meta)),+ metadata,+ )+ variants = (+ get_args(annotation)+ if get_origin(annotation) in (Union, types.UnionType)+ else (annotation,)+ )+ present = [arg for arg in variants if arg is not UnsetType]+ nested = present[0] if len(present) == 1 else None+ field_path = (+ f"{path}.{item.encode_name}" if path else item.encode_name+ )+ section = (+ nested+ if isinstance(nested, type) and issubclass(nested, Config)+ else None+ )+ extra = metadata.extra or {}+ is_experimental = (+ experimental+ or bool(extra.get("experimental"))+ or field_path == "experimental"+ )+ labels: list[str] = []+ if extra.get("deprecated"):+ labels.append(orange("Deprecated"))+ if is_experimental:+ labels.append(muted("Experimental"))+ if extra.get("sensitive"):+ labels.append(cyan("Sensitive"))+ name = (+ green(f"[{field_path}]", bold=True)+ if section is not None+ else yellow(field_path)+ )+ heading = f"{prefix}{name}"+ if labels:+ heading += " (" + ", ".join(labels) + ")"+ if section is not None and level == 0:+ heading += " " + muted("─" * 32)+ output.append(heading)+ details_prefix = prefix + " "+ if metadata.description:+ output.extend(+ details_prefix + line+ for line in metadata.description.splitlines()+ )+ if section is not None:+ output.append("")+ format_fields(section, field_path, level + 1, is_experimental)+ else:+ output.append(+ details_prefix + muted(f"Type: {_format_type(annotation)}")+ )+ if item.default is UNSET:+ output.append("")+ continue+ elif item.default is not NODEFAULT:+ default = repr(item.default)+ elif item.default_factory in (dict, list):+ default = repr(item.default_factory())+ elif item.default_factory is not NODEFAULT:+ default = "dynamic"+ else:+ output.extend([details_prefix + muted("Required"), ""])+ continue+ output.extend(+ [details_prefix + muted(f"Default: {default}"), ""]+ )++ format_fields(cls, "", 0)+ return "\n".join(output).rstrip()diff --git a/marimo/_cli/print.py b/marimo/_cli/print.pyindex 56ef7d3ab3..3148d3e7fd 100644--- a/marimo/_cli/print.py+++ b/marimo/_cli/print.py@@ -67,7 +67,7 @@ class _StyleFn(Protocol):self,text: str,*,- fg: str | None = ...,+ fg: str | int | None = ...,bold: bool = ...,dim: bool = ...,) -> str: ...@@ -76,13 +76,15 @@ class _StyleFn(Protocol):def _ansi_style(text: str,*,- fg: str | None = None,+ fg: str | int | None = None,bold: bool = False,dim: bool = False,) -> str:"""Minimal ANSI fallback for environments without click (e.g. WASM)."""codes: list[int] = []- if fg and fg in _ANSI_COLORS:+ if isinstance(fg, int):+ codes.extend([38, 5, fg])+ elif fg and fg in _ANSI_COLORS:codes.append(_ANSI_COLORS[fg])if bold:codes.append(1)@@ -96,7 +98,7 @@ def _ansi_style(def _noop_style(text: str,*,- fg: str | None = None,+ fg: str | int | None = None,bold: bool = False,dim: bool = False,) -> str:@@ -135,7 +137,7 @@ def yellow(text: str, bold: bool = False) -> str:def orange(text: str, bold: bool = False) -> str:- return _style(text, fg="yellow", bold=bold)+ return _style(text, fg=208, bold=bold)def red(text: str, bold: bool = False) -> str:diff --git a/tests/_cli/test_cli_config.py b/tests/_cli/test_cli_config.pyindex e1e625077b..f6eba09410 100644--- a/tests/_cli/test_cli_config.py+++ b/tests/_cli/test_cli_config.py@@ -4,7 +4,12 @@ from __future__ import annotationsimport subprocessimport pytest+from click.testing import CliRunner+from inline_snapshot import snapshot+from marimo._cli.config.commands import config+from marimo._cli.config.utils import format_config_docs+from marimo._config.config_schema import MCPServerStdioConfig, SaveConfigfrom marimo._utils.platform import is_windows@@ -26,3 +31,102 @@ def test_config_describe() -> None:capture_output=True,)assert p.returncode == 0, p.stderr.decode()+++def test_config_describe_field_metadata() -> None:+ assert format_config_docs(SaveConfig) == snapshot(+ """\+Configuration for saving.++autosave+ one of `"off"` or `"after_delay"`+ Type: Literal['off', 'after_delay']+ Default: 'after_delay'++autosave_delay+ Delay in milliseconds before automatically saving.+ Type: int+ Default: 1000++format_on_save+ if `True`, format the code on save+ Type: bool+ Default: False"""+ )+++def test_config_describe_nested_and_optional_sections(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ # Describing the schema must not resolve config or environment defaults.+ monkeypatch.setenv("MARIMO_OUTPUT_MAX_BYTES", "invalid")+ monkeypatch.setenv("OPENAI_API_KEY", "secret-api-key")+ result = CliRunner().invoke(config, ["describe"])+ assert result.exit_code == 0, result.output+ output = result.output+ assert " [ai.models]\n" in output+ assert " [ai.open_ai]\n" in output+ assert "\n[experimental] (Experimental) " + "─" * 32 + "\n" in output+ assert "\n[cache] " + "─" * 32 + "\n" in output+ assert "\n[venv] " + "─" * 32 + "\n" in output+ assert "Enable live debugging with gutter breakpoints and pdb." in output+ assert "completion.model (Deprecated)\n" in output+ assert "completion.api_key (Deprecated, Sensitive)\n" in output+ assert "completion.codeium_api_key (Sensitive)\n" in output+ assert "completion.activate_on_typing (Sensitive)" not in output+ assert "experimental.debugger (Experimental)\n" in output+ assert "[Deprecated]" not in output+ assert "[Sensitive]" not in output+ assert (+ "Deprecated completion model. Use ai.models.autocomplete_model instead."+ in output+ )+ assert not any(+ line.lstrip().startswith("#") for line in output.splitlines()+ )+ assert "completion.activate_on_typing (Deprecated)" not in output+ assert (+ "display.custom_css\n list of paths to custom CSS files\n Type: list[str]"+ in output+ )+ assert (+ "ai.max_tokens\n the maximum number of tokens to use in AI completions\n Type: int | None"+ in output+ )+ assert "Default: unset" not in output+ assert "Default: dynamic" in output+ assert "Default: []" in output+ assert "Default: {}" in output+ assert (+ "dict[str, MCPServerStdioConfig | MCPServerStreamableHttpConfig]"+ in output+ )+ assert "UnsetType" not in output+ assert "Annotated" not in output+ assert "ClassVar" not in output+ assert "__marimo_transport__" not in output+ assert "secret-api-key" not in output+++def test_config_describe_required_and_nullable_fields() -> None:+ assert format_config_docs(MCPServerStdioConfig) == snapshot(+ """\+Configuration for STDIO transport MCP servers++command+ Command used to launch the MCP server.+ Type: str+ Required++args+ Arguments passed to the MCP server command.+ Type: list[str] | None++env (Sensitive)+ Environment variables supplied to the MCP server.+ Type: dict[str, str] | None++disabled+ Disable this MCP server.+ Type: bool | None"""+ )diff --git a/tests/_cli/test_cli_print.py b/tests/_cli/test_cli_print.pyindex 6c130c637f..06294a1df0 100644--- a/tests/_cli/test_cli_print.py+++ b/tests/_cli/test_cli_print.py@@ -4,6 +4,10 @@ from __future__ import annotationsimport iofrom contextlib import redirect_stderr, redirect_stdout+import click+import pytest++from marimo._cli import print as cli_printfrom marimo._cli.print import echo@@ -53,3 +57,19 @@ def test_echo_fallback_uses_stderr_encoding() -> None:with redirect_stderr(stream):echo("− err", err=True)assert _read(stream) == "\\u2212 err\n"++[email protected]("use_click", [True, False])+def test_orange_and_yellow_have_distinct_colors(+ monkeypatch: pytest.MonkeyPatch, use_click: bool+) -> None:+ monkeypatch.setattr(+ cli_print,+ "_style",+ click.style if use_click else cli_print._ansi_style,+ )+ reset_bold = "\033[22m" if use_click else ""+ assert cli_print.orange("(Deprecated)") == (+ f"\033[38;5;208m{reset_bold}(Deprecated)\033[0m"+ )+ assert cli_print.yellow("model") == f"\033[33m{reset_bold}model\033[0m"