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

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	-	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 modulo
  • hello.py File Python di esempio
• Directorytests

  • __init__.py Inizializzazione modulo
  • conftest.py Configurazione test
  • test_hello.py Test di esempio
• 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

Nota

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.hello import say_hello

Qui sopra, my_scope_my_lib è il nome modulo della libreria, hello corrisponde al file sorgente Python hello.py, e say_hello è un metodo definito in hello.py

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-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 tuo progetto Python è configurato con un target build (definito in project.json), che puoi eseguire 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 completamente qualificato del tuo progetto.

Il target build compilerà, eseguirà il linting e testerà il 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

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

  • hello.py
• Directorytest

  • test_hello.py Test per hello.py

I test sono metodi che iniziano con test_ e fanno 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 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 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 una suite di test usando il flag -k, specificando il nome del file test 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 controllare il progetto, puoi eseguire 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 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 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, 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