Progetti Python

Il generatore di progetti Python può essere utilizzato per creare una libreria o applicazione Python moderna configurata con le best practice, gestita con UV, un singolo lockfile e 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:

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

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

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.
type Obbligatorio	application | library	application	Se il progetto è un'applicazione o una libreria
moduleName	string	-	Nome del modulo Python
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore creerà la seguente struttura di progetto nella directory <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

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

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

Scrivere Codice Sorgente Python

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

Importare il Codice della tua Libreria in Altri Progetti

Usa 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 di progetto completamente qualificati my_scope.my_app e my_scope.my_lib, e per impostazione predefinita avranno ciascuno nomi di modulo my_scope_my_app e my_scope_my_lib.

Affinché my_app dipenda da my_lib, possiamo eseguire il seguente 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 di progetto completamente qualificato sia per il dipendente che per la dipendenza. 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.

Puoi quindi importare il codice della tua libreria:

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.my_module import my_function

Sopra, my_scope_my_lib è il nome del modulo per la 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, per 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 tuo progetto e aggiornerà il uv.lock nella radice.

Codice Runtime

Quando usi 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 lint, testerà e controllerà i tipi del tuo progetto.

L’output della build può essere trovato nella cartella dist nella radice del tuo workspace, all’interno di una directory per il tuo package e target, per esempio dist/packages/<my-library>/build

Per fare la build di 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 tuo progetto, in file python con prefisso test_, per esempio:

• Directorymy_library

  • my_module.py
• Directorytests

  • test_my_module.py Tests for my_module.py

I test sono metodi che iniziano con test_ e fanno asserzioni per verificare le aspettative, per 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 di pytest.

Eseguire i Test

I test verranno eseguiti come parte del target build per il tuo progetto, ma puoi anche eseguirli separatamente eseguendo 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 suite di test usando il flag -k, specificando il nome del file di 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 usano ty per il controllo dei tipi.

Eseguire il Controllo dei Tipi

Il controllo dei tipi viene eseguito come parte del target build per il tuo 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, per 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 pyproject.toml del tuo progetto. Consulta il riferimento di configurazione di ty per le opzioni disponibili.

Linting

I progetti Python usano Ruff per il linting.

Eseguire il Linter

Per invocare il linter per controllare il tuo 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 Lint

La maggior parte dei problemi di linting o formattazione può essere corretta automaticamente. Puoi dire a Ruff di correggere i problemi di lint 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

Allo stesso modo, se desideri correggere tutti i problemi di lint in tutti i package nel tuo 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 radice del tuo workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Saltare Problemi di Lint

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 radice del tuo workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint