Metadata-Version: 2.4
Name: schema-archi
Version: 0.7.3
Summary: Génération de schémas d'architecture SVG (flux applicatifs) depuis des définitions YAML/JSON
Project-URL: Homepage, https://framagit.org/opikanoba/schema-archi
Project-URL: Repository, https://framagit.org/opikanoba/schema-archi.git
Project-URL: Issues, https://framagit.org/opikanoba/schema-archi/-/issues
Project-URL: Changelog, https://framagit.org/opikanoba/schema-archi/-/blob/main/CHANGELOG.md
Author-email: Frédéric Laurent <flt@opikanoba.org>
License-Expression: MIT
License-File: LICENSE
Keywords: architecture,diagram,schema,svg,yaml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: loguru>=0.7.2
Requires-Dist: pyyaml>=6.0.2
Provides-Extra: png
Requires-Dist: cairosvg>=2.7.1; extra == 'png'
Provides-Extra: ui
Requires-Dist: nicegui>=2.14; extra == 'ui'
Description-Content-Type: text/markdown

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

![Exemple de schéma](https://framagit.org/opikanoba/schema-archi/-/raw/main/docs/images/magh2.png)

## Documentation

- [Formats d'entrée](https://framagit.org/opikanoba/schema-archi/-/blob/main/docs/formats.md)
  — référence complète des fichiers de définition et de configuration, grammaire
  des flux, messages de diagnostic.
- [Fonctionnement et algorithme](https://framagit.org/opikanoba/schema-archi/-/blob/main/docs/algorithme.md)
  — les cinq étapes de la génération, les formules de placement, un exemple
  chiffré et les limites connues.
- [Publier sur PyPI](https://framagit.org/opikanoba/schema-archi/-/blob/main/docs/publication.md)
  — comptes, jetons, numérotation, répétition sur TestPyPI et marche à suivre.

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

## Installation

```bash
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

```yaml
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](https://framagit.org/opikanoba/schema-archi/-/blob/main/docs/formats.md).

## Utilisation comme bibliothèque

```python
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 :

```python
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 :

```python
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 :

```bash
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

```bash
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` :

```yaml
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](https://framagit.org/opikanoba/schema-archi/-/blob/main/docs/formats.md#4-le-fichier-de-configuration)
décrit l'effet de chaque paramètre.

## Docker

Voir [docker/README.md](https://framagit.org/opikanoba/schema-archi/-/blob/main/docker/README.md).

## Développement

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

```bash
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` :

```bash
uv run --with pyright pyright
```

### Publication

```bash
./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](https://framagit.org/opikanoba/schema-archi/-/blob/main/docs/publication.md).

## Licence

MIT — voir [LICENSE](LICENSE).
