Salta ai contenuti
@aws/nx-plugin
Blog

Progetti Python

Il generatore di progetti Python consente di creare una libreria o applicazione Python moderna 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:

  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
    • Clicca su Generate

    Opzioni

    Parametro Tipo Predefinito Descrizione
    name Obbligatorio string - Project name.
    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 inoltre notare i seguenti file creati/aggiornati nella root del workspace:

    • pyproject.toml Configurazione del 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 sopra, 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 tuo progetto, puoi eseguire il target add nel tuo progetto Python, ad esempio:

    Terminal window
    pnpm 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 root.

    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 dipendenze. Puoi farlo 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 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 tuo progetto Python è configurato con un target build (definito in project.json), eseguibile tramite:

    Terminal window
    pnpm nx run <project-name>:build

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

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

    L’output della build si troverà nella cartella dist root 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 dovrebbero essere 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 come parte del target build, ma puoi anche eseguirli separatamente tramite il target test:

    Terminal window
    pnpm 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 di test:

    Terminal window
    pnpm 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:

    Terminal window
    pnpm nx run <project-name>:lint

    Correggere i problemi di linting

    La maggior parte dei problemi di linting/formattazione può essere risolta automaticamente. Puoi chiedere a Ruff di correggere i problemi eseguendo con l’argomento --configuration=fix:

    Terminal window
    pnpm nx run <project-name>:lint --configuration=fix

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

    Terminal window
    pnpm nx run-many --target lint --all --configuration=fix