Projets Python

Le générateur de projet Python peut être utilisé pour créer une bibliothèque ou une application Python moderne configurée avec les meilleures pratiques, gérée avec UV, un seul fichier de verrouillage et un environnement virtuel dans un espace de travail UV, pytest pour exécuter les tests, Ruff pour l’analyse statique, et ty pour la vérification de type.

Utilisation

Générer un projet Python

Vous pouvez générer un nouveau projet Python de deux manières :

Exécuter ce générateur@aws/nx-plugin:py#project

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

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - py#project
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Composez votre commande6

nameRequis

typeRequis

applicationlibrary

directory

subDirectory

moduleName

preferInstallDependencies

true

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Options

Options du générateur6 options

nameRequisstring

Le nom du projet Python

typeRequisenumPar défaut: application

Indique si le projet est une application ou une bibliothèque

applicationlibrary

directorystringPar défaut: packages

Répertoire parent où le projet est placé.

subDirectorystring

Le sous-répertoire dans lequel le projet est placé. Par défaut, il s'agit du nom du projet.

moduleNamestring

Nom du module Python

preferInstallDependenciesbooleanPar défaut: true

Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir sur false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Le générateur créera la structure de projet suivante dans le répertoire <directory>/<name> :

• Répertoire<module-name>

  • __init__.py Module initialisation
• Répertoiretests

  • __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

Vous remarquerez peut-être également les fichiers suivants créés/mis à jour à la racine de votre espace de travail :

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

Écrire du code source Python

Ajoutez votre code source Python dans le répertoire <module-name>.

Importer le code de votre bibliothèque dans d’autres projets

Utilisez la cible add pour ajouter une dépendance à un projet Python.

Supposons que nous ayons créé deux projets Python, my_app et my_lib. Ceux-ci auront des noms de projet pleinement qualifiés my_scope.my_app et my_scope.my_lib, et par défaut auront chacun des noms de module my_scope_my_app et my_scope_my_lib.

Pour que my_app dépende de my_lib, nous pouvons exécuter la commande suivante :

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

Noms pleinement qualifiés

Nous utilisons le nom de projet pleinement qualifié pour le dépendant et la dépendance. Nous pouvons utiliser la syntaxe abrégée pour le projet auquel nous voulons ajouter la dépendance, mais nous devons qualifier complètement le nom du projet dont nous dépendons.

Vous pouvez ensuite importer le code de votre bibliothèque :

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.my_module import my_function

Ci-dessus, my_scope_my_lib est le nom du module pour la bibliothèque, my_module correspond à un fichier source Python my_module.py, et my_function est une méthode définie dans ce fichier.

Dépendances

Pour ajouter des dépendances à votre projet, vous pouvez exécuter la cible add dans votre projet Python, par exemple :

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

Cela ajoutera la dépendance au fichier pyproject.toml de votre projet et mettra à jour le uv.lock racine.

Code d’exécution

Lorsque vous utilisez votre projet Python comme code d’exécution (par exemple comme gestionnaire pour une fonction AWS lambda), vous devrez créer un bundle du code source et de toutes ses dépendances. Les générateurs py#lambda-function, py#api et py#mcp-server ajoutent cela pour vous. Pour en ajouter un manuellement, ajoutez des cibles telles que les suivantes à votre fichier project.json, en correspondant à la forme que ces générateurs fournissent :

project.json

{
  "targets": {
    "bundle": {
      "dependsOn": ["bundle-x86"]
    },
    "bundle-x86": {
      "cache": true,
      "inputs": ["production", "^production"],
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle-x86"],
      "options": {
        "commands": [
          "uv export --frozen --no-dev --no-editable --project {projectRoot} --package my_scope.my_library -o dist/{projectRoot}/bundle-x86/requirements.txt",
          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux_2_28 --python-version 3.14 --target dist/{projectRoot}/bundle-x86 -r dist/{projectRoot}/bundle-x86/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    }
  }
}

Installation

Installez les dépendances Python avec la commande suivante :

uv sync

Construction

Votre projet Python est configuré avec une cible build (définie dans project.json), que vous pouvez exécuter via :

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

Où <project-name> est le nom pleinement qualifié de votre projet.

La cible build compilera, analysera, testera et vérifiera le type de votre projet.

La sortie de construction se trouve dans le dossier dist racine de votre espace de travail, à l’intérieur d’un répertoire pour votre package et cible, par exemple dist/packages/<my-library>/build

Pour construire tous les projets de votre espace de travail, exécutez :

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

Ou utilisez la commande abrégée :

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Assemblage

Votre projet dispose également d’une cible assemble, qui produit ce que votre projet contribue à un déploiement (par exemple sa sortie compilée ou regroupée), sans exécuter les contrôles de lint, de test ou de vérification de type.

pnpm

pnpm nx assemble <project-name>

yarn

yarn nx assemble <project-name>

npm

npx nx assemble <project-name>

bun

bunx nx assemble <project-name>

Les cibles de déploiement dépendent de assemble, donc le déploiement ne construit que ce qu’il est sur le point de déployer.

Utilisez build dans votre pipeline

assemble est utilisé pour une itération plus rapide pendant le développement. Exécutez build dans votre pipeline CI pour vous assurer que votre projet passe les contrôles de qualité avant un déploiement en production.

Tests

pytest est configuré pour tester votre projet.

Écrire des tests

Les tests doivent être écrits dans le répertoire tests de votre projet, dans des fichiers Python préfixés par test_, par exemple :

• Répertoiremy_library

  • my_module.py
• Répertoiretests

  • test_my_module.py Tests for my_module.py

Les tests sont des méthodes qui commencent par test_ et font des assertions pour vérifier les attentes, par exemple :

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

Pour plus de détails sur la façon d’écrire des tests, veuillez vous référer à la documentation pytest.

Exécuter les tests

Les tests s’exécuteront dans le cadre de la cible build de votre projet, mais vous pouvez également les exécuter séparément en exécutant la cible 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>

Vous pouvez exécuter un test individuel ou une suite de tests en utilisant le flag -k, en spécifiant soit le nom du fichier de test soit de la méthode :

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'

Fichiers de test et mise en cache

Le répertoire tests de votre projet est exclu de l’entrée nommée production dans nx.json.

Les cibles dont la sortie ne peut pas contenir de fichier de test - telles que compile et toutes les cibles de bundle - lisent production plutôt que default, de sorte que la modification d’un test ne les invalide pas, ni aucune tâche dans un projet qui dépend du vôtre.

L’exclusion est délibérément limitée au répertoire tests. Un fichier test_*.py à l’intérieur du répertoire de votre package est traité comme du code de production, car il est empaqueté dans votre distribution construite, et invalide donc toujours la construction.

Les cibles test, lint, format et typecheck lisent default et se réexécutent donc toujours lorsque vous modifiez un test. Notez que typecheck vérifie également le type de vos tests, donc une erreur de type dans un test est toujours signalée.

Vérification de type

Les projets Python utilisent ty pour la vérification de type.

Exécuter le vérificateur de type

La vérification de type s’exécute dans le cadre de la cible build de votre projet, mais vous pouvez également l’exécuter séparément via la cible 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

Supprimer les erreurs de type

Pour supprimer un diagnostic spécifique pour une seule ligne, ajoutez un commentaire # ty: ignore[<rule>] à la fin de la ligne, par exemple :

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

Pour configurer le comportement de la vérification de type dans votre projet, ajoutez une section [tool.ty] au pyproject.toml de votre projet. Consultez la référence de configuration ty pour les options disponibles.

Analyse

Les projets Python utilisent Ruff pour l’analyse.

Exécuter l’analyseur

Pour invoquer l’analyseur afin de vérifier votre projet, vous pouvez exécuter la cible 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>

Corriger les problèmes d’analyse

La majorité des problèmes d’analyse ou de formatage peuvent être corrigés automatiquement. Vous pouvez demander à Ruff de corriger les problèmes d’analyse en exécutant avec l’argument --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

De même, si vous souhaitez corriger tous les problèmes d’analyse dans tous les packages de votre espace de travail, vous pouvez exécuter :

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

Commande abrégée

Cela a une commande abrégée depuis la racine de votre espace de travail :

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Ignorer les problèmes d’analyse

Pour éviter que les problèmes d’analyse ne vous ralentissent pendant le développement (en particulier si vous avez des problèmes non corrigeables automatiquement dans votre projet), vous pouvez exécuter une construction avec la configuration 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

Cela exécutera toujours Ruff dans le cadre de la construction, mais la cible lint sera toujours considérée comme réussie.

Commande abrégée

Cela a une commande abrégée depuis la racine de votre espace de travail :

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint