Configurez un pyproject.toml

Toutes les applications Flower nécessitent un pyproject.toml. Lorsque vous créez une nouvelle application Flower en utilisant flwr new, un fichier pyproject.toml est généré. Ce fichier définit vos dépendances et la configuration d’initialisation.

Un fichier pyproject.toml complet, par exemple, ressemble à ceci :

Example pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "flower-app"
version = "1.0.0"
description = "A Flower app example"
license = "Apache-2.0"
dependencies = [
    "flwr[simulation]>=1.31.0",
    "numpy>=2.0.2",
]

[tool.hatch.build.targets.wheel]
packages = ["."]

[tool.flwr.app]
publisher = "your-name-or-organization"
fab-include = ["path/to/include_file.py"]  # Optional
fab-exclude = ["path/to/exclude_file.py"]  # Optional

[tool.flwr.app.components]
serverapp = "your_module.server_app:app"
clientapp = "your_module.client_app:app"

[tool.flwr.app.config]
num-server-rounds = 3
any-name-you-like = "any value supported by TOML"

Voici quelques sections clés à prendre en compte:

Méta-données de l’application et dépendances

[project]
name = "your-flower-app-name"
version = "1.0.0"
description = ""
license = "Apache-2.0"
dependencies = [
    "flwr[simulation]>=1.31.0",
    "numpy>=2.0.2",
]

[tool.flwr.app]
publisher = "your-name-or-organization"
fab-include = ["path/to/include_file.py"]  # Optional
fab-exclude = ["path/to/exclude_file.py"]  # Optional
Comprendre chaque champ

Note

* Champs obligatoires

Ces champs suivent la norme de métadonnées pyproject.toml, couramment utilisée par des outils comme uv, pip, et d’autres. Flower reprend ces derniers pour la configuration et le packaging.

  • name*: Le nom de votre application Flower.

  • version*: La version actuelle de votre application, utilisée pour le packaging et la distribution. Doit suivre la versionnement sémantique (par exemple, « 1.0.0 »).

  • description: Une brève synthèse de ce que votre application fait.

  • license: La licence sous laquelle votre application est distribuée (par exemple, Apache-2.0).

  • dependencies*: Une liste des packages Python requis pour exécuter votre application.

  • publisher*: Le nom de la personne ou l’organisation qui publie l’application.

  • fab-include: Une liste de modèles gitignore pour inclure dans le Bundle d’Application Flower. Voir Définition des fichiers inclus/exclus pour plus de détails.

  • fab-exclude: Une liste de modèles gitignore pour exclure de Flower Bundle d’application. Voir Définition des fichiers inclus/exclus pour plus de détails.

Spécifiez les métadonnées, y compris le nom de l’application, la version, etc., dans ces sections. Ajoutez tout package Python dont votre application a besoin sous dependencies. Ces packages seront installés lorsqu’il s’exécutera:

pip install -e .

Définir les fichiers inclus/exclus

Les champs fab-include et fab-exclude permettent de contrôler quels fichiers finissent dans votre Bundle d’application Flower (FAB) — le package qui transporte votre code d’application vers SuperLink et SuperNodes.

Les deux champs sont facultatifs. Lorsqu’ils sont omis, Flower utilise des valeurs sensibles de built-in defaults qui incluent les fichiers sources courants et le fichier d’en-tête principal (LICENSE) tandis que les environnements virtuels, les artefacts de construction, les répertoires __pycache__ et les fichiers de test sont exclus.

[tool.flwr.app]
publisher = "your-name-or-organization"
fab-include = ["src/**/*.py", "conf/*.yaml"]    # Optional
fab-exclude = ["src/scratch.py"]                # Optional
Comprendre chaque champ

  • fab-include: Une liste de modèles gitignore qui réduit le FAB aux seuls fichiers que vous souhaitez. Lorsque défini, Flower commence avec un ensemble candidat vide et ajoute uniquement les fichiers qui correspondent à au moins l’un de vos modèles. Les contraintes intégrées sont ensuite appliquées en surcharge — si l’un de vos modèles entraînerait la récupération d’un type de fichier non supporté (par exemple, un .txt ou une archive), Flower soulève une erreur listant les fichiers concernés afin que vous puissiez les corriger ou supprimer le modèle.

  • fab-exclude: Une liste de modèles gitignore qui supprime des fichiers spécifiques du FAB. Les fichiers qui correspondent à au moins un de vos modèles sont supprimés avant que les contraintes intégrées ne s’exécutent, vous pouvez donc en toute sécurité exclure tout ce que les valeurs par défaut retiendraient.

Note

Les deux champs sont facultatifs. Omettre un champ entièrement fait confiance aux valeurs par défaut intégrées — définir la liste vide est une erreur. Chaque modèle que vous fournissez doit correspondre à au moins un fichier ; Flower soulève une erreur en temps de construction pour les modèles non résolus, empêchant ainsi les erreurs silencieuses qui changeraient votre bundle.

Flower applique le filtrage en deux étapes:

  1. Filtre de publication — Les fichiers sont d’abord réduits aux types supportés, et tout modèle dans votre .gitignore est appliqué pour supprimer les fichiers ignorés. Référez-vous au Flower Hub documentation pour plus de détails sur la façon dont cela fonctionne lors du déploiement d’une application vers Flower Hub.

  2. Filtre FAB — Vos modèles fab-include et fab-exclude sont appliqués ensuite, suivis des contraintes internes non surplombables qui imposent les types de fichiers supportés et excluent les répertoires comme .venv/ ou __pycache__/.

En résumé, fab-include et fab-exclude vous donnent un contrôle fine-grain à l’intérieur des limites de ce que Flower supporte. Vous ne pouvez pas les utiliser pour inclure des types de fichiers non pris en charge (par exemple, .txt) — Flower signalera tout conflit avec un message d’erreur clair.

Exemple : Bundling uniquement votre paquetage source et un fichier de configuration

Supposez que votre projet ressemble à ceci:

my-flower-app/
├── pyproject.toml
├── README.md
├── conf/
│   └── config.yaml
└── your_module/
    ├── client_app.py
    ├── server_app.py
    └── scratch.py      ← you want to exclude this in the FAB

Ajoutez les éléments suivants à votre pyproject.toml:

[tool.flwr.app]
publisher = "your-name-or-organization"
fab-include = ["your_module/**/*.py", "conf/*.yaml"]
fab-exclude = ["your_module/scratch.py"]

Lorsque vous exécutez flwr run ou flwr build, le FAB résultant contiendra pyproject.toml, your_module/client_app.py, your_module/server_app.py, et conf/config.yaml — mais pas your_module/scratch.py ou README.md.

Défauts intégrés pour les fichiers inclus/exclus du FAB

Un FAB est un paquet structuré consommé par SuperLink et SuperNodes, et ils ne savent comment travailler que sur certains types de fichiers. Autoriser des types de fichiers arbitraires dans un FAB ne ferait pas seulement éclater la compatibilité au sein de la fédération et gonfler les tailles des bundles, mais créerait également un risque de sécurité — des fichiers sensibles comme les identifiants, les clés privées ou les configurations d’environnement pourraient être emballés et distribués à tous les SuperNodes de la fédération. C’est pourquoi Flower impose une série de modèles intégrés en plus de ce que vous mettez dans fab-include ou fab-exclude — et ces derniers ne peuvent pas être surchargés. Ils sont définis dans flwr.common.constant comme FAB_INCLUDE_PATTERNS et FAB_EXCLUDE_PATTERNS.

Allowed file types (FAB_INCLUDE_PATTERNS):

Ces sont les types de fichiers qui composent une application Flower typique — code source, configuration, documentation et descripteurs de données. Toute chose en dehors de ce ensemble (par exemple, .txt ou fichiers binaires) n’est pas un type de fichier FAB reconnu et ne peut pas être inclus :

**/*.py        Python source files
**/*.toml      TOML configuration files
**/*.md        Markdown documentation
**/*.yaml      YAML configuration files
**/*.yml       YAML configuration files (alternate extension)
**/*.json      JSON data files
**/*.jsonl     JSON Lines data files
/LICENSE       Top-level license file

Always excluded (FAB_EXCLUDE_PATTERNS):

Ces sont les chemins qui ne devraient jamais voyager à travers le réseau : artefacts générés pouvant être reproduits localement (caches, sorties de build, répertoires de packaging), environnements virtuels spécifiques aux machines, fichiers de test non nécessaires en temps d’exécution et le répertoire interne de Flower :

.flwr/**           Flower internal directory
**/__pycache__/**  Python bytecode cache
pyproject.toml     Re-serialized separately; the original is never bundled as-is
**/*_test.py       Test files
**/test_*.py       Test files
build/**           Build output
eggs/**            Egg build artifacts
.eggs/**
lib/**
lib64/**
parts/**
*.egg
.venv/**           Virtual environments
env/**
venv/**
ENV/**
env.bak/**
venv.bak/**

Note

Si vous utilisez fab-include pour ajouter un fichier qui ne correspond à aucun des modèles d’inclusion intégrés (par exemple, un .txt fichier), Flower lancera une erreur et listera les fichiers en conflit. La solution est de supprimer ces modèles de fab-include. Les fichiers qui font match avec les includes intégrés mais sont également inclus par les exclusions intégrées (par exemple, un *.py fichier à l’intérieur de .venv/) sont silencieusement ignorés — c’est un comportement attendu.

Composants d’application

[tool.flwr.app.components]
serverapp = "your_module.server_app:app"
clientapp = "your_module.client_app:app"
Comprendre chaque champ

Note

* Champs obligatoires

  • serverapp*: Le chemin d’importation de votre objet ServerApp.

  • clientapp*: Le chemin d’importation de votre objet ClientApp.

Ces entrées pointent vers vos définitions ServerApp et ClientApp, au format <module>:<object>. Mettez à jour ces chemins d’importation uniquement si vous renommez vos modules ou les variables qui référencent vos ServerApp ou ClientApp.

Configuration d’application

[tool.flwr.app.config]
num-server-rounds = 3
any-name-you-like = "any value supported by TOML"

Définissez les valeurs de configuration qui devraient être disponibles pour votre application en temps réel. Vous pouvez spécifier un nombre quelconque de paires clé-valeur dans cette section. Toutes les valeurs de configuration de cette section sont facultatives.

Accédez à ces valeurs dans votre code en utilisant context.run_config. Par exemple:

server_rounds = context.run_config["num-server-rounds"]

Astuce

Vous pouvez également surcharger les valeurs de run_config en passant le drapeau --run-config suivi de paires clés-valeurs lors de l’exécution de flwr run. Voir la documentation de flwr run et CLI pour plus de détails.

Configuration de la fédération

Note

Ce qui était précédemment appelé « configuration de la fédération » pour les connexions SuperLink dans pyproject.toml a été renommé et déplacé. Ces paramètres sont maintenant configuration de connexion SuperLink et sont définis dans le fichier de configuration Flower. Référez-vous au Flower Configuration pour en savoir plus.