blackとflake8を使ったPython開発環境のセットアップ手順

概要

半年（もしくは1年）に一度ほど、Pythonを使って簡単なスクリプトを作りたいなと言う機会が訪れるんですが、
その度に開発環境のセットアップどうするんだっけ…となるので雑にメモっておく。

目次

• 前提
• ローカル環境のセットアップ
  • Poetryプロジェクトの作成
  • pre-commitの設定
    • NOTE: blackのrev指定について
  • blackの設定
  • flake8の設定
    • NOTE: extend-ignore
• GitHub ActionsのWorkflow設定
  • NOTE: poetryについて
  • NOTE: black —checkについて

前提

• WSL2 Ubuntu 20.04
• Python 3.11
  • Pythonバージョンはpyenvでローカルバージョンのみ変更
  • パッケージ管理はpoetry
• pyenv 2.3.17
• poetry 1.8.3
• 前提知識
  • Pythonは単発のスクリプト程度でしか書かない。本格的に使った経験も無い。
    今回の環境セットアップの動機も単発利用のスクリプトを作りたいだけ。

ローカル環境のセットアップ

Poetryプロジェクトの作成

とりあえずpyproject.tomlを作る。パッケージは後で追加。

poetry init

NOTE:
pyenvでlocalバージョンを変更していた場合、poetryのデフォルト設定だとローカルプロジェクトのPythonバージョンを見てくれない（venvのPythonバージョンにglobalのバージョンが利用される）。
なのでpoetryの virtualenvs.prefer-active-python を true に設定する。

If you use a tool like pyenv to manage different Python versions, you can set the experimental virtualenvs.prefer-active-python option to true. Poetry will then try to find the current python of your shell.

Managing environments | Documentation | Poetry - Python dependency management and packaging made easy 🔗

poetryはインストールパッケージのバージョン管理にしか使わない（プロジェクト自体をパッケージ化しない）ので、 pyproject.toml に package-mode = false を追加する。

[tool.poetry]
name = "sample-project"
version = "0.1.0"
description = ""
authors = ["lycheejam"]
readme = "README.md"
+ package-mode = false

パッケージを追加。

# pytestは本記事の主題から逸れるが、どうせ使うので。
poetry add -D pytest black flake8 pre-commit

pre-commitの設定

configファイルを作成。

touch .pre-commit-config.yaml

下記を設定ファイルに記載。

repos:
  - repo: https://github.com/ambv/black
    rev: 24.4.2
    hooks:
      - id: black
        language_version: python3.11
        files: (src|tests)/.*\.py$
  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8
        files: (src|tests)/.*\.py$

NOTE: blackのrev指定について

今までrev: stableと言う指定を多用していたが、インストール時に以下の警告が出ていたので利用をやめた。
とりあえず現時点での最新バージョンを指定。利用する際に適宜更新。

[WARNING] The ‘rev’ field of repo ‘https://github.com/ambv/black 🔗’ appears to be a mutable reference (moving tag / branch). Mutable references are never updated after first install and are not supported. See https://pre-commit.com/#using-the-latest-version-for-a-repository 🔗 for more details. Hint: pre-commit autoupdate often fixes this.

警告: リポジトリ ‘https://github.com/ambv/black 🔗’ の ‘rev’ フィールドは、変更可能な参照（移動タグ/ブランチ）のようです。変更可能な参照は、最初のインストール後に更新されることはなく、サポートされていません。詳細は https://pre-commit.com/#using-the-latest-version-for-a-repository 🔗 を参照してください。ヒント: pre-commit autoupdate を実行すると、この問題が解決することがよくあります。

blackの設定

pyproject.toml の末尾に下記を追記する。

[tool.black]
line-length = 88
target-version = ['py311']
include = '\.pyi?$'

今回セットアップを行うまでは exclude オプションも使っていたが、 .gitignore ファイルを勝手に見てくれるようになったので不要だなってことで削除。

.gitignore If —exclude is not set, Black will automatically ignore files and directories in .gitignore file(s), if present.

File collection and discovery - Black 24.4.2 documentation 🔗

flake8の設定

configファイルを作成。

touch .flake8

下記を設定ファイルに記載。

[flake8]
exclude =
  .venv/,
  .git/,
  __pycache__
max-line-length = 88
extend-ignore = E203,E701

NOTE: extend-ignore

blackとflake8で重複しているルールを除外する。詳細は以下の通り。

Using Black with other tools - Black 24.4.2 documentation 🔗

以下はchatgptで翻訳。

E203 PEP 8によって決定されるいくつかの場合において、Blackはスライス演算子の周りに等しい量の空白を強制します。このため、pycodestyleは「’:‘の前に空白がある」というE203警告を発生させます。この警告はPEP 8に準拠していないため、無効にすべきです。

E701 / E704 Blackはクラスおよび関数の実装を一行にまとめます。これはPEP 8での例のフォーマットと一致します。他のすべての場合において、BlackはPEP 8のガイドラインに従って、一行に複数の文を置くことを防ぎます。

しかし、pycodestyleはこのロジックを反映しておらず、この状況でE701「一行に複数の文」を発生させることがあります。デフォルトで無効になっているE704「一行に複数の文（def）」ルールも警告を発生させる可能性があり、有効にすべきではありません。

Using Black with other tools - Black 24.4.2 documentation 🔗

GitHub ActionsのWorkflow設定

Workflow名の命名は適当。

mkdir -p .github/workflow && touch .github/workflow/lint.yml

name: Lint

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Cache Poetry
        uses: actions/cache@v4
        with:
          path: ~/.cache/pypoetry
          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
          restore-keys: |
            ${{ runner.os }}-poetry-

      - name: Install Poetry
        run: pipx install poetry

      - name: Install dependencies
        run: poetry install --no-root

      - name: Run black
        run: poetry run black --check src tests

      - name: Run flake8
        run: poetry run flake8 src tests

NOTE: poetryについて

ローカルとバージョンを合わせるためにわざわざgithub actions内でpoetryを使っているが、blackやflake8のactionsが存在しているのでそっちに寄せても良いかもしれない。

NOTE: black —checkについて

もしActions内でコードフォーマットが実行されても自動コミットは組み込んでないので（組み込む予定も無い）
--check オプションで実際のフォーマットは実行されないようにしている。
じゃあflake8だけでよくない？という話はあると思う。なんとなく実行してるだけ。