複雑化したリポジトリをなんとかした話 pipenvからuvによるモノレポ構成への移行

PyCon JP 2025での登壇資料です。
https://2025.pycon.jp/ja/timetable/talk/EXQTNU

Transcript

1. 複雑化したリポジトリをなんとかした話 pipenvからuvによるモノレポ構成への移行 PyCon JP 2025 2025.09.26 Satoshi Kaneyasu
2. 2 発表者自己紹介 氏名：兼安 聡 所属：株式会社サーバーワークス アプリケーションサービス部 在住：広島（フルリモート） 担当：DevOps、技術支援、PM、SM SNS(X)：@satoshi256kbyte • 2025 AWS Community Builders • 2025 Japan AWS Top Engineers (AI/ML Data Engineer) • 2025 Japan AWS All Certifications Engineers • 認定スクラムマスター • PMP
3. 4 目次 1. 複雑化したリポジトリ 2. ランタイムバージョンマネージャの見直し pyenvからasdfへの移行 3. pipenvからuvへの移行 複雑化したリポジトリをモノレポ構成へ 4. 後回しにしたもの 5. uvによるモノレポ構成移行の効果 6. まとめ
4. 複雑化したリポジトリ 後期 初期 中期
5. 6 プロジェクトとリポジトリの概要 ◼ アジャイル開発（スクラム） ◼ AWS上に構築されたWebアプリケーション ◼ AWSを用いている理由は、スケーリング重視のため ◼ バックエンドがPython、長時間の非同期処理あり ◼ バックエンドは基本サーバーレスで、長時間の非同期処理はコンテナ ◼ pyenv＋pipenvを使用
6. 7 構成図 Python 3.11 Python 3.13 後から追加
7. 8 ディレクトリ構成 追加したモジュールは Python 3.13 最初からあったモジュールは Python 3.11
8. 9 難解なデプロイスクリプト そのフォルダで使用している バージョンに切り替えてデプロイ モジュールごとにフォルダ移動して またバージョンを切り替えてデプロイ
9. 10 この頃思っていたこと ◼ デプロイスクリプトが、かなり違和感を感じるものになった ◼ これもあって、CI/CDまわりが人気がなくなり、CI/CDの属人化が加速 ◼ ユニットテストが書きづらいという声が挙がり始めた ➢ わかりにくい意見だが、 根本は全体的に考えることが多すぎる、認知負荷が高い、ということだと感じた ◼ これはいずれは問題となり、開発チームにとってブレーキになるだろう 次ページから次の話題になります
10. ランタイムバージョンマネージャの見直し pyenvからasdfへの移行 後期 中期 初期
11. 12 ランタイムバージョンマネージャのpyenvからasdfへの移行 ◼ まずはpyenvからasdfの移行に着手 ◼ another_project の担当者がasdfを使い始めてくれたのでそれを横展開 ◼ asdfの横展開を決めたのは、AWS CLIやIaC用のNode.jsなど、 Python以外にもバージョン管理したいものがあり、それとマッチしたから ◼ これにより、言語・ツールを管理する「asdf」、ライブラリを管理する「pipenv」と、 役割分担がわかりやすくなった .tool_versions aws-sam-cli 1.136.0 nodejs 23.10.0 python 3.13.1
12. 13 ランタイムバージョンマネージャの見直し方針 ◼ 機能開発と同時進行する ◼ Gitブランチのイメージ develop 機能開発 移行ブランチ
13. 14 pyenvからasdfへの移行 これだけはPython以外のバージョンも指定している
14. 15 pyenvからasdfの移行に1ヶ月かかる ◼ asdfへの導入自体はすぐできたが、asdfがチームに浸透するまで1ヶ月ほど要した ◼ 時間がかかった理由は、メンバーからasdfが効かないという声が多数あがったこと ◼ pyenvで作られたPythonの仮想環境が残っている場合、 asdfと.tool-versionsの内容より仮想環境のバージョンが優先されることがあるので、 仮想環境から抜けてから削除するとうまくいく ◼ Pythonのパスがpyenvのものを指してしまう場合は、 reshimしたり、シェルの初期化スクリプトを見直す（.zshrcや.bashrcなど)
15. 16 この時点ではデプロイスクリプトの見直しはなし 「pyenv local xxx」が「asdf install」になるだけなので、 そこだけ直して他のデプロイスクリプトの見直しは保留 次ページから次の話題になります
16. pipenvからuvへの移行 複雑化したリポジトリをモノレポ構成へ 中期 後期 初期
17. 18 pipenvからの移行先にuvを選定した理由 ◼ 依存関係解決やパッケージインストールが圧倒的に速い ◼ CI/CDの高速化に繋がる ◼ 最近勢いがあり、メジャーなところで使われている ◼ 単体でトップレベルでの一括ロック／一括installするワークスペース機能を有する ＝uvだけでモノレポ構成が可能
18. 19 リファクタリングの方針 ◼ 機能開発と同時進行する ◼ ディレクトリ構造の再構成とPythonバージョンの統一により、 可読性の向上とデプロイスクリプトの簡素化を目的とする ◼ これにより、今後モジュールがさらに増えても大きな見直しが入らないようにする ◼ 必要以上の見直しは行わない develop 機能開発 移行ブランチ
19. 20 手順 生成AI／手動 ディレクトリの再構成 生成AI Pythonのバージョンを統一 手動 ライブラリの再インストール 手動 デプロイスクリプトの見直しとトライ＆エラー 手動＞生成AI 動作確認 手動 pipenvの設定ファイルをuv形式に書き換え 生成AI＞手動 設定ファイルにモノレポ設定を加える 手動 デプロイスクリプトの見直しとトライ＆エラー 生成AI＞手動 動作確認 手動 リファクタリングの手順 ◼ 生成AIはAmazon Q Developer CLIを使用
20. 21 ディレクトリの再構成＜生成AI＞ <プロンプト> modulesフォルダを作り、 各モジュールをそこに集めます another_project_aをmodules配下に 移動して名前をmodule_aとしてください <プロンプト> 移動したのに合わせて、import文や各種スク リプトのパスを修正してください
21. 22 ディレクトリの再構成＜生成AI＞
22. 23 ディレクトリの再構成 ＜生成AI＞ <プロンプト> リポジトリルート直下にあるモジュールを、 modules/module_cとして移動させてください
23. 24 Pythonのバージョンを統一＜手動＞ asdfの.tools-versionsを一つに集約 ＝Pythonのバージョンを3.13に統一
24. 25 ライブラリの再インストール＜手動＞ 3.13に合わせてからライブラリを 再インストール
25. 26 デプロイスクリプトの見直し＜手動> ディレクトリ構成の見直しにより、 ビルドとデプロイは同じコマンド群をモジュールの個数分 繰り返せばOKと考えることができるようになった 故に、このタイミングでビルドとデプロイをシェル化 親子シェルにしている
26. 27 デプロイスクリプトの見直し 親シェルのイメージ
27. 28 デプロイスクリプトの見直し 子シェルのイメージ 親子シェルにしているのは開発時に モジュール単体のデプロイもすると考えたから シェルにしたのはAWSを用いている関係上、 引数・条件分岐・下準備が多いから
28. 29 デプロイスクリプトの見直しとトライ＆エラー＜生成AI> 作成したビルド・デプロイシェルを生成AI経由で実行、 エラーが出るたびに修正を指示して綺麗にしていく
29. 30 pipenvの設定ファイルをuv形式に書き換え＜手動>
30. 31 生成AIを用いたuv移行の注意点 ◼ 生成AIにpipenvのPipfileからuv用のpyproject.tomlへの移行を指示 ◼ ぱっと見移行をできたが、Pipfileの[scripts]相当のものを無理に書こうとしていた ため手動移行に変更 ◼ 生成AIが作ったものは、雰囲気を掴むためのテスト移行だと割り切り、手動で作り 直しをした
31. 32 設定ファイルにモノレポ設定を加える
32. 33 設定ファイルにモノレポ設定を加える モジュールのリスト
33. 34 設定ファイルにモノレポ設定を加える リンター・フォーマッターなど、 共通のライブラリは各モジュール から移動させてここに集約
34. 35 設定ファイルにモノレポ設定を加える モジュール特有のライブラリは こちらで指定
35. 36 作業中ブランチのマージについて ◼ uvへの移行と、モノレポ構成への移行は作業ブランチで実施 ◼ その間も機能開発は進んでいて、随時更新内容を取り込んで（マージ）いたが、 大きなコンフリクトは起きなかった ◼ やっていることがディレクトリ構成やパッケージ管理の置き換えが中心で、 ビジネスロジックに変更はなかったからと思われる develop 機能開発 移行ブランチ 次ページから次の話題になります
36. 後回しにしたもの 中期 初期 その後 後期
37. 38 後回しにしたもの 後回しにしたもの 理由 落とし所 タスクランナー • uvにタスクランナーはない • 移行先はMakefileが優先っぽいが決定的 なものがなかった • 進めるには議論が必要 • IaCを使っている関係で、package.jsonがあ るので一旦そちらで運用 • 違和感があるのでMakefileに移行 リンター・フォーマッター • 既存はblack+isort+flake8 • uvと合わせるためにruffを試したが、 整形結果が既存ツールと一致しなかったの で後回し • uvへの移行期間中は着手しない • 後日、isortとflake8はruffに移行 • blackは継続使用、整形結果がやはり既存と 完全一致しないため 重複コードの解消 重複コードの解消は、こういう方法もありますよというのを見つけたので紹介します （ベストプラクティスではありません）
38. 39 重複コードの解消 共通モジュールを作ったはいいが、ディレクトリ構造上、 工夫をしないと他のモジュールが参照できない 参照できない
39. 40 重複コードの解消 この書き方だと、エディタ上では共通モジュールを参照させられるが、 AWS Lambda・コンテナのデプロイまではできなかった
40. 41 重複コードのパッケージ化とAWS Lambdaへのデプロイ ① uv run python -m build 共通モジュールをパッケージ化した dist/shared_module.whlができる ② uv export --format requirements-txt --no-emit-workspace --no-dev --output-file requirements_layer/requirements.txt echo “../../../../../shared/dist/shared_module.whl --hash=sha256:ハッシュ値" >> requirements_layer/requirements.txt .whlファイルへの相対パスを追記したrequirements.txtを用意 それを持ってLambdaレイヤー、そしてLambdaをデプロイする
41. 42 重複コードのパッケージ化とコンテナのマルチステージビルド ローカルで共通モジュールをコンテナビルド 他モジュールのコンテナは共通モジュールのビルドイメージ「も」参照して、 共通モジュールのwheelを自身の中にコピーする
42. 43 [見送り]リポジトリサービスを利用する案 次ページから次の話題になります 全員がアクセスするリポジトリサービスを用意しないといけないのと、 サービスの認証・URL取得が手間なので見送り
43. uvによるモノレポ構成移行の効果 中期 初期 その後 後期
44. 45 uvによるモノレポ構成移行の効果 ◼ CI/CDの属人性の軽減、これによるCI/CDにSCA・SASTの導入 Gitプッシュ 静的解析（flake8→後にruff） 自動テスト（pytest） SCA ライブラリのセキュリティチェック SAST ソースコードのセキュリティチェック ビルド デプロイ
45. 46 uvによるモノレポ構成移行の効果 ◼ モジュールの量産体制が整った ◼ ビルド・デプロイ以外の運用シェルのPython化など、新たな改善の動きが見られる ようになった
46. 47 SCAとSASTの補足 ◼ SCAはAmazon Inspectorを使用し、ライブラリのチェック ◼ SASTはSemgrep（CE版）を使用して、ソースコードのチェック ◼ Inspectorはチェック対象としてuv.lockがサポートされていないので、 CI/CDでuvからrequirements.txtを出力してチェックさせる 次ページから次の話題になります uv export --format requirements-txt --no-emit-workspace --no-dev --output-file requirements_layer/requirements.txt
47. まとめ 2ページあります
48. 49 複雑化したリポジトリから、uvによるモノレポ構成への移行手順 手順 生成AI 手動 備考 ランタイムバージョンマネージャの見直し ー ◦ この作業の生成AIの効果は未検証 ディレクトリの再構成 ◦ △ パスの整合性を取るのは生成AIの方が向いている Pythonのバージョンを統一 ー ◦ 生成AIでやるメリットがない 手動で丁寧にやった方が良い ライブラリの再インストール ー ◦ デプロイスクリプトの見直し △ ◦ 大枠は手動で作るのがおすすめ 生成AIに任せると冗長なスクリプトになりがち デプロイスクリプトのトライ＆エラー ◦ △ 何度もトライ＆エラーが要るので、 生成AIにやらせるのがおすすめ pipenvの設定ファイルをuv形式に 書き換え △ ◦ ハルシネーションの影響を受けやすいので、 手動の方が適している 設定ファイルにモノレポ設定を加える △ ◦ ハルシネーションの影響を受けやすいので、 手動の方が適している デプロイスクリプトの見直し △ ◦ 1回目のデプロイスクリプトと同じ デプロイスクリプトのトライ＆エラー ◦ △
49. 50 まとめ ◼ uvだけでランタイム管理もできますが、asdf＋uvも使い勝手がいいです ◼ uvは高速なので、CI/CDの高速化にも寄与します ◼ uvへの移行、uvを用いたモノレポ構成への移行には生成AIが役立ちますが、 ハルネーションに惑わされることがあるので注意してください ◼ uvを導入すると、ruffなども入れたくなりますが、完全互換は難しいので、 段階移行や既存ツールとの併用も視野に入れた方がよいと思います ◼ モノレポ構成にすると共通モジュールの扱いが難しくなりますが、 wheelやマルチステージビルドを活用する手はあります
51. 52 参考資料 ◼ 開発言語のバージョン管理にasdfはいかがですか ◼ v0.16.0以降のasdfのインストール手順（arm64 Amazon Linux 2023） ◼ Pipenv ユーザーのための uv 入門