Este é o Guia do Desenvolvedor AWS CDK v2. A CDK v1 mais antiga 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á.

Trabalhar com o AWS CDK no Python

Python é uma linguagem de cliente totalmente compatível com AWS Cloud Development Kit (AWS CDK) e considerada estável. Trabalhar com o AWS CDK no Python envolve o uso de ferramentas familiares, incluindo a implementação padrão do Python (CPython), ambientes virtuais com virtualenv e o pip instalador do pacote Python. Os módulos que compõem a Biblioteca de Constructos da AWS são distribuídos via pypi.org. A versão Python do AWS CDK até usa identificadores no estilo Python (por exemplo, nomes de métodos snake_case).

Você pode usar qualquer editor ou IDE. Muitos desenvolvedores AWS CDK usam o Visual Studio Code (ou seu equivalente de código aberto VSCodium), que tem um bom suporte para Python por meio de uma extensão oficial. O editor IDLE incluído no Python será suficiente para começar. Os módulos Python para 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 AWS CDK, você deve ter uma conta e credenciais da AWS e ter instalado o Node.js e o AWS CDK Toolkit. Consulte Conceitos básicos da AWS CDK.

Aplicativos AWS CDK do Python exigem o Python 3.6 ou versão posterior. Se você ainda não o tiver instalado, baixe uma versão compatível para sua plataforma em python.org. Se você executa Linux, seu sistema pode ter vindo com uma versão compatível ou você pode instalá-la usando o gerenciador de pacotes da sua distribuição (yum, apt etc.). Usuários de Mac podem se interessar pelo Homebrew, um gerenciador de pacotes no estilo Linux para macOS.

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.

Criação de um projeto

Você cria um novo projeto do 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

Depois de ativar seu ambiente virtual pela primeira vez, instale as dependências padrão do aplicativo:

python -m pip install -r requirements.txt

Gerenciamento de módulos da Biblioteca de Constructos da AWS

Use o instalador de pacotes Python, pip, para instalar e atualizar os módulos da Biblioteca de Constructos da AWS 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 PIP-COMMAND

A maioria dos constructos AWS CDK está em aws-cdk-lib. Os módulos experimentais estão em módulos separados chamados de aws-cdk.SERVICE-NAME.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. Por exemplo, o comando abaixo instala a biblioteca AWS CodeStar.

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.

Os nomes usados para importar módulos da Biblioteca de Constructos da AWS 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 AWS CDK classes e módulos da Biblioteca de Constructos da AWS 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.

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 seu aplicativo depende diretamente) e não as dependências dessas bibliotecas. Essa estratégia simplifica a atualização de suas dependências.

Você pode 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 requirements.txt com a edição adequada 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 aplicativos 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 command options
python -m pip command options

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 porpython -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. Você deve 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. Você deve 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

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 um aplicativo. Caso contrário, todo aplicativo 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; os aplicativos sempre têm a última palavra em qual versão dos pacotes serão instalados.

Expressões idiomáticas AWS CDK no Python

Conflitos de linguagem

No 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 Constructos AWS Lambda ou funções 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 constructos 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 Biblioteca de Constructos da AWS são instanciadas usando três argumentos: o escopo no qual o constructo está sendo definido (seu pai na árvore de constructos), um id e props, um pacote de pares de chave/valor que o constructo 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, você deve aceitar os argumentos que não lhe interessam usando a expressão idiomática **kwargs 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 **kwargs). 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 de 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 pode causar confusão. Você pode 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

AWS CDK utiliza None para representar valores ausentes ou indefinidos. Ao trabalhar com **kwargs, 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 AWS CDK (como tryGetContext() para obter um valor de contexto de runtime) 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, que são semelhantes. (Se você não está familiarizado com interfaces, Wikipedia tem uma boa introdução.) O TypeScript, a linguagem na qual AWS CDK é implementado, fornece interfaces, e constructos 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, AWS CDK fornece seu próprio atributo de interface como parte da camada 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, no Python, é fácil passar o tipo incorreto de valor para um constructo AWS CDK. Em vez de receber um erro de tipo durante a construção, como você faria em uma linguagem com digitação estática, você pode receber um erro de runtime quando a camada JSII (que se traduz entre o Python e o núcleo do TypeScript de AWS 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.

Os módulos do Python AWS CDK incluem anotações de tipo, então você pode usar ferramentas que os suportam para ajudar com os tipos. Se você não estiver usando um IDE que ofereça suporte a eles, como o PyCharm, convém chamar o validador de tipo MyPy como uma etapa do processo de criação. Também existem verificadores de tipo de runtime que podem melhorar as mensagens de erro para erros relacionados ao tipo.