Integrate 'black' Formatter with Bazel for Code Formatting`

[EricRahm]

Motivation

To ensure a consistent Python code style across the project and automate a manual, error-prone process, we should integrate the black code formatter directly into our Bazel build system. We already use black in our CI pipeline, but don't expose it for local usage.

Below is a proposed approach, but we're open to do thing this other ways.

Proposed Solution

We will implement two separate Bazel targets to achieve this:

1. A bazel run Target for Fixing:

   • A target named black_fix will be created.
   • Running bazel run //:black_fix -- . will execute black on the entire workspace, reformatting any non-compliant Python files in-place.

2. A bazel test Target for Checking (Optional):

   • A target named black_check will be created.
   • Running bazel test //:black_check (or as part of bazel test //...) will execute black --check --diff.
   • This test will pass if all files are correctly formatted and fail otherwise, printing a diff of the required changes. This is ideal for CI integration.

Implementation Plan

1. Add black as a Bazel Dependency:

   • Modify MODULE.bazel to use the pip.parse extension from rules_python.
   • Create a requirements.txt file to declare a dependency on black==24.8.0 and its necessary transitive dependencies.

2. Create a py_binary for the Formatter:

   • In the root BUILD file, define a py_binary target named black_binary.
   • This target will use the entry_point attribute set to "black" to directly use the black command-line tool provided by the pip package.

3. Implement the "Fix" Command:

   • Create a sh_binary named black_fix that simply calls the black_binary target with the provided arguments (e.g., . to format the whole project). This will be the user-facing command run with bazel run.

4. Implement the "Check" Test:

   • Create a sh_test named black_check.
   • This test will execute the black_binary target with the --check and --diff flags. The test will succeed only if black returns a zero exit code (indicating no changes are needed).

[EricRahm]

I did a cursory search and didn't find a black bzlmod, but I might not have searched hard enough.

[mrkushalsm]

Hi @EricRahm!

I would like to work on this issue and can proceed with the implementation plan outlined in the description:

1. Update MODULE.bazel to pull in black via rules_python.
2. Add the black_binary target.
3. Create the black_fix (run) and black_check (test) targets in the BUILD file.

Could you please assign this to me? I would love to work on this!

[EricRahm]

@mrkushalsm Happy to take contributions here, please go ahead and put up a draft PR and we can discuss the details further during code review. There may already be some tooling in tree that we can leverage so take a look around before jumping in.

[mrkushalsm]

Hey @EricRahm! 👋

Sorry took 2 weeks, was busy with college. I've submitted a PR #244 for this, would love your feedback!

I followed the implementation plan from the issue description, but ran into one obstacle actually, bazel test runs in a sandbox that doesn't have access to the full source tree, so black_check couldn't actually check the project files.

So I ended up making both black_fix and black_check use bazel run instead. It works great locally as I tested them, but any changes you'd like, would be happy to work on it.

Also took your suggestion to explore the existing tooling first. Found rules_python was already there, which made pulling in Black pretty straightforward. Had to add rules_shell for the shell targets since Bazel v9.0 requires explicit imports, which I hope won't be the issue of me using the v9.0 of Bazel, as I installed it from Arch repos directly.

Do let me know what you think, and cheers!!