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 e Ruff per l’analisi statica.

Utilizzo

Genera 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	-	The name of the Python project
directory	string	packages	Parent directory where the project is placed.
projectType Obbligatorio	string	application	Project type
moduleName	string	-	Python module name

Output del generatore

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

• Directory<module-name>

  • __init__.py Inizializzazione del modulo
  • hello.py File Python di esempio
• Directorytests

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

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

• pyproject.toml Configurazione di 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

Grazie alla configurazione dei workspace UV, puoi referenziare il tuo progetto Python da qualsiasi altro progetto Python nel workspace:

packages/my_other_project/my_other_project/main.py

from "my_library.hello" import say_hello

Nell’esempio, my_library è il nome del modulo, hello corrisponde al file sorgente Python hello.py, e say_hello è un metodo definito in hello.py.

Dipendenze

Per aggiungere dipendenze al 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 file uv.lock principale.

Codice runtime

Quando usi il 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 dipendenze. Puoi farlo aggiungendo un target come il seguente al 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 -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

Il progetto Python è configurato con un target build (definito in project.json), eseguibile tramite:

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

Dove <project-name> è il nome completo del progetto.

Il target build eseguirà la compilazione, il linting e i test del progetto.

L’output della build si trova nella cartella dist principale del workspace, all’interno di una directory specifica per il pacchetto e il target, ad esempio dist/packages/<my-library>/build.

Testing

pytest è configurato per il testing del progetto.

Scrivere test

I test vanno scritti nella directory test del progetto, in file Python prefissati con test_, ad esempio:

• Directorymy_library

  • hello.py
• Directorytest

  • test_hello.py Test per hello.py

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

test/test_hello.py

from my_library.hello import say_hello

def test_say_hello():
  assert say_hello("Darth Vader") == "Hello, Darth Vader!"

Per maggiori dettagli sulla scrittura dei test, consultare la documentazione pytest.

Eseguire i test

I test vengono eseguiti durante il target build, ma puoi eseguirli separatamente con il 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

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

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

I progetti Python utilizzano Ruff per il linting.

Eseguire il linter

Per invocare il linter e verificare il progetto, esegui il 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

Correggere i problemi di lint

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

Analogamente, per correggere tutti i problemi di linting in tutti i pacchetti del workspace:

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