Ceci est le guide du développeur du AWS CDK v2. L'ancien CDK v1 est entré en maintenance le 1er juin 2022 et a pris fin le 1er juin 2023.
Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Travailler avec le AWS CDK en Python
Python est un langage client entièrement pris en charge par le AWS Cloud Development Kit (AWS CDK) et est considéré comme stable. L'utilisation du AWS CDK en Python utilise des outils familiers, notamment l'implémentation standard de Python (CPython), les environnements virtuels avec `virtualenv` et le programme d'installation `pip` du package Python. Les modules composant la bibliothèque AWS Construct sont distribués via [pypi.org](https://pypi.org/search/?q=aws-cdk). La version Python du AWS CDK utilise même des identifiants de type Python (par exemple, `snake_case` les noms de méthodes).
Vous pouvez utiliser n'importe quel éditeur ou IDE. De nombreux développeurs de AWS CDK utilisent [Visual Studio Code](https://code.visualstudio.com/) (ou son équivalent open source [VSCodium](https://vscodium.com/)), qui supporte bien Python via une extension [officielle](https://marketplace.visualstudio.com/items?itemName=ms-python.python). L'éditeur IDLE inclus dans Python suffira pour démarrer. Les modules Python du AWS CDK contiennent des indications de type, utiles pour un outil de linting ou un IDE qui prend en charge la validation de type.
## Commencez avec Python
Pour utiliser le AWS CDK, vous devez disposer d'un AWS compte et d'informations d'identification et avoir installé Node.js et le kit d'outils AWS CDK. Consultez [Commencer à utiliser le AWS CDK.](getting-started.md)
Les applications Python AWS CDK nécessitent Python 3.9 ou version ultérieure. Si ce n'est pas déjà fait, [téléchargez une version compatible](https://www.python.org/downloads/) pour votre système d'exploitation [sur python.org](https://www.python.org/). Si vous utilisez Linux, votre système est peut-être fourni avec une version compatible, ou vous pouvez l'installer à l'aide du gestionnaire de paquets de votre distribution (`yum`,`apt`, etc.). Les utilisateurs de Mac peuvent être intéressés par [Homebrew](https://brew.sh/), un gestionnaire de paquets de style Linux pour macOS.
**Note**
Obsolète linguistique tierce : la version linguistique n'est prise en charge que jusqu'à sa fin de vie (EOL) partagée par le fournisseur ou la communauté et est sujette à modification avec préavis.
Le programme d'installation du package Python et le gestionnaire d'`virtualenv`environnement virtuel sont également requis. `pip` Les installations Windows des versions compatibles de Python incluent ces outils. Sous Linux, ils `pip` `virtualenv` peuvent être fournis sous forme de packages séparés dans votre gestionnaire de packages. Vous pouvez également les installer à l'aide des commandes suivantes :
```
python -m ensurepip --upgrade
python -m pip install --upgrade pip
python -m pip install --upgrade virtualenv
```
Si vous rencontrez une erreur d'autorisation, exécutez les commandes ci-dessus avec l'`--user`indicateur afin que les modules soient installés dans votre répertoire utilisateur, ou utilisez-les `sudo` pour obtenir les autorisations nécessaires pour installer les modules à l'échelle du système.
**Note**
Il est courant que les distributions Linux utilisent le nom de l'exécutable `python3` pour Python 3.x et fassent `python` référence à une installation de Python 2.x. Certaines distributions ont un package optionnel que vous pouvez installer et qui fait référence à Python 3 à la `python` commande. À défaut, vous pouvez ajuster la commande utilisée pour exécuter votre application en la modifiant `cdk.json` dans le répertoire principal du projet.
**Note**
Sous Windows, vous souhaiterez peut-être invoquer Python (et`pip`) à l'aide de l'`py`exécutable, le [lanceur Python pour Windows](https://docs.python.org/3/using/windows.html#launcher). Le lanceur vous permet notamment de spécifier facilement la version installée de Python que vous souhaitez utiliser.
Si vous tapez `python` sur la ligne de commande pour afficher un message concernant l'installation de Python depuis le Windows Store, même après avoir installé une version Windows de Python, ouvrez le panneau des paramètres de gestion des alias d'exécution des applications de Windows et désactivez les deux entrées App Installer pour Python.
## Création d’un projet
Vous créez un nouveau projet AWS CDK en l'appelant `cdk init` dans un répertoire vide. Utilisez l'`--language`option et spécifiez `python` :
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language python
```
`cdk init`utilise le nom du dossier du projet pour nommer les différents éléments du projet, notamment les classes, les sous-dossiers et les fichiers. Les traits d'union figurant dans le nom du dossier sont convertis en traits de soulignement. Toutefois, le nom doit sinon prendre la forme d'un identifiant Python ; par exemple, il ne doit pas commencer par un chiffre ni contenir d'espaces.
Pour travailler avec le nouveau projet, activez son environnement virtuel. Cela permet aux dépendances du projet d'être installées localement dans le dossier du projet, plutôt que globalement.
```
$ source .venv/bin/activate
```
**Note**
Il se peut que vous reconnaissiez qu'il s'agit de la Mac/Linux commande permettant d'activer un environnement virtuel. Les modèles Python incluent un fichier batch, `source.bat`, qui permet d’utiliser la même commande sous Windows. La commande Windows traditionnelle fonctionne également. `.\venv\Scripts\activate`
Si vous avez initialisé votre projet AWS CDK à l'aide de CDK Toolkit v1.70.0 ou version antérieure, votre environnement virtuel se trouve dans le répertoire au lieu de. `.env` `.venv`
**Important**
Activez l'environnement virtuel du projet dès que vous commencez à travailler dessus. Sinon, vous n'aurez pas accès aux modules qui y sont installés, et les modules que vous installez seront placés dans le répertoire global des modules Python (ou provoqueront une erreur d'autorisation).
Après avoir activé votre environnement virtuel pour la première fois, installez les dépendances standard de l'application :
```
$ python -m pip install -r requirements.txt
```
## Gestion des modules AWS de la bibliothèque Construct
Utilisez le programme d'installation de packages Python pour installer et mettre à jour les modules AWS Construct Library destinés à être utilisés par vos applications, ainsi que par les autres packages dont vous avez besoin. `pip` `pip`installe également automatiquement les dépendances de ces modules. Si votre système n'est pas reconnu `pip` comme une commande autonome, invoquez-la `pip` en tant que module Python, comme ceci :
```
$ python -m pip
```
La plupart des constructions AWS CDK sont incluses. `aws-cdk-lib` Les modules expérimentaux se trouvent dans des modules distincts nommés comme`aws-cdk..alpha`. Le nom du service inclut un préfixe *aws*. Si vous n'êtes pas sûr du nom d'un module, [recherchez-le sur PyPI](https://pypi.org/search/?q=aws-cdk). Par exemple, la commande ci-dessous installe la AWS CodeStar bibliothèque.
```
$ python -m pip install aws-cdk.aws-codestar-alpha
```
Les constructions de certains services se trouvent dans plusieurs espaces de noms. Par exemple`aws-cdk.aws-route53`, il existe en outre trois espaces de noms Amazon Route 53 supplémentaires, nommés `aws-route53-targets``aws-route53-patterns`, et`aws-route53resolver`.
**Note**
L'[édition Python du CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/python/index.html) indique également les noms des packages.
Les noms utilisés pour importer les modules AWS Construct Library dans votre code Python sont les suivants.
```
import aws_cdk.aws_s3 as s3
import aws_cdk.aws_lambda as lambda_
```
Nous recommandons les pratiques suivantes lors de l'importation de classes AWS CDK et de modules AWS Construct Library dans vos applications. Le respect de ces directives vous aidera à rendre votre code cohérent avec les autres applications AWS CDK et à le rendre plus facile à comprendre.
+ En général, importez des classes individuelles depuis le niveau supérieur. `aws_cdk`
```
from aws_cdk import App, Construct
```
+ Si vous avez besoin de nombreuses classes provenant de`aws_cdk`, vous pouvez utiliser un alias d'espace de noms de `cdk` au lieu d'importer des classes individuelles. Évitez de faire les deux.
```
import aws_cdk as cdk
```
+ En général, importez des bibliothèques de AWS construction en utilisant des alias d'espace de noms courts.
```
import aws_cdk.aws_s3 as s3
```
Après avoir installé un module, mettez à jour `requirements.txt` le fichier de votre projet, qui répertorie les dépendances de votre projet. Il est préférable de le faire manuellement plutôt que d'utiliser`pip freeze`. `pip freeze`capture les versions actuelles de tous les modules installés dans votre environnement virtuel Python, ce qui peut être utile lorsque vous regroupez un projet à exécuter ailleurs.
Cependant, vous ne `requirements.txt` devez généralement répertorier que les dépendances de haut niveau (modules dont dépend directement votre application) et non les dépendances de ces bibliothèques. Cette stratégie simplifie la mise à jour de vos dépendances.
Vous pouvez effectuer des modifications `requirements.txt` pour autoriser les mises à niveau ; il vous suffit de remplacer le numéro de version `==` précédent par un numéro de version `~=` pour autoriser les mises à niveau vers une version compatible supérieure, ou de supprimer complètement l'exigence de version pour spécifier la dernière version disponible du module.
Après avoir `requirements.txt` été modifiée de manière appropriée pour autoriser les mises à niveau, émettez cette commande pour mettre à niveau les modules installés de votre projet à tout moment :
```
$ pip install --upgrade -r requirements.txt
```
## Gestion des dépendances en Python
En Python, vous spécifiez les dépendances en les insérant `requirements.txt` pour les applications ou `setup.py` pour les bibliothèques de construction. Les dépendances sont ensuite gérées avec l'outil PIP. Le PIP est invoqué de l'une des manières suivantes :
```
pip
python -m pip
```
L'`python -m pip`invocation fonctionne sur la plupart des systèmes ; `pip` nécessite que l'exécutable du PIP se trouve sur le chemin du système. Si `pip` cela ne fonctionne pas, essayez de le remplacer par`python -m pip`.
La `cdk init --language python` commande crée un environnement virtuel pour votre nouveau projet. Cela permet à chaque projet de disposer de ses propres versions des dépendances, ainsi que d'un `requirements.txt` fichier de base. Vous devez activer cet environnement virtuel en l'exécutant `source .venv/bin/activate` chaque fois que vous commencez à travailler sur le projet. Sous Windows, exécutez `.\venv\Scripts\activate` plutôt
### Applications CDK
Voici un exemple de fichier `requirements.txt`. Comme PIP ne possède pas de fonction de verrouillage des dépendances, nous vous recommandons d'utiliser l'opérateur == pour spécifier les versions exactes de toutes les dépendances, comme indiqué ici.
```
aws-cdk-lib==2.14.0
aws-cdk.aws-appsync-alpha==2.10.0a0
```
L'installation d'un module avec `pip install` ne l'ajoute pas automatiquement à`requirements.txt`. Tu dois le faire toi-même. Si vous souhaitez effectuer une mise à niveau vers une version ultérieure d'une dépendance, modifiez son numéro de version dans`requirements.txt`.
Pour installer ou mettre à jour les dépendances de votre projet après la création ou la modification`requirements.txt`, exécutez ce qui suit :
```
python -m pip install -r requirements.txt
```
**Astuce**
La `pip freeze` commande affiche les versions de toutes les dépendances installées dans un format qui peut être écrit dans un fichier texte. Cela peut être utilisé comme fichier d'exigences avec`pip install -r`. Ce fichier est pratique pour attribuer toutes les dépendances (y compris les dépendances transitives) aux versions exactes avec lesquelles vous avez effectué les tests. Pour éviter tout problème lors de la mise à niveau ultérieure des packages, utilisez un fichier distinct, tel que `freeze.txt` (not`requirements.txt`). Puis, régénérez-le lorsque vous mettez à niveau les dépendances de votre projet.
### Bibliothèques de construction tierces
Dans les bibliothèques, les dépendances sont spécifiées dans`setup.py`, de sorte que les dépendances transitives sont automatiquement téléchargées lorsque le package est consommé par une application. Dans le cas contraire, chaque application qui souhaite utiliser votre package doit copier vos dépendances dans son propre package`requirements.txt`. Un exemple `setup.py` est présenté ici.
```
from setuptools import setup
setup(
name='my-package',
version='0.0.1',
install_requires=[
'aws-cdk-lib==2.14.0',
],
...
)
```
Pour travailler sur le package à des fins de développement, créez ou activez un environnement virtuel, puis exécutez la commande suivante.
```
python -m pip install -e .
```
Bien que PIP installe automatiquement les dépendances transitives, il ne peut y avoir qu'une seule copie installée d'un package. La version spécifiée le plus haut dans l'arborescence des dépendances est sélectionnée ; les applications ont toujours le dernier mot quant à la version des packages à installer.
## AWS Expressions idiomatiques CDK en Python
### Conflits linguistiques
En Python, `lambda` est un mot-clé de langage, vous ne pouvez donc pas l'utiliser comme nom pour le module de bibliothèque de AWS constructions Lambda ou les fonctions Lambda. La convention de Python pour de tels conflits consiste à utiliser un trait de soulignement final, comme dans`lambda_`, dans le nom de la variable.
Par convention, le deuxième argument des constructions AWS CDK est nommé. `id` Lorsque vous écrivez vos propres piles et constructions, appelez un paramètre `id` « ombres » la fonction intégrée de Python`id()`, qui renvoie l'identifiant unique d'un objet. Cette fonction n'est pas souvent utilisée, mais si vous en avez besoin dans votre construction, renommez l'argument, par exemple`construct_id`.
### Arguments et propriétés
Toutes les classes de la bibliothèque de AWS construction sont instanciées à l'aide de trois arguments : la *portée* dans laquelle la construction est définie (son parent dans l'arbre de construction), un *identifiant*, et *props*, un ensemble de key/value paires que la construction utilise pour configurer les ressources qu'elle crée. D'autres classes et méthodes utilisent également le modèle « bundle of attributes » pour les arguments.
*scope* et *id* doivent toujours être transmis en tant qu'arguments positionnels, et non en tant qu'arguments de mot clé, car leurs noms changent si la construction accepte une propriété nommée *scope* ou *id*.
En Python, les accessoires sont exprimés sous forme d'arguments de mots clés. Si un argument contient des structures de données imbriquées, celles-ci sont exprimées à l'aide d'une classe qui prend ses propres arguments de mots clés lors de l'instanciation. Le même modèle est appliqué aux autres appels de méthode qui prennent un argument structuré.
Par exemple, dans la `add_lifecycle_rule` méthode d'un compartiment Amazon S3, la `transitions` propriété est une liste d'`Transition`instances.
```
bucket.add_lifecycle_rule(
transitions=[
Transition(
storage_class=StorageClass.GLACIER,
transition_after=Duration.days(10)
)
]
)
```
Lorsque vous étendez une classe ou que vous remplacez une méthode, vous souhaiterez peut-être accepter des arguments supplémentaires pour vos propres besoins qui ne sont pas compris par la classe parent. Dans ce cas, vous devez accepter les arguments qui ne vous intéressent pas en utilisant l'idiome \$1\$1kwargs, et utiliser des arguments contenant uniquement des mots clés pour accepter les arguments qui vous intéressent. Lorsque vous appelez le constructeur du parent ou la méthode remplacée, ne transmettez que les arguments attendus (souvent juste \$1\$1kwargs). La transmission d'arguments auxquels la classe ou la méthode parent ne s'attend pas entraîne une erreur.
```
class MyConstruct(Construct):
def __init__(self, id, *, MyProperty=42, **kwargs):
super().__init__(self, id, **kwargs)
# ...
```
Une future version du AWS CDK pourrait par hasard ajouter une nouvelle propriété avec un nom que vous avez utilisé pour votre propre propriété. Cela ne posera aucun problème technique aux utilisateurs de votre construction ou de votre méthode (étant donné que votre propriété n'est pas transmise « en haut de la chaîne », la classe parent ou la méthode remplacée utilisera simplement une valeur par défaut) mais cela peut être source de confusion. Vous pouvez éviter ce problème potentiel en nommant vos propriétés de manière à ce qu'elles appartiennent clairement à votre construction. S'il existe de nombreuses nouvelles propriétés, regroupez-les dans une classe au nom approprié et transmettez-la en tant qu'argument de mot clé unique.
### Valeurs manquantes
Le AWS CDK est utilisé `None` pour représenter les valeurs manquantes ou non définies. Lorsque vous travaillez avec \$1\$1kwargs, utilisez la `get()` méthode du dictionnaire pour fournir une valeur par défaut si aucune propriété n'est fournie. Évitez d'en utiliser`kwargs[…]`, car cela augmente le `KeyError` nombre de valeurs manquantes.
```
encrypted = kwargs.get("encrypted") # None if no property "encrypted" exists
encrypted = kwargs.get("encrypted", False) # specify default of False if property is missing
```
Certaines méthodes AWS CDK (par exemple `tryGetContext()` pour obtenir une valeur de contexte d'exécution) peuvent être `None` renvoyées, ce que vous devrez vérifier explicitement.
### Utilisation d'interfaces
Python ne possède pas de fonctionnalité d'interface comme certains autres langages, bien qu'il possède des [classes de base abstraites](https://docs.python.org/3/library/abc.html), qui sont similaires. (Si vous n'êtes pas familier avec les interfaces, Wikipedia propose [une bonne introduction](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages).) TypeScript, le langage dans lequel le AWS CDK est implémenté, fournit des interfaces, et les constructions et autres objets AWS CDK nécessitent souvent un objet qui adhère à une interface particulière, plutôt que d'hériter d'une classe particulière. Le AWS CDK fournit donc sa propre fonctionnalité d'interface dans le cadre de la couche [JSII](https://github.com/aws/jsii).
Pour indiquer qu'une classe implémente une interface particulière, vous pouvez utiliser le `@jsii.implements` décorateur :
```
from aws_cdk import IAspect, IConstruct
import jsii
@jsii.implements(IAspect)
class MyAspect():
def visit(self, node: IConstruct) -> None:
print("Visited", node.node.path)
```
### Type de pièges
Python utilise le typage dynamique, où toutes les variables peuvent faire référence à une valeur de n'importe quel type. Les paramètres et les valeurs de retour peuvent être annotés avec des types, mais ce sont des « indices » qui ne sont pas appliqués. Cela signifie qu'en Python, il est facile de transmettre le type de valeur incorrect à une construction AWS CDK. Au lieu de recevoir une erreur de type lors de la construction, comme c'est le cas dans un langage à typage statique, vous pouvez obtenir une erreur d'exécution lorsque la couche JSII (qui traduit entre Python et le TypeScript noyau du AWS CDK) n'est pas en mesure de gérer le type inattendu.
D'après notre expérience, les erreurs de type commises par les programmeurs Python ont tendance à entrer dans ces catégories.
+ Transmettre une valeur unique lorsqu'une construction attend un conteneur (liste Python ou dictionnaire) ou vice versa.
+ Transmission d'une valeur d'un type associé à une construction de couche 1 (`CfnXxxxxx`) à une construction L2 ou L3, ou vice versa.
## Prévention des erreurs de saisie
Les modules Python d'AWS CDK incluent des annotations de type. Vous pouvez donc utiliser les outils qui les prennent en charge pour détecter les erreurs de type avant le déploiement.
### Intégration IDE (recommandée)
Visual Studio Code with Pylance fournit une vérification de type en temps réel lorsque vous écrivez du code :
1. Installation de l'extension [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
1. Configurez l'enregistrement de type strict `.vscode/settings.json` :
```
{
"python.languageServer": "Pylance",
"python.analysis.typeCheckingMode": "strict"
}
```
1. Les erreurs de type apparaissent désormais immédiatement avec des gribouillis rouges et des messages d'erreur détaillés
[PyCharm](https://www.jetbrains.com/pycharm/)fournit également une vérification de type intégrée avec des fonctionnalités similaires.
### Vérification du type par ligne de commande
Pour les CI/CD pipelines ou la validation préalable à la validation, utilisez l'un de ces vérificateurs de type :
**MyPy (basé sur Python) :**
```
pip install mypy
mypy app.py
```
**Pyright (plus rapide, JavaScript basé sur le même moteur que Pylance) :**
```
npm install -g pyright
pyright app.py
```
### Flux de travail recommandé
1. Pendant le développement : utilisez Pyright ou Pylance pour un feedback instantané
1. Avant la validation : Exécuter `mypy app.py` ou `pyright app.py`
1. Dans CI/CD : faire de la vérification de type une étape obligatoire avant le déploiement