Support configuration in [tool.biome] section of pyproject.toml

[kdeldycke]

Biome is a fantastic tool and with #8818 on the horizon, it starts to play nice with the Python ecosystem.

To integrate even more with Python projects, it would be cool to have biome source its configuration from a [tool.biome] section in pyproject.toml.

Other non-Python tools are supporting this, probably to increase adoption of their own tools in the Python world. See:

• [tool.ruff]: https://docs.astral.sh/ruff/configuration/#configuring-ruff (Rust)
• [tool.typos]: https://github.com/crate-ci/typos/blob/master/docs/reference.md (Rust)
• [tool.uv]: https://docs.astral.sh/uv/concepts/configuration-files/ (Rust)
• [tool.ty]: https://docs.astral.sh/ty/ (Rust)
• [tool.maturin]: https://www.maturin.rs/config (Rust)
• [tool.pyright]: https://github.com/microsoft/pyright/blob/main/docs/configuration.md (TypeScript)
• [tool.tombi]: https://tombi-toml.github.io/tombi/docs/configuration/ (Rust)
• [tool.rumdl]: https://github.com/rvben/rumdl (Rust)
• [tool.lychee]: Support for pyproject.toml (and cargo.toml) lycheeverse/lychee#1930 (Rust)

Other tools are considering adding support:

• https://github.com/orgs/zizmorcore/discussions/322#discussioncomment-15919620 (Rust)
• Support taplo configuration in pyproject.toml tamasfe/taplo#603 (Rust)
• Support configuration in [tool.actionlint] section of pyproject.toml rhysd/actionlint#623 (Go)
• Support configuration in [tool.shfmt] section of pyproject.toml mvdan/sh#1268 (Go)
• Support configuration from pyproject.toml gitleaks/gitleaks#2066 (Go)

[kdeldycke]

Just to keep track of the support landscape, lychee just added support for [tool.*] in pyproject.toml, as well as Cargo.toml and package.json in the upcoming v0.24 release. See: lycheeverse/lychee#1930 (comment) and lycheeverse/lychee#2104

As for the "precedence/order issue", here is my benchmarking of existing tools:

Looking at other projects, a dedicated configuration file wins over pyproject.toml. In which case it is completely ignored and not merged at all.

Examples of strict precedence:

• Ruff: .ruff.toml > ruff.toml > pyproject.toml (source)
• Uv: uv.toml > pyproject.toml (source)
• Typos: either typos.toml / _typos.toml / .typos.toml, then > Cargo.toml > pyproject.toml (source)

I guess the reason for the strict no-merge policy is to avoid confusion and surprises: only one source of configuration.

As for the dedicated file precedence, it feels like a file at the root of a repository, named after your tool, is way more visible and explicit than a section in pyproject.toml.

As for my personal preference, I like tool-dedicated sections in pyproject.toml to keep the root of my repository clean. And review my tools configurations altogether in a centralized place. Because more often that not, I need to tweak the configuration of tools and coordinate them so they can play nice with each others.

[kdeldycke]

I implemented a "tool runner" in repomatic that translates [tool.biome] sections from pyproject.toml into biome's native JSON config, caches the result, and passes it via --config-path. No changes needed in biome itself.

So now you can have a pyproject.toml that looks like:

[tool.biome.formatter]
indentStyle = "space"
indentWidth = 4

[tool.biome.linter.rules.style]
useConst = "error"

With an example.js to check:

let greeting="hello"
let   items = [1,2,3,4,5]
let total=items.reduce((sum,   n) =>sum+n,0)
console.log(greeting,total)

Then run biome via repomatic:

$ uvx repomatic run biome -- check --write ./example.js
Checked 1 file in 9ms. Fixed 1 file.

Which produces a formatted and linted example.js:

const greeting = "hello";
const items = [1, 2, 3, 4, 5];
const total = items.reduce((sum, n) => sum + n, 0);
console.log(greeting, total);

Both the formatter config (spacing around operators, semicolons) and the linter rule (let rewritten to const via useConst) are applied from the [tool.biome] section.

This bridges the gap for Python projects that want to centralize all tool configuration in pyproject.toml without requiring native support from each tool. The same translation works for other tools like zizmor, gitleaks, actionlint, shfmt, and others.

[siketyan]

I agree that it is helpful to centralise configuration for all tools used in the project. I think Vite+ is a success story for that in JS/TS world, which places all config into a single vite.config.ts.

However, if we support multiple types of configuration in one tool, the config hell begins. Back in the day many JS/TS tools used to support including configs in package.json. But now, majority of them prefer using their dedicated config file instead.

It is hard to know which config is applied or where it is configured when multiple config locations are supported. What is their priority? Can multiple configs get merged? If so, how are they merged?

pyproject.toml is defined by third-party tools that is not directly related to Biome. If we started supporting it, we should support other tools too. We don't have bandwidth to support lots of patterns that user configures Biome. Only biome.json(c) files should be the Single Source of Truth for us.