【ITニュース解説】Managing Dependencies with Poetry for a Flask App on Ubuntu 24.04

Pythonプロジェクト開発では、アプリケーションが動作するために必要な外部ライブラリ（これを「依存関係」と呼ぶ）を適切に管理することが非常に重要である。システムエンジニアを目指す上で、この依存関係管理を効率的に行うスキルは不可欠となる。今回紹介するPoetryは、Pythonプロジェクトの依存関係管理とパッケージングを強力にサポートするオープンソースツールである。依存関係の明確なツリーを維持し、インストールと管理を効率化し、さらにPyPI（Python Package Index）へのパッケージングと配布も簡素化する。

Poetryを使い始めるには、まずUbuntu 24.04サーバーにPoetryをインストールする必要がある。この際、Pipxというツールを介してインストールすることが推奨される。Pipxは、個別のPythonアプリケーションをそれぞれの分離された環境にインストールし、システム全体や他のプロジェクトの依存関係との衝突を防ぐ。具体的には、まずシステムのパッケージリストを最新の状態に更新し、次にPipxをインストールする。その後、Pipxがインストールしたプログラムをどこからでも実行できるように、そのパスをシステムの環境変数PATHに追加する設定を行う。シェル設定ファイル（.bashrc）を編集してPATHを更新し、変更を現在のセッションに反映させるためsourceコマンドで読み込み直す。これらの準備が整ったら、pipx install poetryコマンドを実行し、PoetryをPipxによって分離された環境にインストールする。インストールが完了したかを確認するには、poetry --versionコマンドでPoetryのバージョン情報を表示する。

Poetryのインストール後、新しいFlaskアプリケーションプロジェクトを作成する。poetry new flask-appコマンドを実行すると、flask-appという名前のディレクトリが作成される。このディレクトリ内には、Flaskコードを格納するflask_appサブディレクトリ、プロジェクトの情報やPoetryの設定、依存関係が記述されるpyproject.tomlファイル、基本的な説明を記述するREADME.mdファイル、そしてテストケースを整理するためのtestsディレクトリが自動生成される。プロジェクトの作成が完了したら、cd flask-appコマンドで新しく作成されたプロジェクトディレクトリへ移動する。

次に、このプロジェクト専用の仮想環境を作成し、その中にFlaskをインストールする。仮想環境は、プロジェクトごとに独立したPython環境を提供し、プロジェクトAで必要なライブラリのバージョンがプロジェクトBのライブラリのバージョンと衝突するのを防ぐために不可欠である。poetry env use python3コマンドで、システムにインストールされているデフォルトのPython 3インタープリタを使って仮想環境を作成するようPoetryに指示する。仮想環境が作成されると、Poetryはそれをアクティベートするためのコマンドを表示する。このコマンド（source .../bin/activateのような形式）を実行することで、現在のシェルセッションで仮想環境が有効になる。仮想環境がアクティブな状態で、poetry add flaskコマンドを実行すると、Flaskとその依存関係がインストールされる。この際、pyproject.tomlファイルにはFlaskが依存関係として追加され、poetry.lockファイルが生成される。poetry.lockは、インストールされた各依存関係の正確なバージョンを記録し、他の開発者やデプロイ環境で全く同じ依存関係セットを再現できるようにする役割を持つ。作業を終える際はdeactivateコマンドで仮想環境を終了する。

Flaskアプリケーションを外部からアクセスできるようにするため、サーバーのファイアウォール設定を行う必要がある。Ubuntu 24.04では「UFW (Uncomplicated Firewall)」がデフォルトで有効な場合が多い。Flaskアプリケーションが通常使用するポート5000へのTCP接続を許可するルールを追加するため、sudo ufw allow 5000/tcpコマンドを実行する。ルールを追加したら、sudo ufw reloadコマンドでUFWを再読み込みし、設定変更を適用する。最後にsudo ufw statusコマンドで、ポート5000への接続が許可されていることを確認する。

ファイアウォールの設定後、いよいよFlaskアプリケーションを動かす。まず、再度仮想環境をアクティベートする。プロジェクトのflask_appディレクトリに移動し、app.pyという名前のPythonファイルを作成する。このファイルには、簡単なFlaskアプリケーションのコードを記述する。具体的には、Flaskオブジェクトを初期化し、ルートURL（/）にアクセスした際に「Hello from Flask」というメッセージを返すhome関数を定義する。さらに、開発目的でアプリケーションを起動するために、0.0.0.0のIPアドレスとポート5000でサーバーを実行する設定を含める。このapp.pyを実行するには、仮想環境がアクティブな状態でpoetry run python app.pyコマンドを使用する。これによりFlaskの開発サーバーが起動し、表示されるIPアドレス（<SERVER-IP>）とポート5000をウェブブラウザに入力することで、アプリケーションにアクセスし、「Hello from Flask」のメッセージを確認できる。ただし、この開発サーバーは本番環境での利用には適さないため注意が必要である。

Poetryでは、依存関係を「グループ」として管理することも可能である。これにより、本番環境で実際にアプリケーションを動かすために必要なライブラリと、開発やテストの際にのみ必要なツール（例えばテストフレームワーク）を区別できる。例えば、Pytestのようなテストツールを「dev（開発）」グループに追加するには、poetry add pytest --group devコマンドを実行する。このコマンドにより、pyproject.tomlファイル内に[tool.poetry.group.dev.dependencies]という新しいセクションが作成され、その下にpytestとそのバージョン情報が追加される。本番環境で使う依存関係は、グループに属さず、直接[tool.poetry.dependencies]セクションに記述する。Pytestをインストールしたら、プロジェクトのtestsディレクトリ内にunitというサブディレクトリを作成し、その中に__init__.pyファイルとtest_app.pyというテストファイルを配置する。test_app.pyには、Flaskアプリケーションの/ルートにアクセスし、期待通りのレスポンス（<h1>Hello from Flask</h1>）が返されることを確認するテストコードを記述する。テストを実行するには、プロジェクトのルートディレクトリでpytestコマンドを実行する。

本番環境でFlaskアプリケーションを運用する際は、開発サーバーの代わりにGunicornのようなWSGI (Web Server Gateway Interface) HTTPサーバーを使用することが一般的である。Gunicornはクライアントからのリクエストを効率的かつ同時に処理でき、安定した運用に適している。Gunicornをインストールするには、poetry add gunicornコマンドを実行し、これを本番環境の依存関係として追加する。次に、GunicornがFlaskアプリケーションを起動できるように、wsgi.pyというファイルを作成する。このファイルは、FlaskアプリケーションのインスタンスをGunicornに提供する役割を担う。wsgi.pyを作成したら、gunicorn --bind 0.0.0.0:5000 wsgi:appコマンドでGunicornを起動する。これにより、Gunicornがポート5000でリクエストを待ち受け、Flaskアプリケーションを提供するようになる。ウェブブラウザで再度アクセスし、アプリケーションが正常に動作していることを確認する。

仮想環境の管理もPoetryの重要な機能である。deactivateコマンドで仮想環境を終了した後、poetry env listコマンドを実行すると、プロジェクトに関連付けられているすべての仮想環境を一覧表示できる。特定の仮想環境を削除したい場合は、poetry env remove <仮想環境名>コマンドを使用する。誤って仮想環境を削除してしまっても、poetry env use python3でいつでも再作成でき、その後poetry installコマンドを実行すれば、pyproject.tomlファイルに基づいて必要なすべての依存関係が自動的に再インストールされる。これにより、プロジェクトの環境を簡単に再現できる。

デフォルトでは、Poetryは仮想環境をホームディレクトリの.cache/pypoetry/virtualenvs以下に作成する。しかし、仮想環境をプロジェクトのファイルと共に管理したい場合、その場所を変更できる。まず、アクティブな仮想環境からdeactivateで抜けてから、既存の仮想環境をpoetry env removeで削除する。次に、poetry config virtualenvs.in-project trueコマンドを実行し、Poetryが仮想環境をプロジェクトのルートディレクトリ直下の.venvディレクトリに作成するよう設定を変更する。この設定が適用されたことをpoetry config virtualenvs.in-projectで確認した後、poetry env use python3で仮想環境を再作成すると、プロジェクトルートに新しい仮想環境が作成される。poetry env infoコマンドで仮想環境の詳細情報を確認し、新しい場所が反映されていることを確かめる。この新しい環境でpoetry installを実行して依存関係をインストールし、GunicornでFlaskアプリを起動して正常に動作することを確認すれば、仮想環境の場所変更が完了となる。

Poetryを使ってFlaskアプリケーションの依存関係管理、仮想環境のセットアップ、開発サーバーと本番用WSGIサーバーでの実行、そしてテスト環境の構築まで一通り学んだ。次のステップとしては、Gunicornの前にNginxのようなリバースプロキシを配置し、systemdサービスとしてGunicornを起動することで、より堅牢な本番環境を構築することが推奨される。さらに、lintやdocsといった追加の依存関係グループを作成してツールを分類したり、CI (継続的インテグレーション) パイプラインにPytestを組み込んでコード変更時に自動的にテストを実行したり、プロジェクトが完成したらPyPIにパッケージとして公開することも検討できる。