appflows 1.0.0__py3-none-any.whl

appflows/__init__.py

@@ -0,0 +1,94 @@
+"""Génération de schémas d'architecture SVG à partir de définitions YAML/JSON.
+
+Exemple minimal :
+
+    >>> from appflows import Generator
+    >>> g = Generator()
+    >>> g.load_data("examples/yaml/bus.yaml")
+    True
+    >>> g.calculate_positions()
+    >>> svg = g.graph()
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from loguru import logger
+
+from appflows.config import (
+    MAIN_APP_CODE,
+    AppConfig,
+    BusConfig,
+    Colors,
+    ConnectorConfig,
+    FlowConfig,
+    GraphConfig,
+    MainConfig,
+    PageConfig,
+    Size,
+    TagConfig,
+)
+from appflows.formats import (
+    BACKWARD_FLOW,
+    FORWARD_FLOW,
+    load_file,
+    parse_chain,
+    parse_flow,
+    parse_flows_def,
+    split_endpoints,
+)
+from appflows.generator import Generator
+from appflows.models import (
+    Application,
+    Bus,
+    Chain,
+    Connector,
+    DiagramType,
+    Flow,
+    LayoutMode,
+    Link,
+    Position,
+    Segment,
+)
+
+try:
+    __version__ = version("appflows")
+except PackageNotFoundError:  # paquet non installé (exécution depuis les sources)
+    __version__ = "0.0.0.dev0"
+
+# Convention loguru pour une bibliothèque : ne rien écrire sur la sortie d'erreur
+# de l'application appelante tant qu'elle ne l'a pas demandé. La CLI et l'UI
+# rappellent `logger.enable("appflows")` ; un intégrateur fait de même.
+logger.disable(__name__)
+
+__all__ = [
+    "BACKWARD_FLOW",
+    "FORWARD_FLOW",
+    "MAIN_APP_CODE",
+    "AppConfig",
+    "Application",
+    "Bus",
+    "BusConfig",
+    "Chain",
+    "Colors",
+    "Connector",
+    "ConnectorConfig",
+    "DiagramType",
+    "Flow",
+    "FlowConfig",
+    "Generator",
+    "GraphConfig",
+    "LayoutMode",
+    "Link",
+    "MainConfig",
+    "PageConfig",
+    "Position",
+    "Segment",
+    "Size",
+    "TagConfig",
+    "__version__",
+    "load_file",
+    "parse_chain",
+    "parse_flow",
+    "parse_flows_def",
+    "split_endpoints",
+]

appflows/cli.py

@@ -0,0 +1,237 @@
+"""Interface en ligne de commande : traitement par lot d'un répertoire.
+
+Chaque fichier de définition trouvé dans le répertoire d'entrée est converti en
+SVG, et en PNG si l'extra ``png`` est installé.
+"""
+
+import argparse
+import sys
+from collections.abc import Sequence
+from enum import Enum
+from pathlib import Path
+
+from loguru import logger
+
+from appflows.formats import SUPPORTED_SUFFIXES
+from appflows.generator import Generator
+
+LOG_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+    "<level>{level: <8}</level> | <level>{message}</level>"
+)
+
+
+class DiagramStatus(Enum):
+    """Issue du traitement d'une définition.
+
+    Distinguer « ignoré » de « en échec » est ce qui permet au code de retour de
+    la commande d'être exploitable en intégration continue : un fichier déjà
+    présent n'est pas une erreur, une définition illisible en est une.
+    """
+
+    PRODUCED = "produit"
+    SKIPPED = "ignoré"
+    FAILED = "en échec"
+
+
+def setup_logging(verbose: bool = False, log_file: Path | None = None) -> None:
+    """Configure loguru pour la CLI.
+
+    Args:
+        verbose: active le niveau DEBUG sur la sortie d'erreur.
+        log_file: si fourni, les erreurs sont également écrites dans ce fichier.
+            Sans lui, rien n'est écrit sur disque.
+    """
+    logger.enable("appflows")  # la bibliothèque est muette par défaut
+    logger.remove()
+    logger.add(sys.stderr, format=LOG_FORMAT, level="DEBUG" if verbose else "INFO")
+
+    if log_file is not None:
+        logger.add(
+            log_file,
+            format=LOG_FORMAT,
+            level="ERROR",
+            rotation="1 week",
+            retention="1 month",
+        )
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Analyse et valide les arguments de la ligne de commande."""
+    parser = argparse.ArgumentParser(
+        prog="appflows",
+        description=(
+            "Convertit par lot des définitions de flux applicatifs en schémas SVG (et PNG)."
+        ),
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    parser.add_argument(
+        "-i",
+        "--input-dir",
+        type=Path,
+        required=True,
+        help=f"Répertoire contenant les définitions ({', '.join(SUPPORTED_SUFFIXES)})",
+    )
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        type=Path,
+        required=True,
+        help="Répertoire de destination des fichiers générés",
+    )
+    parser.add_argument(
+        "-c",
+        "--config",
+        type=str,
+        help="Nom du fichier de configuration situé dans le répertoire d'entrée",
+    )
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Écraser les fichiers de sortie existants",
+    )
+    parser.add_argument(
+        "--no-png",
+        action="store_true",
+        help="Ne produire que le SVG, sans conversion PNG",
+    )
+    parser.add_argument(
+        "--log-file",
+        type=Path,
+        help="Fichier où consigner les erreurs (aucun par défaut)",
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="Sortie détaillée")
+
+    args = parser.parse_args(argv)
+
+    if not args.input_dir.is_dir():
+        parser.error(f"Le répertoire d'entrée n'existe pas : {args.input_dir}")
+
+    if args.config:
+        config_path = args.input_dir / args.config
+        if not config_path.is_file():
+            parser.error(f"Le fichier de configuration n'existe pas : {config_path}")
+
+    return args
+
+
+def collect_input_files(input_dir: Path, config_file: Path | None = None) -> list[Path]:
+    """Liste les définitions à traiter, en excluant le fichier de configuration."""
+    excluded = config_file.resolve() if config_file else None
+    return sorted(
+        f
+        for suffix in SUPPORTED_SUFFIXES
+        for f in input_dir.glob(f"*{suffix}")
+        if excluded is None or f.resolve() != excluded
+    )
+
+
+def _write_png(svg_content: str, output_file: Path) -> bool:
+    """Convertit le SVG en PNG. Retourne ``False`` si cairosvg est absent."""
+    try:
+        import cairosvg
+    except ImportError:
+        logger.warning(
+            "PNG non généré : cairosvg n'est pas installé. "
+            "Installez l'extra correspondant avec « pip install appflows[png] » "
+            "ou passez --no-png pour masquer cet avertissement."
+        )
+        return False
+
+    cairosvg.svg2png(bytestring=svg_content.encode("utf-8"), write_to=str(output_file))
+    return True
+
+
+def process_diagram(
+    input_file: Path,
+    output_dir: Path,
+    config_file: Path | None = None,
+    overwrite: bool = False,
+    png: bool = True,
+) -> DiagramStatus:
+    """Traite une définition et écrit le SVG (et le PNG) correspondant.
+
+    Returns:
+        L'issue du traitement : produit, ignoré ou en échec.
+    """
+    output_svg_file = output_dir / input_file.with_suffix(".svg").name
+    output_png_file = output_dir / input_file.with_suffix(".png").name
+
+    if output_svg_file.exists() and not overwrite:
+        logger.debug(f"{input_file.name} ignoré (le SVG existe déjà)")
+        return DiagramStatus.SKIPPED
+
+    logger.debug(f"Traitement de {input_file.name}")
+
+    generator = Generator()
+    if not generator.load_data(input_file):
+        logger.warning(f"{input_file.name} écarté : définition illisible")
+        return DiagramStatus.FAILED
+
+    if config_file:
+        generator.load_config(config_file)
+
+    try:
+        generator.calculate_positions()
+        svg_content = generator.graph()
+        output_svg_file.write_text(svg_content, encoding="utf-8")
+    except Exception as e:
+        # Un fichier fautif ne doit pas interrompre le lot en cours.
+        logger.error(f"{input_file.name} écarté : {e}")
+        return DiagramStatus.FAILED
+
+    produced = output_svg_file.name
+    if png and _write_png(svg_content, output_png_file):
+        produced += f" et {output_png_file.name}"
+
+    logger.info(f"{input_file.name} → {produced}")
+    return DiagramStatus.PRODUCED
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parse_args(argv)
+    setup_logging(args.verbose, args.log_file)
+
+    config_file = args.input_dir / args.config if args.config else None
+
+    logger.debug(f"Répertoire d'entrée : {args.input_dir}")
+    logger.debug(f"Répertoire de sortie : {args.output_dir}")
+
+    input_files = collect_input_files(args.input_dir, config_file)
+    if not input_files:
+        logger.error(
+            f"Aucune définition ({', '.join(SUPPORTED_SUFFIXES)}) trouvée dans {args.input_dir}"
+        )
+        return 1
+
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+    logger.info(f"{len(input_files)} fichier(s) à traiter")
+
+    statuses = [
+        process_diagram(
+            input_file,
+            args.output_dir,
+            config_file=config_file,
+            overwrite=args.overwrite,
+            png=not args.no_png,
+        )
+        for input_file in input_files
+    ]
+
+    produced = statuses.count(DiagramStatus.PRODUCED)
+    skipped = statuses.count(DiagramStatus.SKIPPED)
+    failed = statuses.count(DiagramStatus.FAILED)
+
+    bilan = f"Terminé : {produced}/{len(input_files)} fichier(s) produit(s)"
+    if skipped:
+        bilan += f", {skipped} ignoré(s) (déjà présent(s))"
+    if failed:
+        bilan += f", {failed} en échec"
+    logger.info(bilan)
+
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())