tailor

An opinionated Python formatter: ruff format, then a house style.

tailor runs ruff format, then puts one item on each line, spaces keyword arguments, groups the code with blank lines and sorts imports by length. It also lays out the SQL in """--sql strings.

Example

Before:

import structlog
from jobs.models import JobAborted
import asyncio

class Builder:
    async def create(self, *, user_request: str, title: str, milestone: str, next_title: str) -> Response:
        prediction = await self.orchestration.predict(self.anchor.acall, user_request=user_request)
        numbers = [number for number in bundle.steps if 1 <= number <= len(steps) and number not in claimed]
        return Node(label=self.state.next_label(), name=card.name, keywords=set(card.keywords))

After:

import asyncio

import structlog

from jobs.models import JobAborted


class Builder:
    async def create(
        self,
        *,
        user_request: str,
        title: str,
        milestone: str,
        next_title: str,
    ) -> Response:
        prediction = await self.orchestration.predict(
            self.anchor.acall,
            user_request = user_request,
        )

        numbers = [
            number
            for number in bundle.steps
            if 1 <= number <= len(steps) and number not in claimed
        ]
        return Node(
            label = self.state.next_label(),
            name = card.name,
            keywords = set(card.keywords),
        )

Installation

uv tool install pytailor

tailor runs on Python 3.14, and uv gets it for you. It formats projects that target Python 3.12 to 3.14. It reads the target the same way ruff does. If a project targets another version, tailor stops before it changes a file. For a project that targets Python 3.12 or 3.13, ruff adds from __future__ import annotations to each file.

Usage

tailor src tests                  # format in place
tailor --check src                # list the files that would change
tailor --diff src                 # show the changes as a colored diff
tailor --line-length 100 src      # replace the line length for this run

tailor formats the .py files that ruff check finds: ruff's default exclusions, exclude and extend-exclude in [tool.ruff], and .gitignore apply. The excludes of [tool.ruff.lint] and [tool.ruff.format] do not apply. With --check or --diff, the exit code is 1 when a file would change, so tailor --check src tests works as a CI step.

To format on save in Neovim, add tailor to conform.nvim:

require("conform").setup({
    formatters = {
        tailor = { command = "tailor", args = { "$FILENAME" }, stdin = false },
    },
    formatters_by_ft = { python = { "tailor" } },
    format_on_save = { timeout_ms = 1000 },
})

Configuration

Put the options in [tool.tailor] of pyproject.toml. tailor uses the nearest pyproject.toml above each file. An unknown option or a wrong type stops tailor with an error that names the file.

House style

The numbers below are the defaults.

• Line breaks. A call, definition, import or literal that does not fit puts each item on its own line. A long comprehension puts each for and if on its own line. A long and/or, operator or conditional expression goes in parentheses, one operand on each line, operator first.
• Spaces. Keyword arguments and defaults are written name = value.
• Blank lines. 2 around top-level definitions and methods, and after the imports. Runs of 6 or more assignments split into groups of 3 to 5. A long for, while or if gets a blank line after it.
• Classes. Dunders, classmethods and properties move up, in that order, constructors first. Overloads and property setters move with their group.
• Imports. Standard library, third party, local. Shortest first in each group.

SQL

A string whose first line is """--sql holds SQL. tailor lays out SQLite SQL with syntaqlite and other dialects with sqruff:

row = db.fetch_one(
    """--sql
    SELECT
      @assists
      - (
        SELECT COUNT(*)
        FROM jobs
        WHERE
          json_extract(data, '$.user_id') = @user
          AND status NOT IN ('FAILED', 'CANCELLED')
      ) AS assists_left
    """,
    bindings = {"user": user, "assists": assists},
)

A clause that fits stays on one line. Keywords are upper case, and the SQL starts at the column of the opening quotes. SQLite SQL that ends with ; keeps one ; after each statement. tailor adds no ; to other SQL, because that SQL can be part of a longer query. tailor compares the SQL tokens before and after: if more than whitespace or case would change, or the SQL does not parse, the string stays as written.

tailor finds the dialect of each file in this order:

1. The sql-dialect option.
2. The dialect in the nearest .sqruff or .sqlfluff file.
3. The database driver that the file imports, for example import duckdb.
4. The database driver that the project depends on in pyproject.toml.
5. SQLite. If the project depends on drivers of two databases, tailor also shows a warning.

Notes

• Do not run ruff format after tailor. It reverses the keyword spacing, the comprehension layout and the blank lines.
• Turn off ruff's import sorting (I), and the pycodestyle rules for = spacing (E251, E252) and blank lines (E30x). The other ruff check rules can stay. tailor uses your ruff formatter settings, such as quote-style.
• tailor compares the syntax tree of ruff's output with its own result. If anything other than the order of the imports, the class members, the type statements and the definitions that the aliases use changed, it writes nothing and shows an error.
• tailor moves class members without a check of what they use when the class is created. A decorator or default value that uses another member of the class can fail after the move.
• A definition that moves above the aliases runs earlier when Python loads the module. If its decorator or its value has a side effect, that side effect also occurs earlier. An example is the registration order of routes.
• tailor also changes # fmt: off and # fmt: skip regions. A file that contains ǂǂ is not formatted: tailor uses these characters while ruff runs.

License

MIT