Projetos Python

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

Uso

Gerar um Projeto Python

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

Execute este gerador@aws/nx-plugin:py#project

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

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

Monte seu comando6

nameObrigatório

typeObrigatório

applicationlibrary

directory

subDirectory

moduleName

preferInstallDependencies

true

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

Opções

Opções do gerador6 opções

nameObrigatóriostring

O nome do projeto Python

typeObrigatórioenumPadrão: application

Se o projeto é uma aplicação ou biblioteca

applicationlibrary

directorystringPadrão: packages

Diretório pai onde o projeto é colocado.

subDirectorystring

O subdiretório onde o projeto é colocado. Por padrão, este é o nome do projeto.

moduleNamestring

Nome do módulo Python

preferInstallDependenciesbooleanPadrão: true

Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

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

• Directory<module-name>

  • __init__.py Module initialisation
• Directorytests

  • __init__.py Module initialisation
  • conftest.py Test configuration
  • test_noop.py Placeholder test
• project.json Project configuration and build targets
• pyproject.toml Packaging configuration file used by UV
• .python-version Contains the project’s Python version

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

• pyproject.toml Workspace level packaging configuration for UV
• .python-version Contains the workspace Python version
• uv.lock Lockfile for Python dependencies

Escrevendo Código-Fonte Python

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

Importando o Código da sua 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 de my_scope.my_app e my_scope.my_lib, e por padrão cada um terá nomes de módulo de 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

Nomes Totalmente Qualificados

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

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

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.my_module import my_function

Acima, my_scope_my_lib é o nome do módulo para a lib, my_module corresponde a um arquivo-fonte Python my_module.py, e my_function é um método definido nesse arquivo.

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 o handler para uma função AWS lambda), você precisará criar um bundle do código-fonte e todas as suas dependências. Os geradores py#lambda-function, py#api e py#mcp-server adicionam isso para você. Para adicionar um manualmente, adicione targets como o seguinte ao seu arquivo project.json, correspondendo à forma que esses geradores fornecem:

project.json

{
  "targets": {
    "bundle": {
      "dependsOn": ["bundle-x86"]
    },
    "bundle-x86": {
      "cache": true,
      "inputs": ["production", "^production"],
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle-x86"],
      "options": {
        "commands": [
          "uv export --frozen --no-dev --no-editable --project {projectRoot} --package my_scope.my_library -o dist/{projectRoot}/bundle-x86/requirements.txt",
          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux_2_28 --python-version 3.14 --target dist/{projectRoot}/bundle-x86 -r dist/{projectRoot}/bundle-x86/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    }
  }
}

Instalação

Instale as dependências Python com o seguinte comando:

uv sync

Construção

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

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

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

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

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

Para construir todos os projetos no seu workspace, execute:

pnpm

pnpm nx run-many --target build

yarn

yarn nx run-many --target build

npm

npx nx run-many --target build

bun

bunx nx run-many --target build

Ou use o comando abreviado:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Assembling

Seu projeto também tem um target assemble, que produz o que seu projeto contribui para um deployment (por exemplo, sua saída compilada ou em bundle), sem executar as verificações de lint, teste ou verificação de tipos.

pnpm

pnpm nx assemble <project-name>

yarn

yarn nx assemble <project-name>

npm

npx nx assemble <project-name>

bun

bunx nx assemble <project-name>

Os targets de deploy dependem de assemble, então o deploy constrói apenas o que está prestes a implantar.

Use build no seu pipeline

assemble é usado para iteração mais rápida durante o desenvolvimento. Execute build no seu pipeline de CI para garantir que seu projeto passe pelas verificações de qualidade antes de um deployment de produção.

Testes

pytest está configurado para testar seu projeto.

Escrevendo Testes

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

• Directorymy_library

  • my_module.py
• Directorytests

  • test_my_module.py Tests for my_module.py

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

tests/test_my_module.py

from my_library.my_module 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 para seu projeto, mas você também pode executá-los separadamente executando o target test:

pnpm

pnpm nx test <project-name>

yarn

yarn nx test <project-name>

npm

npx nx test <project-name>

bun

bunx nx test <project-name>

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

pnpm

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

yarn

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

npm

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

bun

bunx nx test <project-name> -k 'test_say_hello'

Arquivos de Teste e Cache

O diretório tests do seu projeto é excluído da entrada nomeada production em nx.json.

Targets cuja saída não pode conter um arquivo de teste - como compile e quaisquer targets de bundle - leem production em vez de default, então editar um teste não os invalida nem qualquer tarefa em um projeto que depende do seu.

A exclusão é deliberadamente limitada ao diretório tests. Um arquivo test_*.py dentro do diretório do seu pacote é tratado como código de produção, já que é empacotado na sua distribuição construída, e portanto ainda invalida a construção.

Os targets test, lint, format e typecheck leem default e, portanto, ainda são executados novamente quando você edita um teste. Note que typecheck verifica os tipos dos seus testes também, então um erro de tipo em um teste ainda é reportado.

Verificação de Tipos

Projetos Python usam ty para verificação de tipos.

Executando o Verificador de Tipos

A verificação de tipos é executada como parte do target build para seu projeto, mas você também pode executá-la separadamente via o target typecheck:

pnpm

pnpm nx run <project-name>:typecheck

yarn

yarn nx run <project-name>:typecheck

npm

npx nx run <project-name>:typecheck

bun

bunx nx run <project-name>:typecheck

Suprimindo Erros de Tipo

Para suprimir um diagnóstico específico para uma única linha, adicione um comentário # ty: ignore[<rule>] no final da linha, por exemplo:

value: int = "not an int"  # ty: ignore[invalid-assignment]

Para configurar o comportamento da verificação de tipos em todo o seu projeto, adicione uma seção [tool.ty] ao pyproject.toml do seu projeto. Consulte a referência de configuração do ty para opções disponíveis.

Linting

Projetos Python usam Ruff para linting.

Executando o Linter

Para invocar o linter para verificar seu projeto, você pode executar o target lint.

pnpm

pnpm nx lint <project-name>

yarn

yarn nx lint <project-name>

npm

npx nx lint <project-name>

bun

bunx nx lint <project-name>

Corrigindo Problemas de Lint

A maioria dos problemas de linting ou formatação pode ser corrigida automaticamente. Você pode dizer ao Ruff para corrigir problemas de lint executando com o argumento --configuration=fix.

pnpm

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

yarn

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

npm

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

bun

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

Da mesma forma, se você quiser corrigir todos os problemas de lint em todos os pacotes no 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

Comando Abreviado

Isso tem um comando abreviado a partir da raiz do seu workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Ignorando Problemas de Lint

Para evitar que problemas de linting te atrasem durante o desenvolvimento (particularmente se você tiver problemas não auto-corrigíveis no seu projeto), você pode executar uma construção com a configuração skip-lint:

pnpm

pnpm nx run-many --target build --configuration=skip-lint

yarn

yarn nx run-many --target build --configuration=skip-lint

npm

npx nx run-many --target build --configuration=skip-lint

bun

bunx nx run-many --target build --configuration=skip-lint

Isso ainda executará o Ruff como parte da construção, mas o target lint sempre será considerado bem-sucedido.

Comando Abreviado

Isso tem um comando abreviado a partir da raiz do seu workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint