top of page
  • Foto do escritorRan Isenberg

Python Cookiecutter: Simplifique os projetos de modelo para uma experiência aprimorada do desenvolvedor


Cortador de biscoitos
Foto de Pavel Danilyuk: https://www.pexels.com/photo/close-up-shot-of-unbaked-cookies-6996345/


A biblioteca Python Cookiecutter revoluciona o desenvolvimento de projetos ao oferecer uma abordagem simplificada para criar projetos de modelo e melhorar a experiência do desenvolvedor.

O cookiecutter permite que os desenvolvedores criem rapidamente estruturas, configurações e práticas recomendadas predefinidas para seus projetos.

Ao abstrair as complexidades da configuração do ambiente, o cookiecutter permite que os desenvolvedores mergulhem direto na codificação, reduzindo significativamente o tempo e o esforço necessários para começar a trabalhar. Adotar o cookiecutter como uma ferramenta valiosa pode revolucionar a experiência de integração, aumentar a produtividade e capacitar os desenvolvedores a se concentrarem no que fazem de melhor: construir software inovador e de alta qualidade.


Neste post, você aprenderá como gerar templates Python com cookiecutter e construir novos projetos de template do zero. Revisaremos exemplos de uso e seguiremos passos precisos para ajudar você a desenvolver seu projeto de template Python cookiecutter.

 

Índice

 

Experiência do desenvolvedor e projetos de modelo são importantes


Eu diria que os projetos de modelo são essenciais para o sucesso da sua organização.

Na minha organização, a CyberArk, estávamos no processo de adoção de uma nova tecnologia: Serverless.

Eu estava em um grupo pioneiro trabalhando furiosamente para aprender as cordas dessa nova tecnologia. Eventualmente, nós construímos um novo serviço Serverless com inúmeras práticas recomendadas, como infraestrutura como código (AWS CDK), um pipeline CI/CD dedicado e observabilidade incorporada.

Foi um serviço excelente e funcionou bem.

No entanto, agora a equipe enfrentava novos desafios: construir o segundo serviço e outro desafio, ainda mais difícil: ajudar as equipes de notícias da CyberArk a criar os mesmos níveis de serviços sem servidor com as mesmas ferramentas. É aí que os projetos de modelo são úteis.

Transformamos o primeiro serviço, aquele serviço de última geração, em um projeto modelo - um serviço simples, mas genérico o suficiente para que qualquer equipe possa usá-lo como ponto de partida. Era um repositório totalmente funcional com todos os recursos que ajudam as equipes de desenvolvimento a se concentrarem no que mais importa - o domínio do negócio. Leia mais sobre isso aqui .

Em um caso, uma equipe desenvolvendo um serviço serverless com o template chegou aos estágios de parceiros de design (quando um cliente real usa o serviço) em apenas quatro meses. Para uma empresa como a CyberArk, isso era inédito e muito rápido.


Agora que entendemos o incentivo para projetos de modelo, vamos começar gerando um novo repositório a partir de um modelo com o cookiecutter e então processar para criar nosso modelo.

 

Instalando o Cookiecutter

Primeiro, certifique-se de instalar o Python 3.

Em seguida, execute o seguinte comando:

pip install cookiecutter

ou em um mac:

brew install cookiecutter

Se precisar de mais assistência, leia as diretrizes oficiais de instalação.

 

Cookicutter - A experiência do usuário

Antes de criar modelos, devemos entender que tipo de experiência do usuário nossos desenvolvedores terão. Devemos nos esforçar para torná-lo simples, rápido e remover o máximo de etapas manuais possível.


Criar um novo ambiente de trabalho para desenvolvedores é um dos desafios mais complexos que os desenvolvedores geralmente enfrentam. Podemos usar cookiecutter para construir nosso projeto e configurar o ambiente do desenvolvedor — mais sobre isso na seção 'hooks'.


Vamos criar um novo serviço Serverless a partir do meu projeto serverless cookiecutter, com base no meu projeto de livro de receitas do manipulador AWS Lambda.

O modelo de serviço sem servidor tem vários recursos:

  • Infraestrutura CDK com testes de infraestrutura e testes de segurança.

  • Pipelines de CI/CD baseados em ações do Github que são implantadas na AWS com linters Python, verificações de complexidade e formatadores de estilo.

  • Makefile para uma experiência simples de desenvolvedor.

  • O manipulador AWS Lambda incorpora as melhores práticas do Serverless e tem todos os recursos necessários para um manipulador adequado e pronto para produção.

  • Arquitetura de 3 camadas do manipulador AWS Lambda: camada do manipulador, camada lógica e camada de acesso a dados.

  • Possui sinalizadores e configuração baseados no AWS AppConfig.

  • Testes unitários, de infraestrutura, de segurança, de integração e E2E.

E o diagrama de arquitetura:

design de serviço
design de serviço

A configuração

Execute este comando:

cookiecutter gh:ran-isenberg/cookiecutter-serverless-python

Responda às seguintes perguntas para estruturar o projeto:

responda às perguntas
responda às perguntas

O Cookiecutter começará a estruturar o projeto e inicializará um ambiente de trabalho.

Após a conclusão, aparecerá uma mensagem: "Projeto inicializado com sucesso".

Pronto! Simples assim, você pode começar a desenvolver seu novo e brilhante serviço serverless e implantá-lo na AWS.

Se você gostou do projeto e da experiência, não seja um estranho e dê uma estrela :)

 

Crie seu próprio modelo

Agora que entendemos o que queremos alcançar, vamos construí-lo.


Estrutura do Repositório

Comece com um repositório vazio. Você precisará adicionar quatro arquivos no nível superior do projeto:

  1. Arquivo leia-me - explique o propósito do projeto e forneça instruções de configuração.

  2. cookiecutter.json - este arquivo fornece ao cookiecutter os parâmetros de configuração e scaffold para usar ao clonar um novo projeto. Mais sobre isso abaixo.

  3. A pasta raiz do projeto de modelo que você deseja fornecer.

  4. Pasta Hooks - usada para casos de uso avançados; veja abaixo.


Então você acaba com algo parecido com isto:

estrutura de pastas
estrutura de pastas

Vamos analisar a pasta principal, a pasta hooks e os arquivos cookiecutter.json.

 

cortador de biscoitos.json

Neste arquivo, você define os parâmetros de scaffolding do cookiecutter que impactam as perguntas apresentadas ao usuário durante a configuração inicial. Você pode escolher o que quiser, mas eu usaria o seguinte exemplo como ponto de partida:

Os valores fornecidos são padrão se o usuário pressionar Enter como resposta e não fornecer nenhuma outra entrada.

A parte "_copy_without_render" ajuda a adicionar arquivos e pastas que você não quer que o cookiecutter passe por cima e copie como estão.


As partes de autor, e-mail e descrições podem ser inseridas no arquivo leia-me do modelo e na seção de descrições do poetry.toml.

Veja um exemplo aqui e aqui .


Também há suporte para opções de múltipla escolha, conforme descrito aqui .


Pasta de modelo principal

Esta é a pasta de entrada para seu projeto de modelo. Você deve renomeá-la para um nome que o cookiecutter possa reconhecer e fazer scaffold. Todos os arquivos abaixo dela serão adicionados e terão scaffold.

No meu modelo, renomeei-o para '{{cookiecutter.repo_name}}'. Observe que o 'repo_name' é o parâmetro definido no arquivo cookiecutter.json.

Normalmente, na pasta principal, você adicionaria outra pasta para o nome do serviço, que eu defini como '{{cookiecutter.service_name}}.'

Então pode ficar assim:

estrutura interna do projeto
estrutura interna do projeto

Nem todas as pastas exigem suporte de scaffolding, e você pode decidir quais pastas permanecem constantes e quais são renomeadas.

Observe como a pasta interna tem seu arquivo .toml para poesia, .github para fluxos de trabalho de CI/CD, pasta CDK para implantação, pasta de testes e outras pastas necessárias. Você pode adicionar o que quiser.


Uma questão crucial que você precisa saber é que o scaffolding quebra o caminho de importação do Python. Como a pasta principal é dinâmica e determinada pelo usuário quando ele responde a perguntas cookiecutter, isso significa que as declarações de caminho de importação do Python exigem que as editemos também.

Aqui está um exemplo de como você pode superar isso:

Observe as linhas 10 a 12 e como importamos os arquivos com suporte a scaffolding.

O arquivo completo pode ser encontrado aqui .


Você pode usar o método para renomear quaisquer valores em qualquer arquivo.

 

Pasta de ganchos

A pasta hooks é opcional, mas sugiro que você a implemente também.

Os ganchos são códigos executados antes do processo de renomeação padrão ou depois que ele é concluído.

Você pode usá-lo para conduzir a validação de entrada nas perguntas e configurar um ambiente de desenvolvedor completo depois que o projeto estiver estruturado.


Pré-gancho

Você pode usar o pre-hook para validação de entrada nas strings do usuário. Se você se lembra, algumas dessas strings são usadas como nomes de serviço ou repositório. Elas são usadas no caminho de importação dos arquivos de repositório gerados, então elas devem estar em conformidade com a convenção de nomenclatura do Python.

Você pode usar o seguinte exemplo:


Gancho de postagem

É aqui que a mágica acontece. Nós falamos muito sobre a importância da experiência do desenvolvedor, e o post hook é onde você pode fazer a diferença.

Você pode escrever scripts e inicializar o ambiente do desenvolvedor para que ele possa começar a escrever novos códigos em vez de perder tempo com configurações manuais e tediosas do ambiente.

Aqui está um exemplo do meu script post-hook onde eu inicializo o git, instalo todas as dependências de poesia e instalo o pre-commit para que todas as verificações sejam executadas antes que um PR possa funcionar.



 

Testando e depurando localmente

Parece bem simples, certo?

No entanto, não vai funcionar para você na primeira vez. Nunca funciona. Então você precisa depurar, consertar e depurar novamente.

O cookiecutter oferece suporte à execução a partir de uma pasta local, não apenas de uma URL de repositório do GitHub.

Você pode desenvolver o novo repositório de modelos localmente, fazer alterações e então executar o cookiecutter no terminal e ver se funciona:

cookiecutter {path-to-project-on-local-disk}

Para mais dicas e truques, leia a documentação oficial: https://cookiecutter.readthedocs.io/en/stable/




Comments


bottom of page