Pular para o conteúdo
@aws/nx-plugin
Blog

Projetos Python

O gerador de projetos Python pode ser usado para criar uma biblioteca ou aplicação moderna em Python configurada com melhores práticas, gerenciada com UV, um único arquivo de lock e ambiente virtual em um UV workspace, pytest para execução de testes e Ruff para análise estática.

Utilização

Gerar um Projeto Python

Você pode gerar um novo projeto Python de duas formas:

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - py#project
  5. Preencha os parâmetros obrigatórios
    • Clique em Generate

    Opções

    Parâmetro Tipo Padrão Descrição
    name Obrigatório string - Project name.
    directory string packages Parent directory where the project is placed.
    projectType Obrigatório string application Project type
    moduleName string - Python module name

    Saída do Gerador

    O gerador criará a seguinte estrutura de projeto no diretório <directory>/<name>:

    • Directory<module-name>
      • __init__.py Inicialização do módulo
      • hello.py Exemplo de arquivo fonte Python
    • Directorytests
      • __init__.py Inicialização do módulo
      • conftest.py Configuração de testes
      • test_hello.py Exemplo de testes
    • project.json Configuração do projeto e targets de build
    • pyproject.toml Arquivo de configuração de empacotamento usado pelo UV
    • .python-version Contém a versão do Python do projeto

    Você também pode notar os seguintes arquivos criados/atualizados na raiz do workspace:

    • pyproject.toml Configuração de empacotamento em nível de workspace para UV
    • .python-version Contém a versão do Python do workspace
    • uv.lock Arquivo de lock para dependências Python

    Escrevendo Código Fonte Python

    Adicione seu código fonte Python no diretório <module-name>.

    Importando Código da Sua Biblioteca em Outros Projetos

    Como os UV workspaces estão configurados para você, é possível referenciar seu projeto Python de qualquer outro projeto Python no seu workspace:

    packages/my_other_project/my_other_project/main.py
    from "my_library.hello" import say_hello

    No exemplo acima, my_library é o nome do módulo, hello corresponde ao arquivo fonte Python hello.py, e say_hello é um método definido em hello.py

    Dependências

    Para adicionar dependências ao seu projeto, você pode executar o target add no seu projeto Python, por exemplo:

    Terminal window
    pnpm nx run my_scope.my_library:add some-pip-package

    Isso adicionará a dependência ao arquivo pyproject.toml do seu projeto e atualizará o uv.lock raiz.

    Código de Runtime

    Quando você usa seu projeto Python como código de runtime (por exemplo como handler de uma função AWS Lambda), será necessário criar um bundle do código fonte e todas suas dependências. Você pode fazer isso adicionando um target como o seguinte ao seu arquivo project.json:

    project.json
    {
      ...
      "targets": {
        ...
        "bundle": {
          "cache": true,
          "executor": "nx:run-commands",
          "outputs": ["{workspaceRoot}/dist/packages/my_library/bundle"],
          "options": {
            "commands": [
              "uv export --frozen --no-dev --no-editable --project my_library -o dist/packages/my_library/bundle/requirements.txt",
              "uv pip install -n --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux2014 --python `uv python pin` --target dist/packages/my_library/bundle -r dist/packages/my_library/bundle/requirements.txt"
            ],
            "parallel": false
          },
          "dependsOn": ["compile"]
        },
      },
    }

    Build

    Seu projeto Python está configurado com um target build (definido em project.json), que pode ser executado via:

    Terminal window
    pnpm nx run <project-name>:build

    Onde <project-name> é o nome totalmente qualificado do seu projeto.

    O target build irá compilar, verificar lint e testar seu projeto.

    A saída do build pode ser encontrada na pasta dist raiz do seu workspace, dentro de um diretório para seu pacote e target, por exemplo dist/packages/<my-library>/build

    Testes

    pytest está configurado para testar seu projeto.

    Escrevendo Testes

    Os testes devem ser escritos no diretório test dentro do seu projeto, em arquivos Python prefixados com test_, por exemplo:

    • Directorymy_library
      • hello.py
    • Directorytest
      • test_hello.py Testes para hello.py

    Testes são métodos que começam com test_ e fazem asserções para verificar expectativas, por exemplo:

    test/test_hello.py
    from my_library.hello import say_hello
    

    def test_say_hello():
      assert say_hello("Darth Vader") == "Hello, Darth Vader!"

    Para mais detalhes sobre como escrever testes, consulte a documentação do pytest.

    Executando Testes

    Os testes serão executados como parte do target build do seu projeto, mas você também pode executá-los separadamente usando o target test:

    Terminal window
    pnpm nx run <project-name>:test

    Você pode executar um teste individual ou um conjunto de testes usando o flag -k, especificando o nome do arquivo de teste ou método:

    Terminal window
    pnpm nx run <project-name>:test -k 'test_say_hello'

    Linting

    Projetos Python usam Ruff para linting.

    Executando o Linter

    Para invocar o linter e verificar seu projeto, você pode executar o target lint:

    Terminal window
    pnpm nx run <project-name>:lint

    Corrigindo Problemas de Lint

    A maioria dos problemas de linting ou formatação podem ser corrigidos automaticamente. Você pode instruir o Ruff a corrigir problemas de lint executando com o argumento --configuration=fix:

    Terminal window
    pnpm nx run <project-name>:lint --configuration=fix

    Da mesma forma, se desejar corrigir todos os problemas de lint em todos os pacotes do seu workspace, você pode executar:

    Terminal window
    pnpm nx run-many --target lint --all --configuration=fix