首頁 詩集標誌

存放庫

存放庫 #

Poetry 支援使用 PyPI 和個人存放庫來找出套件，以及發布您的專案。

預設情況下，Poetry 會設定使用 PyPI 存放庫，來安裝套件和發布專案。

因此，當您新增依賴項到專案中時，Poetry 會假設這些依賴項可在 PyPI 中取得。

這應用了大部分情況，且對於大多數使用者來說已足夠。

私人存放庫範例 #

從私人套件來源進行安裝 #

預設情況下，Poetry 會從 PyPI 中找出並安裝套件。但是，您想要為您的專案安裝一個依賴項，以便進行 簡易 API 存放庫 ？讓我們來做做看。

首先，將 設定 套件來源 為專案的 補充 (或 明確) 套件來源。

poetry source add --priority=supplemental foo https://pypi.example.org/simple/

接著，假設存放庫需要驗證，請設定憑證。

poetry config http-basic.foo <username> <password>
警告
依據您的系統設定，憑證可能儲存在您的命令列歷程中。許多殼辦程式不會在命令前面加上空白字元時，儲存這些命令到歷程中。如需更多資訊，請參閱您殼辦程式的文件。
注意

如果您想互動式地提供密碼，您只要在命令中省略 <密碼>。然後，Poetry 將提示您手動輸入憑證。

poetry config http-basic.foo <username>

這樣做完後，您就可以從這個來源新增依賴項到您的專案中。

poetry add --source foo private-package

發布到私人存放庫 #

太棒了，現在剩下的就是發布您的套件了。假設您希望私下與團隊成員分享，您可以設定 Upload API 端點，以作為您的 可發布的儲存庫。

poetry config repositories.foo https://pypi.example.org/legacy/
注意

如果您需要為您的 套件來源 使用不同的憑證，建議您使用不同的名稱作為您的發布儲存庫。

poetry config repositories.foo-pub https://pypi.example.org/legacy/
poetry config http-basic.foo-pub <username> <password>
注意

當使用環境變數設定儲存庫時，請注意必須使用正確的字尾。

export POETRY_REPOSITORIES_FOO_URL=https://pypi.example.org/legacy/
export POETRY_HTTP_BASIC_FOO_USERNAME=<username>
export POETRY_HTTP_BASIC_FOO_PASSWORD=<password>

現在，剩下的就是使用 publish 來建置並發布您的專案。

poetry publish --build --repository foo-pub

套件來源 #

預設情況下，Poetry 會設定為使用 Python 生態系統的標準套件索引 PyPI。

注意
除了 PyPI 內建設定來源名為 pypi 之外，套件來源是專案本地的，必須在專案的 pyproject.toml 檔案內進行設定。這並不是在發布套件時使用的組態。

專案組態 #

這些套件來源可以使用 source 指令在您的專案中進行管理。

poetry source add foo https://foo.bar/simple/
注意
如果您的套件來源需要 憑證 或 憑證，請參閱以下相關章節。

這會在您的 pyproject.toml 檔案中產生下列組態程式碼片段。

[[tool.poetry.source]]
name = "foo"
url = "https://foo.bar/simple/"
priority = "primary"

如果 priority 未定義，來源會被視為比 PyPI、次要、補充和明確來源優先的來源。

套件來源會依據下列順序優先考量

  1. 預設來源（已不建議使用）、
  2. 主要來源,
  3. 隱含的 PyPI（除非由其他 主要來源、預設來源 停用，或明確設定）、
  4. 次要來源（已不建議使用）、
  5. 補充來源.

明確來源 只會考慮用於特別 指示其來源 的套件。

在每個優先順序類別中，套件來源的優先考量順序為出現在 pyproject.toml 中的順序。

注意

如果您想變更 PyPI 的優先順序，可以明確地設定，例如

poetry source add --priority=primary PyPI

如果您偏好完全停用 PyPI，只要新增一個 主要來源 或將 PyPI 設定為 明確來源 即可。

預設套件來源（已不建議使用）#

在 1.8.0 中已不建議使用

警告
組態預設套件來源已不建議，因為它與最上層的 主來源 相同。只要組態一個主套件來源，並將它放在套件來源清單的第一個位置即可。

預設情況下，如果你尚未組態任何主來源，Poetry 會將 PyPI 組態為專案的套件來源。你可以變更此行為，並只從已組態的套件來源中查看套件，方法是新增至少一個主來源（建議）或使用 priority = "default"（已不建議）的單一來源。

poetry source add --priority=default foo https://foo.bar/simple/

主套件來源 #

會在每個沒有 來源約束 的依賴項中搜尋所有主套件來源。如果你組態至少一個主來源，則隱含的 PyPI 來源會停用。

poetry source add --priority=primary foo https://foo.bar/simple/

沒有優先順位的來源也會視為主來源。

poetry source add foo https://foo.bar/simple/
警告

如果已組態至少一個主來源，則會自動停用隱含的 PyPI 來源。如果你想要除了主來源之外再使用 PyPI，請使用特定的優先順序明確地組態它，例如

poetry source add --priority=primary PyPI

這樣，就能以細緻的方式設定 PyPI 的優先順序。

pyproject.toml 中的等效規格是

[[tool.poetry.source]]
name = "pypi"
priority = "primary"

明確指定 PyPI 時，省略 url。由於 PyPI 在 Poetry 中是內部組態，因此無法透過指定的 URL 組態 PyPI 存放庫。請記住，你隨時可以使用 poetry check 來確保 pyproject.toml 檔案有效。

次要套件來源（已不建議） #

已在 1.5.0 中不建議使用

如果套件來源組態為次要，則表示在選擇也存在於你的預設和主套件來源中相容套件發行版時，它們會被給予較低的優先順序。如果你希望僅在優先順序較高的存放庫未傳回結果時才搜尋套件來源，請改考慮 補充來源。

你可以在套件來源組態中使用 priority = "secondary"，將套件來源組態為次要來源。

poetry source add --priority=secondary foo https://foo.bar/simple/

次要套件來源可以有一個以上。

警告
次要套件來源已不建議使用，建議改用補充套件來源。

補充套件來源 #

已在 1.5.0 中引入

組態為補充的套件來源只有在沒有其他（優先順序較高）來源產生相容套件發行版時才會被搜尋。如果來源的回應時間很長，而且需要從此來源擷取相對較少的套件發行版，這會特別方便。

你可以在套件來源組態中使用 priority = "supplemental"，將套件來源組態為補充來源。

poetry source add --priority=supplemental foo https://foo.bar/simple/

補充套件來源可以有一個以上。

警告
請考量到有人可能會在與你的補充來源相符的主要來源發佈新的套件。他們可能會出於巧合或故意地用你意料之外的東西來取代你的相依性。

明確的套件來源 #

已在 1.5.0 中引入

如果套件來源被設定為明確的，則唯有當套件配置明確地指出應該在這個套件來源上找到套件時，才會搜尋這些來源。

你可以使用套件來源配置中 priority = "explicit" 來設定套件來源為明確來源。

poetry source add --priority=explicit foo https://foo.bar/simple/

明確的套件來源可以超過一個。

注意

一個明確的套件來源在現實世界中會派上用場的範例，就是 PyTorch GPU 套件。

poetry source add --priority=explicit pytorch-gpu-src https://download.pytorch.org/whl/cu118
poetry add --source pytorch-gpu-src torch torchvision torchaudio

套件來源限制 #

在套件查找程序期間，將會搜尋所有套件來源（包括次要和平補來源）。無論是在一個或多個來源找到套件，都會對所有來源傳送這些網路要求。

為了將特定套件的搜尋範圍限制在某個套件儲存庫，你可以明確地指定來源。

poetry add --source internal-pypi httpx

這會在 pyproject.toml 中產生下列設定

[tool.poetry.dependencies]
...
httpx = { version = "^0.22", source = "internal-pypi" }

[[tool.poetry.source]]
name = "internal-pypi"
url = ...
priority = ...
注意
被設定為擷取特定套件的唯一來源的儲存庫本身可以有任意優先權。特別地，它不需要具有優先權 "explicit"。如果某個儲存庫被設定為套件的來源，它將是該套件被考量的唯一來源，而儲存庫的優先權將不會對解析產生影響。
注意

套件 source 金鑰不會被其相依性繼承。特別地，如果 package-A 被設定為在 source = internal-pypi 中找到，而 package-A 相依於 package-B（它也應該在 internal-pypi 中找到），那麼 package-B 需要在 pyproject.toml 中被設定為這樣。實現這個目的的最簡單方法是使用萬用字元限制來新增 package-B

poetry add --source internal-pypi package-B@*

這將確保 package-B 只會在 internal-pypi 套件來源中被搜尋。在 package-B 的版本限制通常會從 package-A（和其他用戶端套件）衍生而來。

如果你想要避免附加的主要相依性，你可以將 package-B 新增到一個專用的相依性群組

poetry add --group explicit --source internal-pypi package-B@*
注意
對於預期僅由某個特定來源提供的套件，強烈建議使用套件來源限制，以避免相依性混淆攻擊。

支援的套件來源 #

Python 套件索引 (PyPI) #

Poetry 透過其 JSON API 與 PyPI 互動。這會用來擷取所要求封裝的版本、資料、檔案等。

注意
如果封裝已發布的資料無效，Poetry 會下載可用的 bdist/sdist 以在本機檢查它，來識別相關資料。

如果要從 PyPI 明確選擇封裝，可以使用 add 指令的 --source 選項，如下所示。

poetry add --source pypi httpx@^0.22.0

這會在你的 pyproject.toml 檔案產生下列設定片段。

httpx = {version = "^0.22.0", source = "pypi"}
警告
如果專案中的任何來源已設定 priority = "default"，隱含的 pypi 來源會停用且不用於任何封裝。

簡易 API 儲存庫 #

Poetry 可以從公共或私人自訂儲存庫擷取和安裝封裝相依性，這些儲存庫實現簡易儲存庫 API，如 PEP 503 中所述。

警告
在使用在檔案 URL 中未提供檔案核取總和就發布大型輪子的來源時，Poetry 會至少下載各候選輪子一次，以產生核取總和。在從此來源新增封裝時，這可能會表現為較長的相依性解析時間。

這些封裝來源可以在你的專案中透過下列指令設定。

poetry source add testpypi https://test.pypi.org/simple/
注意
請注意尾端的 /simple/。在設定與 PEP 503 相符的封裝來源時，這很重要。

除了 PEP 503 之外，Poetry 也可以處理實作 PEP 658 的簡易 API 儲存庫（自 1.2.0 版引入）。這可協助減少來自這些來源的封裝的相依性解析時間，因為 Poetry 可以免去下載各候選配送以確定相關資料的必要性。

注意

如果沒有可用的資料，為何 Poetry 堅持為所有平台下載所有候選配送？

需要這樣做的原因在於 Poetry 的鎖定檔與平台無關。這表示，為了替專案解析相依性，Poetry 需要所有特定平台配送的資料。而當此資料並非隨時可得，下載配送並在本地檢查它就是唯一的方法。

單一頁面連結來源 #

自 1.2.0 版引入

有些專案選擇透過單一頁面連結來源釋出其二進位配送，此來源部分遵循 PEP 503 中封裝頁面的結構。

這些封裝來源可以在你的專案中透過下列指令設定。

poetry source add jax https://storage.googleapis.com/jax-releases/jax_releases.html
注意
前面描述的簡易 API 儲存庫在解析時間較慢的相關警告，在此也適用。

可發布的儲存庫 #

與套件來源不同，Poetry 將您發布套件的儲存庫視為針對使用者而非針對專案的特定設定。詩集目前僅支援舊版上傳 API，供您發布專案。

這些設定透過config指令，在repositories金鑰下進行設定。

poetry config repositories.testpypi https://test.pypi.org/legacy/
注意
舊版上傳 API的 URL 通常與儲存庫提供的簡易 API 中提供的 URL 不同。您會注意到，在Test PyPI的範例中，主機 (test.pypi.org) 和路徑 (/legacy) 都與其簡易 API (https://test.pypi.org/simple) 不同。

設定憑證 #

如果您想要儲存針對特定儲存庫的憑證，您可以輕鬆地執行此動作

poetry config http-basic.foo <username> <password>

如果您沒有指定密碼，系統會提示您輸入密碼。

注意

若要發布至 PyPI，您可以設定名為 pypi 的儲存庫憑證。

請注意，建議在將套件上傳至 PyPI 時使用API 權杖。一旦您建立新的權杖，您可以通知 Poetry 使用該權杖

poetry config pypi-token.pypi <my-token>

如果您已將 testpypi 設定為可發布儲存庫，可以使用以下方式設定此權杖

poetry config pypi-token.testpypi <your-token>

如果您仍然想要使用您的使用者名稱和密碼，您可以透過以下呼叫 config 來執行此動作。

poetry config http-basic.pypi <username> <password>

您也可以在使用 publish 指令時，透過 --username 和 --password 選項指定使用者名稱和密碼。

如果系統提供並支援金鑰圈，就會將密碼儲存至金鑰圈中，並從中擷取密碼。在上方的範例中，將使用 poetry-repository-pypi 這個名稱儲存憑證。如果無法存取金鑰圈或不受支援，就會回朔至將密碼連同使用者名稱寫入 auth.toml 檔案中。

透過使用keyring 函式庫啟用金鑰圈支援。若要瞭解支援的後端詳細資訊，請參閱函式庫文件。

如果您不想使用金鑰圈，您可以通知 Poetry 將其停用，並將憑證儲存在純文字設定檔中

poetry config keyring.enabled false
注意
Poetry 會回朔至 Pip 類型的金鑰圈使用方式，讓 Microsoft 的 artifacts-keyring 等後端有機會擷取有效的憑證。它必須適當安裝至 Poetry 的虛擬環境中，最理想的方式是由外掛程式進行安裝。

或者，您可以使用環境變數來提供憑證

export POETRY_PYPI_TOKEN_FOO=my-token
export POETRY_HTTP_BASIC_FOO_USERNAME=<username>
export POETRY_HTTP_BASIC_FOO_PASSWORD=<password>

其中 FOO 是儲存庫名稱，且以大寫表示 (例如 PYPI)。請參閱使用環境變數，以取得如何使用環境變數設定 Poetry 的詳細資訊。

如果您的密碼以破折號開頭（例如 CI 環境中的隨機產生衍生字元），它會被剖析成命令列選項而不是密碼。您可以透過新增雙破折號來防止此情況，以防止任何後續參數被剖析成選項。

poetry config -- http-basic.pypi myUsername -myPasswordStartingWithDash

憑證 #

自訂憑證授權機構和雙向 TLS 驗證 #

Poetry 支援使用自訂憑證授權機構來保護儲存庫，以及需要基於憑證的用戶端驗證的儲存庫。下列將配置「foo」儲存庫，使用自訂憑證授權機構來驗證儲存庫的憑證，並使用用戶端憑證（注意，這些設定變數不都需要設定）。

poetry config certificates.foo.cert /path/to/ca.pem
poetry config certificates.foo.client-cert /path/to/client.pem
注意

如果需要略過憑證驗證，certificates.<repository>.cert 的值可以設定為 false。這對於使用自簽署憑證的封裝來源是有用的。

poetry config certificates.foo.cert false
警告
不建議停用憑證驗證，因為這不符合最佳安全性做法。

快取 #

Poetry 使用封裝來源的許多快取，以便改善使用者體驗並避免重複的網路要求。

第一層快取是 Cache-Control 標頭快取，適用於幾乎所有的 HTTP 要求。

此外，每個透過 HTTP 備份的封裝來源，都會在取得或產生封裝後快取與封裝相關的資料。此外，已下載的檔案（封裝發行）也會快取。

除錯問題 #

如果您在封裝來源遇到問題，最簡單的除錯步驟之一，就是重新執行您的指令，加上 --no-cache 旗標。

poetry --no-cache add pycowsay

如果這解決您的問題，您可以考慮使用 cache 指令來清除您的快取。

或者，您也可以考慮啟用詳細記錄 -vvv，並加上 --no-cache，以在記錄中看到發出的網路要求。