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 :

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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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. 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

Options

Paramètre	Type	Par défaut	Description
name Requis	string	-	Le nom du projet Python
directory	string	packages	Répertoire parent où le projet est placé.
subDirectory	string	-	Le sous-répertoire dans lequel le projet est placé. Par défaut, il s'agit du nom du projet.
type Requis	application | library	application	Indique si le projet est une application ou une bibliothèque
moduleName	string	-	Nom du module Python
preferInstallDependencies	boolean	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. Vous pouvez y parvenir en ajoutant une cible telle que la suivante à votre fichier 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"]
    },
  },
}

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

Tests

pytest est configuré pour tester votre projet.

Écrire des tests

Les tests doivent être écrits dans le répertoire test 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'

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