Skip to content

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.

Prefer tomllib over tomlkit for reading TOML (#8827)

Trevor Manzb52a9c23d586
diff --git a/marimo/_config/packages.py b/marimo/_config/packages.py
index 956c53b59c..2f10b5eb07 100644
--- a/marimo/_config/packages.py
+++ b/marimo/_config/packages.py
@@ -6,7 +6,7 @@ import sys
from pathlib import Path
from typing import Literal, Optional
-from marimo._utils.toml import read_toml
+from marimo._utils.toml import toml_reader
PackageManagerKind = Literal["pip", "rye", "uv", "poetry", "pixi"]
@@ -74,7 +74,7 @@ def infer_package_manager_from_pyproject(
) -> Optional[PackageManagerKind]:
"""Infer the package manager from a pyproject.toml file."""
try:
- data = read_toml(pyproject_toml)
+ data = toml_reader.read(pyproject_toml)
if "tool" not in data:
return None
diff --git a/marimo/_config/reader.py b/marimo/_config/reader.py
index 06b769e861..85e14cb0c5 100644
--- a/marimo/_config/reader.py
+++ b/marimo/_config/reader.py
@@ -6,21 +6,21 @@ from typing import Any, Optional, Union, cast
from marimo import _loggers
from marimo._config.config import PartialMarimoConfig
-from marimo._utils.toml import read_toml
+from marimo._utils.toml import toml_reader
LOGGER = _loggers.marimo_logger()
def read_marimo_config(path: str) -> PartialMarimoConfig:
"""Read the marimo.toml configuration."""
- return cast(PartialMarimoConfig, read_toml(path))
+ return cast(PartialMarimoConfig, toml_reader.read(path))
def read_pyproject_marimo_config(
pyproject_path: Union[str, Path],
) -> Optional[PartialMarimoConfig]:
"""Read the marimo tool config from a pyproject.toml file."""
- pyproject_config = read_toml(pyproject_path)
+ pyproject_config = toml_reader.read(pyproject_path)
marimo_tool_config = get_marimo_config_from_pyproject_dict(
pyproject_config
)
diff --git a/marimo/_utils/config/config.py b/marimo/_utils/config/config.py
index 870b08a6bb..1b3c81bd00 100644
--- a/marimo/_utils/config/config.py
+++ b/marimo/_utils/config/config.py
@@ -5,7 +5,7 @@ from dataclasses import asdict
from typing import TYPE_CHECKING, Any, TypeVar
from marimo._utils.parse_dataclass import parse_raw
-from marimo._utils.toml import is_toml_error, read_toml
+from marimo._utils.toml import toml_reader
from marimo._utils.xdg import marimo_state_dir
if TYPE_CHECKING:
@@ -32,12 +32,10 @@ class ConfigReader:
def read_toml(self, cls: type[T], *, fallback: T) -> T:
try:
- data = read_toml(self.filepath)
+ data = toml_reader.read(self.filepath)
return parse_raw(data, cls, allow_unknown_keys=True)
- except Exception as e:
- if is_toml_error(e) or isinstance(e, FileNotFoundError):
- return fallback
- raise e
+ except (toml_reader.decode_error, FileNotFoundError):
+ return fallback
def write_toml(self, data: Any) -> None:
import tomlkit
diff --git a/marimo/_utils/scripts.py b/marimo/_utils/scripts.py
index 53549305f3..a511730b8e 100644
--- a/marimo/_utils/scripts.py
+++ b/marimo/_utils/scripts.py
@@ -5,7 +5,7 @@ import platform
import re
from typing import Any
-from marimo._utils.toml import read_toml_string
+from marimo._utils.toml import toml_reader
REGEX = (
r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)$\s(?P<content>(^#(| .*)$\s)+)^# ///$"
@@ -39,7 +39,7 @@ def read_pyproject_from_script(script: str) -> dict[str, Any] | None:
for line in matches[0].group("content").splitlines(keepends=True)
)
- pyproject = read_toml_string(content)
+ pyproject = toml_reader.reads(content)
return pyproject
else:
return None
diff --git a/marimo/_utils/toml.py b/marimo/_utils/toml.py
index 1c1e6823ad..e4124069df 100644
--- a/marimo/_utils/toml.py
+++ b/marimo/_utils/toml.py
@@ -1,54 +1,46 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from typing import TYPE_CHECKING, Any, Union
-
-from marimo._dependencies.dependencies import DependencyManager
+import sys
+from typing import IO, TYPE_CHECKING, Any, Callable, Union
if TYPE_CHECKING:
from pathlib import Path
-
-def read_toml(file_path: Union[str, Path]) -> dict[str, Any]:
- """Read and parse a TOML file."""
-
- # tomllib is only available in python 3.11+
- if DependencyManager.tomlkit.has():
- import tomlkit
-
- with open(file_path, "rb") as file:
- # Use unwrap() to convert tomlkit types to Python built-ins
- return tomlkit.load(file).unwrap()
- else:
- import tomllib
-
- with open(file_path, "rb") as file:
- return tomllib.load(file)
+# tomllib is available in python 3.11+ and is much faster than tomlkit
+# (C extension vs pure Python). Prefer it for read-only operations.
+_HAS_TOMLLIB = sys.version_info >= (3, 11)
-def read_toml_string(s: str) -> dict[str, Any]:
- """Read and parse a TOML string."""
+class TomlReader:
+ """TOML reader that prefers tomllib (3.11+) over tomlkit."""
- # tomllib is only available in python 3.11+
- if DependencyManager.tomlkit.has():
- import tomlkit
+ decode_error: type[Exception]
+ _load: Callable[[IO[bytes]], dict[str, Any]]
+ _loads: Callable[[str], dict[str, Any]]
- # Use unwrap() to convert tomlkit types to Python built-ins
- return tomlkit.loads(s).unwrap()
- else:
- import tomllib
+ def __init__(self) -> None:
+ if _HAS_TOMLLIB:
+ import tomllib
- return tomllib.loads(s)
+ self._load = tomllib.load # type: ignore[assignment]
+ self._loads = tomllib.loads # type: ignore[assignment]
+ self.decode_error = tomllib.TOMLDecodeError
+ else:
+ import tomlkit
+ self._load = lambda f: tomlkit.load(f).unwrap()
+ self._loads = lambda s: tomlkit.loads(s).unwrap()
+ self.decode_error = tomlkit.exceptions.TOMLKitError
-def is_toml_error(e: Exception) -> bool:
- """Check if an exception is a TOML error."""
+ def read(self, file_path: Union[str, Path]) -> dict[str, Any]:
+ """Read and parse a TOML file."""
+ with open(file_path, "rb") as file:
+ return self._load(file)
- if DependencyManager.tomlkit.has():
- import tomlkit
+ def reads(self, s: str) -> dict[str, Any]:
+ """Read and parse a TOML string."""
+ return self._loads(s)
- return isinstance(e, tomlkit.exceptions.TOMLKitError)
- else:
- import tomllib
- return isinstance(e, tomllib.TOMLDecodeError)
+toml_reader = TomlReader()
diff --git a/tests/_cli/test_cli.py b/tests/_cli/test_cli.py
index 03e24b92fd..3575a45b61 100644
--- a/tests/_cli/test_cli.py
+++ b/tests/_cli/test_cli.py
@@ -34,7 +34,7 @@ from marimo._server.file_router import (
)
from marimo._server.templates.templates import get_version
from marimo._utils.platform import is_windows
-from marimo._utils.toml import read_toml
+from marimo._utils.toml import toml_reader
if TYPE_CHECKING:
from collections.abc import Iterator
@@ -160,7 +160,7 @@ def _get_port() -> int:
def _read_toml(filepath: Path) -> Optional[dict[str, Any]]:
if not filepath.exists():
return None
- return read_toml(filepath)
+ return toml_reader.read(filepath)
def _write_temp_notebook(notebook: str, tmp_dir: Path) -> Path:
diff --git a/tests/_config/test_config_packages.py b/tests/_config/test_config_packages.py
index b189c72117..e6cbc1f8e8 100644
--- a/tests/_config/test_config_packages.py
+++ b/tests/_config/test_config_packages.py
@@ -27,7 +27,7 @@ def mock_cwd(tmp_path: Path):
def test_infer_package_manager_from_pyproject():
# Test poetry detection
with patch(
- "marimo._config.packages.read_toml",
+ "marimo._config.packages.toml_reader.read",
return_value={"tool": {"poetry": {}}},
):
assert (
@@ -36,14 +36,16 @@ def test_infer_package_manager_from_pyproject():
)
# Test no tool section
- with patch("marimo._config.packages.read_toml", return_value={}):
+ with patch("marimo._config.packages.toml_reader.read", return_value={}):
assert (
infer_package_manager_from_pyproject(Path("pyproject.toml"))
is None
)
# Test exception handling
- with patch("marimo._config.packages.read_toml", side_effect=Exception):
+ with patch(
+ "marimo._config.packages.toml_reader.read", side_effect=Exception
+ ):
assert (
infer_package_manager_from_pyproject(Path("pyproject.toml"))
is None
diff --git a/tests/_config/test_reader.py b/tests/_config/test_reader.py
index 8b8e2af462..a998a9a570 100644
--- a/tests/_config/test_reader.py
+++ b/tests/_config/test_reader.py
@@ -12,7 +12,7 @@ from marimo._config.reader import (
read_marimo_config,
read_pyproject_marimo_config,
)
-from marimo._utils.toml import is_toml_error, read_toml
+from marimo._utils.toml import toml_reader
def test_read_toml():
@@ -21,7 +21,7 @@ def test_read_toml():
key = "value"
"""
with patch("builtins.open", mock_open(read_data=toml_content)):
- result = read_toml("dummy.toml")
+ result = toml_reader.read("dummy.toml")
assert result == {"section": {"key": "value"}}
@@ -145,6 +145,5 @@ def test_read_toml_invalid_content():
"""
with patch("builtins.open", mock_open(read_data=invalid_toml)):
- with pytest.raises(Exception) as e:
- read_toml("dummy.toml")
- assert is_toml_error(e.value)
+ with pytest.raises(toml_reader.decode_error):
+ toml_reader.read("dummy.toml")