Tools and workflows

What does a Python code formatter do?

See what Ruff and Black-style formatting changes, how to check a file before writing it, and how formatting differs from linting and tests.

A Python code formatter standardizes source layout, including whitespace, quotation marks, and which expressions wrap onto several lines. Use the formatter configured by your project. For Ruff, ruff format --check example.py reports whether a file needs formatting, and ruff format example.py writes the changes. Review the diff before committing.

Preview formatting changes on a single file

A formatter works best on valid Python source. If the file has a syntax error, fix that first. With Ruff installed in your project tooling environment, use ruff format --check example.py to check whether the file matches its format. Run ruff format example.py to write formatted code. Compare the result to the previous version with your version-control diff or a saved copy.

Do the first run on a file you already understand. For example, put several named arguments into a function call with uneven spaces and let the formatter lay it out. Ask whether a colleague can now follow the call without guessing how it belongs on the screen. Try a slightly longer call and compare the result. Line length is a formatting target. One long URL or string may still exceed it.

Separate formatting, linting, and tests

Formatting makes the same patterns look the same. A Python linter can flag a probable mistake, such as using a name that was never defined. A test executes the code to check a specific expectation, such as whether an empty export contains column headings.

For instance, a formatter can improve the layout of a condition, but it cannot tell you whether a discount should apply to a rounded subtotal. A linter may report an unused import but cannot decide whether removing that import also removes a side effect you rely on. A test with a known subtotal checks the business rule. Format the file, review lint findings, and use tests to cover behavior.

Share the settings with the project

Keep the formatter choice and its settings in a tracked project file such as pyproject.toml. Specify the tool version in your development setup and use the same settings locally and in automated checks. A teammate should be able to reproduce a formatting result without copying your editor profile.

In an existing project, check which directories the formatter should skip. Generated files and vendored code may need separate treatment. Format a small path first and inspect it before applying a whole-repository command. Set the editor's format-on-save behavior only after confirming it picks the same formatter as the project's command.

See what formatting can clarify

The two calls below pass the same arguments. In the multiline version, each argument has its own line in the diff when you change it.

publish_summary("march", include_empty=False, output_dir="reports")
publish_summary(
    "march",
    include_empty=False,
    output_dir="reports",
)

These examples illustrate the difference rather than predict what every formatter will do. A formatter may keep a short call on a single line. With supported settings, a trailing comma in a multiline call can help preserve the lines you have chosen. Consult the tool's settings when a style choice matters to the team.

The formatted layout makes argument changes easier to review. It does not establish that include_empty=False is the correct decision. For a reporting tool, a separate test can establish which reports should include empty sections.

Use a checking command where files should not change

A format-on-save editor writes changes to files you edit. A continuous integration check usually should only report whether files need formatting. Use a formatter's check or diff mode there. If a check fails, run the write command locally for the intended files and inspect the diff before committing.

Do not rely on a passing format command to prove it saw everything. When a generated folder or a different language should be excluded, verify that the exclusion matches the intended paths. When a file should be checked but is ignored, start by running the command on it directly and inspecting the configuration. This is especially useful with nested project files and tools that discover settings based on the working directory.

Keep review focused

A one-line behavior change is difficult to review if it appears alongside thousands of unrelated formatting lines. On a project adopting formatting for the first time, make an isolated formatting change and verify the tests. Follow it with behavior changes in separate work. Reviewers can then evaluate the style decision once and see the actual feature against a consistent background.

If two tools repeatedly reformat the same statement differently, check the project's chosen formatter, editor settings, and versions. A single style decision shared by the workspace and terminal is easier to maintain than suppressing differences file by file. Good formatting reduces review effort and leaves the project's design choices visible.

Sources and further reading

Related reading

Browse Tools and workflows · Explore project tutorials

Search PythonProjects.org