Este é o Guia do Desenvolvedor AWS CDK v2. A versão CDK 1 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á.

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 virtualenv e o instalador do pacote Python. pip Os módulos que compõem a AWS Construct Library são distribuídos via pypi.org. A versão Python do AWS CDK evento usa identificadores no estilo Python (por exemplo, nomes de métodos). snake_case

Você pode usar qualquer editor ouIDE. Muitos AWS CDK desenvolvedores 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 IDLE editor 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 que oferece suporte à validação de IDE 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 Começando com o AWS CDK.

Os AWS CDK aplicativos Python exigem o Python 3.6 ou posterior. Se você ainda não o tiver instalado, baixe uma versão compatível para seu sistema operacional 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 e pip o gerenciador de ambiente virtual também são necessários. virtualenv 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. Como alternativa, você pode instalá-los com os seguintes comandos:

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 --user sinalizador 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 AWS CDK projeto invocando cdk init em um diretório vazio. Use a --language opção e especifiquepython:

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

cdk initusa o nome da pasta do projeto para nomear vários elementos do projeto, incluindo classes, subpastas e arquivos. Os hífens no nome da pasta são convertidos em sublinhados. No entanto, caso contrário, o nome deve seguir a forma de um identificador Python; por exemplo, ele não deve começar com um número ou 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

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. piptambém instala as dependências desses módulos automaticamente. Se seu sistema não reconhecer pip como um comando independente, invoque-o pip como um módulo Python, assim:

python -m pip PIP-COMMAND

A maioria das AWS CDK construções está pronta. aws-cdk-lib Os módulos experimentais estão em módulos separados chamados deaws-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 AWS CodeStar biblioteca.

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

Algumas construções de serviços estão em mais de um namespace. Por exemplo, além dissoaws-cdk.aws-route53, há três namespaces adicionais do Amazon Route 53, chamados aws-route53-targetsaws-route53-patterns, e. aws-route53resolver

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 AWS CDK classes e módulos da AWS Construct Library em seus aplicativos. Seguir essas diretrizes ajudará a tornar seu código consistente com outros AWS CDK aplicativos, além de ser mais fácil de entender.

Depois de instalar um módulo, atualize o requirements.txt arquivo do seu projeto, que lista as dependências do seu projeto. É melhor fazer isso manualmente em vez de usarpip freeze. pip freezecaptura as versões atuais de todos os módulos instalados em seu ambiente virtual Python, o que pode ser útil ao agrupar um projeto para ser executado em outro lugar.

Normalmente, porém, você 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 o número de versão == anterior por 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 a requirements.txt 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

Gerenciando dependências em Python

Em Python, você especifica dependências colocando-as em aplicativos ou setup.py em requirements.txt bibliotecas de construção. As dependências são então gerenciadas com a PIP ferramenta. PIPé invocado de uma das seguintes formas:

pip command options
python -m pip command options

A python -m pip invocação funciona na maioria dos sistemas; pip exige que PIP o executável esteja no caminho do sistema. Se pip não funcionar, tente substituí-lo porpython -m pip.

O cdk init --language python comando 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 requirements.txt arquivo 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

CDKaplicações

Veja a seguir um exemplo de arquivo requirements.txt. Como PIP não tem um recurso 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 aorequirements.txt. Você deve fazer isso sozinho. Se você quiser atualizar para uma versão posterior de uma dependência, edite o número da versão emrequirements.txt.

Para instalar ou atualizar as dependências do seu projeto depois de criar ou editarrequirements.txt, execute o seguinte:

python -m pip install -r requirements.txt

Bibliotecas de construção de terceiros

Nas bibliotecas, as dependências são especificadas emsetup.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 o delesrequirements.txt. Um exemplo 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, em seguida, execute o comando a seguir.

python -m pip install -e .

Embora instale PIP 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.

AWS CDK expressões idiomáticas em Python

Conflitos linguísticos

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 AWS Lambda construção ou funções Lambda. A convenção do Python para esses conflitos é usar um sublinhado à direita, como no nome da lambda_ variável.

Por convenção, o segundo argumento para AWS CDK construções é denominadoid. Ao escrever suas próprias pilhas e construções, chame um parâmetro de id “sombrear” a função integrada do Pythonid(), que retorna o identificador exclusivo de um objeto. Essa função não é usada com muita frequência, mas se você precisar dela em sua construção, renomeie o argumento, por exemploconstruct_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 pares de chave/valor 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.

scope e id devem sempre ser passados como argumentos posicionais, não como argumentos de palavra-chave, porque seus nomes mudam se a construção aceitar uma propriedade chamada scope ou id.

Em Python, os adereços 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, no add_lifecycle_rule método de um bucket do Amazon S3, a transitions propriedade é uma lista de Transition instâncias.

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 usar o **kwargs idioma e usar argumentos somente com palavras-chave para aceitar os argumentos nos quais está interessado. Ao chamar o construtor do pai ou o método substituído, passe somente os argumentos que ele espera (geralmente apenas). **kwargs Passar argumentos de que a classe ou o método pai não espera 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 de sua construção 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 à sua construção. 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

Os AWS CDK usos None para representar valores ausentes ou indefinidos. Ao trabalhar com**kwargs, use o get() método do dicionário para fornecer um valor padrão se uma propriedade não for fornecida. Evite usarkwargs[...], pois isso aumenta os valores KeyError 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 AWS CDK métodos (como tryGetContext() obter um valor de contexto de tempo de execução) podem retornarNone, o que você precisará verificar explicitamente.

Usando interfaces

O Python não tem um recurso de interface como algumas outras linguagens, embora tenha classes básicas abstratas, que são semelhantes. (Se você não está familiarizado com interfaces, a Wikipedia tem uma boa introdução.) TypeScript, a linguagem na qual o AWS CDK é implementado, fornece interfaces, e construções e outros AWS CDK objetos geralmente exigem um objeto que adira a uma interface específica, em vez de herdar de uma classe específica. Portanto, AWS CDK ele fornece seu próprio recurso de interface como parte da JSIIcamada.

Para indicar que uma classe implementa uma interface específica, você pode usar o @jsii.implements decorador:

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 AWS CDK construção. Em vez de receber um erro de tipo durante a construção, como você faria em uma linguagem de tipo estático, você pode receber um erro de tempo de execução quando a JSII camada (que se traduz entre o Python e o TypeScript núcleo) não consegue lidar com o AWS CDK 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 AWS CDK Python 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 suporte isso, como PyCharm, convém chamar o validador MyPyde tipo como uma etapa do processo de criação. Também existem verificadores de tipo de tempo de execução que podem melhorar as mensagens de erro para erros relacionados ao tipo.