ruff

Bazel rules for the Python linter ruff.

Setup

First ensure rules_venv is setup by referring to rules_venv setup.

Next, the ruff rules work mostly off of toolchains which are used to provide the necessary python targets (aka ruff) for the process wrappers. Users will want to make sure they have a way to get the necessary python dependencies. Tools such as req-compile can provide these.

With the appropriate dependencies available, a py_ruff_toolchain will need to be configured. The toolchain accepts either ruff (a py_library, e.g. from pip) or ruff_bin (an executable); the two are mutually exclusive.

load("@rules_venv//python/ruff:defs.bzl", "py_ruff_toolchain")

py_ruff_toolchain(
    name = "toolchain_impl",
    ruff = "@pip_deps//ruff",
    visibility = ["//visibility:public"]
)

toolchain(
    name = "toolchain",
    toolchain = ":toolchain_impl",
    toolchain_type = "@rules_venv//python/ruff:toolchain_type",
    visibility = ["//visibility:public"]
)

This toolchain then needs to be registered in the MODULE.bazel file.

register_toolchains("//tools/python/ruff:toolchain")

From here, py_ruff_test and the py_ruff_aspect should now be usable. py_ruff_test is a convenience that creates a test suite running both py_ruff_check_test and py_ruff_format_test. Both the test rules and the aspect use a global flag to determine which ruff configuration file to use in actions. The default config is //python/ruff:ruff.toml; the chosen file must be a valid label (e.g. ruff.toml or pyproject.toml). Add the following to .bazelrc to choose a different configuration file:

build --@rules_venv//python/ruff:config=//:.ruffrc.toml

To use the aspect, you must also enable it and request its output group in .bazelrc:

build --aspects=@rules_venv//python/ruff:py_ruff_aspect.bzl%py_ruff_aspect
build --output_groups=+py_ruff_checks

Test rules can override the config per target via the config attribute (they default to the label flag above).

Usage

Python code can be formatted using:

bazel run @rules_venv//python/ruff:format

Lint issues that support auto-fix can be applied using:

bazel run @rules_venv//python/ruff:fix

Both commands accept optional Bazel scope arguments (e.g. //... or //some/package:all); the default is //...:all.

Functions

py_ruff_test

Aspects

py_ruff_aspect

py_ruff_check_test

load("@rules_venv//python/ruff:defs.bzl", "py_ruff_check_test")

py_ruff_check_test(name, config, target)

A rule for running ruff check on a Python target.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
config	The config file (ruff.toml) containing ruff settings.	Label	optional	`"@rules_venv//python/ruff:config"`
target	The target to run `ruff` on.	Label	required

py_ruff_format_test

load("@rules_venv//python/ruff:defs.bzl", "py_ruff_format_test")

py_ruff_format_test(name, config, target)

A rule for running ruff format on a Python target.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
config	The config file (ruff.toml) containing ruff settings.	Label	optional	`"@rules_venv//python/ruff:config"`
target	The target to run `ruff` on.	Label	required

py_ruff_toolchain

load("@rules_venv//python/ruff:defs.bzl", "py_ruff_toolchain")

py_ruff_toolchain(name, ruff, ruff_bin)

A toolchain for the ruff linter and formatter rules.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
ruff	The ruff `py_library` with the rules.	Label	optional	`None`
ruff_bin	A `ruff` binary to use with the rules.	Label	optional	`None`

py_ruff_test

load("@rules_venv//python/ruff:defs.bzl", "py_ruff_test")

py_ruff_test(*, name, target, config, **kwargs)

A rule for running ruff check and ruff format on a given target.

This macro defines the following target:

rule	name
(py_ruff_check_test)[#py_ruff_check_test]	`{name}.check`
(py_ruff_format_test)[#py_ruff_format_test]	`{name}.format`

PARAMETERS

Name	Description	Default Value
name	The name of the test suite	none
target	The target to run `ruff` on.	none
config	The config file (ruff.toml) containing ruff settings.	`None`
kwargs	Additional keyword arguments.	none

py_ruff_aspect

load("@rules_venv//python/ruff:defs.bzl", "py_ruff_aspect")

py_ruff_aspect()

An aspect for running ruff on targets with Python sources.

This aspect can be configured by adding the following snippet to a workspace's .bazelrc file:

build --aspects=@rules_venv//python/ruff:py_ruff_aspect.bzl%py_ruff_aspect
build --output_groups=+py_ruff_checks

ASPECT ATTRIBUTES

ATTRIBUTES