VSCodeでのPython開発環境構築：仮想環境、型チェック、リンター、フォーマッター、pre-commitを設定する #Python

はじめに

この記事では、Pythonの依存関係管理ツールであるPoetryを使ったプロジェクトの構築から、Jupyterの設定、型チェック、リンター及びフォーマッター、pre-commit 設定の流れを紹介します。

主な流れ

Poetryのインストールと構築
Jupyterのインストールと実行
Pyrightの型チェックを有効にする
Ruffの設定
pre-commitの設定

Poetryとは

Poetryは、Pythonのパッケージ管理,依存関係解決を扱うツールです。
さらにパッケージの公開なども行える高機能なツールです。
Poetryは仮想環境(venv)を作成して各ライブラリをインストールするため、プロジェクトごとに使用するライブラリを分けられます。

pipとvenvでも同じようなことができますが、requirements.txtへの追加忘れなどが発生する可能性があります。

またPoetryと同じようなツールとしてPipenvがあります。
Pipenvも仮想環境と依存関係解決の両方を提供します

主な違い

依存関係解決速度がpipenvと比べて早い
pyproject.tomlが使える
パッケージの公開を行う機能がある

基本的にPoetryの方が多機能で高速という認識でいいかなと思います。

PoetryとPipenvの比較参考

Poetryのインストール

brew install poetry

任意のディレクトリを作って移動します

mkdir 任意名前
cd 任意の名前

プロジェクトを作成します。
基本全部enterで大丈夫です。

poetry init

完了するとpyproject.tomlが作成されます。
pyproject.tomlは、Pythonプロジェクトの依存関係、ビルドシステム、ツール設定を一元管理するための設定ファイルです。

pyproject.toml

[tool.poetry]
name = "python-env"
version = "0.1.0"
description = ""
authors = ["beyond-toyama"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

次に仮想環境が作られる場所を変更します。
デフォルトだと~/.cache/pypoetry/virtualenvsに仮想環境が構築されてしまうのでプロジェクト直下に作成されるように設定します。

poetry config --local virtualenvs.in-project true

例としてnumpyとmatplotlibをプロジェクトの依存関係として追加します。

poetry add numpy matplotlib

するとpyproject.tomlが更新されます。

pyproject.toml

[tool.poetry.dependencies]
python = "^3.12"
numpy = "^1.26.4"
matplotlib = "^3.8.4"

仮想環境のシェルに切り替わります。

poetry shell

numpyとmatplotlibが存在するか確認できます。

pip3 list

コマンド結果

❯ pip3 list                                                                                                                                                      ─╯
Package         Version
--------------- -----------
contourpy       1.2.1
cycler          0.12.1
fonttools       4.51.0
kiwisolver      1.4.5
matplotlib      3.9.0
numpy           1.26.4
packaging       24.0
pillow          10.3.0
pip             24.0
pyparsing       3.1.2
python-dateutil 2.9.0.post0
six             1.16.0

仮想環境から抜けます。

exit

VSCodeの設定と実行

VSCodeにPython拡張機能をインストールします。
これを入れるとPylance,Pythonデバッガーの二つの拡張機能がインストールされます。

インタープリターの選択をします。
Cmd+Shift+Pでコマンドパレットを開き、Python: Select Interpreterを選択。

その後.venv:poetryを選ぶ。これで、VSCodeが仮想環境からインポートを探すようになります。

main.pyを作成

main.py

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.plot(x, y)
plt.show()

poetry runを使うと仮想環境内で直接スクリプトを実行できます(便利)。

poetry run python3 main.py

実行結果

Code Runnerと組み合わせる

コードの言語に応じて特定のコマンドを実行できるプラグインです
これを使うと毎回コマンドを打つ手間が減ります

.vscodeディレクトリにsettings.jsonを作成し以下のようにします。

.vscode/settings.json

{
  "code-runner.executorMap": {
    "python": "poetry run python3 -u",
  }
}

コマンドパレットを開きRun CodeでPythonのコードを実行できます。
ショートカットを当てるともっと便利になります。(自分の環境ではCmd+R)

Jupyterの拡張機能の設定

VSCodeにJupyterの拡張機能を入れます。

Jupyter Notebookを実行するために開発環境の依存関係にipykernelを追加します。

poetry add -D ipykernel

pyproject.tomlが更新されます。

pyproject.toml

[tool.poetry.group.dev.dependencies]
ipykernel = "^6.29.4"

main.ipynbを作成

main.ipynb

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.plot(x, y)
plt.show()

コマンドパレットからJupyterのInterpreterを選択します。

Poetry環境を選択します。

実行して表示

Pyrightで型をチェックする

PyrightはMicrosoft製のPythonコード向け静的型チェッカーです。
実行時にエラーが出ないコードだったとしても、型ヒントに合致しない値が代入される可能性がある場合は警告やエラーを出してくれます。

コードの型チェックの厳密さを設定するtypeCheckingModeにはoff、basic、standard、strictの4種類があります。

違いについては以下を見るといいです。

strictでもいいですが、少し厳しすぎるので個人的にはstandardでもいいと思います。

pyproject.tomlに追記

pyproject.toml

[tool.pyright]
# settings.jsonにも設定できるがこちらが優先される模様
typeCheckingMode = "standard"
# basePath
venvPath = "."
# basePathから指定する
venv = ".venv"

コードを少し変更。
エラーが出ればOK。
Pylanceからエラーが出ていますが、これは拡張機能Pylanceの内部でPyrightが使われている関係でそうなってます。

Ruff(リンター、フォーマッター)を設定

2022年8月にリリースされた比較的新しい、Pythonのリンター兼フォーマッターです。
他のツールと比較して高速に動作するのが公式ページで示されています。

参照(https://docs.astral.sh/ruff/)

インストール

brew install ruff

拡張機能を入れます。

pyproject.tomlに追記

pyproject.toml

[tool.ruff]
extend-include = ["*.ipynb"]
[tool.ruff.lint]
select = ["ALL"]
# 無視したいルールを書く
ignore = ["D100"]

settings.jsonに追記

.vscode/settings.json

  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    } 
  },
  "notebook.formatOnSave.enabled": true,
  "notebook.codeActionsOnSave": {
    "notebook.source.fixAll": "explicit",
    "notebook.source.organizeImports": "explicit"
  },

保存した時にフォーマットとリンターのコードアクションが実行されます。

pre-commit

コミット前にコードに対してチェックやタスクを実行できるフレームワークです。
今回はコミット前にruffのリントとフォーマット,pyrightを走らせ問題がないかチェックします。

インストール

brew install pre-commit

git initします

git init

pre-commit-config.yamlを作成する。

.pre-commit-config.yaml

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.3
    hooks:
      # Run the linter.
      - id: ruff
        files: '\.(py|ipynb)$'
      # Run the formatter.
      - id: ruff-format
        files: '\.(py|ipynb)$'
  - repo: local
    hooks:
      - id: pyright
        name: pyright
        entry: poetry run pyright
        language: system
        files: '\.(py|ipynb)$'

Gitリポジトリにコミットフックをインストールします。

pre-commit install

仮想環境でPyrightを実行する必要があるので依存関係に追加します。

poetry add -D pyright

ソースコードにprintを入れます。

main.py

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)
print(x)
print(y)
plt.plot(x, y)
plt.show()

コミットしようとすると失敗します。

printを消して再びコミットすると成功します。

終わりに

この記事では、Poetry、Jupyter、Pyright、Ruff、pre-commitを使ったPythonプロジェクトのセットアップ方法を説明しました。これらのツールを活用することで、より効率的にPythonの開発を行えるようになると思います。