業務でPoetryを使っています。
Poetryを使うにあたり色々調べたのでメモとして整理しておきます。

Poetryとは

PoetryとはPythonの依存関係やパッケージの管理ツール。

python-poetry.org

pyproject.tomlに依存関係を記述することで簡単にパッケージ管理ができます。

pyproject.tomlとは

pyproject.tomlはTOML形式で記載されており、poetry newやpoetry initした際に自動で出力されます。

pyproject.toml

[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["Sébastien Eustace <sebastien@eustace.io>"]
readme = "README.md"
packages = [{include = "poetry_demo"}]

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

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

参考：TOML(Tom's Obvious Minimal Language)

依存関係はtool.poetry.dependenciesセクションで定義し、パッケージ名 = バージョン制約で記載します。

pyproject.toml

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

依存関係はpyproject.tomlに直接もしくはコマンドで追加することができます。
（コマンドでの追加は下記のように実行）

$ poetry add パッケージ名

参考：The pyproject.toml file

バージョン制約について

pyproject.tomlに記載するバージョン制約は「セマンティックバージョニング」を前提とした指定を行います。

セマンティックバージョニングとは、ソフトウェアのバージョンをどう管理するかのルールで、バージョン番号をmajor:minor:patch形式で表す仕様のことです。

major：互換性のない変更を行った場合にインクリメント
minor：下位互換性のある方法で機能を追加した場合にインクリメント
patch：下位互換性のあるバグ修正を行った場合にインクリメント
参考：Semantic Versioning 2.0.0

例えば、pyproject.tomlのバージョン制約として下記のようにいろいろな指定が可能となります。

バージョン制約	許可されるバージョン	説明
^1.2.3	>=1.2.3 <2.0.0	minorレベルの変更のみ許可
～1.2.3	>=1.2.3 <1.3.0	patchレベルの変更のみ許可
1.2.*	>=1.2.0 <1.3.0	`*`が配置される最新のバージョンを許可
>= 1.2.0	>= 1.2.0	指定したバージョン範囲を許可
==1.2.3	1.2.3	一意のバージョンを許可

例えば、バージョン制約に^1.2.3を指定した場合、ビルド時に1.2.3 =< バージョン <2.0.0の範囲内でその時の最新バージョンをダウンロードおよびインストールします。

上記のような指定が可能なため、新しいバージョンが出るたびにpython:pyproject.tomlを変更しなくても良いとういメリットがあります。

参考：Dependency specification

poetry.lockとは

Poetryにはpyproject.toml以外にもpoetry.lockというファイルもあります。

2つのファイルの違いは、以下となります。

pyproject.toml：適用したいライブラリおよびバージョンが記載されたファイル
poetry.lock：現環境に適用されているライブラリおよびバージョンが記載されたファイル

また、ビルド時に参照するファイルについては、下記の条件で判断されます。

poetry.lockが存在しない場合、python:pyproject.tomlにリストされている依存関係を解決し、許可されるバージョンをダウンロードします。
ダウンロードおよびインストールが完了すると、ダウンロードしたすべてのパッケージとその正確なバージョンがpoetry.lockに書き込まれます。

そのため、pyproject.tomlに^3.11と書いた場合、その時にインストールされたバージョンが何なのかはpoetry.lockを見ればわかるようになっています。

また、使用しているパッケージの最新バージョンが公開されるなど、ビルドするタイミングによってはメンバーによっては使っているバージョンが異なってしまう可能性もでてきます。

それだと困るので、poetry.lockファイルを出力し、poetry.lockがある場合はpoetry.lockを先に見にいくようになっています。

このような仕様となっているのでpoetry.lockをバージョン管理下にすることで、メンバー全員が同じバージョンのパッケージを使って開発ができるようにすることが推奨されています。

依存関係グループについて

最後に、Poetryでは依存関係をグループ別に整理することができる。
依存関係のグループを宣言するにはtool.poetry.group.<group>セクションを使用します。

このグループはあくまでラベル的な扱いで論理的に依存関係を整理するためのものとなります。

[tool.poetry.dependencies]
python = "^3.11"
pydantic = "^1.10.7"
spectree = "^1.1.2"

[tool.poetry.group.dev.dependencies]
pytest = "^7.3.1"
ruff = "^0.0.261"
black = "^23.3.0"

参考：dependencies and dependency groups

以上です。