🐍

2024年度サマーインターン研修資料公開！Python 環境セットアップ (mise + Poetry) | TrustHub テックブログ

Shinichiro NAKAMURA

2024/08/19に公開

トラストハブ AI チームの中村です。

弊社では今年度もサマーインターンシップを実施しており、AI チームでは「機械学習コース」を開きました。本記事では、今年度の機械学習コースで実際に使用した研修資料「Python 環境セットアップ」を記事用に加筆修正したものを公開します。

0. はじめに

ここでいう Python 環境とは次の3つが出来ることを言います。

ランタイム言語としての Python のバージョン管理
プロジェクトごとに Python の仮想環境を切り替えること
仮想環境で使用するパッケージの管理

本記事では、1. の役割として mise を活用し、2. と 3. の役割として Poetry を活用する環境構築方法を紹介しようと思います。

なお、Python を用いた開発を進めていく上で重要な以下の項目については、本記事で詳しくは触れません。また別の記事で詳細について解説する予定です。

IDE やエディタの設定（例：VSCode）
テストフレームワーク（例：pytest）
formatter, linter の導入（例：Ruff）
type checker の導入（例：mypy）

コラム：包括的管理ツール Rye について

最近では Rye というツールが Python コミュニティで多くの注目を集めています。上で挙げた3つの基本的機能だけではなく、テストフレームワークや formatter & linter の機能を兼ね備えているオールインワンの超便利ツールです。

https://rye.astral.sh/

個人的にはこちらも推したい環境構築方法ですが、弊社ではこちらを使わずに、mise + Poetry を使うようにしています。その理由として、mise は他のランタイム言語の管理も兼ね備えているから、というのがあります。

弊社が開発するアプリのバックエンドは TypeScript で書いていることが多いのですが、レコメンドなど機械学習が関係するバックエンドは主に Python を用いて実装されています。つまり、プロジェクトごとに Node.js なのか Python なのか、使用するランタイム言語を切り替える必要があるわけですが、mise はその問題を解決してくれます。また、これから説明するように mise を用いる環境構築方法を採用すれば、Python 自体だけではなく Poetry も mise の plugin の一つとしてまとめて管理できるので、弊社で多くのエンジニアが新たなツールをインストールせずに Python プロジェクトを動かせる、というメリットがあります。

1. mise について

mise とは？

mise（発音は「ミーズ」）とは、プログラミング言語やツールのバージョンを管理するためのツールです。以前まで rtx という名称で呼ばれていましたが、某半導体メーカーの製品名と被ってしまうのを避けたのか、最近になって改名されたようです。

公式サイト

https://mise.jdx.dev/

インストール手順

公式サイトで説明されている手順通りに進めてください。

Python のバージョン管理

mise を使った Python のバージョン管理方法について説明します。

今回は test-project/ というプロジェクトで作業することを想定して話を進めます。

バージョン指定

プロジェクトに .mise.toml というファイルを作成します。

test-project/
└── .mise.toml

このファイルには、プロジェクトで使用する Python のバージョンを記載します。例えば、Python 3.12.3 を使用するには次のように記述します。

.mise.toml

[tools]
python = "3.12.3"

バージョンの自動切り替え

mise は .mise.toml ファイルが存在する場合に自動的にそのバージョンのランタイム言語を使用します。このバージョンの Python がインストールされていない場合、プロジェクトに作業ディレクトリを移動するとmise missing: *** というように不足しているバージョンが表示されます。

$ cd test-project/
mise missing: python@3.12.3

バージョンのインストール

不足しているバージョンがある場合、プロジェクトで mise install を実行すると自動でインストールしてくれます。

$ mise install
mise installing precompiled python from indygreg/python-build-standalone
mise if you experience issues with this python (e.g.: running poetry), switch to python-build
mise by running: mise settings set python_compile 1
mise python@3.12.3 ✓ installed

Python インタプリタ実行ファイルパス切り替えの確認

使用している Python が無事に切り替わっていることを確認しましょう。先ほどのプロジェクトに作業ディレクトリを移動してから which python を実行してみます。すると、mise でインストールしたものに切り替わっているのが確認できると思います。

$ which python
/Users/<user>/.local/share/mise/installs/python/3.12.3/bin/python

コラム：mise がデフォルトでインストールする Python

先ほど実行した mise install のログを見ると、Python を indygreg/python-build-standalone からインストールしていることが分かります。これは mise がデフォルトで設定しているインストール先で、様々な OS と CPU アーキテクチャに対応している自己完結型で移植性の高いビルド済み Python ディストリビューションです。詳しくは公式サイトを見てください。

2. Poetry について

Poetry とは？

Python の Poetry とは、パッケージの依存関係管理とパッケージングのためのツールです。

https://python-poetry.org/docs/

mise を用いた Poetry のバージョン管理

Python のバージョンとともに、Poetry のバージョン管理を mise で行う方法を説明します。

mise の plugin を追加

mise で Poetry を使用するには plugin の設定が必要です。公式 GitHub の README にある通り、次のコマンドを実行して Poetry plugin を追加します。

$ mise plugin add poetry

追加された plugin の確認

無事に plugin が追加されているか確認するために mise plugins を実行しましょう。すると、現在 mise に追加されている plugin の一覧が表示されます。この一覧に poetry が含まれていれば plugin の追加は成功です。

$ mise plugins
poetry

Poetry を用いた仮想環境 & パッケージ管理

Poetry の具体的な使い方について解説します。

`pyproject.toml` を作成

今回のプロジェクトで使用する Python パッケージや、その他 Python 関連の設定を一元的に管理するファイル pyproject.toml^[1] を作成しましょう。

test-project/
├── .mise.toml
└── pyproject.toml

作成した pyproject.toml には次のように記述します。

pyproject.toml

[tool.poetry]
package-mode = false

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

バージョン指定

プロジェクトにある .mise.toml に Poetry 自体のバージョンを記載します。Poetry plugin 公式 GitHub の README の説明に従いましょう。例えば、最新バージョンの Poetry を使用したい場合は次のように記述します。

.mise.toml

[tools]
poetry = {version="latest", pyproject="pyproject.toml"}  # ここを追記する
python = "3.12.3"

バージョンのインストール

不足しているバージョンがある場合、プロジェクトで mise install を実行すると自動でインストールしてくれます。

$ mise install
mise poetry@1.8.3 ✓ installed

Poetry の設定

Poetry は仮想環境のディレクトリを自動で作成してくれるのですが、デフォルトの設定だとプロジェクトの直下に仮想環境を作成してくれません。この設定を変更するには、次のコマンドを実行します。

$ poetry config virtualenvs.in-project true --local

すると、このプロジェクトにおける poetry の config が記載されているファイル poetry.toml が作成されます。これは、先ほどの pyproject.toml とは区別されるものです。

test-project/
├── .mise.toml
├── poetry.toml
└── pyproject.toml

これにより、次の poetry install を実行すると自動でプロジェクト直下に仮想環境 .venv/ を作成してくれます。この設定には次のようなメリットがあります。

複数のプロジェクトがあっても、作業ディレクトリを移動することで自動的に仮想環境を切り替えることができる
VSCode などの IDE にインストールした Python パッケージを認識させることができる

仮想環境の自動生成

poetry install ^[2] を実行すると、Poetry が自動で Python の仮想環境を構築してくれます。また、この poetry install は既存プロジェクトの clone 直後に必要なパッケージをインストールする際にも使用するコマンドですので、覚えておきましょう。

$ poetry install
Creating virtualenv non-package-mode in /Users/<user>/Projects/test-project/.venv
Updating dependencies
Resolving dependencies...

Writing lock file

インストールが完了すると、プロジェクトのディレクトリ構造は次のようになっているはずです。仮想環境 .venv/ がプロジェクトの直下に作成されていることが確認できます。

test-project/
├── .venv/
├── .mise.toml
├── poetry.lock
├── poetry.toml
└── pyproject.toml

これで必要な環境セットアップは完了です。

コラム：Poetry が採用する依存関係アルゴリズムについて

Poetry ではパッケージの依存関係解決アルゴリズムとして PubGrub というものを採用しています。これは2018年に Google 社の Natalie Weizenbaum 氏によって提案されたもので、元々は Dart 言語のパッケージ管理システム Pub のために開発されたアルゴリズムです。これにより、他のパッケージ管理ツールでは解消できていなかった依存関係の問題が効率的に解決できるようになったようです。そのほかのパッケージ管理ツールとの比較など、この辺の技術的・歴史的背景の解説は vaaaaanquish 氏による次のブログ記事が非常によくまとまっています。

3. サンプルコード

Poetry を用いた具体的な Python のパッケージ管理方法について説明します。今回は具体例として、次のような Python コードを動かすケースを考えます。

sample.py

import numpy as np

def main() -> None:
    # 1次元配列の作成
    x = np.array([1, 2, 3, 4, 5])
    y = np.array([10, 20, 30, 40, 50])

    # 配列の足し算
    result = x + y

    # 結果の表示
    print(result)

if __name__ == "__main__":
    main()

このサンプルコードを実行するには Python パッケージの NumPy が必要です。プロジェクトで使用する Python パッケージを追加するには poetry add <package-name> を実行^[3]します。

$ poetry add numpy

すると、次のようなログが流れます。

$ poetry add numpy
Using version ^2.0.1 for numpy

Updating dependencies
Resolving dependencies...

Package operations: 1 install, 0 updates, 0 removals

  - Installing numpy (2.0.1)

Writing lock file

ここでは Poetry が NumPy のバージョンを自動で選択しています（執筆当時の最新バージョンは 2.0.1 でした）。Poetry が最新バージョンの NumPy を仮想環境にインストールしつつ、先ほどの pyproject.toml に「今後はバージョン 2.0.1 と互換性のある最新バージョンを使ってください」という内容を自動で書き込んでくれます。

pyproject.toml

[tool.poetry]
package-mode = false

[tool.poetry.dependencies]
python = "^3.12.3"
numpy = "^2.0.1"  # ここが自動で追記されている

また、ログの最後を見ると Writing lock file とあります。ここでは Poetry が依存関係の情報を記録した lock ファイル poetry.lock を自動更新しています。先述した通り、このファイルは手動で編集する必要はありません。全て自動で Poetry が管理してくれます。

パッケージの追加ができたら、いよいよ Python コードの実行です。先ほどのサンプルコードを sample.py というファイル名で保存したら、次を実行してみましょう。

$ poetry run python sample.py

実行して、NumPy 配列の足し算の結果が無事に表示されていれば成功です。

$ poetry run python sample.py
[11 22 33 44 55]

他にもある Poetry の便利機能

以上で Poetry の基本的な機能の説明を終えますが、まだまだ説明しきれてない便利機能が山ほどあるので、ここで簡単に紹介しようと思います。

Dependency groups

例えば、Poetry には dependencies をグループ化する機能が標準で備わっており、これにより開発環境と本番環境で使用するパッケージのバージョン管理を分けたり、monorepo 構成を簡単に構築するなどができます。

Packaging build & publish

本稿では主に Poetry をパッケージの依存関係管理ツールを目的として活用していましたが、開発した Python プロジェクトをパッケージングして PyPI などに公開する機能も備わっています。

困った時は…

公式ドキュメントがよくまとまっているので、困ったときはこちらを読みましょう。

https://python-poetry.org/docs/

4. 快適な開発環境を整えるために

ひとまず、ここまでのセットアップで最初に挙げた3つの基本的な機能を持つ Python 環境が完成しました。しかし、より快適な Python 開発環境を作り上げるには次の項目も重要です。

IDE やエディタの設定（例：VSCode）
テストフレームワーク（例：pytest）
formatter, linter の導入（例：Ruff）
type checker の導入（例：mypy）

サマーインターンシップの研修では、この続きでこれらの使い方や導入方法についても解説しているのですが、こちらは長くなるので別の記事にまとめたいと思います。

5. まとめ

本記事では、mise と Poetry の組み合わせを用いた Python 環境構築について解説しました。

mise を使用して Python を含むランタイム言語のバージョン管理を行い、プロジェクトごとに適切なバージョンを簡単に切り替えることができます
Poetry を用いて、仮想環境の作成とパッケージ管理が効率的に行えます

なお、本記事では触れませんでしたが、IDE 設定、テストフレームワーク、formatter, linter, type checker などの導入も、より快適な開発環境を整える上で非常に重要です。これらについては、別の記事で詳しく解説する予定です。

最後に

株式会社トラストハブではカード事業だけでなく toC 向けの様々なプロダクトを提供していますが、やりたいことに対してエンジニアが足りておりません。toC 向けプロダクトを開発したいという方はぜひこちらからお話しさせてください！

脚注

venv + pip の環境構築における requirements.txtや setup.py にあたります ↩︎
venv + pip における pip install -r requirements.txt と似ていますが、仮想環境の構築や有効化を自動でやってくれる分、比較すると多機能になっています ↩︎
venv + pip における pip install <package-name> と似ていますが、次の部分で説明する通り、Poetry は追加したパッケージと依存関係を自動で pyproject.toml および poetry.lock に書き出してくれる分、多機能になっています ↩︎

TrustHub テックブログPublication

トレカEC「Cloveストア」や、トレカオリパ「Cloveオリパ」を提供する株式会社トラストハブのテックブログです

0. はじめに

1. mise について

mise とは？

公式サイト

インストール手順

Python のバージョン管理

バージョン指定

バージョンの自動切り替え

バージョンのインストール

Python インタプリタ実行ファイルパス切り替えの確認

2. Poetry について

Poetry とは？

mise を用いた Poetry のバージョン管理

mise の plugin を追加

追加された plugin の確認

Poetry を用いた仮想環境 & パッケージ管理

pyproject.toml を作成

バージョン指定

バージョンのインストール

Poetry の設定

仮想環境の自動生成

3. サンプルコード

他にもある Poetry の便利機能

Dependency groups

Packaging build & publish

困った時は…

4. 快適な開発環境を整えるために

5. まとめ

最後に

Discussion

`pyproject.toml` を作成