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 espaço de trabalho UV, 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:

VSCode

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
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#project

yarn

yarn nx g @aws/nx-plugin:py#project

npm

npx nx g @aws/nx-plugin:py#project

bun

bunx nx g @aws/nx-plugin:py#project

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:py#project --dry-run

yarn

yarn nx g @aws/nx-plugin:py#project --dry-run

npm

npx nx g @aws/nx-plugin:py#project --dry-run

bun

bunx nx g @aws/nx-plugin:py#project --dry-run

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 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 Biblioteca em Outros Projetos

Use o target add para adicionar uma dependência a um projeto Python.

Suponha que criamos dois projetos Python, my_app e my_lib. Estes terão nomes de projeto totalmente qualificados como my_scope.my_app e my_scope.my_lib, e por padrão terão nomes de módulo my_scope_my_app e my_scope_my_lib.

Para que my_app dependa de my_lib, podemos executar o seguinte comando:

pnpm

pnpm nx run my_scope.my_app:add my_scope.my_lib

yarn

yarn nx run my_scope.my_app:add my_scope.my_lib

npm

npx nx run my_scope.my_app:add my_scope.my_lib

bun

bunx nx run my_scope.my_app:add my_scope.my_lib

Nota

Usamos o nome totalmente qualificado do projeto tanto para o dependente quanto para a dependência. Podemos usar a sintaxe abreviada para o projeto ao qual queremos adicionar a dependência, mas devemos qualificar totalmente o nome do projeto da dependência.

Você pode então importar o código da biblioteca:

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.hello import say_hello

Acima, my_scope_my_lib é o nome do módulo para a biblioteca, 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:

pnpm

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

yarn

yarn nx run my_scope.my_library:add some-pip-package

npm

npx nx run my_scope.my_library:add some-pip-package

bun

bunx 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), precisará 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 packages/my_library --package my_scope.my_library -o dist/packages/my_library/bundle/requirements.txt",
          "uv pip install -n --no-deps --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 você pode executar via:

pnpm

pnpm nx run <project-name>:build

yarn

yarn nx run <project-name>:build

npm

npx nx run <project-name>:build

bun

bunx nx run <project-name>:build

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

O target build irá compilar, verificar 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:

pnpm

pnpm nx run <project-name>:test

yarn

yarn nx run <project-name>:test

npm

npx nx run <project-name>:test

bun

bunx nx run <project-name>:test

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

pnpm

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

yarn

yarn nx run <project-name>:test -k 'test_say_hello'

npm

npx nx run <project-name>:test -k 'test_say_hello'

bun

bunx 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:

pnpm

pnpm nx run <project-name>:lint

yarn

yarn nx run <project-name>:lint

npm

npx nx run <project-name>:lint

bun

bunx nx run <project-name>:lint

Corrigindo Problemas de Linting

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

pnpm

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

yarn

yarn nx run <project-name>:lint --configuration=fix

npm

npx nx run <project-name>:lint --configuration=fix

bun

bunx nx run <project-name>:lint --configuration=fix

Similarmente, se desejar corrigir todos os problemas de linting em todos os pacotes do seu workspace, você pode executar:

pnpm

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

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix