Progetti Python

Il generatore di progetti Python può essere utilizzato per creare una moderna libreria o applicazione Python configurata con le migliori pratiche, gestita con UV, un singolo file di lock e un ambiente virtuale in un workspace UV, pytest per l’esecuzione dei test, Ruff per l’analisi statica, e ty per il controllo dei tipi.

Utilizzo

Generare un Progetto Python

Puoi generare un nuovo progetto Python in due modi:

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - py#project
5. Compila i parametri richiesti
6. Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Il nome del progetto Python
directory	string	packages	Directory principale dove viene posizionato il progetto.
subDirectory	string	-	La sottodirectory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.
projectType Obbligatorio	string	application	Se il progetto è un'applicazione o una libreria
moduleName	string	-	Nome del modulo Python

Output del Generatore

Il generatore creerà la seguente struttura del progetto nella directory <directory>/<name>:

• Directory<module-name>

  • __init__.py Inizializzazione modulo
• Directorytests

  • __init__.py Inizializzazione modulo
  • conftest.py Configurazione test
  • test_noop.py Test segnaposto
• project.json Configurazione progetto e target di build
• pyproject.toml File di configurazione packaging utilizzato da UV
• .python-version Contiene la versione Python del progetto

Potresti anche notare i seguenti file creati/aggiornati nella root del workspace:

• pyproject.toml Configurazione packaging a livello workspace per UV
• .python-version Contiene la versione Python del workspace
• uv.lock File di lock per le dipendenze Python

Scrivere Codice Python

Aggiungi il tuo codice sorgente Python nella directory <module-name>.

Importare il Codice della Libreria in Altri Progetti

Utilizza il target add per aggiungere una dipendenza a un progetto Python.

Supponiamo di aver creato due progetti Python, my_app e my_lib. Questi avranno nomi progetto completamente qualificati my_scope.my_app e my_scope.my_lib, e per default avranno nomi modulo my_scope_my_app e my_scope_my_lib.

Per far dipendere my_app da my_lib, possiamo eseguire il 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

Nomi completamente qualificati

Utilizziamo il nome progetto completamente qualificato sia per il dipendente che per il dipendente. Possiamo usare la sintassi abbreviata per il progetto a cui vogliamo aggiungere la dipendenza, ma dobbiamo qualificare completamente il nome del progetto da cui dipendere.

Potrai quindi importare il codice della libreria:

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.my_module import my_function

Qui sopra, my_scope_my_lib è il nome modulo della libreria, my_module corrisponde a un file sorgente Python my_module.py, e my_function è un metodo definito in quel file.

Dipendenze

Per aggiungere dipendenze al tuo progetto, puoi eseguire il target add nel tuo progetto Python, ad esempio:

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

Questo aggiungerà la dipendenza al file pyproject.toml del progetto e aggiornerà il root uv.lock.

Codice Runtime

Quando utilizzi il tuo progetto Python come codice runtime (ad esempio come handler per una funzione AWS lambda), dovrai creare un bundle del codice sorgente e di tutte le sue dipendenze. Puoi ottenere questo aggiungendo un target come il seguente al tuo file 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-manylinux_2_28 --python `uv python pin` --target dist/packages/my_library/bundle -r dist/packages/my_library/bundle/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    },
  },
}

Build

Il tuo progetto Python è configurato con un target build (definito in project.json), che puoi eseguire tramite:

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

Dove <project-name> è il nome completamente qualificato del tuo progetto.

Il target build compilerà, eseguirà il linting, testerà e controllerà i tipi del progetto.

L’output della build si troverà nella cartella root dist del workspace, all’interno di una directory per il tuo package e target, ad esempio dist/packages/<my-library>/build

Per compilare tutti i progetti nel tuo workspace, esegui:

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

Oppure usa il comando abbreviato:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Testing

pytest è configurato per testare il tuo progetto.

Scrivere Test

I test dovrebbero essere scritti nella directory test all’interno del progetto, in file Python prefissati con test_, ad esempio:

• Directorymy_library

  • my_module.py
• Directorytests

  • test_my_module.py Test per my_module.py

I test sono metodi che iniziano con test_ e fanno asserzioni per verificare le aspettative, ad esempio:

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!"

Per maggiori dettagli su come scrivere test, consulta la documentazione pytest.

Eseguire Test

I test verranno eseguiti come parte del target build del progetto, ma puoi anche eseguirli separatamente con il 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>

Puoi eseguire un singolo test o una suite di test usando il flag -k, specificando il nome del file test o del metodo:

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'

Controllo dei Tipi

I progetti Python utilizzano ty per il controllo dei tipi.

Eseguire il Controllo dei Tipi

Il controllo dei tipi viene eseguito come parte del target build del progetto, ma puoi anche eseguirlo separatamente tramite il 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

Sopprimere Errori di Tipo

Per sopprimere una diagnostica specifica per una singola riga, aggiungi un commento # ty: ignore[<rule>] alla fine della riga, ad esempio:

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

Per configurare il comportamento del controllo dei tipi nel tuo progetto, aggiungi una sezione [tool.ty] al file pyproject.toml del progetto. Consulta il riferimento alla configurazione di ty per le opzioni disponibili.

Linting

I progetti Python utilizzano Ruff per il linting.

Eseguire il Linter

Per invocare il linter e controllare il progetto, puoi eseguire il 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>

Correggere Problemi di Linting

La maggior parte dei problemi di linting o formattazione può essere corretta automaticamente. Puoi chiedere a Ruff di correggere i problemi eseguendo con l’argomento --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

Analogamente, se vuoi correggere tutti i problemi di linting in tutti i package del workspace, puoi eseguire:

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 abbreviato

Questo ha un comando abbreviato dalla root del tuo workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Ignorare Problemi di Linting

Per evitare che i problemi di linting ti rallentino durante lo sviluppo (in particolare se hai problemi non correggibili automaticamente nel tuo progetto), puoi eseguire una build con la configurazione 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

Questo eseguirà comunque Ruff come parte della build, ma il target lint sarà sempre considerato riuscito.

Comando abbreviato

Questo ha un comando abbreviato dalla root del tuo workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint