首頁 Poetry 標誌

pyproject.toml 檔案

pyproject.toml 檔案 #

pyproject.toml 檔案的 tool.poetry 區段由多個區段組成。

package-mode #

Poetry 是以套件模式運作 (預設)，還是不以套件模式運作。非必要

請參閱 基本用法 以取得更多詳細資訊。

package-mode = false

name #

套件名稱。套件模式中必要

這應該是一個由 PEP 508 所定義的有效名稱。

name = "my-package"

version #

套件版本。套件模式中必要

這應該是一個有效的 PEP 440 字串。

version = "0.1.0"
注意
如果您想為專案使用語意化版本，請參閱 這裡。

description #

套件簡述。套件模式中必要

description = "A short description of the package."

license #

套件授權。

對於最常見的授權，建議使用的表示法為 (依字母順序)

  • Apache-2.0
  • BSD-2-Clause
  • BSD-3-Clause
  • BSD-4-Clause
  • GPL-2.0-only
  • GPL-2.0-or-later
  • GPL-3.0-only
  • GPL-3.0-or-later
  • LGPL-2.1-only
  • LGPL-2.1-or-later
  • LGPL-3.0-only
  • LGPL-3.0-or-later
  • MIT

這是選用的，但強烈建議提供。更多的識別碼會列在 SPDX 開放源始碼授權註冊 中。

license = "MIT"
注意
如果你的專案為所有權且未使用特定的授權，你可以將這個值設為所有權。

作者 #

套件的作者。在套件模式中是必須的

這是一個作者清單且至少需要有一個作者。作者必須是 name <email> 的格式。

authors = [
    "Sébastien Eustace <sebastien@eustace.io>",
]

維護者 #

套件的維護者。選用的

這是維護者的清單，並且與作者不同。維護者可以包括電子郵件且為 name <email> 的格式。

maintainers = [
    "John Smith <johnsmith@example.org>",
    "Jane Smith <janesmith@example.org>",
]

readme #

路徑，或對應套件各 README 檔之路徑列表。選用的

該檔案可用各種格式，但如果你打算發布至 PyPI，請將 對 PyPI 友善的 README 建議 牢記在心。README 路徑隱含相對於 pyproject.toml。

注意

路徑是否區分大小寫則會遵循平台預設，但建議保持大小寫。

明確來說，你可以在 macOS 和 Windows 上為 README.md 設定 readme = "rEaDmE.mD"，但 Linux 使用者在你複製儲存庫後將無法 poetry install。這是因為 macOS 和 Windows 不區分大小寫且會保留大小寫。

README 檔的內容會用於填寫散佈之資料中的 說明欄位（類似 setuptools 中的 long_description）。當指定多個檔案時，它們會加上換行符號連接起來。

[tool.poetry]
# ...
readme = "README.md"

[tool.poetry]
# ...
readme = ["docs/README1.md", "docs/README2.md"]

首頁 #

專案網站的 URL。選用的

homepage = "https://poetry.dev.org.tw/"

儲存庫 #

專案儲存庫的 URL。選用的

repository = "https://github.com/python-poetry/poetry"

說明文件 #

專案說明文件的 URL。選用的

documentation = "https://poetry.dev.org.tw/docs/"

關鍵字 #

與套件相關的關鍵字清單。選用的

keywords = ["packaging", "poetry"]

分類 #

描述專案的 PyPI 套件分類清單。選用的

[tool.poetry]
# ...
classifiers = [
    "Topic :: Software Development :: Build Tools",
    "Topic :: Software Development :: Libraries :: Python Modules"
]
注意

請注意，Python 分類仍會自動為你新增，並且由你的 python 需求確定。

授權 屬性也會自動設定授權分類。

套件 #

最後散佈需包括的套件和模組清單。

如果您專案結構不同於 poetry 支援的標準，您可以指定要包含於最終發行版本中的套件。

[tool.poetry]
# ...
packages = [
    { include = "my_package" },
    { include = "extra_package/**/*.py" },
]

如果您的套件儲存在 “lib” 目錄中，您必須指定該目錄。

[tool.poetry]
# ...
packages = [
    { include = "my_package", from = "lib" },
]

to 參數用於指定安裝後套件將在哪個相對目的地路徑中。此參數讓您可以更進一步控制專案結構中套件的組織方式。

[tool.poetry]
# ...
packages = [
    { include = "my_package", from = "lib", to = "target_package" },
]

如果您想要針對特定組建格式限制套件，您可以使用 format 來指定它。

[tool.poetry]
# ...
packages = [
    { include = "my_package" },
    { include = "my_other_package", format = "sdist" },
]

從現在起，只有 sdist 組建封存檔會包含 my_other_package 套件。

注意

使用 packages 會停用套件自動偵測功能，這意味著您必須明確指定“預設值”套件。

例如，如果您有個套件名為 my_package，而您也想包含另一個名為 extra_package 的套件，您需要明確指定 my_package。

packages = [
    { include = "my_package" },
    { include = "extra_package" },
]
注意

Poetry 十分聰明，能夠偵測 Python 子套件。

因此，您只要指定您的根套件所在的目錄即可。

包含與排除 #

將會包含於最終套件的樣式清單。

您可以明確指定 Poetry 應該忽略或包含的 glob 群組，以作為套件化目的。exclude 欄位中指定的一些 glob 會識別一套在組建套件時不會包含的檔案。

如果套件使用了 VCS, 則 exclude 欄位會以 VCS 忽視設定為種子 (例如 git 的 .gitignore)。

注意
明確宣告 include 中的項目會否定 VCS 的忽視設定。
[tool.poetry]
# ...
include = ["CHANGELOG.md"]

您也可以指定這些樣式要包含的格式，如下所示

[tool.poetry]
# ...
include = [
    { path = "tests", format = "sdist" },
    { path = "for_wheel.txt", format = ["sdist", "wheel"] }
]

如果沒有指定格式，include 預設值僅為 sdist。

相對地，exclude 預設值為 sdist 和 wheel。

exclude = ["my_package/excluded.py"]

依賴關係與依賴關係群組 #

Poetry 的設定預設會在 PyPI 上尋找依賴關係。此時只要求提供名稱和版本字串即可。

[tool.poetry.dependencies]
requests = "^2.13.0"

如果您想要使用 私人儲存庫，您可以將它新增到您的 pyproject.toml 檔案中，如下所示

[[tool.poetry.source]]
name = "private"
url = "http://example.com/simple"

如果您已經設定好多個儲存庫，您可以明確告訴 poetry 到哪裡尋找特定套件。

[tool.poetry.dependencies]
requests = { version = "^2.13.0", source = "private" }
注意

請注意，宣告您的套件相容的 python 版本是強制性的。

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

您可以在 群組 中組織您的依賴關係，以便以更細微的方式管理它們。

[tool.poetry.group.test.dependencies]
pytest = "*"

[tool.poetry.group.docs.dependencies]
mkdocs = "*"

有關如何管理相依性群組，請參閱 相依性群組；有關其他金鑰與指定版本範圍的更多資訊，請參閱 相依性規格說明。

指令碼 #

這個區段說明安裝套件時將會安裝哪些指令碼或可執行程式

[tool.poetry.scripts]
my_package_cli = 'my_package.console:run'

在此，會安裝 my_package_cli 指令碼，這個指令碼將執行 my_package 套件中的 console 模組中的 run 函式。

注意
新增或更新指令碼時，請執行 poetry install 以將其置於專案的 virtualenv 中。

額外 #

Poetry 支援額外功能，以讓表達成為可能

  • 選擇性的相依性，有助於增強套件，但不是必要的；還有
  • 選擇性相依性的群集。
[tool.poetry]
name = "awesome"

[tool.poetry.dependencies]
# These packages are mandatory and form the core of this package’s distribution.
mandatory = "^1.0"

# A list of all of the optional dependencies, some of which are included in the
# below `extras`. They can be opted into by apps.
psycopg2 = { version = "^2.9", optional = true }
mysqlclient = { version = "^1.3", optional = true }

[tool.poetry.extras]
mysql = ["mysqlclient"]
pgsql = ["psycopg2"]
databases = ["mysqlclient", "psycopg2"]

使用 Poetry 安裝套件時，你可以透過 -E|--extras 選項指定額外功能

poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql

任何未指定的額外功能將會被移除。請注意，此行為與未選取安裝的 選擇性相依性群組 不同，例如未透過 install --with 指定的。

你可以使用 --all-extras 選項安裝所有額外功能

poetry install --all-extras
注意

請注意，install --extras 與上述提到的變異（--all-extras、--extras foo 等）只適用於目前專案中定義的相依性。如果你想安裝由相依性定義的額外功能，你必須在相依性本身中表達出來

[tool.poetry.dependencies]
pandas = {version="^2.2.1", extras=["computation", "performance"]}

[tool.poetry.group.dev.dependencies]
fastapi = {version="^0.92.0", extras=["all"]}

在安裝或指定由 Poetry 建置的套件時，可以依 PEP 508 中所述，啟用在這個區段定義的額外功能。

舉例來說，在使用 pip 安裝套件時，可以依以下所示，安裝 databases 額外功能所需的相依性。

pip install awesome[databases]
注意

為每個 extra 指定的相依性，都必須已經定義為專案相依性。

列在 相依性群組 中的相依性，無法指定為額外功能。

外掛程式 #

Poetry 支援任意的外掛程式，其公開為生態系統標準 進入點，並可以使用 importlib.metadata 偵測。這類似（並相容於）setuptools 的進入點功能。註冊外掛程式的語法為

[tool.poetry.plugins] # Optional super table

[tool.poetry.plugins."A"]
B = "C:D"

其中

  • A - 外掛程式的類型，例如 poetry.plugin 或 flake8.extension
  • B - 外掛程式的名稱
  • C - Python 模組匯入路徑
  • D - 外掛程式的進入點（一個函式或類別）

範例（來自 poetry-plugin-export）

[tool.poetry.plugins."poetry.application.plugin"]
export = "poetry_plugin_export.plugins:ExportApplicationPlugin"

網址 #

除了一般的網址（首頁、儲存庫以及文件）外，您還可以在網址部分指定任何自訂網址。

[tool.poetry.urls]
"Bug Tracker" = "https://github.com/python-poetry/poetry/issues"

如果您在 PyPI 上發布您的套件，它會顯示在專案連結部分。

詩與 PEP-517 #

PEP-517 提出一個標準的方式，用來定義替代建置系統以建置 Python 專案。

詩相符於 PEP-517，因為它提供了一個輕量級的核心函式庫，所以如果您用詩來管理您的 Python 專案，您需要在pyproject.toml 檔的建置系統部分中參照它，如下方所示

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
注意
當使用新增或初始化指令時，這個區塊將會自動加入。
注意
如果您的pyproject.toml檔仍然直接引用poetry作為建置後端，您需要將它更新為引用poetry-core。