Este é o Guia do desenvolvedor do AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Trabalhando com o AWS CDK em Python
Python é uma linguagem cliente totalmente compatível com o AWS Cloud Development Kit (AWS CDK) e é considerada estável. Trabalhar com o AWS CDK em Python usa ferramentas familiares, incluindo a implementação padrão do Python CPython (), ambientes virtuais com e o instalador do `virtualenv` pacote Python. `pip` Os módulos que compõem a AWS Construct Library são distribuídos via [pypi.org](https://pypi.org/search/?q=aws-cdk). A versão Python do AWS CDK até usa identificadores no estilo Python (por exemplo, nomes de métodos). `snake_case`
É possível usar qualquer editor ou IDE. [Muitos desenvolvedores de AWS CDK usam o [Visual Studio Code (ou seu equivalente de código](https://code.visualstudio.com/) aberto [VSCodium](https://vscodium.com/)), que tem um bom suporte para Python por meio de uma extensão oficial.](https://marketplace.visualstudio.com/items?itemName=ms-python.python) O editor IDLE incluído no Python será suficiente para começar. Os módulos Python para o AWS CDK têm dicas de tipo, que são úteis para uma ferramenta de linting ou um IDE que oferece suporte à validação de tipo.
## Conceitos básicos do Python
Para trabalhar com o AWS CDK, você deve ter uma AWS conta e credenciais e ter instalado o Node.js e o AWS CDK Toolkit. Consulte [Introdução ao AWS CDK.](getting-started.md)
Os aplicativos Python AWS CDK exigem o Python 3.9 ou posterior. Se você ainda não o tiver instalado, [baixe uma versão compatível](https://www.python.org/downloads/) para seu sistema operacional em [python.org](https://www.python.org/). Se você usa Linux, seu sistema pode ter vindo com uma versão compatível ou é possível instalá-la usando o gerenciador de pacotes da sua distribuição (`yum`, `apt`, etc.). Usuários de Mac podem se interessar pelo [Homebrew](https://brew.sh/), um gerenciador de pacotes no estilo Linux para macOS.
**nota**
Suspensão de uso de linguagem de terceiros: a versão da linguagem só é suportada até seu EOL (End Of Life) compartilhado pelo fornecedor ou pela comunidade e está sujeita a alterações mediante aviso prévio.
O instalador do pacote Python, `pip`, e o gerenciador de ambiente virtual, `virtualenv`, também são necessários . As instalações do Windows de versões compatíveis do Python incluem essas ferramentas. No Linux, `pip` e `virtualenv` podem ser fornecidos como pacotes separados em seu gerenciador de pacotes. Ou, então, você pode instalá-los com o seguinte comando:
```
python -m ensurepip --upgrade
python -m pip install --upgrade pip
python -m pip install --upgrade virtualenv
```
Se você encontrar um erro de permissão, execute os comandos acima com o sinalizador `--user` para que os módulos sejam instalados em seu diretório de usuário ou use `sudo` para obter as permissões para instalar os módulos em todo o sistema.
**nota**
É comum que as distribuições Linux usem o nome executável de `python3` para Python 3.x e que `python` se refira uma instalação do Python 2.x. Algumas distribuições têm um pacote opcional que você pode instalar que faz com que o comando `python` se refira ao Python 3. Caso contrário, é possível ajustar o comando usado para executar sua aplicação editando `cdk.json` no diretório principal do projeto.
**nota**
No Windows, talvez você queira invocar o Python (e o `pip`) usando o executável `py`, o [inicializador Python para Windows](https://docs.python.org/3/using/windows.html#launcher). Entre outras coisas, o lançador permite que você especifique facilmente qual versão instalada do Python deseja usar.
Se digitar `python` na linha de comando resultar em uma mensagem sobre a instalação do Python na Windows Store, mesmo depois de instalar uma versão do Python para Windows, abra o painel de configurações de aliases de execução de aplicações do Windows e desative as duas entradas do App Installer para Python.
## Criação de um projeto
Você cria um novo projeto AWS CDK invocando `cdk init` em um diretório vazio. Use a opção `--language` e especifique `python`:
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language python
```
`cdk init` usa o nome da pasta do projeto para nomear vários elementos do projeto, incluindo classes, subpastas e arquivos. Hifens no nome da pasta são convertidos em sublinhados. No entanto, o nome deve seguir a forma de um identificador do Python; por exemplo, não deve começar com um número nem conter espaços.
Para trabalhar com o novo projeto, ative o respectivo ambiente virtual. Isso permite que as dependências do projeto sejam instaladas localmente na pasta do projeto, em vez de globalmente.
```
$ source .venv/bin/activate
```
**nota**
Você pode reconhecer isso como o Mac/Linux comando para ativar um ambiente virtual. Os modelos do Python incluem um arquivo em lote, `source.bat`, que permite que o mesmo comando seja utilizado no Windows. O comando tradicional do Windows `.\venv\Scripts\activate` também funciona.
Se você inicializou seu projeto AWS CDK usando o CDK Toolkit v1.70.0 ou anterior, seu ambiente virtual estará no diretório em vez de. `.env` `.venv`
**Importante**
Ative o ambiente virtual do projeto sempre que começar a trabalhar nele. Caso contrário, você não terá acesso aos módulos instalados lá, e os módulos que você instalar entrarão no diretório global do módulo do Python (ou resultarão em um erro de permissão).
Depois de ativar seu ambiente virtual pela primeira vez, instale as dependências padrão da aplicação:
```
$ python -m pip install -r requirements.txt
```
## Gerenciando módulos da AWS Construct Libr
Use o instalador de pacotes Python,`pip`, para instalar e atualizar os módulos da AWS Construct Library para uso por seus aplicativos, bem como por outros pacotes necessários. `pip`também instala as dependências desses módulos automaticamente. Se seu sistema não reconhecer `pip` como um comando independente, invoque `pip` como um módulo Python, desta forma:
```
$ python -m pip
```
A maioria das construções de AWS CDK está pronta. `aws-cdk-lib` Os módulos experimentais estão em módulos separados chamados de `aws-cdk..alpha`. O nome do serviço inclui um prefixo *aws*. Se você não tiver certeza do nome de um módulo, [procure-o no PyPI](https://pypi.org/search/?q=aws-cdk). Por exemplo, o comando abaixo instala a AWS CodeStar biblioteca.
```
$ python -m pip install aws-cdk.aws-codestar-alpha
```
Alguns constructos de serviços estão em mais de um namespace. Por exemplo, além de `aws-cdk.aws-route53`, há três namespaces adicionais do Amazon Route 53, denominados `aws-route53-targets`, `aws-route53-patterns` e `aws-route53resolver`.
**nota**
A [edição Python de referência de API do CDK](https://docs.aws.amazon.com/cdk/api/v2/python/index.html) também mostra os nomes dos pacotes.
Os nomes usados para importar módulos da AWS Construct Library em seu código Python são semelhantes aos seguintes.
```
import aws_cdk.aws_s3 as s3
import aws_cdk.aws_lambda as lambda_
```
Recomendamos as seguintes práticas ao importar classes AWS CDK e módulos da AWS Construct Library em seus aplicativos. Seguir essas diretrizes ajudará a tornar seu código consistente com outros aplicativos AWS CDK, além de ser mais fácil de entender.
+ Geralmente, importe classes individuais de `aws_cdk` de nível superior.
```
from aws_cdk import App, Construct
```
+ Se você precisar de muitas classes de `aws_cdk`, poderá usar um alias de namespace de `cdk` em vez de importar classes individuais. Evite fazer as duas coisas.
```
import aws_cdk as cdk
```
+ Geralmente, importe AWS Construct Libraries usando aliases curtos de namespace.
```
import aws_cdk.aws_s3 as s3
```
Depois de instalar um módulo, atualize o arquivo `requirements.txt` do seu projeto, que lista as dependências do seu projeto. É melhor fazer isso manualmente em vez de usar `pip freeze`. `pip freeze` captura as versões atuais de todos os módulos instalados em seu ambiente virtual Python, o que pode ser útil durante o empacotamento de um projeto para ser executado em outro lugar.
Normalmente, porém, `requirements.txt` deve listar somente as dependências de nível superior (módulos dos quais sua aplicação depende diretamente) e não as dependências dessas bibliotecas. Essa estratégia simplifica a atualização de suas dependências.
É possível editar `requirements.txt` para permitir atualizações; basta substituir `==` que precede o número da versão por `~=` para permitir atualizações para uma versão compatível superior ou remover totalmente o requisito de versão para especificar a versão mais recente disponível do módulo.
Com o arquivo `requirements.txt` editado adequadamente para permitir atualizações, emita este comando para atualizar os módulos instalados do seu projeto a qualquer momento:
```
$ pip install --upgrade -r requirements.txt
```
## Gerenciamento de dependências em Python
No Python, você especifica dependências colocando-as em `requirements.txt` para aplicações ou `setup.py` para bibliotecas de constructos. As dependências são, então, gerenciadas com a ferramenta PIP. PIP é chamado de uma das seguintes maneiras:
```
pip
python -m pip
```
A invocação `python -m pip` funciona na maioria dos sistemas; `pip` requer que o executável do PIP esteja no caminho do sistema. Se `pip` não funcionar, tente substituir por `python -m pip`.
O comando `cdk init --language python` cria um ambiente virtual para seu novo projeto. Isso permite que cada projeto tenha suas próprias versões de dependências e também um arquivo `requirements.txt` básico. É necessário ativar esse ambiente virtual executando `source .venv/bin/activate` sempre que começar a trabalhar com o projeto. No Windows, execute `.\venv\Scripts\activate` em vez disso
### Aplicações do CDK
Veja a seguir um exemplo de arquivo `requirements.txt`. Como o PIP não tem um atributo de bloqueio de dependências, recomendamos que você use o operador == para especificar as versões exatas de todas as dependências, conforme mostrado aqui.
```
aws-cdk-lib==2.14.0
aws-cdk.aws-appsync-alpha==2.10.0a0
```
A instalação de um módulo com `pip install` não o adiciona automaticamente a `requirements.txt`. É necessário fazer isso sozinho. Se quiser atualizar para uma versão posterior de uma dependência, edite o número da versão em `requirements.txt`.
Para instalar ou atualizar as dependências do seu projeto depois de criar ou editar `requirements.txt`, execute o seguinte:
```
python -m pip install -r requirements.txt
```
**dica**
O comando `pip freeze` gera as versões de todas as dependências instaladas em um formato que pode ser gravado em um arquivo de texto. Isso pode ser usado como um arquivo de requisitos com `pip install -r`. Esse arquivo é conveniente para fixar todas as dependências (inclusive as transitivas) nas versões exatas com as quais você testou. Para evitar problemas ao atualizar pacotes posteriormente, use um arquivo separado para isso, como `freeze.txt` (não `requirements.txt`). Em seguida, regenere ao atualizar as dependências do seu projeto.
### Bibliotecas de constructos de terceiros
Nas bibliotecas, as dependências são especificadas em `setup.py`, para que as dependências transitivas sejam baixadas automaticamente quando o pacote é consumido por uma aplicação. Caso contrário, toda aplicação que quiser usar seu pacote precisará copiar suas dependências para `requirements.txt`. Um exemplo de `setup.py` é mostrado aqui.
```
from setuptools import setup
setup(
name='my-package',
version='0.0.1',
install_requires=[
'aws-cdk-lib==2.14.0',
],
...
)
```
Para trabalhar no pacote para desenvolvimento, crie ou ative um ambiente virtual e execute o comando a seguir.
```
python -m pip install -e .
```
Embora o PIP instale automaticamente dependências transitivas, só pode haver uma cópia instalada de qualquer pacote. A versão mais alta especificada na árvore de dependências é selecionada; as aplicações sempre têm a última palavra em qual versão dos pacotes serão instalados.
## AWS Expressões idiomáticas do CDK em Python
### Conflitos de linguagem
Em Python, `lambda` é uma palavra-chave de linguagem, então você não pode usá-la como um nome para o módulo da biblioteca de construção do AWS Lambda ou para as funções do Lambda. A convenção do Python para esses conflitos é usar um sublinhado à direita, como em `lambda_`, no nome da variável.
Por convenção, o segundo argumento para construções AWS CDK é denominado. `id` Ao escrever suas próprias pilhas e constructos, chamar um parâmetro `id` “sombreia” a função integrada do Python `id()`, que retorna o identificador exclusivo de um objeto. Essa função não é usada com muita frequência, mas se você precisar dela em seu constructo, renomeie o argumento, como `construct_id`.
### Argumentos e propriedades
Todas as classes da AWS Construct Library são instanciadas usando três argumentos: o *escopo* no qual a construção está sendo definida (seu pai na árvore de construção), um *id* e *props*, um pacote de key/value pares que a construção usa para configurar os recursos que cria. Outras classes e métodos também usam o padrão “pacote de atributos” para argumentos.
*escopo* e *id* devem sempre ser passados como argumentos posicionais, não como argumentos de palavra-chave, porque seus nomes mudam se o constructo aceitar uma propriedade chamada *escopo* ou *id*.
No Python, props são expressos como argumentos de palavras-chave. Se um argumento contiver estruturas de dados aninhadas, elas serão expressas usando uma classe que usa seus próprios argumentos de palavra-chave na instanciação. O mesmo padrão é aplicado a outras chamadas de método que usam um argumento estruturado.
Por exemplo, em um método `add_lifecycle_rule` de um bucket do Amazon S3, a propriedade `transitions` é uma lista de instâncias `Transition`.
```
bucket.add_lifecycle_rule(
transitions=[
Transition(
storage_class=StorageClass.GLACIER,
transition_after=Duration.days(10)
)
]
)
```
Ao estender uma classe ou substituir um método, talvez você queira aceitar argumentos adicionais para seus próprios propósitos que não sejam compreendidos pela classe principal. Nesse caso, é necessário aceitar os argumentos que não lhe interessam usando a expressão idiomática \$1\$1kwargs e usar argumentos somente com palavras-chave para aceitar os argumentos nos quais tem interesse. Ao chamar o construtor do pai ou o método substituído, passe somente os argumentos que ele espera (geralmente apenas \$1\$1kwargs). Passar argumentos inesperados para a classe ou o método resulta em um erro.
```
class MyConstruct(Construct):
def __init__(self, id, *, MyProperty=42, **kwargs):
super().__init__(self, id, **kwargs)
# ...
```
Uma versão futura do AWS CDK poderia coincidentemente adicionar uma nova propriedade com um nome que você usou para sua própria propriedade. Isso não causará problemas técnicos para os usuários do seu constructo ou método (como sua propriedade não é passada “para cima na cadeia”, a classe principal ou o método substituído simplesmente usará um valor padrão), mas isso pode causar confusão. É possível evitar esse problema em potencial nomeando suas propriedades de forma que elas claramente pertençam ao seu constructo. Se houver muitas propriedades novas, agrupe-as em uma classe com nome apropriado e passe-a como um único argumento de palavra-chave.
### Valores ausentes
O AWS CDK é usado `None` para representar valores ausentes ou indefinidos. Ao trabalhar com \$1\$1kwargs, use o método `get()` do dicionário para fornecer um valor padrão se uma propriedade não for fornecida. Evite usar `kwargs[…]`, pois isso aumenta `KeyError` para valores ausentes.
```
encrypted = kwargs.get("encrypted") # None if no property "encrypted" exists
encrypted = kwargs.get("encrypted", False) # specify default of False if property is missing
```
Alguns métodos de AWS CDK (como `tryGetContext()` obter um valor de contexto de tempo de execução) podem retornar`None`, o que você precisará verificar explicitamente.
### Uso de interfaces
O Python não tem um atributo de interface como algumas outras linguagens, embora tenha [classes básicas abstratas](https://docs.python.org/3/library/abc.html), que são semelhantes. (Se você não está familiarizado com interfaces, a Wikipedia tem [uma boa introdução](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages).) TypeScript, a linguagem na qual o AWS CDK é implementado, fornece interfaces, e as construções e outros objetos AWS CDK geralmente exigem um objeto que adira a uma interface específica, em vez de herdar de uma classe específica. Portanto, o AWS CDK fornece seu próprio recurso de interface como parte da camada [JSII](https://github.com/aws/jsii).
Para indicar que uma classe implementa uma interface específica, você pode usar o decorador `@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)
```
### Armadilhas de tipo
O Python usa tipagem dinâmica, em que todas as variáveis podem se referir a um valor de qualquer tipo. Os parâmetros e valores de retorno podem ser anotados com tipos, mas essas são “dicas” e não são impostas. Isso significa que, em Python, é fácil passar o tipo incorreto de valor para uma construção de AWS CDK. Em vez de receber um erro de tipo durante a compilação, como ocorre em uma linguagem com digitação estática, você pode receber um erro de tempo de execução quando a camada JSII (que se traduz entre o Python e o núcleo do AWS TypeScript CDK) não consegue lidar com o tipo inesperado.
Em nossa experiência, os erros de tipo que os programadores de Python cometem tendem a se enquadrar nessas categorias.
+ Passar um único valor em que um constructo espera um contêiner (lista ou dicionário do Python) ou vice-versa.
+ Passar um valor de um tipo associado a um constructo de camada 1 (`CfnXxxxxx`) para um constructo L2 ou L3, ou vice-versa.
## Evitando erros de tipo
Os módulos Python do AWS CDK incluem anotações de tipo, para que você possa usar ferramentas que os ajudem a detectar erros de tipo antes da implantação.
### Integração com IDE (recomendada)
O Visual Studio Code com Pylance fornece verificação de tipos em tempo real à medida que você escreve código:
1. Instale a extensão [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
1. Configure a verificação estrita de tipo em`.vscode/settings.json`:
```
{
"python.languageServer": "Pylance",
"python.analysis.typeCheckingMode": "strict"
}
```
1. Os erros de digitação agora aparecem imediatamente com rabiscos vermelhos e mensagens de erro detalhadas
[PyCharm](https://www.jetbrains.com/pycharm/)também fornece verificação de tipos integrada com recursos semelhantes.
### Verificação do tipo de linha de comando
Para CI/CD pipelines ou validação pré-confirmação, use um desses verificadores de tipo:
**MyPy (Baseado em Python):**
```
pip install mypy
mypy app.py
```
**Pyright (mais rápido, JavaScript baseado, com o mesmo motor do Pylance):**
```
npm install -g pyright
pyright app.py
```
### Fluxo de trabalho recomendado
1. Durante o desenvolvimento: use Pyright ou Pylance para obter feedback instantâneo
1. Antes de confirmar: Execute `mypy app.py` ou `pyright app.py`
1. Em CI/CD: faça da verificação de tipo uma etapa necessária antes da implantação