schema-archi 0.7.3

Génération de schémas d'architecture SVG (flux applicatifs) depuis des définitions YAML/JSON

schema-archi

Génération de schémas d'architecture SVG à partir de définitions YAML ou JSON.

Le schéma s'organise autour d'une application centrale : les applications qui émettent vers elle sont placées à gauche, celles qui en reçoivent à droite. Chaque flux est tracé comme une flèche horizontale portant un libellé, et éventuellement un lien cliquable.

Documentation

• Formats d'entrée — référence complète des fichiers de définition et de configuration, grammaire des flux, messages de diagnostic.
• Fonctionnement et algorithme — les cinq étapes de la génération, les formules de placement, un exemple chiffré et les limites connues.
• Publier sur PyPI — comptes, jetons, numérotation, répétition sur TestPyPI et marche à suivre.

Ce fichier n'en donne qu'un aperçu.

Installation

pip install schema-archi              # bibliothèque + commande
pip install schema-archi[png]         # + export PNG (cairosvg)
pip install schema-archi[ui]          # + éditeur web (NiceGUI)

Format de définition

apps:
  m : "Opik"
  g2 : "Application1"
  ju : "Application2"
  pr : "App 3"

main:
  m

flows_def:
  - g2 -> m [commande](https://example.org/commande)
  - g2 -> m [sortie]
  - m <- ju [sortie2]
  - m <- pr [structure]

• apps — code court → libellé affiché. Les codes acceptent lettres, chiffres, souligné, point et tiret (si-rh, app.v2).
• main — code de l'application centrale ; facultatif, m par défaut.
• flows_def — une ligne par flux, au format source -> cible [libellé](url). L'URL est facultative ; <- inverse le sens. La ligne doit correspondre entièrement au motif : pas de commentaire en fin de ligne.

Attention au placement : g2 -> m met g2 à gauche, tandis que m <- ju met ju à droite. Le sens d'écriture détermine la colonne — c'est le mécanisme qui permet d'équilibrer les deux côtés du schéma sans changer le sens des flèches dessinées.

La grammaire complète, les codes admis et les cas rejetés sont détaillés dans docs/formats.md.

Utilisation comme bibliothèque

from schema_archi import Generator

g = Generator()
g.load_data("examples/copilote.yaml")
g.load_config("examples/config.yaml")  # facultatif
g.calculate_positions()

svg = g.graph()

Sans passer par des fichiers :

from schema_archi import Generator

g = Generator(
    apps={"m": "Magh2", "gdd": "GDD", "ref": "Ref"},
    flows=[
        ("gdd->m", "commande", "https://example.org/commande"),
        ("m->ref", "produits"),
    ],
    main="m",  # facultatif : "m" par défaut
)
g.calculate_positions()

svg = g.graph()

Les libellés et les URL sont échappés : un nom d'application contenant & ou < produit un SVG valide. Seuls les liens http, https, mailto et relatifs donnent lieu à une ancre cliquable ; les autres schémas d'URL sont rendus sans lien, avec un avertissement.

La bibliothèque est muette par défaut. Pour voir ses avertissements — flux écartés, applications orphelines — activez-la explicitement :

from loguru import logger

logger.enable("schema_archi")

API publique

Objet	Rôle
Generator	Construction du schéma et rendu SVG
GraphConfig	Paramètres de mise en page et couleurs
Application, Flow, Params, Position	Modèle de données
load_file	Lecture d'un YAML/JSON, sans transformation
parse_flow, parse_flows_def	Analyse des définitions de flux
split_endpoints	Sépare "a->b" en source, cible et sens

Le paquet est typé (PEP 561) : les annotations sont exploitables par mypy ou pyright sans stub supplémentaire.

Ligne de commande

Traitement par lot d'un répertoire :

schema-archi -i examples -o /tmp/out -c config.yaml --overwrite

Option	Effet
-i, --input-dir	Répertoire des définitions (.yaml, .yml, .json)
-o, --output-dir	Répertoire de destination (créé si absent)
-c, --config	Nom du fichier de configuration, situé dans le répertoire d'entrée. Il est exclu des fichiers traités.
--overwrite	Écraser les sorties existantes
--no-png	Ne produire que le SVG
--log-file	Consigner les erreurs dans un fichier (aucun par défaut)
-v, --verbose	Sortie détaillée

Le PNG n'est produit que si l'extra png est installé.

Le code de retour vaut 0 si toutes les définitions ont été traitées, 1 si au moins l'une d'elles a échoué — un fichier de sortie déjà présent et conservé faute d'--overwrite n'est pas un échec.

Éditeur web

schema-archi-ui          # http://localhost:8080

Deux panneaux YAML — configuration et définition — avec aperçu du SVG et téléchargement.

Configuration

Tous les paramètres de rendu sont regroupés sous la clé parameters :

parameters:
  APP_PARAM:            # gabarit d'un rectangle d'application
    height: 40
    width: 100
  HSPACE: 20            # marge ajoutée à la largeur du SVG
  VSPACE: 20            # marge ajoutée à la hauteur, et écart entre applications
  MARGIN_TOP: 20
  MARGIN_LEFT: 20
  FLOW_MARGIN: 15       # écart vertical entre deux flux d'une même application
  FLOW_WIDTH: 120       # longueur des flèches
  RECT_CORNER: 5
  LINK_LINE_ARROW: 5
  APP_COLORS: ['#0050ef', '#6c8ebf', '#dae8fc']   # texte, bordure, fond
  MAIN_COLORS: ['#000000', '#9673a6', '#e1d5e7']  # idem, application centrale
  FLOW_COLOR: '#004C99'                           # trait et pointe des flèches
  FLOW_TEXT_COLOR: '#000000'                      # libellé des flux

Les clés omises conservent leur valeur par défaut ; les clés inconnues sont ignorées avec un avertissement. examples/config.yaml reprend les valeurs par défaut, et docs/formats.md décrit l'effet de chaque paramètre.

Docker

Voir docker/README.md.

Développement

uv sync --all-extras --group dev
uv run pytest

Analyse statique

Ruff assure à la fois le lint et le formatage ; sa configuration est dans pyproject.toml.

uv run ruff check .            # analyse
uv run ruff check --fix .      # + corrections automatiques
uv run ruff format .           # formatage
uv run ruff format --check .   # vérification sans écriture

Le jeu de règles couvre les erreurs réelles (F), les pièges courants (B, SIM, RET), le nommage (N), les motifs à risque (S), l'ordre des imports (I), la modernisation de syntaxe (UP, cible 3.11), l'usage de pathlib (PTH), les conventions pytest (PT) et le code commenté oublié (ERA). Les dérogations sont documentées ligne par ligne dans [tool.ruff.lint.per-file-ignores].

Le typage est vérifié séparément, la configuration étant dans pyrightconfig.json :

uv run --with pyright pyright

Publication

./scripts/build-release.sh                 # construit et vérifie
./scripts/build-release.sh --test-pypi     # + publie sur TestPyPI
./scripts/build-release.sh --publish       # + publie sur PyPI

Sans drapeau, le script se contente de produire dist/ : rien n'est envoyé sur un index.

ruff check et ruff format --check passent avant toute construction et ne peuvent pas être contournés : le moindre signalement interrompt le script, et dist/ n'est pas produit. Les diagnostics sont affichés tels quels, sans avoir à relancer l'outil. Le script vérifie de surcroît que ruff a bien analysé les fichiers du paquet — une exclusion trop large dans pyproject.toml le ferait sinon passer à vide.

Il refuse également de construire si le dépôt n'est pas propre, si la version n'est pas documentée dans CHANGELOG.md, ou si pyright ou pytest échouent. Il contrôle ensuite les artefacts — métadonnées, rendu du README sur la fiche PyPI, présence de py.typed et de la licence, absence de tests et de fichiers compilés — puis installe le wheel dans un environnement isolé hors du dépôt et y lance la commande schema-archi sur les exemples.

La publication demande une confirmation ; celle vers PyPI est irréversible, une version ne pouvant y être ni remplacée ni republiée. Le jeton d'authentification se fournit par UV_PUBLISH_TOKEN.

--skip-checks saute pyright et pytest — jamais ruff. --allow-dirty autorise un dépôt non commité, pour une construction d'essai.

La marche à suivre complète — création des comptes et des jetons, choix du numéro de version, répétition sur TestPyPI, étiquetage, et que faire en cas de publication ratée — est dans docs/publication.md.

Licence

MIT — voir LICENSE.