Python Poetry 套件管理工具

Poetry 是一個現代化的 Python 依賴管理和打包工具。它提供了一個統一的工具來管理專案依賴、虛擬環境、套件建置和發布。你可以把它想像成 Python 世界的 npm 或 yarn。

為什麼選擇 Poetry？

依賴解析：Poetry 擁有強大的依賴解析器，可以解決複雜的版本衝突。
單一設定檔：使用 pyproject.toml 管理所有設定，不需要 setup.py、requirements.txt、setup.cfg。
鎖定檔案：自動產生 poetry.lock，確保所有開發者和部署環境使用完全相同的套件版本。
虛擬環境管理：自動為專案建立和管理虛擬環境。

安裝

官方推薦的安裝方式（Linux, macOS, WSL）：

curl -sSL https://install.python-poetry.org | python3 -

Windows (PowerShell):

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

安裝完成後，確認版本：

poetry --version

基本用法

1. 初始化專案

在現有目錄中初始化：

poetry init

這會引導你建立 pyproject.toml 檔案。

或者建立新專案：

poetry new my-project

2. 新增依賴

使用 add 指令安裝套件，這會自動更新 pyproject.toml 和 poetry.lock：

# 安裝最新版 requests
poetry add requests

# 安裝特定版本
poetry add "flask=^2.0"

# 安裝開發依賴 (例如測試工具)
poetry add pytest --group dev

3. 安裝依賴

當你下載別人的專案時，執行 install 來安裝所有依賴：

poetry install

這會根據 poetry.lock 安裝確切的版本。如果沒有 lock 檔，則根據 pyproject.toml 解析並產生 lock 檔。

4. 執行程式

Poetry 會自動管理虛擬環境。要使用虛擬環境中的 Python 執行程式：

poetry run python main.py

或者進入虛擬環境的 shell：

poetry shell

5. 更新依賴

# 更新所有套件到符合 pyproject.toml 規範的最新版
poetry update

# 更新特定套件
poetry update requests

常用指令列表

指令	說明
`poetry init`	初始化專案（建立 pyproject.toml）
`poetry add <package>`	安裝套件並加入依賴
`poetry remove <package>`	移除套件
`poetry install`	安裝專案所有依賴
`poetry update`	更新依賴套件版本
`poetry run <cmd>`	在虛擬環境中執行指令
`poetry shell`	進入虛擬環境 shell
`poetry check`	檢查 pyproject.toml 是否有效
`poetry build`	建置套件 (sdist 和 wheel)
`poetry publish`	發布套件到 PyPI

設定檔 (pyproject.toml) 範例

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
authors = ["Mike <mike@example.com>"]

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28.1"
fastapi = "^0.85.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.1.3"
black = "^22.8.0"

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

虛擬環境位置

預設情況下，Poetry 會將虛擬環境建立在系統的快取目錄中。如果你希望虛擬環境建立在專案目錄下的 .venv 資料夾（這讓 VS Code 等編輯器更容易偵測），可以設定：

poetry config virtualenvs.in-project true