背景

最近、pyproject.tomlを編集しているときに、ふと自動整形してくれるようなフォーマッターがないかと思い、探してみました。結果としてTaploというフォーマッターが簡単に使えましたので、この記事で紹介したいと思います。使用環境としてはLinuxのターミナルを想定していますが、Windowsでも使えるようです。

ダウンロード

以下からご自身の環境に合ったファイルをダウンロードしてください。なお、バージョン0.9.0がリリースされていますが、添付忘れなのかAssetsがないため、ここでは0.8.1のリンクを貼っています（2024年3月10日現在）。

前準備

ダウンロードしたファイルは圧縮されたバイナリですので、これを解凍して、実行権限を付与します。

$ gunzip taplo-linux-x86_64.gz  # or gzip -d taplo-linux-x86_64.gz
$ mv taplo-linux-x86_64 taplo   # rename as you like
$ chmod +x taplo

あとは必要に応じてパスを通してください。

ここでヘルプを見てみましょう。

$ ./taplo -h
taplo 0.8.1

USAGE:
    taplo [OPTIONS] <SUBCOMMAND>

OPTIONS:
        --colors <COLORS>    [default: auto] [possible values: auto, always, never]
    -h, --help               Print help information
        --log-spans          Enable logging spans
    -V, --version            Print version information
        --verbose            Enable a verbose logging format

SUBCOMMANDS:
    config    Operations with the Taplo config file [aliases: cfg]
    format    Format TOML documents [aliases: fmt]
    get       Extract a value from the given TOML document
    help      Print this message or the help of the given subcommand(s)
    lint      Lint TOML documents [aliases: check, validate]
    lsp       Language server operations

基本的に、サブコマンドとしてはformatを用いることが多いと思います。以下で詳細なヘルプを確認できます。

$ ./taplo format -h

使い方

フォーマットする場合は

$ ./taplo format hoge.toml

リンターとして利用する場合（ファイルを書き換えない場合）は

$ ./taplo format --check hoge.toml

となります。ヘルプにもあるように、formatはfmtと書いてもOKです。サブコマンドlintは、単にTOMLの構文チェックをするだけのもののようです。

コンフィグ設定

.taplo.tomlかtaplo.tomlという名前のファイルがあれば、それを自動で読みにいくようになっています。明示的に指定したい場合は、taplo formatの-cオプションで設定できます。コンフィグファイルにはformattingテーブルを用意し、そこに設定を列挙する形になります。以下は例です。

[formatting]
align_entries = false

また、ruleテーブルを用いることで、特定のファイルのみフォーマットするようなこともできます。詳細はドキュメントを参照してください。

formattingテーブルで設定するオプションの挙動がドキュメントからは分かりにくかったので、以下にまとめました。

align_entries

false

[tool.black]
target-version = ["py37", "py38"]
line-length = 120

true

[tool.black]
target-version = ["py37", "py38"]
line-length    = 120

イコールでそろえる（デフォルトはfalse）

align_comments

false

[tool.black]
target-version = ["py37", "py38"] # ABC
line-length = 120 # abc

true

[tool.black]
target-version = ["py37", "py38"] # ABC
line-length = 120                 # abc

コメントをそろえる（デフォルトはtrue）

array_trailing_comma

false

classifiers = [
  "Programming Language :: Python :: 3.6",
  "Programming Language :: Python :: 3.7"
]

true

classifiers = [
  "Programming Language :: Python :: 3.6",
  "Programming Language :: Python :: 3.7",
]

末尾要素にカンマを付ける（デフォルトはtrue）

array_auto_expand

false

classifiers = ["Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7"]

true

classifiers = [
  "Programming Language :: Python :: 3.6",
  "Programming Language :: Python :: 3.7",
]

column_widthの値を越えるなら、要素ごとに改行する（デフォルトは80文字でtrue）

inline_table_expand

false

a = { classifiers = ["Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7"] }

true

a = { classifiers = [
  "Programming Language :: Python :: 3.6",
  "Programming Language :: Python :: 3.7",
] }

column_widthの値を越えるなら、インラインテーブル内で改行する（デフォルトはtrue）

array_auto_collapse

false

classifiers = [
  "Programming Language :: Python :: 3.6",
]

true

classifiers = ["Programming Language :: Python :: 3.6"]

一行で書けるなら一行にまとめる（デフォルトはtrue）

compact_arrays

false

package = [ "a", "b" ]

true

package = ["a", "b"]

括弧[]の内側にスペースを追加しない（デフォルトはtrue）

compact_inline_tables

false

mypackage = { version = "^1.0", optional = true }

true

mypackage = {version = "^1.0", optional = true}

括弧{}の内側にスペースを追加しない（デフォルトはfalse）

compact_entries

false

mypackage = { version = "^1.0", optional = true }

true

mypackage={ version="^1.0", optional=true }

イコールの両側にスペースを追加しない（デフォルトはfalse）

indent_tables

false

[tool.poetry]
version = "0.1.0"

[tool.poetry.dependencies]
python = "*"

true

[tool.poetry]
version = "0.1.0"

  [tool.poetry.dependencies]
  python = "*"

サブテーブルをインデントする（デフォルトはfalse）
インデントの文字はindent_stringで設定する

indent_entries

false

[tool.poetry]
version = "0.1.0"

[tool.poetry.dependencies]
python = "*"

true

[tool.poetry]
  version = "0.1.0"

[tool.poetry.dependencies]
  python = "*"

エントリーをインデントする（デフォルトはfalse）
インデントの文字はindent_stringで設定する

reorder_keys

false

[tool.black]
target-version = ["py37", "py38"]
line-length = 120

true

[tool.black]
line-length = 120
target-version = ["py37", "py38"]

キーをアルファベット順に並べる（デフォルトはfalse）

reorder_arrays

false

[tool.black]
target-version = ["py39", "py310"]
line-length = 120

true

[tool.black]
target-version = ["py310", "py39"]
line-length = 120

配列要素をアルファベット順に並べる（デフォルトはfalse）

allowed_blank_lines

0

[tool.poetry]
version = "0.1.0"
[tool.poetry.dependencies]
python = "*"

1

[tool.poetry]
version = "0.1.0"

[tool.poetry.dependencies]
python = "*"

最大の空行数を設定する（デフォルトは2）

trailing_newline

ファイルの最後に改行コードを入れる（デフォルトはtrue）

crlf

改行コードをCRLFにする（デフォルトはfalse)

設定できない事項

シングルクォートとダブルクォートの統一は今のところできないみたいです。

その他

サブコマンドgetを使うことで、TOMLの内容を取ってくることができます。便利ですね！

$ ./taplo get formatting.compact_inline_tables -f .taplo.toml
false
$ echo "data = ['a', 'b', 'c']" | ./taplo get data
a
b
c

終わりに

今回はCLIの使い方のみを説明しましたが、VSCodeでも使えるようです。
こちらの記事が開発の一助となれば幸いです。

参考