appflows 1.0.0__py3-none-any.whl

appflows/config.py

@@ -0,0 +1,533 @@
+"""Configuration du rendu graphique.
+
+`GraphConfig` regroupe tous les paramètres de mise en page et de couleur du SVG
+produit par :class:`appflows.generator.Generator`, rangés par sujet : page,
+application, centre, flux, tag, bus, connecteur. Chaque sujet est une
+dataclass, et l'arborescence est **celle du fichier** de configuration :
+``cfg.flow.label.halo.width`` se lit ``flow: {label: {halo: {width: 3}}}``.
+
+La configuration est sérialisable via :meth:`GraphConfig.to_dict` /
+:meth:`GraphConfig.from_dict`. Les valeurs lues depuis un fichier sont
+contrôlées avant d'être retenues : une définition peut provenir d'une source
+non maîtrisée, et une couleur non validée finirait telle quelle dans le SVG.
+Le contrôle est porté par les champs eux-mêmes (``field(metadata=...)``), ce
+qui évite de tenir à part la liste des champs de chaque sorte.
+"""
+
+import re
+from dataclasses import dataclass, field, fields, is_dataclass
+from typing import Any, NamedTuple, TypeGuard, TypeVar, get_args, get_origin
+
+from loguru import logger
+
+from appflows.logtext import excerpt
+
+#: Code de l'application centrale par défaut.
+MAIN_APP_CODE = "m"
+
+#: Couleur admise : notation hexadécimale (``#RGB``, ``#RRGGBB``, ``#RRGGBBAA``)
+#: ou mot-clé CSS. Tout le reste est refusé : la valeur est interpolée dans le
+#: SVG, y compris dans un bloc ``<style>`` qui ne peut pas être échappé.
+COLOR_PATTERN = re.compile(r"#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|[a-zA-Z]+")
+
+
+#: Variations appliquées aux couleurs de l'application pour habiller son tag,
+#: faute de couleurs déclarées pour ce tag : bordure assombrie, fond éclairci.
+#: Le texte, lui, reprend celui de l'application sans retouche.
+TAG_BORDER_DARKEN = 0.30
+TAG_BACKGROUND_LIGHTEN = 0.45
+
+
+class Colors(NamedTuple):
+    """Habillage d'une boîte ou d'une pastille : texte, bordure, fond.
+
+    Un tuple nommé plutôt qu'une dataclass : le triplet se dépaquette
+    (``_, border, fill = colors``) et s'indexe comme le faisait le tuple
+    anonyme, tout en donnant un nom à chaque couleur.
+    """
+
+    text: str
+    stroke: str
+    fill: str
+
+
+# ----------------------------------------------------------------------
+# Contrôle des feuilles
+# ----------------------------------------------------------------------
+#
+# Chaque feuille porte sa règle dans ``metadata`` :
+#   - ``positive`` : entier ou réel strictement positif — une police ou une
+#     largeur plancher nulle ferait disparaître ce qu'elle mesure ;
+#   - ``signed`` : entier de signe libre — une retouche de centrage doit
+#     pouvoir remonter comme descendre ;
+#   - ``color`` : chaîne de couleur, contrôlée par ``COLOR_PATTERN``.
+# Sans metadata, un entier est positif ou nul : dimension ou blanc.
+
+
+def _positive(default: int | float) -> Any:
+    return field(default=default, metadata={"positive": True})
+
+
+def _signed(default: int) -> Any:
+    return field(default=default, metadata={"signed": True})
+
+
+def _color(default: str) -> Any:
+    return field(default=default, metadata={"color": True})
+
+
+# ----------------------------------------------------------------------
+# Sous-objets partagés
+# ----------------------------------------------------------------------
+
+
+@dataclass
+class Size:
+    """Gabarit d'un rectangle d'application.
+
+    ``width`` est une largeur **plancher** : une colonne dont les libellés
+    l'exigent s'élargit (voir ``layout.Layout._lane_width``). ``height`` est
+    celle d'un rectangle à un seul flux.
+    """
+
+    width: int = _positive(100)
+    height: int = _positive(48)
+
+
+@dataclass
+class Margin:
+    """Marges de la page, avant le premier rectangle."""
+
+    top: int = 28
+    left: int = 28
+
+
+@dataclass
+class Padding:
+    """Blanc laissé autour d'un texte dans sa boîte."""
+
+    x: int = 12
+    y: int = 8
+
+
+@dataclass
+class Halo:
+    """Trait tracé derrière un texte pour qu'il reste lisible sur un fond chargé."""
+
+    #: ``0`` désactive le halo.
+    width: int = 3
+    #: La couleur du fond sur lequel le schéma est posé.
+    color: str = _color("#ffffff")
+
+
+@dataclass
+class Line:
+    """Un trait : épaisseur et couleur."""
+
+    width: int = 2
+    color: str = _color("#9e9e9e")
+
+
+@dataclass
+class Port:
+    """Port écrit à côté de la pastille d'un connecteur, à l'intérieur de la boîte."""
+
+    font_size: int = _positive(10)
+    gap: int = 4
+
+
+@dataclass
+class FlowLabel:
+    """Libellé dessiné au-dessus d'une flèche de flux."""
+
+    font_size: int = _positive(12)
+    #: Couleur du libellé, distincte de celle du trait.
+    color: str = _color("#000000")
+    #: Hauteur du libellé au-dessus de son trait.
+    offset_y: int = 8
+    #: Halo tracé derrière le libellé, pour qu'il reste lisible là où il
+    #: croise un trait.
+    halo: Halo = field(default_factory=Halo)
+
+
+# ----------------------------------------------------------------------
+# Sections
+# ----------------------------------------------------------------------
+
+
+@dataclass
+class PageConfig:
+    """La page : marges et espacement entre colonnes et lignes."""
+
+    margin: Margin = field(default_factory=Margin)
+    #: Blanc horizontal entre deux colonnes.
+    hspace: int = 28
+    #: Blanc vertical entre deux boîtes d'une même colonne.
+    vspace: int = 28
+
+
+@dataclass
+class AppConfig:
+    """Les rectangles d'application, centre compris sauf mention contraire."""
+
+    size: Size = field(default_factory=Size)
+    corner: int = 8
+    #: Épaisseur de la bordure des rectangles.
+    stroke_width: int = 2
+    #: ``x`` : blanc de chaque côté du libellé. ``y`` : blanc au-dessus du
+    #: libellé et sous le dernier flux, quand une boîte porte des connecteurs
+    #: et range donc son nom au-dessus d'eux.
+    padding: Padding = field(default_factory=lambda: Padding(x=12, y=8))
+    font_size: int = _positive(14)
+    #: Retouche fine du centrage vertical d'un libellé. Nulle par défaut :
+    #: `dominant-baseline` centre déjà ; à n'ajuster que si une police
+    #: substituée tombe mal.
+    text_vertical_offset: int = _signed(0)
+    colors: Colors = field(default_factory=lambda: Colors("#0050ef", "#6c8ebf", "#dae8fc"))
+
+
+@dataclass
+class MainConfig:
+    """Ce qui distingue l'application centrale des satellites."""
+
+    font_size: int = _positive(16)
+    #: Largeur de l'application centrale, en multiple de celle des satellites.
+    #: Son propre libellé reste un plancher : elle ne rétrécit jamais dessous.
+    width_ratio: float = _positive(1.2)
+    colors: Colors = field(default_factory=lambda: Colors("#000000", "#9673a6", "#e1d5e7"))
+
+
+@dataclass
+class FlowConfig:
+    """Les flèches de flux et leur libellé."""
+
+    #: Largeur de la bande réservée aux flèches entre deux colonnes.
+    width: int = _positive(160)
+    #: Blanc entre le bord d'une boîte et le premier flux.
+    margin: int = 18
+    #: Blanc entre la pointe d'une flèche et ce qu'elle désigne — bord de
+    #: rectangle, de boîte de bus ou de pastille de connecteur. Nul par
+    #: défaut : la pointe touche sa cible, ce qui donne à lire le raccordement.
+    gap: int = 0
+    #: Épaisseur du trait d'une flèche.
+    stroke_width: int = 2
+    #: Longueur de la pointe de flèche.
+    arrow: int = 12
+    color: str = _color("#004C99")
+    label: FlowLabel = field(default_factory=FlowLabel)
+
+
+@dataclass
+class TagConfig:
+    """La pastille de tag, sous le nom d'une application."""
+
+    font_size: int = _positive(11)
+    padding: Padding = field(default_factory=lambda: Padding(x=8, y=3))
+    corner: int = 6
+    stroke_width: int = 1
+    #: Écart entre le libellé de l'application et la pastille de son tag.
+    gap: int = 6
+    #: Habillage par nom de tag. Un tag absent de la table reprend les
+    #: couleurs de son application, nuancées par :func:`derive_tag_colors`.
+    colors: dict[str, Colors] = field(default_factory=dict)
+
+
+@dataclass
+class BusConfig:
+    """La boîte d'un bus : angles vifs par défaut, bordure gris moyen et fond
+    gris clair, pour qu'elle se lise comme une infrastructure et non comme une
+    application."""
+
+    corner: int = 0
+    stroke_width: int = 2
+    font_size: int = _positive(13)
+    #: ``y`` : blanc au-dessus et au-dessous des tronçons, dans la boîte. Le
+    #: blanc du haut porte aussi le nom du bus.
+    padding: Padding = field(default_factory=lambda: Padding(x=12, y=8))
+    colors: Colors = field(default_factory=lambda: Colors("#333333", "#9e9e9e", "#f0f0f0"))
+    #: Trait qui matérialise, dans la boîte, la traversée d'un flux.
+    line: Line = field(default_factory=Line)
+
+
+@dataclass
+class ConnectorConfig:
+    """La pastille d'un connecteur, posée à cheval sur le bord de sa boîte."""
+
+    height: int = _positive(18)
+    #: Largeur plancher, et largeur exacte d'un connecteur neutre.
+    min_width: int = _positive(14)
+    corner: int = 3
+    padding_x: int = 6
+    font_size: int = _positive(10)
+    stroke_width: int = 1
+    #: Blanc entre le libellé d'une boîte et le premier connecteur, sous lui.
+    label_gap: int = 40
+    #: Habillage par protocole. Un protocole absent de la table reprend les
+    #: couleurs de sa boîte, nuancées par :func:`derive_connector_colors`.
+    colors: dict[str, Colors] = field(default_factory=dict)
+    port: Port = field(default_factory=Port)
+
+
+@dataclass
+class GraphConfig:
+    """Paramètres de mise en page du graphe, section par section."""
+
+    page: PageConfig = field(default_factory=PageConfig)
+    app: AppConfig = field(default_factory=AppConfig)
+    main: MainConfig = field(default_factory=MainConfig)
+    flow: FlowConfig = field(default_factory=FlowConfig)
+    tag: TagConfig = field(default_factory=TagConfig)
+    bus: BusConfig = field(default_factory=BusConfig)
+    connector: ConnectorConfig = field(default_factory=ConnectorConfig)
+
+    def to_dict(self) -> dict:
+        """Retourne la configuration sous forme de dictionnaire sérialisable.
+
+        L'arborescence est celle du fichier de configuration ; un ``Colors``
+        y devient ``{text, stroke, fill}``.
+        """
+        return _dump(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "GraphConfig":
+        """Construit une configuration depuis un dictionnaire arborescent.
+
+        Les clés inconnues et les valeurs invalides sont signalées puis
+        écartées, plutôt que de lever : un fichier écrit pour une autre version
+        reste exploitable, et un lot de génération n'est jamais interrompu par
+        un paramètre fautif.
+        """
+        config = _load(cls, data, "")
+        config.check_consistency()
+        return config
+
+    def check_consistency(self) -> None:
+        """Signale les réglages qui, valides un à un, se contredisent ensemble.
+
+        Deux flux d'une même boîte sont espacés de ``2 * flow.margin`` ; les
+        pastilles de connecteur, hautes de ``connector.height``, sont centrées
+        sur eux. En dessous, elles se chevauchent — et les ports avec elles.
+        C'est le seul réglage qui mène à une collision de textes ; il se
+        décide à la lecture du fichier, sans attendre le rendu.
+        """
+        spacing = 2 * self.flow.margin
+        if spacing < self.connector.height:
+            logger.warning(
+                f"flow.margin = {self.flow.margin} : deux flux ne sont espacés que de "
+                f"{spacing} px, moins que la hauteur d'une pastille de connecteur "
+                f"(connector.height = {self.connector.height}) — sur un schéma "
+                "appli+tech, les pastilles et les ports se chevaucheront"
+            )
+
+
+# ----------------------------------------------------------------------
+# Sérialisation
+# ----------------------------------------------------------------------
+
+
+def _dump(value: object) -> Any:
+    """Sérialise récursivement, en gardant l'ordre de déclaration des champs."""
+    if isinstance(value, Colors):
+        return {"text": value.text, "stroke": value.stroke, "fill": value.fill}
+    if is_dataclass(value) and not isinstance(value, type):
+        return {f.name: _dump(getattr(value, f.name)) for f in fields(value)}
+    if isinstance(value, dict):
+        return {key: _dump(item) for key, item in value.items()}
+    return value
+
+
+T = TypeVar("T")
+
+
+def _load(cls: type[T], data: object, path: str) -> T:
+    """Construit une dataclass depuis un dictionnaire, champ par champ.
+
+    Chaque défaut est signalé avec le chemin pointé de la valeur en cause
+    (``flow.label.halo.width``), et la valeur par défaut est conservée.
+    """
+    default = cls()
+    if not isinstance(data, dict):
+        logger.warning(f"{path or 'configuration'} : dictionnaire attendu, reçu {excerpt(data)}")
+        return default
+
+    where = f"{path}." if path else ""
+    known = {f.name for f in fields(default)}  # type: ignore[arg-type]
+    unknown = sorted(set(data) - known)
+    if unknown:
+        logger.warning(
+            f"Paramètres de configuration inconnus, ignorés : "
+            f"{', '.join(where + str(key) for key in unknown)}"
+        )
+
+    values = {}
+    for f in fields(default):  # type: ignore[arg-type]
+        if f.name not in data:
+            continue
+        values[f.name] = _load_field(
+            f.type, getattr(default, f.name), f.metadata, data[f.name], f"{where}{f.name}"
+        )
+    return cls(**values)  # type: ignore[arg-type]
+
+
+def _load_field(kind: object, default: Any, metadata: Any, value: object, path: str) -> Any:
+    """Contrôle une valeur selon le type déclaré du champ, ou garde le défaut."""
+    if kind is Colors:
+        return _load_colors(default, value, path)
+    if get_origin(kind) is dict and get_args(kind)[1] is Colors:
+        return _load_color_table(value, path)
+    if isinstance(kind, type) and is_dataclass(kind):
+        return _load(kind, value, path)
+    if kind is float:
+        if not _is_number(value) or value <= 0:
+            logger.warning(f"{path} : nombre strictement positif attendu, reçu {excerpt(value)}")
+            return default
+        return value
+    if kind is int:
+        return _load_int(default, metadata, value, path)
+    if metadata.get("color"):
+        if not _is_color(value):
+            logger.warning(f"{path} : couleur invalide ({excerpt(value)})")
+            return default
+        return value
+    return value
+
+
+def _load_int(default: int, metadata: Any, value: object, path: str) -> int:
+    """Contrôle un entier : son type, puis son intervalle.
+
+    Contrôler le seul type laissait passer un blanc négatif ou une police
+    nulle, retenus en silence pour produire un schéma illisible.
+    """
+    if not _is_int(value):
+        logger.warning(f"{path} : entier attendu, reçu {excerpt(value)}")
+        return default
+    if metadata.get("signed"):
+        return value
+    if metadata.get("positive") and value <= 0:
+        logger.warning(f"{path} : entier strictement positif attendu, reçu {value}")
+        return default
+    if value < 0:
+        logger.warning(f"{path} : entier positif ou nul attendu, reçu {value}")
+        return default
+    return value
+
+
+def _load_colors(default: Colors, value: object, path: str) -> Colors:
+    """Un triplet ``{text, stroke, fill}``, complété depuis le défaut s'il est partiel."""
+    if not isinstance(value, dict):
+        logger.warning(f"{path} : {{text, stroke, fill}} attendu, reçu {excerpt(value)}")
+        return default
+
+    unknown = sorted(set(value) - set(Colors._fields))
+    if unknown:
+        logger.warning(f"{path} : couleur(s) inconnue(s), ignorée(s) : {unknown}")
+
+    retained = {}
+    for name in Colors._fields:
+        if name not in value:
+            continue
+        if not _is_color(value[name]):
+            logger.warning(f"{path}.{name} : couleur invalide ({excerpt(value[name])})")
+            continue
+        retained[name] = value[name]
+    return default._replace(**retained)
+
+
+def _load_color_table(value: object, path: str) -> dict[str, Colors]:
+    """Contrôle une table d'habillage nommée, entrée par entrée.
+
+    Sert aussi bien aux tags qu'aux connecteurs : une entrée fautive ou
+    incomplète est écartée sans emporter les autres, et le tag ou le protocole
+    concerné retombe sur les couleurs de sa boîte.
+    """
+    if not isinstance(value, dict):
+        logger.warning(f"{path} : dictionnaire attendu, reçu {excerpt(value)}")
+        return {}
+
+    retained = {}
+    for name, entry in value.items():
+        where = f"{path}.{name}"
+        if not isinstance(entry, dict) or set(entry) != set(Colors._fields):
+            logger.warning(
+                f"{where} : {{text, stroke, fill}} complet attendu, reçu {excerpt(entry)}"
+            )
+            continue
+        invalid = [c for c in entry.values() if not _is_color(c)]
+        if invalid:
+            logger.warning(f"{where} : couleur(s) invalide(s) {excerpt(invalid)}")
+            continue
+        retained[str(name)] = Colors(entry["text"], entry["stroke"], entry["fill"])
+    return retained
+
+
+def _is_number(value: object) -> TypeGuard[int | float]:
+    return isinstance(value, int | float) and not isinstance(value, bool)
+
+
+def _is_int(value: object) -> TypeGuard[int]:
+    """Un booléen est un ``int`` pour Python, mais jamais une dimension ici."""
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _is_color(value: object) -> bool:
+    return isinstance(value, str) and COLOR_PATTERN.fullmatch(value) is not None
+
+
+# ----------------------------------------------------------------------
+# Couleurs dérivées
+# ----------------------------------------------------------------------
+
+
+def _shade(color: str, factor: float) -> str:
+    """Éclaircit (`factor > 0`) ou assombrit (`factor < 0`) une couleur.
+
+    Une couleur nommée (`red`) est rendue telle quelle : sans composantes, il
+    n'y a rien à faire varier.
+    """
+    if not color.startswith("#"):
+        return color
+
+    digits = color[1:]
+    if len(digits) in (3, 4):  # notation courte : #rgb, #rgba
+        digits = "".join(c * 2 for c in digits)
+    if len(digits) not in (6, 8):
+        return color
+
+    canaux = [int(digits[i : i + 2], 16) for i in range(0, 6, 2)]
+    cible = 255 if factor > 0 else 0
+    varies = [round(c + (cible - c) * abs(factor)) for c in canaux]
+
+    return "#" + "".join(f"{c:02x}" for c in varies) + digits[6:]
+
+
+def derive_tag_colors(app_colors: Colors) -> Colors:
+    """Habillage d'un tag déduit des couleurs de son application.
+
+    Args:
+        app_colors: les couleurs de l'application.
+
+    Returns:
+        Celles du tag : même texte, bordure assombrie, fond éclairci.
+    """
+    return Colors(
+        app_colors.text,
+        _shade(app_colors.stroke, -TAG_BORDER_DARKEN),
+        _shade(app_colors.fill, TAG_BACKGROUND_LIGHTEN),
+    )
+
+
+def derive_connector_colors(host_colors: Colors) -> Colors:
+    """Habillage d'un connecteur déduit des couleurs de la boîte qui le porte.
+
+    Un protocole absent de ``connector.colors`` reste ainsi lisible sans rien
+    déclarer : pastille pleine dans le ton de la bordure de sa boîte, texte et
+    bord blancs — c'est ce liseré blanc qui la détache de la boîte et donne à
+    lire la notion de connecteur.
+
+    Args:
+        host_colors: les couleurs de la boîte hôte.
+
+    Returns:
+        Celles du connecteur.
+    """
+    return Colors("#ffffff", "#ffffff", host_colors.stroke)