基本用法
基本用法 #
對於基本用法介紹，我們將安裝日期時間函式庫 pendulum。如果您尚未安裝 Poetry，請參閱 簡介章節。
專案設定 #
首先，讓我們建立新的專案，我們稱它為 poetry-demo
poetry new poetry-demo
這樣會建立 poetry-demo 目錄，其中包含下列內容
poetry-demo
├── pyproject.toml
├── README.md
├── poetry_demo
│ └── __init__.py
└── tests
└── __init__.py
其中最重要的是 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"
Poetry 假設您的套件包含一個套件，其名稱與 tool.poetry.name 相同，且位於專案的根目錄。如果不是這種情況，請填充 tool.poetry.packages 以指定您的套件及其位置。
類似地，傳統的 MANIFEST.in 檔案已由 tool.poetry.readme、tool.poetry.include 和 tool.poetry.exclude 部分取代。此外，tool.poetry.exclude 會透過您的 .gitignore 隱含填入。如需有關專案格式的完整說明，請參閱說明文件中的 pyproject 部分。
設定 Python 版本 #
使用 Poetry 時，你需要明確指出要支援的 Python 版本，通用鎖定機制將保證專案可以安裝（所有相依性宣稱支援）所有受支援的 Python 版本。再次提醒，很重要的一點是，相較於其他相依性，設定 Python 版本只是單純指出打算要支援哪些 Python 版本。
舉例來說，在這個 pyproject.toml 檔案中
[tool.poetry.dependencies]
python = "^3.7.0"
我們允許 Python 3 的任何版本，大於 3.7.0。
執行 poetry install 時，系統上必須有可以滿足這個約束條件的 Python 解釋器版本。Poetry 不會 替你安裝 Python 解釋器。如果你使用 pyenv 這樣的工具，可以使用實驗性的組態值 virtualenvs.prefer-active-python。
初始化現有專案 #
除了建立新的專案，也可以使用 Poetry 來「初始化」已填充的目錄。要在目錄 pre-existing-project 中以互動方式建立 pyproject.toml 檔案
cd pre-existing-project
poetry init
執行模式 #
Poetry 有兩種不同的執行模式。預設模式為套件模式，如果你想要將專案封裝成 sdist 或輪子，還有可能是將其發佈到套件索引，這是有用的執行模式。在此模式中，某些元資料，例如包裝所需的 name 和 version，是強制性的。此外，執行 poetry install 時，會以可編輯模式安裝專案本身。
如果你只想使用 Poetry 進行相依性管理，而不想使用來進行包裝，你可以使用非套件模式
[tool.poetry]
package-mode = false
在此模式中，元資料，例如 name 和 version，是可選的。因此，建立發行版或將專案發布到套件索引是不可能的。此外，執行 poetry install 時，Poetry 並不會嘗試安裝專案本身，而是只安裝其相依性（等同於 poetry install --no-root）。
指定相依性 #
如果你想要在你的專案中新增相依性，你可以使用在 tool.poetry.dependencies 區段中指定它們。
[tool.poetry.dependencies]
pendulum = "^2.1"
正如你可以看到的，這需要對應的套件名稱和版本約束。
Poetry 使用此資訊來搜尋套件「儲存庫」中適當的檔案集，這些儲存庫是你註冊在 tool.poetry.source 區段中，或者預設是在 PyPI 上。
此外，除了手動修改 pyproject.toml 檔案，你也可以使用 add 指令。
$ poetry add pendulum
它會自動尋找適當的版本約束並安裝套件和次相依性。
Poetry 支援豐富的 依賴項規格 語法，包括插入符號、約等於、萬用字元、不等於和 多個約束 需求。
使用虛擬環境 #
預設情況下，Poetry 會在 {cache-dir}/virtualenvs 中建立虛擬環境。你可以透過編輯 Poetry 設定來變更 cache-dir 值。此外，你可以使用 virtualenvs.in-project 設定變數在專案目錄中建立虛擬環境。
有數種方法可以在此虛擬環境中執行命令。
外部虛擬環境管理
Poetry 會偵測已經外部啟用的現有虛擬環境並尊重它。這是一個強大的機制，旨在作為 Poetry 內建簡化環境管理的替代方案。
若要利用這點，只需在執行任何預期要操作環境的 Poetry 命令之前，使用你偏好的方法或工具啟動虛擬環境即可。
使用 poetry run #
若要執行你的腳本，只需使用 poetry run python your_script.py。同樣地，如果你有 pytest 或 black 等命令列工具，你可以使用 poetry run pytest 來執行它們。
如果你在外部管理自己的虛擬環境，則不需要使用 poetry run 或 poetry shell，因為你可能已經啟動了該虛擬環境並提供了正確的 python 執行個體。例如，下列命令應會輸出相同的 Python 路徑
conda activate your_env_name
which python
poetry run which python
poetry shell
which python
啟動虛擬環境 #
啟動虛擬環境的最簡單方法是使用 poetry shell 建立巢狀 shell。
若要停用虛擬環境並離開此新 shell，請輸入 exit。若要停用虛擬環境而不離開 shell，請使用 deactivate。
為何要巢狀 shell？
子處理序會繼承其父處理序的環境，但不會共用這些環境。因此，子處理序所做的任何變更在子處理序結束後不會保留。Python 應用程式 (Poetry) 是子處理序，無法變更呼叫它的 shell 的環境，使得啟動的虛擬環境在 Poetry 命令執行完畢後仍然處於啟動狀態。
因此，Poetry 必須建立一個具有已啟動虛擬環境的子 shell，以便後面的命令能從虛擬環境內執行。
如果你想防止 poetry shell 在虛擬環境啟動時變更你的 shell 提示，你應該在執行命令之前將 VIRTUAL_ENV_DISABLE_PROMPT=1 設定為環境變數。
使用其他方式，為了避免建立新的 shell，您可以手動執行 source {path_to_venv}/bin/activate ({path_to_venv}\Scripts\activate.ps1 in PowerShell) 來啟用虛擬環境。若要取得您的虛擬環境路徑，請執行 poetry env info --path。您也可以將這些內容結合為一行，例如 source $(poetry env info --path)/bin/activate (& ((poetry env info --path) + "\Scripts\activate.ps1") in Powershell)。
若要停用此虛擬環境，請直接使用 deactivate。
| POSIX Shell | Windows (PowerShell) | 退出/停用 | |
|---|---|---|---|
| 次 shell | poetry shell |
poetry shell |
exit |
| 手動啟用 | source {path_to_venv}/bin/activate |
{path_to_venv}\Scripts\activate.ps1 |
deactivate |
| 一行 | source $(poetry env info --path)/bin/activate |
& ((poetry env info --path) + "\Scripts\activate.ps1") |
deactivate |
版本約束 #
在我們的範例中，我們要求 pendulum 套件版本限制為 ^2.1。這表示大於或等於 2.1.0 且小於 3.0.0 的任何版本 (>=2.1.0 <3.0.0)。
請閱讀 相依性規格 以深入了解各版本、版本之間的關係，以及指定相依性的不同方式。
Poetry 如何下載正確的檔案?
當你在 pyproject.toml 中指定相依性時，Poetry 會先取得你要求的套件名稱，然後在使用 repositories 關鍵字註冊的任何儲存庫中搜尋它。如果你尚未註冊任何額外的儲存庫，或是在你指定的儲存庫中找不到同名的套件，它會回退至 PyPI。
當 Poetry 找到正確的套件後，它會嘗試找出最符合你所指定版本約束的版本。
安裝相依性 #
若要為你的專案安裝已定義的相依性，請執行 install 指令。
poetry install
執行這項指令時，可能會發生以下兩種情況
在未採用 poetry.lock 的情況下安裝 #
如果你從未執行過指令，且不存在 poetry.lock 檔案，Poetry 會簡單地解析 pyproject.toml 檔案中列出的所有相依性，並下載它們的最新版本檔案。
當 Poetry 安裝完畢後，它會將所有套件及其下載的確切版本寫入 poetry.lock 檔案，將專案鎖定為那些特定版本。你應該提交 poetry.lock 檔案至你的專案儲存庫，以便所有參與專案的人員都鎖定在相同的相依性版本 (更多內容見下)。
在採用 poetry.lock 的情況下安裝 #
這將我們帶到第二種場景。如果你在執行 `poetry install` 時已有了 `poetry.lock` 檔案和 `pyproject.toml` 檔案，這代表你之前執行過 `install` 指令，或者專案中的其他人執行過 `install` 指令並將 `poetry.lock` 檔案提交到專案中（這是好的）。
無論如何，在有 `poetry.lock` 檔案時執行 `install`，可以解析並安裝你列在 `pyproject.toml` 中的所有相依項目，但 Poetry 會使用 `poetry.lock` 中列出的確切版本，以確保你的專案中的所有人都有相符的套件版本。結果是，你將具備 `pyproject.toml` 檔案中要求的所有相依項目，但它們可能不會是最新的可用版本（自建立 `poetry.lock` 檔案以來，檔案中列出的某些相依項目可能已發布更新版本）。這是由設計而成的，它確保你的專案不會因相依項目的意外變更而中斷。
將你的 `poetry.lock` 檔案提交到版本控制 #
身為應用程式開發人員 #
應用程式開發人員提交 `poetry.lock` 以取得更具可複製性的建置。
將此檔案提交到 VC 很重要，因為它將導致任何設定專案的人使用你正在使用的相依項目的完全相同版本。你的 CI 伺服器、製作機器、你團隊中的其他開發人員，所有事務和人員都在相同的相依項目上執行，這可以減輕僅影響部署某些部分的錯誤的可能性。即使你單獨開發，在六個月後重新安裝專案時，你也可以確信安裝的相依項目仍在運作，即使你的相依項目自那時以來已發布了許多新版本。（請參閱下方關於使用更新指令的說明。）
[build-system] 部分，你可以使用例如 `pip install -e .` 之類的指令成功將你的專案及其相依項目安裝到虛擬環境中。但是，pep 會不使用鎖定檔案來確定相依項目的版本，因為 `poetry-core` 建置系統是為函式庫開發人員設計的（請參閱下一部分）。身為函式庫開發人員 #
函式庫開發人員必須考慮更多事項。你的使用者是應用程式開發人員，而你的函式庫將在你不控制的 Python 環境中執行。
應用程式忽略你的函式庫的鎖定檔案。它可以使用任何符合你的 `pyproject.toml` 中限制條件的相依項目版本。應用程式可能使用最新的相容相依項目版本。如果你的函式庫的 `poetry.lock` 落後於某些新的相依項目版本，而這對你的使用者的某些功能造成影響，你很可能會是最後一個知道這件事的人。
避免這樣情形的簡單方法是忽略 poetry.lock 檔案。然而，這麼做會在某個程度上犧牲了可重製性和效能。在沒有鎖定檔案的情況下，可能會很難找出測試失敗的原因，因為除了變更程式碼之外，沒有注意到的程式庫更新可能是罪魁禍首。此外，如果忽略了 poetry.lock，Poetry 在安裝依賴項之前必須先鎖定。根據依賴項的數量，鎖定可能會花費相當長的時間。
如果你不想要放棄可重製性和效能的優點，可以考慮定期更新 poetry.lock，以保持最新狀態並降低使用者突然發生問題的風險。
只安裝依賴項 #
目前的專案預設會安裝為 可編輯 模式。
如果你只想安裝依賴項，可以使用 install 指令以及 --no-root 旗標
poetry install --no-root
將依賴項更新至最新版本 #
如上所述，poetry.lock 檔案會防止你自動取得最新版本的依賴項。若要更新至最新版本，請使用 update 指令。這會擷取最新的一致版本 (根據你的 pyproject.toml 檔案) 並更新鎖定檔案的新版本。(這等於刪除 poetry.lock 檔案並重新執行 install。)
poetry.lock 和 pyproject.toml 未同步，執行安裝指令時，Poetry 會顯示 **警告訊息**。