パッケージ管理したい（poetry）

$ pipx install poetry
$ which poetry
/Users/shotakaha/.local/bin/poetry
$ poetry --version
Poetry (version 1.8.2)

$ poetry add pandas matplotlib
$ poetry add --group=dev ipykernel pytests commitizen ruff
$ poetry add --group=docs sphinx_book_theme myst_parser

プロジェクトに依存するパッケージを管理したり、PyPIなどに公開するにはPoetryがオススメです。 Pythonのパッケージ管理ツールはいろいろ存在していますが、（おそらく複雑な歴史的な経緯があり）まったく統一されておらず、すべてを把握＆理解するのは不可能だと思います。 僕は、たまたま使い始めてみたのですが、使い勝手がよいなと感じています。

インストールしたい（pipx install poetry）

$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -

公式ドキュメントでは独自スクリプトを使った方法が推奨されています。

$ pipx install poetry
$ which poetry
~/.local/bin/poetry

pip3のインストールは推奨されてないみたいですが、pipxはフルサポートされています。

$ brew install poetry
$ which poetry
/opt/homebrew/bin/poetry

Homebrewを使ったインストールでも、とくに問題なく使えました。

注意

このいずれかひとつの方法でインストールしてください。

シェル補完したい（poetry completions）

$ poetry completions fish > ~/.config/fish/completions/poetry.fish

poetryコマンドのシェル補完が使えるようにしておくと便利です。 bash、zsh、fishのシェルに対応しています。

ヒント

fishのシェル補完を使うと、シェルセッションで最初に実行したときにエラーが表示されます。 v1.2.0から存在しているバグ（poetry#5929）ですが、v1.5.0になっても修正されていません。 そのままでも使うことはできますが、以下のようにsdコマンドを使って置換して対処できます。

$ poetry completions fish | sd "'([^']+)''" '"$1"\'' > ~/.config/fish/completions/poetry.fish

エラーの原因は、以下のように__fish_seen_subcommand_fromが使われている部分の引数の文字列の囲み方に問題があるようです。

- < complete -c poetry -A -n '__fish_seen_subcommand_from 'cache clear'' -l all -d 'Clear all entries in the cache.'
---
+ > complete -c poetry -A -n '__fish_seen_subcommand_from "cache clear"' -l all -d 'Clear all entries in the cache.'

新規プロジェクトしたい（poetry new）

$ poetry new プロジェクト名
$ cd プロジェクト名

新規プロジェクトを作成する場合は、poetry newコマンドを使います。 プロジェクト名のディレクトリが作成され、その下に、pyproject.toml、プロジェクト名（＝プロジェクト本体のソースコード置き場）、testsなどの必要なファイルが自動で生成されます。

既存プロジェクトを使いたい（poetry init）

$ cd プロジェクト名
$ poetry init

既存のプロジェクトはpoetry initを使って、対話的にプロジェクトを初期化できます。 プロンプトの表示にしたがってプロジェクト情報（プロジェクト名、説明、作成者、バージョン番号、ライセンスなど）を入力します。 続けて、必要なパッケージに関するプロンプトが表示されるので、パッケージ名やバージョン番号を入力して、パッケージを選択します。 これらの設定はすべてpyproject.tomlの[tool.poetry]セクションに保存されます。 あとから直接編集できるので、間違えてしまっても大丈夫です。

パッケージを追加したい（poetry add）

$ poetry add パッケージ名
$ poetry add パッケージ名 -E パッケージ名
$ poetry add --group=dev パッケージ名
$ poetry add --group=docs パッケージ名

必要なパッケージ名をpyproject.tomlに追記して、仮想環境（.venv）の中にインストールします。 -E / --extraオプションを使って、追加パッケージも指定できます。 パッケージは[tool.poetry.dependencies]のセクションに追記され、ロックファイル（poetry.lock）が生成されます。

開発環境を追加したい（--group=dev）

$ poetry add --group=dev pytests
$ poetry add --group=dev commitizen
$ poetry add --group=dev jupyterlab

開発に必要なパッケージは--group=devに追加します。 （たしか）v1.3.0からグループ化する機能追加され、add -Dオプションが非推奨になりました。

ドキュメント環境を追加したい（--group=docs）

$ poetry add --group=docs sphinx_book_theme
$ poetry add --group=docs myst_parser

ドキュメント作成に必要なパッケージは--groupd=docsに追加します。

パッケージをインストールしたい（poetry install）

$ poetry install

poetry.lockにあるパッケージをインストールします。 poetry.lockがない場合は、pyproject.tomlにあるパッケージをインストールして、poetry.lockを生成します。

デフォルトでは{cache-dir}/virtualenvs/に設定されたパスの仮想環境を作成し、パッケージをインストールします。 virtualenvs.in-project = trueに設定した場合は、プロジェクト内の{project-dir}/.venv/に仮想環境を作成します。

パッケージを公開したい（poetry publish）

$ poetry build
$ poetry publish -r testpypi  # TestPyPIに公開
$ poetry publish              # PyPIに公開

パッケージをビルドしてから公開します。 はじめて公開する場合は必ずTestPyPIでテストするのがよいです。 公開する前にリポジトリとAPIトークンの設定が必要です。

参考

僕のZennスクラップ「poetryを使ってpythonパッケージを作成する」に、Poetryを使ってパッケージを新規作成してPyPIで公開するまでの手順を整理しました。

現在の設定を確認したい（poetry config）

$ poetry config --list
cache-dir = "~/Library/Caches/pypoetry"
experimental.new-installer = true
experimental.system-git-client = false
installer.max-workers = null
installer.modern-installation = true
installer.no-binary = null
installer.parallel = true
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = false
virtualenvs.options.no-pip = false
virtualenvs.options.no-setuptools = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}/virtualenvs"  # ~/Library/Caches/pypoetry/virtualenvs
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"

現在の設定はpoetry config --listで確認できます。 デフォルトの設定は上記のようになっていました。 全体の設定は~/Library/Application Support/pypoetry/config.tomlに保存されます。 --localオプションをつけて設定した項目は、プロジェクト内のpoetry.tomlに保存されます。

注釈

全体の設定は、以前は~/Library/Preferences/pypoetry/config.tomlに保存されていました。 その状態でもまだ使えるようですが、将来的にはパスを変更したほうがよさそうです。

設定を変更したい

$ poetry config キー名 値
$ poetry config キー名 値 --local

変更可能な設定はPoetryドキュメントのAvailable Settingsを参照してください。 Poetry v1.2.0になって設定できる項目が増えました。

設定を削除したい

$ poetry config キー名 --unset
$ poetry config キー名 --unset --local

追加した設定を削除する場合はキー名に対して--unsetします。

プロジェクト内に仮想環境を作成したい

# 現在の設定値を確認する
$ poetry config virtualenvs.in-project
null

# 設定を有効にする
$ poetry config virtualenvs.in-project true

# 変更後の設定値を確認する
$ poetry config virtualenvs.in-project
true

仮想環境はvirtualenvs.pathで設定されたパスに作成されます。 デフォルトでは{cache-dir}/virtualenvsに設定されています。

virtualenvs.in-projectをtrueにすると、その設定をカレントディレクトリの.venvに変更できます。 GitHub/GitLabなどを通じて複数のマシンで作業する場合は、この値を有効にしておくとよいです。

注意

すでに{cache-dir}/virtualenvs/に仮想環境がある場合は、一度削除（rm -r）してから作成しなおしてください。

システムのパッケージを使いたい

1$ poetry config virtualenvs.option.system-site-packages true

virtualenvs.option.system-site-packagesをtrueにすると、システムのPythonのsite-packagesにインストールが仮想環境から使えるようになります。 開発環境で使うパッケージ（pytest / black / commitizen / pysen）などを使うには、これを有効にしておいてもいいかもしれません。

ヒント

複数のPythonプロジェクトを持っていると、それぞれのプロジェクトの.venvにパッケージがインストールされます。 開発環境にだけ必要なパッケージを共通化することで、少しだけでもディスク節約になるかもしれません。

リポジトリとAPIトークンを設定したい

$ poetry config repositories.名前 URL
$ poetry config pypi-token.名前 "APIトークン"

名前の部分は任意の文字列で構いません。 以下にPyPIとTestPyPIの設定例を挙げておきます。

1# PyPIの設定
2$ poetry config pypi-token.pypi "PyPIのAPIトークン"
3
4# TestPyPIの設定
5$ poetry config repositories.testpypi https://test.pypi.org/legacy/
6$ poetry config pypi-token.testpypi "TestPyPIのAPIトークン"

PyPIはデフォルトの公開先になっているため、リポジトリの設定は必要ありません。 TestPyPIに公開する場合は、リポジトリのURLを設定する必要があります。 公開先のAPIトークンをそれぞれ事前に発行しておく必要があります。