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
from typing import Literal
from unittest.mock import Mock, patch
import pytest
from marimo._dependencies.dependencies import DependencyManager
from marimo._sql.utils import convert_to_output
native_result = {"data": "native_result"}
polars_result = {"data": "polars_result"}
pandas_result = {"data": "pandas_result"}
lazy_polars_result = {"data": "lazy_polars_result"}
MockFunctions = Literal[
"to_native", "to_polars", "to_pandas", "to_lazy_polars"
]
MockFnDict = dict[MockFunctions, Mock]
@pytest.fixture
def mock_functions() -> MockFnDict:
"""Returns a dictionary of mock conversion functions keyed by their names."""
return {
"to_native": Mock(return_value=native_result),
"to_polars": Mock(return_value=polars_result),
"to_pandas": Mock(return_value=pandas_result),
"to_lazy_polars": Mock(return_value=lazy_polars_result),
}
def assert_only_one_called(
mock_functions: MockFnDict, function_name: MockFunctions
) -> None:
"""Assert that only the specified mock function was called."""
for name, mock_fn in mock_functions.items():
if name == function_name:
mock_fn.assert_called_once()
else:
mock_fn.assert_not_called()
def assert_multiple_called_once(
mock_functions: MockFnDict, expected_called: list[MockFunctions]
) -> None:
"""Assert that only the specified mock functions were called once each."""
for name, mock_fn in mock_functions.items():
if name in expected_called:
mock_fn.assert_called_once()
else:
mock_fn.assert_not_called()
class TestNativeOutputFormat:
"""Test different native output format scenarios."""
def test_with_to_native(self, mock_functions: MockFnDict) -> None:
"""Test native output format when to_native is provided."""
result = convert_to_output(
sql_output_format="native",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
to_native=mock_functions["to_native"],
)
assert result == native_result
assert_only_one_called(mock_functions, "to_native")
def test_without_to_native(self, mock_functions: MockFnDict) -> None:
"""Test native output format when to_native is not provided."""
with pytest.raises(
ValueError, match="to_native is required for native output format"
):
convert_to_output(
sql_output_format="native",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
class TestPolarsOutputFormat:
"""Test polars output format scenarios."""
@pytest.mark.skipif(
not DependencyManager.polars.has(),
reason="Polars is not installed",
)
def test_polars_format(self, mock_functions: MockFnDict) -> None:
"""Test polars output format."""
result = convert_to_output(
sql_output_format="polars",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
assert result == polars_result
assert_only_one_called(mock_functions, "to_polars")
@pytest.mark.skipif(
not DependencyManager.polars.has(),
reason="Polars is not installed",
)
class TestLazyPolarsOutputFormat:
"""Test lazy-polars output format scenarios."""
def test_with_to_lazy_polars(self, mock_functions: MockFnDict) -> None:
"""Test lazy-polars output format when to_lazy_polars is provided."""
result = convert_to_output(
sql_output_format="lazy-polars",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
to_lazy_polars=mock_functions["to_lazy_polars"],
)
assert result == lazy_polars_result
assert_only_one_called(mock_functions, "to_lazy_polars")
def test_without_to_lazy_polars_dataframe(
self, mock_functions: MockFnDict
) -> None:
"""Test lazy-polars output format when to_lazy_polars is not provided and to_polars returns DataFrame."""
mock_dataframe = Mock()
mock_lazy_frame = Mock()
mock_dataframe.lazy.return_value = mock_lazy_frame
mock_functions["to_polars"].return_value = mock_dataframe
result = convert_to_output(
sql_output_format="lazy-polars",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
assert result == mock_lazy_frame
mock_functions["to_polars"].assert_called_once()
mock_dataframe.lazy.assert_called_once()
mock_functions["to_pandas"].assert_not_called()
def test_without_to_lazy_polars_series(
self, mock_functions: MockFnDict
) -> None:
"""Test lazy-polars output format when to_lazy_polars is not provided and to_polars returns Series."""
import polars as pl
mock_series = Mock(spec=pl.Series)
mock_frame = Mock()
mock_lazy_frame = Mock()
mock_series.to_frame.return_value = mock_frame
mock_frame.lazy.return_value = mock_lazy_frame
mock_functions["to_polars"].return_value = mock_series
result = convert_to_output(
sql_output_format="lazy-polars",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
assert result == mock_lazy_frame
mock_functions["to_polars"].assert_called_once()
mock_series.to_frame.assert_called_once()
mock_frame.lazy.assert_called_once()
mock_functions["to_pandas"].assert_not_called()
@pytest.mark.skipif(
not DependencyManager.pandas.has(),
reason="Pandas is not installed",
)
class TestPandasOutputFormat:
"""Test pandas output format scenarios."""
def test_pandas_format(self, mock_functions: MockFnDict) -> None:
"""Test pandas output format."""
result = convert_to_output(
sql_output_format="pandas",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
assert result == pandas_result
assert_only_one_called(mock_functions, "to_pandas")
class TestAutoOutputFormat:
"""Test auto output format scenarios."""
@pytest.mark.skipif(
not DependencyManager.polars.has(),
reason="Polars is not installed",
)
@patch("marimo._sql.utils.DependencyManager")
def test_with_polars_success(
self, mock_dependency_manager: Mock, mock_functions: MockFnDict
) -> None:
"""Test auto output format when polars is available and succeeds."""
mock_dependency_manager.polars.has.return_value = True
mock_dependency_manager.pandas.has.return_value = False
result = convert_to_output(
sql_output_format="auto",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
assert result == polars_result
assert_only_one_called(mock_functions, "to_polars")
@pytest.mark.skipif(
not DependencyManager.polars.has(),
reason="Polars is not installed",
)
@patch("marimo._sql.utils.DependencyManager")
@patch("marimo._sql.utils.LOGGER")
def test_with_polars_failure_fallback_to_pandas(
self,
mock_logger: Mock,
mock_dependency_manager: Mock,
mock_functions: MockFnDict,
) -> None:
"""Test auto output format when polars fails and falls back to pandas."""
mock_dependency_manager.polars.has.return_value = True
mock_dependency_manager.pandas.has.return_value = True
import polars as pl
mock_functions["to_polars"].side_effect = pl.exceptions.PanicException(
"test error"
)
result = convert_to_output(
sql_output_format="auto",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
assert result == pandas_result
assert_multiple_called_once(mock_functions, ["to_polars", "to_pandas"])
mock_logger.info.assert_called_once_with(
"Failed to convert to polars, falling back to pandas"
)
@pytest.mark.skipif(
not DependencyManager.polars.has(),
reason="Polars is not installed",
)
@patch("marimo._sql.utils.DependencyManager")
@patch("marimo._sql.utils.LOGGER")
def test_with_polars_compute_error_fallback_to_pandas(
self,
mock_logger: Mock,
mock_dependency_manager: Mock,
mock_functions: MockFnDict,
) -> None:
"""Test auto output format when polars ComputeError occurs and falls back to pandas."""
mock_dependency_manager.polars.has.return_value = True
mock_dependency_manager.pandas.has.return_value = True
import polars as pl
mock_functions["to_polars"].side_effect = pl.exceptions.ComputeError(
"test error"
)
result = convert_to_output(
sql_output_format="auto",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
assert result == pandas_result
assert_multiple_called_once(mock_functions, ["to_polars", "to_pandas"])
mock_logger.info.assert_called_once_with(
"Failed to convert to polars, falling back to pandas"
)
@patch("marimo._sql.utils.DependencyManager")
def test_without_polars_with_pandas_success(
self, mock_dependency_manager: Mock, mock_functions: MockFnDict
) -> None:
"""Test auto output format when polars is not available but pandas succeeds."""
mock_dependency_manager.polars.has.return_value = False
mock_dependency_manager.pandas.has.return_value = True
result = convert_to_output(
sql_output_format="auto",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
assert result == pandas_result
assert_only_one_called(mock_functions, "to_pandas")
@pytest.mark.parametrize(
"has_polars",
[
False,
pytest.param(
True,
marks=pytest.mark.skipif(
not DependencyManager.polars.has(),
reason="Polars is not installed",
),
),
],
)
@patch("marimo._sql.utils.DependencyManager")
def test_pandas_failure_propagates(
self,
mock_dependency_manager: Mock,
mock_functions: MockFnDict,
has_polars: bool,
) -> None:
"""Auto output preserves the final error, including after Polars fallback."""
mock_dependency_manager.polars.has.return_value = has_polars
mock_dependency_manager.pandas.has.return_value = True
if has_polars:
import polars as pl
mock_functions[
"to_polars"
].side_effect = pl.exceptions.ComputeError(
"polars conversion failed"
)
pandas_error = ValueError("pandas conversion failed")
mock_functions["to_pandas"].side_effect = pandas_error
with pytest.raises(ValueError) as exc_info:
convert_to_output(
sql_output_format="auto",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
assert exc_info.value is pandas_error
if has_polars:
assert_multiple_called_once(
mock_functions, ["to_polars", "to_pandas"]
)
else:
assert_only_one_called(mock_functions, "to_pandas")
@patch("marimo._sql.utils.DependencyManager")
def test_without_polars_without_pandas(
self, mock_dependency_manager: Mock, mock_functions: MockFnDict
) -> None:
"""Test auto output format when neither polars nor pandas is available."""
mock_dependency_manager.polars.has.return_value = False
mock_dependency_manager.pandas.has.return_value = False
with pytest.raises(
ModuleNotFoundError, match="pandas or polars is required"
):
convert_to_output(
sql_output_format="auto",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
mock_functions["to_polars"].assert_not_called()
mock_functions["to_pandas"].assert_not_called()
@pytest.mark.skipif(
not DependencyManager.polars.has(),
reason="Polars is not installed",
)
@patch("marimo._sql.utils.DependencyManager")
def test_with_polars_failure_no_pandas(
self, mock_dependency_manager: Mock, mock_functions: MockFnDict
) -> None:
"""Test auto output format when polars fails and pandas is not available."""
mock_dependency_manager.polars.has.return_value = True
mock_dependency_manager.pandas.has.return_value = False
import polars as pl
mock_functions["to_polars"].side_effect = pl.exceptions.PanicException(
"test error"
)
with pytest.raises(
ModuleNotFoundError, match="pandas or polars is required"
):
convert_to_output(
sql_output_format="auto",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
mock_functions["to_polars"].assert_called_once()
mock_functions["to_pandas"].assert_not_called()
class TestAllOutputFormats:
"""Test all output format types."""
@pytest.mark.skipif(
not DependencyManager.polars.has()
and not DependencyManager.pandas.has(),
reason="Polars and pandas are not installed",
)
@pytest.mark.parametrize(
("format_type", "expected_result", "expected_called_once"),
[
("polars", polars_result, ["to_polars"]),
("pandas", pandas_result, ["to_pandas"]),
("native", native_result, ["to_native"]),
("lazy-polars", lazy_polars_result, ["to_lazy_polars"]),
],
)
def test_basic_formats(
self,
format_type: str,
expected_result: dict,
expected_called_once: list[str],
mock_functions: MockFnDict,
) -> None:
"""Test basic output formats without complex dependencies."""
result = convert_to_output(
sql_output_format=format_type,
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
to_native=mock_functions["to_native"],
to_lazy_polars=mock_functions["to_lazy_polars"],
)
assert result == expected_result
assert_multiple_called_once(mock_functions, expected_called_once) # type: ignore
@pytest.mark.skipif(
not DependencyManager.polars.has(),
reason="Polars is not installed",
)
@patch("marimo._sql.utils.DependencyManager")
def test_auto_format_with_polars(
self, mock_dependency_manager: Mock, mock_functions: MockFnDict
) -> None:
"""Test auto format when polars is available."""
mock_dependency_manager.polars.has.return_value = True
mock_dependency_manager.pandas.has.return_value = False
result = convert_to_output(
sql_output_format="auto",
to_polars=mock_functions["to_polars"],
to_pandas=mock_functions["to_pandas"],
)
assert result == polars_result
assert_only_one_called(mock_functions, "to_polars")