這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

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

# 在 Python 中使用 AWS CDK
<a name="work-with-cdk-python"></a>

Python 是完全支援的 AWS 雲端開發套件 (AWS CDK) 用戶端語言，並被視為穩定。在 Python 中使用 AWS CDK 會使用熟悉的工具，包括標準 Python 實作 (CPython)`virtualenv`、搭配 的虛擬環境，以及 Python 套件安裝程式 `pip`。包含 AWS Construct Library 的模組會透過 https：//[pypi.org](https://pypi.org/search/?q=aws-cdk) 進行分發。 AWS CDK 的 Python 版本甚至使用 Python 樣式識別符 （例如`snake_case`方法名稱）。

您可以使用任何編輯器或 IDE。許多 AWS CDK 開發人員使用 [Visual Studio Code](https://code.visualstudio.com/) （或其開放原始碼同等 [VSCodium](https://vscodium.com/))，可透過[官方擴充](https://marketplace.visualstudio.com/items?itemName=ms-python.python)功能對 Python 提供良好的支援。Python 隨附的 IDLE 編輯器足以開始使用。 AWS CDK 的 Python 模組確實有類型提示，對於支援類型驗證的 linting 工具或 IDE 很有用。

## Python 入門
<a name="python-prerequisites"></a>

若要使用 AWS CDK，您必須擁有 AWS 帳戶和登入資料，並已安裝 Node.js 和 AWS CDK Toolkit。請參閱 [AWS CDK 入門](getting-started.md)。

Python AWS CDK 應用程式需要 Python 3.9 或更新版本。如果您尚未安裝，請在 https：//[python.org](https://www.python.org/) 下載作業系統的[相容版本](https://www.python.org/downloads/)。如果您執行 Linux，您的系統可能隨附相容的版本，或者您可以使用 distro 的套件管理員 (`yum`、 `apt`等） 安裝它。Mac 使用者可能對 [Homebrew](https://brew.sh/) 感興趣，後者是適用於 macOS 的 Linux 型套件管理員。

**注意**  
第三方語言棄用：只有在廠商或社群共用其 EOL （生命週期結束） 之前，才支援語言版本，且可能會有所變更，恕不另行通知。

`virtualenv`也需要 Python 套件安裝程式 `pip`和虛擬環境管理員 。相容的 Python 版本的 Windows 安裝包含這些工具。在 Linux 上， `pip` 和 `virtualenv`可能會在您的套件管理員中以個別套件的形式提供。或者，您可以使用下列命令來安裝它們：

```
python -m ensurepip --upgrade
python -m pip install --upgrade pip
python -m pip install --upgrade virtualenv
```

如果您遇到許可錯誤，請使用 `--user`旗標執行上述命令，以便將模組安裝在您的使用者目錄中，或使用 `sudo`取得整個系統安裝模組的許可。

**注意**  
Linux 部屬通常會使用 Python 3.x `python3`的可執行檔名稱，並`python`參考 Python 2.x 安裝。有些 distros 有選用的套件，您可以安裝讓 `python`命令參考 Python 3。否則，您可以透過`cdk.json`在專案的主目錄中編輯 來調整用於執行應用程式的命令。

**注意**  
在 Windows 上，您可能想要使用適用於 Windows `py` 的 Python [啟動器可執行檔來叫用 Python](https://docs.python.org/3/using/windows.html#launcher) （和 `pip`)。此外，啟動器可讓您輕鬆指定要使用的 Python 安裝版本。  
如果在`python`命令列中輸入 會產生從 Windows 存放區安裝 Python 的訊息，即使安裝了 Windows 版本的 Python，也請開啟 Windows 的管理應用程式執行別名設定面板，並關閉 Python 的兩個應用程式安裝程式項目。

## 建立專案
<a name="python-newproject"></a>

您可以透過`cdk init`在空目錄中叫用 來建立新的 AWS CDK 專案。使用 `--language`選項並指定 `python`：

```
$ mkdir my-project
$ cd my-project
$ cdk init app --language python
```

 `cdk init` 使用專案資料夾的名稱來命名專案的各種元素，包括類別、子資料夾和檔案。資料夾名稱中的連字號會轉換為底線。不過，名稱應該遵循 Python 識別符的形式；例如，它不應以數字開頭或包含空格。

若要使用新專案，請啟用其虛擬環境。這可讓專案的相依性在本機安裝在專案資料夾中，而不是全域安裝。

```
$ source .venv/bin/activate
```

**注意**  
您可以將其識別為用來啟用虛擬環境的 Mac/Linux 命令。Python 範本包含一個批次檔案 `source.bat`，允許在 Windows 上使用相同的命令。傳統的 Windows 命令 也可`.\venv\Scripts\activate`運作。  
如果您使用 AWS CDK Toolkit v1.70.0 或更早版本初始化 CDK 專案，您的虛擬環境位於 `.env`目錄中，而不是 `.venv`。

**重要**  
開始處理專案時，請啟用專案的虛擬環境。否則，您將無法存取該處安裝的模組，而您安裝的模組將進入 Python 全域模組目錄 （或會導致許可錯誤）。

第一次啟用虛擬環境後，請安裝應用程式的標準相依性：

```
$ python -m pip install -r requirements.txt
```

## 管理 AWS 建構程式庫模組
<a name="python-managemodules"></a>

使用 Python 套件安裝程式 `pip`來安裝和更新 AWS Construct Library 模組以供您的應用程式使用，以及您需要的其他套件。 `pip`也會自動安裝這些模組的相依性。如果您的系統無法辨識`pip`為獨立命令，請呼叫 `pip` 做為 Python 模組，如下所示：

```
$ python -m pip <PIP-COMMAND>
```

大多數 AWS CDK 建構模組都在 中`aws-cdk-lib`。實驗模組位於名為 的個別模組中`aws-cdk.<SERVICE-NAME>.alpha`。服務名稱包含 *aws* 字首。如果您不確定模組的名稱，[請在 PyPI 中搜尋](https://pypi.org/search/?q=aws-cdk)。例如，以下命令會安裝 AWS CodeStar 程式庫。

```
$ python -m pip install aws-cdk.aws-codestar-alpha
```

有些服務的建構模組位於多個命名空間中。例如，除了 之外`aws-cdk.aws-route53`，還有三個額外的 Amazon Route 53 命名空間，名為 `aws-route53-targets`、 `aws-route53-patterns`和 `aws-route53resolver`。

**注意**  
[CDK API 參考的 Python 版本](https://docs.aws.amazon.com/cdk/api/v2/python/index.html)也會顯示套件名稱。

用於將 AWS Construct Library 模組匯入 Python 程式碼的名稱如下所示。

```
import aws_cdk.aws_s3 as s3
import aws_cdk.aws_lambda as lambda_
```

我們建議您在應用程式中匯入 AWS CDK 類別和 AWS 建構程式庫模組時採用下列實務。遵循這些準則有助於讓您的程式碼與其他 AWS CDK 應用程式保持一致，並且更容易理解。
+ 一般而言，從頂層 匯入個別類別`aws_cdk`。

  ```
  from aws_cdk import App, Construct
  ```
+ 如果您需要來自 的許多類別`aws_cdk`，您可以使用 命名空間別名，`cdk`而不是匯入個別類別。避免同時執行這兩個動作。

  ```
  import aws_cdk as cdk
  ```
+ 一般而言，使用短命名空間別名匯入 AWS 建構程式庫。

  ```
  import aws_cdk.aws_s3 as s3
  ```

安裝模組後，請更新專案的 `requirements.txt` 檔案，其中列出專案的相依性。最好手動執行此操作，而不是使用 `pip freeze`。 會`pip freeze`擷取安裝在 Python 虛擬環境中所有模組的目前版本，這在綁定要在其他位置執行的專案時非常有用。

不過，通常，您的 `requirements.txt` 應該只列出頂層相依性 （應用程式直接依賴的模組），而不是這些程式庫的相依性。此策略可讓您更輕鬆地更新相依性。

您可以編輯 `requirements.txt` 以允許升級；只需將`==`前面的版本編號取代`~=`為 以允許升級到更高的相容版本，或完全移除版本需求以指定模組的最新可用版本。

在適當`requirements.txt`編輯以允許升級的情況下，發出此命令以隨時升級專案已安裝的模組：

```
$ pip install --upgrade -r requirements.txt
```

## 在 Python 中管理相依性
<a name="work-with-cdk-python-dependencies"></a>

在 Python 中，您可以將應用程式或建構程式庫`requirements.txt`的相依性放入 `setup.py`，以指定相依性。然後，使用 PIP 工具管理相依性。以下列其中一種方式叫用 PIP：

```
pip <command options>
python -m pip <command options>
```

`python -m pip` 調用適用於大多數系統；`pip`要求 PIP 的可執行檔位於系統路徑上。如果 `pip`無法運作，請嘗試將其取代為 `python -m pip`。

`cdk init --language python` 命令會為您的新專案建立虛擬環境。這可讓每個專案都有自己的相依性版本，以及基本`requirements.txt`檔案。您必須`source .venv/bin/activate`在每次開始使用專案時執行 ，以啟用此虛擬環境。在 Windows 上執行 `.\venv\Scripts\activate` 

### CDK 應用程式
<a name="work-with-cdk-python-dependencies-apps"></a>

以下是範例 `requirements.txt` 檔案。由於 PIP 沒有相依性鎖定功能，我們建議您使用 == 運算子來指定所有相依性的確切版本，如下所示。

```
aws-cdk-lib==2.14.0
aws-cdk.aws-appsync-alpha==2.10.0a0
```

使用 安裝模組`pip install`不會自動將其新增至 `requirements.txt`。您必須自行執行。如果您想要升級至較新版本的相依性，請在 中編輯其版本編號`requirements.txt`。

若要在建立或編輯 之後安裝或更新專案的相依性`requirements.txt`，請執行下列動作：

```
python -m pip install -r requirements.txt
```

**提示**  
`pip freeze` 命令會以可寫入文字檔案的格式輸出所有已安裝相依性的版本。這可以用作 的要求檔案`pip install -r`。此檔案方便將所有相依性 （包括可轉移相依性） 鎖定到您測試的確切版本。若要避免稍後升級套件時發生問題，請為此使用不同的檔案，例如 `freeze.txt`（而非 `requirements.txt`)。然後，當您升級專案的相依性時，請將其重新產生。

### 第三方建構程式庫
<a name="work-with-cdk-python-dependencies-libraries"></a>

在程式庫中，相依性是在 中指定`setup.py`，因此應用程式使用套件時會自動下載傳輸相依性。否則，每個想要使用套件的應用程式都需要將您的相依性複製到其 `requirements.txt`。此處`setup.py`顯示範例。

```
from setuptools import setup

setup(
  name='my-package',
  version='0.0.1',
  install_requires=[
    'aws-cdk-lib==2.14.0',
  ],
  ...
)
```

若要使用 套件進行開發，請建立或啟用虛擬環境，然後執行下列命令。

```
python -m pip install -e .
```

雖然 PIP 會自動安裝暫時性相依性，但任何一個套件只能有一個已安裝的副本。選取相依性樹狀目錄中指定的最高版本；應用程式一律在安裝的套件版本中具有最後一個單字。

## AWS Python 中的 CDK 慣用詞
<a name="python-cdk-idioms"></a>

### 語言衝突
<a name="python-keywords"></a>

在 Python 中， `lambda` 是語言關鍵字，因此您無法將其用作 AWS Lambda 建構程式庫模組或 Lambda 函數的名稱。這類衝突的 Python 慣例是在變數名稱中使用結尾底線`lambda_`，如 所示。

根據慣例， AWS CDK 建構的第二個引數名為 `id`。撰寫您自己的堆疊和建構時，呼叫參數`id`「陰影」Python 內建函數 `id()`，這會傳回物件的唯一識別符。此函數不常使用，但如果您應該在建構中需要它，請重新命名引數，例如 `construct_id`。

### 引數和屬性
<a name="python-props"></a>

所有 AWS 建構程式庫類別都會使用三個引數來執行個體化：定義建構*的範圍* （其在建構樹狀結構中的父系）、*ID* 和 *props*，即建構函數用來設定其建立之資源的金鑰/值對套件。其他類別和方法也會針對引數使用「屬性組合」模式。

 *範圍*和 *ID* 應一律做為位置引數傳遞，而非關鍵字引數，因為如果建構接受名為*範圍*或 *ID* 的屬性，其名稱會變更。

在 Python 中，prop 會以關鍵字引數表示。如果引數包含巢狀資料結構，則會使用在執行個體化時採用自己關鍵字引數的類別來表示這些引數。相同的模式會套用至採用結構化引數的其他方法呼叫。

例如，在 Amazon S3 儲存貯體的 `add_lifecycle_rule`方法中， `transitions` 屬性是`Transition`執行個體的清單。

```
bucket.add_lifecycle_rule(
  transitions=[
    Transition(
      storage_class=StorageClass.GLACIER,
      transition_after=Duration.days(10)
    )
  ]
)
```

延伸類別或覆寫方法時，您可能想要接受父類別無法理解的其他引數，以達成自己的目的。在此情況下，您應該接受您不在意使用 \$1\$1kwargs idiom 的引數，並使用僅限關鍵字的引數來接受您感興趣的引數。呼叫父系建構函數或覆寫方法時，僅傳遞預期的引數 （通常僅 \$1\$1kwargs)。傳遞父類別或方法預期不會導致錯誤的引數。

```
class MyConstruct(Construct):
    def __init__(self, id, *, MyProperty=42, **kwargs):
        super().__init__(self, id, **kwargs)
        # ...
```

 AWS CDK 的未來版本可能會同時新增具有您用於自有屬性名稱的新屬性。這不會對建構或方法的使用者造成任何技術問題 （因為您的屬性未傳遞「上鏈」，父類別或覆寫方法只會使用預設值），但可能會導致混淆。您可以透過命名屬性來避免此潛在問題，以便它們明確屬於您的建構。如果有許多新屬性，請將它們綁定到適當命名的類別中，並將其做為單一關鍵字引數傳遞。

### 缺少值
<a name="python-missing-values"></a>

 AWS CDK 使用 `None` 來表示遺失或未定義的值。使用 \$1\$1kwargs 時，如果未提供屬性，請使用字典的 `get()`方法提供預設值。避免使用 `kwargs[…​]`，因為這會導致`KeyError`缺少值。

```
encrypted = kwargs.get("encrypted")         # None if no property "encrypted" exists
encrypted = kwargs.get("encrypted", False)  # specify default of False if property is missing
```

有些 AWS CDK 方法 （例如`tryGetContext()`取得執行時間內容值） 可能會傳回 `None`，您需要明確檢查。

### 使用界面
<a name="python-interfaces"></a>

Python 不像其他某些語言那樣具有界面功能，但它確實具有[類似抽象的基礎類別](https://docs.python.org/3/library/abc.html)。（如果您不熟悉界面，維基百科會有[很好的介紹](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages)。) TypeScript 是實作 AWS CDK 的語言，提供界面，建構和其他 AWS CDK 物件通常需要遵循特定界面的物件，而不是繼承自特定類別。因此， AWS CDK 提供自己的界面功能，做為 [JSII](https://github.com/aws/jsii) layer 的一部分。

若要指出類別實作特定界面，您可以使用`@jsii.implements`裝飾項目：

```
from aws_cdk import IAspect, IConstruct
import jsii

@jsii.implements(IAspect)
class MyAspect():
    def visit(self, node: IConstruct) -> None:
        print("Visited", node.node.path)
```

### 類型陷阱
<a name="python-type-pitfalls"></a>

Python 使用動態類型，其中所有變數都可以參考任何類型的值。參數和傳回值可以使用 類型加上註釋，但這些是「提示」且不會強制執行。這表示在 Python 中，將不正確類型的值輕鬆傳遞至 AWS CDK 建構。當 JSII 層 （在 Python 和 AWS CDK 的 TypeScript 核心之間轉換） 無法處理非預期的類型時，您可能會改為收到執行階段錯誤，而不是在建置期間收到類型錯誤，就像從靜態類型語言一樣。

在我們的經驗中，Python 程式設計人員的類型錯誤往往屬於這些類別。
+ 傳遞單一值，其中建構需要容器 (Python 清單或字典），反之亦然。
+ 將與第 1 層 (`CfnXxxxxx`) 建構相關聯的類型值傳遞至 L2 或 L3 建構，反之亦然。

## 防止類型錯誤
<a name="_preventing_type_errors"></a>

AWS CDK Python 模組包含類型註釋，因此您可以使用支援它們的工具在部署之前擷取類型錯誤。

### IDE 整合 （建議）
<a name="_ide_integration_recommended"></a>

Visual Studio Code with Pylance 在您編寫程式碼時提供即時類型檢查：

1. 安裝 [Pylance 延伸](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)模組 

1. 在 中設定嚴格類型檢查`.vscode/settings.json`：

   ```
   {
     "python.languageServer": "Pylance",
     "python.analysis.typeCheckingMode": "strict"
   }
   ```

1. 類型錯誤現在會立即出現，並顯示紅色魷魚和詳細的錯誤訊息

 [PyCharm](https://www.jetbrains.com/pycharm/) 也提供具有類似功能的內建類型檢查。

### 命令列類型檢查
<a name="_command_line_type_checking"></a>

針對 CI/CD 管道或預先遞交驗證，請使用下列其中一種類型檢查程式：

 **MyPy (Python 型）：**

```
pip install mypy
mypy app.py
```

 **Pyright （更快、JavaScript 型、與 Pylance 相同的引擎）：**

```
npm install -g pyright
pyright app.py
```

### 建議的工作流程
<a name="_recommended_workflow"></a>

1. 在開發期間：使用 Pyright 或 Pylance 進行即時意見回饋

1. 遞交之前：執行 `mypy app.py`或 `pyright app.py` 

1. 在 CI/CD 中：讓類型在部署之前檢查必要步驟