本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 搭配 Python 使用 CodeArtifact
<a name="using-python"></a>

這些主題說明如何使用 `pip`、Python 套件管理員`twine`，以及 Python 套件發佈公用程式搭配 CodeArtifact。

**Topics**
+ [

# 搭配 CodeArtifact 設定和使用 pip
](python-configure-pip.md)
+ [

# 使用 CodeArtifact 設定和使用雙身
](python-configure-twine.md)
+ [

# Python 套件名稱標準化
](python-name-normalization.md)
+ [

# Python 相容性
](python-compatibility.md)
+ [

# 從上游和外部連線請求 Python 套件
](python-upstream-external-connections-request.md)

# 搭配 CodeArtifact 設定和使用 pip
<a name="python-configure-pip"></a>

[pip](https://pypi.org/project/pip/) 是 Python 套件的套件安裝程式。若要使用 pip 從 CodeArtifact 儲存庫安裝 Python 套件，您必須先使用 CodeArtifact 儲存庫資訊和登入資料來設定 pip 用戶端。

pip 只能用於安裝 Python 套件。若要發佈 Python 套件，您可以使用[雙工](https://pypi.org/project/twine/)。如需詳細資訊，請參閱[使用 CodeArtifact 設定和使用雙身](python-configure-twine.md)。

## 使用 `login`命令設定 pip
<a name="python-configure-pip-login"></a>

首先，設定您的 AWS 登入資料以與 搭配使用 AWS CLI，如中所述[CodeArtifact 入門](getting-started.md)。然後，使用 CodeArtifact `login`命令來擷取憑證並使用它們`pip`進行設定。

**注意**  
如果您在擁有的網域中存取儲存庫，則不需要包含 `--domain-owner`。如需詳細資訊，請參閱[跨帳戶網域](domain-overview.md#domain-overview-cross-account)。

若要設定 pip，請執行下列命令。

```
aws codeartifact login --tool pip --domain my_domain --domain-owner 111122223333 --repository my_repo
```

 `login` 使用您的 AWS 登入資料從 CodeArtifact 擷取授權字符。`login` 命令會編輯 `~/.config/pip/pip.conf`以`index-url`將 設定為 `--repository`選項指定的儲存庫，`pip`以將 設定為與 CodeArtifact 搭配使用。

呼叫 後的預設授權期間`login`為 12 小時，`login`必須呼叫 以定期重新整理字符。如需使用 `login`命令建立的授權字符的詳細資訊，請參閱 [使用 `login`命令建立的字符](tokens-authentication.md#auth-token-login)。

## 設定不含登入命令的 pip
<a name="python-configure-without-pip"></a>

 如果您無法使用 `login`命令來設定 `pip`，您可以使用 `pip config`。

1. 使用 AWS CLI 擷取新的授權字符。
**注意**  
如果您在擁有的網域中存取儲存庫，則不需要包含 `--domain-owner`。如需詳細資訊，請參閱[跨帳戶網域](domain-overview.md#domain-overview-cross-account)。

   ```
   CODEARTIFACT_AUTH_TOKEN=`aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --query authorizationToken --output text`
   ```

1. 使用 `pip config` 設定 CodeArtifact 登錄 URL 和登入資料。下列命令只會更新目前的環境組態檔案。若要更新整個系統的組態檔案，請將 取代`site`為 `global`。

   ```
   pip config set site.index-url https://aws:$CODEARTIFACT_AUTH_TOKEN@my_domain-111122223333.d.codeartifact.region.amazonaws.com/pypi/my_repo/simple/
   ```
**注意**  
若要使用雙堆疊端點，請使用 `codeartifact.region.on.aws`端點。

**重要**  
登錄 URL 必須以正斜線 (/) 結尾。否則，您無法連線到儲存庫。

**範例 pip 組態檔案**

以下是設定 CodeArtifact 登錄 URL 和登入資料後`pip.conf`的檔案範例。

```
[global]
index-url = https://aws:eyJ2ZX...@my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/pypi/my_repo/simple/
```

## 執行 pip
<a name="python-run-pip"></a>

若要執行`pip`命令，您必須`pip`使用 CodeArtifact 設定 。如需詳細資訊，請參閱下列文件。

1. 請依照 [使用 AWS CodeArtifact 設定](get-set-up-for-codeartifact.md)區段中的步驟來設定 AWS 您的帳戶、工具和許可。

1. `twine` 請依照中的步驟進行設定[使用 CodeArtifact 設定和使用雙身](python-configure-twine.md)。

假設您的儲存庫或其中一個上游儲存庫中有套件，您可以使用 安裝套件`pip install`。例如，使用下列命令來安裝 `requests`套件。

```
pip install requests
```

使用 `-i`選項暫時還原為從 [https://pypi.org](https://pypi.org) 安裝套件，而非 CodeArtifact 儲存庫。

```
pip install -i https://pypi.org/simple requests
```

# 使用 CodeArtifact 設定和使用雙身
<a name="python-configure-twine"></a>

[Twine](https://pypi.org/project/twine/) 是 Python 套件的套件發佈公用程式。若要使用孿生將 Python 套件發佈到您的 CodeArtifact 儲存庫，您必須先使用 CodeArtifact 儲存庫資訊和登入資料來設定孿生。

Twine 只能用於發佈 Python 套件。若要安裝 Python 套件，您可以使用 [pip](https://pypi.org/project/pip/)。如需詳細資訊，請參閱[搭配 CodeArtifact 設定和使用 pip](python-configure-pip.md)。

## 使用 `login`命令設定雙身
<a name="python-configure-twine-login"></a>

首先，設定您的 AWS 登入資料以與 搭配使用 AWS CLI，如中所述[CodeArtifact 入門](getting-started.md)。然後，使用 CodeArtifact `login`命令來擷取憑證，並與他們設定雙身。

**注意**  
如果您在擁有的網域中存取儲存庫，則不需要包含 `--domain-owner`。如需詳細資訊，請參閱[跨帳戶網域](domain-overview.md#domain-overview-cross-account)。

若要設定雙工，請執行下列命令。

```
aws codeartifact login --tool twine --domain my_domain --domain-owner 111122223333 --repository my_repo
```

 `login` 使用您的 AWS 登入資料從 CodeArtifact 擷取授權字符。`login` 命令會編輯 `~/.pypirc`以使用 登入資料新增 `--repository`選項指定的儲存庫，藉此設定雙工以搭配 CodeArtifact 使用。

呼叫 後的預設授權期間`login`為 12 小時，`login`必須呼叫 以定期重新整理字符。如需使用 `login`命令建立的授權字符的詳細資訊，請參閱 [使用 `login`命令建立的字符](tokens-authentication.md#auth-token-login)。

## 不使用 `login`命令設定雙身
<a name="python-configure-twine-without-login"></a>

 如果您無法使用 `login`命令來設定雙身，您可以使用 `~/.pypirc` 檔案或環境變數。若要使用 `~/.pypirc` 檔案，請在其中新增下列項目。密碼必須是 `get-authorization-token` API 取得的身分驗證字符。

```
[distutils]
index-servers =
 codeartifact
[codeartifact]
repository = https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/pypi/my_repo/
password = auth-token
username = aws
```

**注意**  
若要使用雙堆疊端點，請使用 `codeartifact.region.on.aws`端點。

若要使用環境變數，請執行下列動作。

**注意**  
如果您在擁有的網域中存取儲存庫，則不需要包含 `--domain-owner`。如需詳細資訊，請參閱[跨帳戶網域](domain-overview.md#domain-overview-cross-account)。

```
export TWINE_USERNAME=aws
export TWINE_PASSWORD=`aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --query authorizationToken --output text`
export TWINE_REPOSITORY_URL=`aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format pypi --query repositoryEndpoint --output text`
```

## 執行雙身
<a name="python-run-twine"></a>

使用分身發佈 Python 套件資產之前，您必須先設定 CodeArtifact 許可和資源。

1. 請依照 [使用 AWS CodeArtifact 設定](get-set-up-for-codeartifact.md)區段中的步驟來設定 AWS 您的帳戶、工具和許可。

1. 遵循 [使用 `login`命令設定雙身](#python-configure-twine-login)或 中的步驟來設定分身[不使用 `login`命令設定雙身](#python-configure-twine-without-login)。

設定雙工之後，您可以執行`twine`命令。使用下列命令來發佈 Python 套件資產。

```
twine upload --repository codeartifact mypackage-1.0.tgz
```

如需有關如何建置和封裝 Python 應用程式的資訊，請參閱 Python Packaging Authority [網站上的產生分佈封存](https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives)。

# Python 套件名稱標準化
<a name="python-name-normalization"></a>

CodeArtifact 會在儲存套件名稱之前將套件名稱標準化，這表示 CodeArtifact 中的套件名稱可能與發佈套件時提供的名稱不同。

對於 Python 套件，執行標準化時，套件名稱會小寫`-`，且字元 `.`、 和 的所有執行個體`_`都會取代為單一`-`字元。因此，套件名稱 `pigeon_cli` 和 `pigeon.cli`會標準化並儲存為 `pigeon-cli`。非標準化名稱可由 pip 和 Twine 使用，但標準化名稱必須在 CodeArtifact CLI 或 API 請求 （例如 `list-package-versions`) 和 ARNs 中使用。如需 Python 套件名稱標準化的詳細資訊，請參閱 Python 文件中的 [PEP 503](https://www.python.org/dev/peps/pep-0503/#normalized-names)。

# Python 相容性
<a name="python-compatibility"></a>

CodeArtifact 不支援 PyPI `XML-RPC`或 `JSON` APIs。

CodeArtifact 支援 PyPI 的 `Legacy` API，但 `simple` API 除外。 APIs 雖然 CodeArtifact 不支援 `/simple/` API 端點，但它確實支援`/simple/<project>/`端點。

如需詳細資訊，請參閱 Python Packaging Authority 的 GitHub 儲存庫上的以下內容。
+ [XML-RPC API](https://github.com/pypi/warehouse/blob/main/docs/dev/api-reference/xml-rpc.rst)
+ [JSON API](https://github.com/pypi/warehouse/blob/main/docs/dev/api-reference/json.rst)
+ [舊版 API](https://github.com/pypi/warehouse/blob/main/docs/dev/api-reference/legacy.rst)

## pip 命令支援
<a name="pip-command-support"></a>

除了不支援的特定命令之外，以下各節摘要 CodeArtifact 儲存庫支援的 pip 命令。

**Topics**
+ [

### 支援與儲存庫互動的命令
](#supported-pip-commands-that-interact-with-a-repository)
+ [

### 支援的用戶端命令
](#supported-pip-client-side-commands)

### 支援與儲存庫互動的命令
<a name="supported-pip-commands-that-interact-with-a-repository"></a>

本節列出 `pip` 命令，其中`pip`用戶端向所設定的登錄檔發出一或多個請求。已驗證這些命令在針對 CodeArtifact 儲存庫調用時可正常運作。


****  

| 命令 | Description | 
| --- | --- | 
|   [安裝](https://pip.pypa.io/en/stable/reference/pip_install/)   |  安裝套件。  | 
|   [下載](https://pip.pypa.io/en/stable/reference/pip_download/)   |  下載套件。  | 

CodeArtifact 不會實作 `pip search`。如果您已`pip`設定 CodeArtifact 儲存庫，執行 `pip search`會搜尋並顯示來自 [PyPI](https://pypi.org/) 的套件。

### 支援的用戶端命令
<a name="supported-pip-client-side-commands"></a>

這些命令不需要與儲存庫進行任何直接互動，因此 CodeArtifact 不需要執行任何動作來支援儲存庫。


****  

| 命令 | Description | 
| --- | --- | 
|   [解除安裝](https://pip.pypa.io/en/stable/reference/pip_uninstall/)   |  解除安裝套件。  | 
|   [凍結](https://pip.pypa.io/en/stable/reference/pip_freeze/)   |  以要求格式輸出已安裝的套件。  | 
|   [清單](https://pip.pypa.io/en/stable/reference/pip_list/)   |  列出已安裝的套件。  | 
|   [sh](https://pip.pypa.io/en/stable/reference/pip_show/)ow   |  顯示已安裝套件的相關資訊。  | 
|   [檢查](https://pip.pypa.io/en/stable/reference/pip_check/)   |  確認已安裝的套件具有相容的相依性。  | 
|   [組態](https://pip.pypa.io/en/stable/reference/pip_config/)   |  管理本機和全域組態。  | 
|   [滾輪](https://pip.pypa.io/en/stable/reference/pip_wheel/)   |  根據您的需求建置車輪。  | 
|   [雜湊](https://pip.pypa.io/en/stable/reference/pip_hash/)   |  套件封存的運算雜湊。  | 
|   [完成](https://pip.pypa.io/en/stable/user_guide/#command-completion)   |  協助完成命令。  | 
|   [debug](https://pip.pypa.io/en/stable/reference/pip_debug/)   |  顯示適用於偵錯的資訊。  | 
|  說明  |  顯示 命令的說明。  | 

# 從上游和外部連線請求 Python 套件
<a name="python-upstream-external-connections-request"></a>

從 [pypi.org](https://pypi.org/) 匯入 Python 套件版本時，CodeArtifact 會匯入該套件版本中的所有資產。雖然大多數 Python 套件都包含少量資產，但有些套件包含超過 100 個資產，通常支援多個硬體架構和 Python 解譯器。

對於現有的套件版本，新資產通常會發佈到 pypi.org。例如，有些專案會在發行新版本的 Python 時發佈新資產。從 CodeArtifact 安裝 Python 套件並搭配 時`pip install`，會更新 CodeArtifact 儲存庫中保留的套件版本，以反映來自 pypi.org：// 的最新資產集。

同樣地，如果上游 CodeArtifact 儲存庫中的套件版本沒有新的資產，則在`pip install`執行時，這些資產會保留在目前的 CodeArtifact 儲存庫中。

## Yanked 套件版本
<a name="python-yanked-versions"></a>

部分 pypi.org 中的套件版本標示為 *yanked*，它會與套件安裝程式 （例如 pip) 通訊，除非版本是唯一符合版本指標 （使用 `==`或 `===`) 的版本。如需詳細資訊，請參閱 [PEP\$1592](https://peps.python.org/pep-0592/)。

如果 CodeArtifact 中的套件版本最初是從外部連線至 [pypi.org](https://pypi.org/) 擷取，當您從 CodeArtifact 儲存庫安裝套件版本時，CodeArtifact 會確保從 pypi.org 擷取套件版本的更新偏擺中繼資料。

### 如何知道套件版本是否已取消
<a name="test-yanked-version"></a>

若要檢查 CodeArtifact 中的套件版本是否遭到取消，您可以嘗試使用 安裝套件版本`pip install packageName===packageVersion`。如果套件版本已取消，您會收到類似以下的警告訊息：

```
WARNING: The candidate selected for download or install is a yanked version
```

若要檢查套件版本是否在 [pypi.org](https://pypi.org/)：//www.microsoft.com/microsoft.com/microsoft.microsoft.com/microsoft.com/microsoft.microsoft.com/microsoft.microsoft.microsoft.com/microsoft.microsoft.microsoft.microsoft.microsoft.com/soft.microsoft.microsoft.micro；若要查看套件版本的 pypi.org`https://pypi.org/project/packageName/packageVersion/`.com/

### 在私有套件上設定偏擺狀態
<a name="yanked-private-packages"></a>

CodeArtifact 不支援為直接發佈至 CodeArtifact 儲存庫的套件設定偏擺中繼資料。

## 為什麼 CodeArtifact 未擷取套件版本的最新偏擺中繼資料或資產？
<a name="no-yanked-metadata"></a>

通常，CodeArtifact 可確保從 CodeArtifact 儲存庫擷取 Python 套件版本時，偏擺的中繼資料會up-to-date，且具有 [pypi.org](https://pypi.org/)：//www. 上的最新值。此外，套件版本中的資產清單也會以 https：// pypi.org 和任何上游 CodeArtifact 儲存庫上的最新設定來保持最新狀態。無論您是第一次安裝套件版本，而且 CodeArtifact 從 pypi.org 將其匯入 CodeArtifact 儲存庫，或是先前已安裝套件，都是如此。不過，在某些情況下，套件管理員用戶端，例如 pip，不會從 pypi.org 或上游儲存庫提取最新的偏擺中繼資料。反之，CodeArtifact 會傳回已存放在儲存庫中的資料。本節說明發生這種情況的三種方式：

**上游組態：**如果使用 [disassociate-external-connection](external-connection.md#removing-an-external-connection) 從儲存庫或其上游移除與 pypi.org 的外部連線，則不會再從 pypi.org 重新整理偏擺的中繼資料。同樣地，如果您移除上游儲存庫，來自已移除儲存庫和已移除儲存庫上游的資產將無法再供目前的儲存庫使用。如果您使用 CodeArtifact [套件原始伺服器控制](package-origin-controls.md)來防止提取特定套件的新版本，則同樣情況是如此 — 設定`upstream=BLOCK`會封鎖重新整理偏擺的中繼資料。

**套件版本狀態：**如果您將套件版本的狀態設定為 `Published`或 以外的任何項目`Unlisted`，將不會重新整理套件版本的偏擺中繼資料和資產。同樣地，如果您要擷取特定套件版本 （例如 `torch 2.0.1`)，且上游儲存庫中存在狀態不是 `Published`或 的相同套件版本`Unlisted`，這也會封鎖上游儲存庫到目前儲存庫的偏擺中繼資料和資產傳播。這是因為其他套件版本狀態表示版本不再在任何儲存庫中使用。

**直接發佈：**如果您將特定套件版本直接發佈至 CodeArtifact 儲存庫，這將防止套件版本的受阻中繼資料和資產重新整理從其上游儲存庫和 pypi.org 進行。例如，假設您從套件版本 下載資產`torch 2.0.1`，例如 `torch-2.0.1-cp311-none-macosx_11_0_arm64.whl`，使用 Web 瀏覽器，然後使用 Twine 做為 將其發佈到您的 CodeArtifact 儲存庫`torch 2.0.1`。CodeArtifact 會透過直接發佈至您的儲存庫來追蹤套件版本是否進入網域，而不是從與 pypi.org 的外部連線或上游儲存庫。在此情況下，CodeArtifact 不會讓偏擺中繼資料與上游儲存庫或 pypi.org 保持同步。如果您發佈`torch 2.0.1`到上游儲存庫，也是如此 — 套件版本的存在會阻止將偏擺中繼資料和資產傳播到更深入上游圖形的儲存庫。