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, utilizando um único arquivo de lock e ambiente virtual em um espaço de trabalho UV, pytest para execução de testes e Ruff para análise estática.

Uso

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 - The name of the Python project
    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 Arquivo de exemplo em Python
    • Directorytests
      • __init__.py Inicialização do módulo
      • conftest.py Configuração de testes
      • test_hello.py Testes de exemplo
    • 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 Python

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

    Importando Código da Biblioteca em Outros Projetos

    Como os espaços de trabalho UV estão configurados, você pode referenciar seu projeto Python de qualquer outro projeto Python no 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

    Ao usar seu projeto Python como código de runtime (por exemplo, como handler de uma função AWS Lambda), você precisará criar um bundle do código-fonte e todas suas dependências. Isso pode ser alcançado 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, lintar e testar seu projeto.

    A saída do build pode ser encontrada na pasta dist raiz do 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 projeto, mas também podem ser executados separadamente usando o target test:

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

    Você pode executar um teste individual ou suite de testes usando a 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, execute o target lint:

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

    Corrigindo Problemas de Linting

    A maioria dos problemas de linting ou formatação pode ser corrigida automaticamente. Você pode pedir ao Ruff para corrigir problemas usando o argumento --configuration=fix:

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

    Similarmente, para corrigir todos os problemas de linting em todos os pacotes do workspace, execute:

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