手元のPythonスクリプトをスタイルガイド（PEP 8）に合わせたいあなたへ

はじめに

楳図かずお先生なくして、アイの歌声を聴かせてなし。ご冥福をお祈りします。

nikkieです。

Pythonコミュニティで広く採用されているコーディング規約に沿ったPythonスクリプトを書きたい方に捧げます。

目次

• はじめに
• 目次
• この記事のきっかけ
• PEP 8 – Style Guide for Python Code
• フォーマッタでPEP 8のスタイルを適用する
  • Black
  • Ruff
• Ruffを開発環境にどのように組み込むか
  • VS Code拡張として使う
  • コマンドラインから実行
• 終わりに

この記事のきっかけ

Kanonさんからの質問がきっかけでした。

@ftnext
ちょっとPythonのこと教えてほしいです🙏
Pythonのコードのお作法的なことを学びたいんですが、良さげなドキュメントとか本ってあるでしょうか？…

— Kanon (@ysknsid25) 2024年10月27日

このスレッドの内容について、加筆する形で現時点の私の考えを書いていきます。
Pythonのスクリプト¹を書いている方が、スタイルガイドに沿うようにするための具体的な方法です。

なお、KanonさんはRuffをVS Code拡張で実行する形にたどり着いたそうです。
ref: じぶん Release Note (ver 2.10.5)｜Kanon

PEP 8 – Style Guide for Python Code

PEPは「Python Enhancement Proposal」の略です。
用語集より
https://docs.python.org/ja/3/glossary.html#term-PEP

PEP は、Python コミュニティに対して情報を提供する、あるいは Python の新機能やその過程や環境について記述する設計文書です。

PEP 8がPythonコードのスタイルガイドです。

スタイルとは「見た目」です。
別にPEP 8のスタイルにしなくてもPython処理系としては動きます。
なので、見た目は開発者のためのもの²であり、PEP 8が1つのガイドラインを示しているという理解です。

PEP 8は多岐にわたりますが、その一部をご紹介

• 字下げはタブよりスペースの方が好まれる³
• ホワイトスペースの入れ方⁴
  • 例：if x == 4: print(x, y); x, y = y, x
• import文の順番⁵

開発中のコーディング規約としてPEP 8を採用することが多いかなと思います。
私の経験した範囲では、規約がない（みんな好きに書く⁶） or PEP 8を採用する（ツールで自動的に適用する）ですね。

フォーマッタでPEP 8のスタイルを適用する

PEP 8をコーディング規約に採用したとき、開発者が気をつけるだけでは限界があります。
PEP 8には非常にたくさんの項目があり、私は全部を覚えているわけではありません。
ではどのようにPEP 8に沿ったPythonコードを書いているかというと、Pythonは好きに書いて、最後にツールでスタイルをPEP 8に合わせます。
このツールがフォーマッタです。

Black

The Uncompromising Code Formatter（妥協なきコードフォーマッタ）

Black以前にもフォーマッタは（いくつも）存在していました。
Black以前のフォーマッタは、PEP 8の中から採用する項目を設定して適用していたと聞いています。
なので、PEP 8をコーディング規約に採用したプロジェクトと言っても、コードのスタイルは異なることがあったそうです。

Blackが革新的だったのは、設定できなくしたこと。
"妥協がない"のです。強制的にPEP 8準拠！！

当時の私はPEP 8の項目を全然知らなかったので、「設定せずに使えるBlackはかえって簡単でいいな」と採用しました。
Black自体もコミュニティに受け入れられたと見えています（リポジトリがPSF下に移管されるまでに。Google発じゃなかったかな？）

なお、Blackだけでは手の届かない箇所が存在しており、他のフォーマッタと一緒に使う必要がありました⁷。
import順の並び替えはisort、また、不要なimport文の削除はautoflakeです。

Ruff

2023年くらいからPythonのフォーマッタの状況が変わってきているように感じます。
きっかけはRuffの登場。

RuffはRust製で、Astral社が開発しています（後にuvを爆誕させたり、Ryeが移管されたりした会社です）。
Ruffの特徴は、Black、isort、autoflakeとツールの組合せに対して、Ruff 1つで済むというスタンスをとったこと。

現在Pythonで静的コード解析やフォーマットに使われるツールが複数あり、それぞれが構文解析をしているため、もっと効率よくできるのでは？

Ruffは1回の処理で目立ったパフォーマンスの低下なく、すべてのチェック・自動修正が行われることを目標の1つにしています。

Ruffのフォーマットは2つのコマンドを走らせると理解しています

• ruff format：Blackのようなフォーマッタが走る
• ruff check --fix --extend-select I：実行しているのはリンター
  • リンターが検出したルール違反のうち、自動で直せるものは直すのが--fix（例：autoflakeのような、使われていないimportの削除）
  • さらに--extend-select Iとimportのルール(: I) を追加する（isortのフォーマットも適用される）

Ruffを開発環境にどのように組み込むか

現在のところ、私はフォーマッタとしてはRuffをオススメしています。
Ruffという存在がある今、Pythonのフォーマッタを初めて使う方に、「Blackとisortとautoflakeと」って伝えるのはハードル高すぎるんじゃないかと思うんですよね。

それでは、開発中にどのように使っていくかを考えてみます。

VS Code拡張として使う

この記事を書くにあたって知ったのですが、便利そうでした。
ファイルを保存した（またはフォーカスが別に移った）ときに、ruff formatもruff check --fixも実行されている印象です

コマンドラインから実行

VS Code拡張を知る前は、uvx ruff（またはpipx run ruff）で使うのがよいと考えていました。
uv⁸（またはpipx⁹）をインストールする必要がありますが、これらのツールが最新のRuffを管理して実行してくれます¹⁰。
（Ruffは1つの統合コマンドを計画中とのことですが、）現在は2つのコマンドを実行する必要があるので、私はmake devの1コマンドで済むようにMakefileを書いています（Ruffのところで挙げた拙記事を参照）

終わりに

手元のPythonスクリプトをスタイルガイド（PEP 8）に合わせる方法について、現時点の私の考えを書きました。

• Ruffを採用
  • Ruffの登場前はBlackやisortなどの組合せが使われていたが、Ruffがある今、組合せるアプローチは最初にオススメしづらい
• エディタの拡張でRuffを実行できるなら、それを使うとよいのでは（例：VS Code）
• （エディタが対応していないなどで）コマンドラインから実行する場合は、ruff formatとruff checkの2つのコマンドを実行

今回はスクリプトという点でまとめており、プロジェクト（複数ファイル）になるとHatch¹¹が代わりの候補かなあと思います。
HatchはRuffを採用しており、hatch fmtという1コマンドにまとめてくれています。
Ruffをコマンドラインから実行するときの煩雑さを吸収してくれていますね。
ただスクリプトしか書かない状況では、Hatchには使わない機能が多すぎるので紹介しづらいところがあります。