arctyp 0.1.2__py3-none-any.whl

arctyp/__init__.py

@@ -0,0 +1,22 @@
+"""arctyp — orchestration CLI for Typst composition at HE-Arc.
+
+Renders UML diagrams via the internal PlantUML server and compiles the PDF
+locally.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+
+APP_NAME = "arctyp"
+
+try:
+    # Single source of truth: [project].version in pyproject.toml, read from
+    # the installed package's metadata (never duplicated in code).
+    __version__: str = _package_version(APP_NAME)
+except PackageNotFoundError:  # running from an uninstalled source tree
+    __version__ = "0.0.0+unknown"
+
+
+def user_agent() -> str:
+    """Shared User-Agent for the CLI's HTTP requests (name + version, single source)."""
+    return f"{APP_NAME}/{__version__} (HE-Arc)"

arctyp/__main__.py

@@ -0,0 +1,8 @@
+"""Support for `python -m arctyp`."""
+
+import sys
+
+from arctyp.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

arctyp/cli.py

@@ -0,0 +1,40 @@
+"""Entry point of the `arctyp` CLI: parsing, dispatch, and exit codes.
+
+Command structure is declared in `arctyp.commands` (decorators), and the
+argparse tree is built by `arctyp.parser`. This module only does the core
+work: call the handler, map errors to exit codes, and never let a traceback
+reach the user.
+"""
+
+from __future__ import annotations
+
+import signal
+import sys
+
+from arctyp.errors import ArctypError
+from arctyp.output import FAIL
+from arctyp.parser import build_parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Closed pipe (e.g. `arctyp doctor | head`): classic Unix behavior —
+    # die silently instead of letting a BrokenPipeError pollute the output.
+    if hasattr(signal, "SIGPIPE"):
+        signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except ArctypError as exc:
+        print(f"{FAIL} {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print(f"\n{FAIL} interrompu.", file=sys.stderr)
+        return 130
+    except Exception as exc:  # safety net: never output a traceback
+        print(f"{FAIL} erreur inattendue — {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

arctyp/commands/__init__.py

@@ -0,0 +1,35 @@
+"""Subcommands of the arctyp CLI.
+
+Automatically discovers and imports every module in this package: each one
+declares its commands with the decorators from `arctyp.decorators`. The
+``COMMANDS`` registry, filled by these imports, is re-exported here and
+consumed by `arctyp.parser.build_parser`. Display order in the help follows
+the alphabetical order of the modules.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+
+from arctyp.decorators import COMMANDS
+
+
+def _load_command_modules() -> None:
+    """Imports each command module in the package (alphabetical order).
+
+    The import is the trigger: it runs the decorators and fills the
+    ``COMMANDS`` registry. Modules prefixed with ``_`` are reserved for
+    internal helpers and declare no commands.
+    """
+    modules = sorted(
+        info.name for info in pkgutil.iter_modules(__path__)
+        if not info.name.startswith("_")
+    )
+    for module in modules:
+        importlib.import_module(f"{__name__}.{module}")
+
+
+_load_command_modules()
+
+__all__ = ["COMMANDS"]

arctyp/commands/_shared.py

@@ -0,0 +1,24 @@
+"""Argument declarations shared by several commands.
+
+Single source of the options and positionals declared identically by more
+than one command (DRY). Underscore-prefixed module: skipped by the commands'
+auto-discovery, which only registers decorated handlers.
+"""
+
+from __future__ import annotations
+
+from arctyp.decorators import argument
+
+# One decorator instance reused on several handlers is safe: `argument()`
+# appends to each decorated function's own attribute, with no shared state.
+PUBLIC_OPTION = argument(
+    "--public",
+    action="store_true",
+    help="utilise le serveur PlantUML public au lieu du serveur de l'école",
+)
+
+PDF_ARGUMENT = argument(
+    "pdf",
+    metavar="rapport.pdf",
+    help="nom complet du PDF de sortie (obligatoire)",
+)

arctyp/commands/compile.py

@@ -0,0 +1,29 @@
+"""`arctyp compile <rapport.pdf>`: renders the diagrams, then compiles the Typst entry.
+
+Thin handler: the compilation pipeline lives in `arctyp.pipeline`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from arctyp.commands._shared import PDF_ARGUMENT, PUBLIC_OPTION
+from arctyp.decorators import command
+from arctyp.output import ok
+from arctyp.pipeline import compile_typst, render_diagrams
+from arctyp.project import project_root
+
+
+@command(
+    name="compile",
+    help="rend les diagrammes du projet puis compile l'entrée Typst en PDF",
+    description="Le nom complet du PDF de sortie est un argument obligatoire.",
+)
+@PDF_ARGUMENT
+@PUBLIC_OPTION
+def cmd_compile(args) -> int:
+    project = project_root()
+    render_diagrams(project, public=args.public)
+    compile_typst(project, Path(args.pdf))
+    ok(f"PDF généré : {args.pdf}")
+    return 0

arctyp/commands/doctor.py

@@ -0,0 +1,107 @@
+"""`arctyp doctor`: diagnoses the project and the toolchain's reachability.
+
+Checks, in pipeline order: the project, the PlantUML server, UML diagram
+rendering, the Typst compiler (Python package), then the Git binary (needed
+by `arctyp init`). Each line is prefixed [OK] or [FAIL] and printed as soon
+as its check finishes; the exit code is 0 when everything is OK, 1 as soon
+as a check fails.
+"""
+
+from __future__ import annotations
+
+import importlib
+import shutil
+from functools import partial
+
+from arctyp.commands._shared import PUBLIC_OPTION
+from arctyp.decorators import command
+from arctyp.errors import ArctypError
+from arctyp.output import fail, ok
+from arctyp.plantuml import render_project_diagrams, render_svg
+from arctyp.project import ENTRY_FILE, find_config, project_root
+
+# Each check returns (ok, label, detail).
+Check = tuple[bool, str, str]
+
+
+@command(
+    name="doctor",
+    help="diagnostique configuration, typst et accessibilité des serveurs",
+    description=(
+        "Vérifie le projet, le serveur PlantUML, rend les diagrammes UML, puis "
+        "contrôle le compilateur Typst et la présence de Git."
+    ),
+)
+@PUBLIC_OPTION
+def cmd_doctor(args) -> int:
+    all_ok = True
+    for check in (
+        _check_project,
+        partial(_check_plantuml, public=args.public),
+        partial(_check_diagrams, public=args.public),
+        _check_typst,
+        _check_git,
+    ):
+        check_ok, label, detail = check()
+        (ok if check_ok else fail)(f"{label} : {detail}")
+        all_ok = all_ok and check_ok
+
+    # Error recovery (Nielsen H9): clear exit action on failure.
+    if not all_ok:
+        fail("Des contrôles ont échoué — corrigez puis relancez `arctyp doctor`.")
+    return 0 if all_ok else 1
+
+
+def _check_project() -> Check:
+    root = project_root()
+    config = find_config(root)
+    entry = root / ENTRY_FILE
+    ok = entry.is_file()
+    detail = (
+        f"config {config or 'absente (défauts utilisés)'} ; "
+        f"entrée {ENTRY_FILE} {'présente' if ok else 'ABSENTE'}"
+    )
+    return ok, "Projet", detail
+
+
+def _check_plantuml(public: bool = False) -> Check:
+    try:
+        render_svg("@startuml\n@enduml", public=public)
+    except ArctypError as exc:
+        return False, "Serveur PlantUML", str(exc)
+    return True, "Serveur PlantUML", "joignable"
+
+
+def _check_diagrams(public: bool = False) -> Check:
+    """Renders each .puml in the project (first step of the compile pipeline)."""
+    outcomes = render_project_diagrams(project_root(), public=public)
+    if not outcomes:
+        return True, "Diagrammes UML", "aucun fichier .puml (rien à rendre)"
+    failures = [outcome for outcome in outcomes if outcome.error]
+    if failures:
+        first = failures[0]
+        return (
+            False,
+            "Diagrammes UML",
+            f"{len(failures)}/{len(outcomes)} échec(s) — {first.puml}: {first.error}",
+        )
+    return True, "Diagrammes UML", f"{len(outcomes)} diagramme(s) rendu(s)"
+
+
+def _check_typst() -> Check:
+    try:
+        module = importlib.import_module("typst")
+    except ImportError as exc:
+        return False, "Compilateur Typst", f"paquet manquant ({exc}) — lancez uv sync"
+    return True, "Compilateur Typst", f"paquet importable (v{getattr(module, '__version__', '?')})"
+
+
+def _check_git() -> Check:
+    """Git is required by `arctyp init` (repository and templates managed with Git)."""
+    if shutil.which("git") is None:
+        return (
+            False,
+            "Git",
+            "binaire introuvable — installez Git (nécessaire pour `arctyp init`)",
+        )
+    return True, "Git", "binaire présent"

arctyp/commands/init.py

@@ -0,0 +1,211 @@
+"""`arctyp init [directory]`: creates a complete base project.
+
+Creates a ready-to-use Typst project: conf.typ, template.typ, uml.typ,
+main.typ, diagrams/ and images/ folders, and an initialized Git repository.
+Official templates are fetched directly with Git (`git clone` of the repo) —
+the CLI does not manage templates.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from arctyp.decorators import argument, command
+from arctyp.errors import ArctypError
+from arctyp.output import display_path, ok, steps
+from arctyp.project import CONFIG_FILE, project_config_content
+
+BASE_MAIN_TYP = """#import "conf.typ": conf
+#import "template.typ": template
+#import "uml.typ": uml
+
+#show: template.with(..conf)
+
+= Introduction
+
+Écrivez ici le contenu de votre document.
+
+// Exemple de diagramme UML (rendu par `arctyp` avant la compilation) :
+// #figure(uml("diagrams/schema.puml"), caption: [Légende])
+"""
+
+BASE_CONF_TYP = """// conf.typ — Paramètres du document, à modifier.
+#let conf = (
+  title: [Titre du document],
+  author: [Prénom Nom],
+)
+"""
+
+BASE_TEMPLATE_TYP = """// template.typ — Mise en page minimale du document.
+#let template(title: none, author: none, body) = {
+  set text(lang: "fr", size: 11pt)
+  set page(paper: "a4", margin: 2.5cm, numbering: "1")
+  set par(justify: true)
+
+  if title != none {
+    align(center)[#text(20pt, weight: "bold", title)]
+  }
+  if author != none {
+    align(center)[#author]
+  }
+  v(1cm)
+  body
+}
+"""
+
+BASE_UML_TYP = """// uml.typ — Intégration des diagrammes PlantUML dans le document.
+//
+// # `uml(path, ..args)`
+//
+// Charge le SVG (ou PNG) d'un diagramme PlantUML dans le document.
+//
+// **Convention** : chaque fichier `foo.puml` doit avoir été rendu à côté de
+// lui par la CLI `arctyp` **avant** la compilation (`foo.svg`, ou `foo.png`
+// si `[plantuml] format = "png"` dans l'arctyp.toml). Cette fonction ne fait
+// aucune requête réseau — Typst interdit tout accès au réseau au moment de la
+// compilation — elle résout simplement le chemin du fichier rendu et le
+// charge comme une image.
+//
+// **Arguments** : `path` est le chemin du fichier `.puml`, relatif à la racine
+// du projet. Tous les autres arguments sont transmis tels quels à la fonction
+// `image` (mêmes arguments, mêmes valeurs par défaut) : `width`, `height`,
+// `fit`, `alt`, `kind`, etc.
+//
+// **Exemple** :
+//
+//   #figure(
+//     uml("diagrams/schema.puml", width: 100%, alt: "Schéma"),
+//     caption: [Légende],
+//   )
+
+#let uml(path, ..args) = {
+  // Le format vient de l'arctyp.toml du projet ([plantuml] format) :
+  // "svg" par défaut, "png" pour un rendu PNG.
+  let conf = toml("arctyp.toml")
+  let format = conf.at("plantuml", default: (:)).at("format", default: "svg")
+  let ext = if format == "png" { ".png" } else { ".svg" }
+
+  // foo.puml -> foo.svg (ou foo.png), rendu par `arctyp` en amont.
+  // Le chemin est résolu par `image` relativement à ce fichier, donc à la
+  // racine du projet : d'où la convention « chemins relatifs à la racine ».
+  let output = path.replace(".puml", ext)
+  image(output, ..args)
+}
+"""
+
+BASE_GITIGNORE = """# PDF générés par `arctyp compile`
+/*.pdf
+"""
+
+
+@command(
+    name="init",
+    help="initialise un projet de base complet avec dépôt Git",
+    description=(
+        "Crée un projet Typst prêt à l'emploi (conf.typ, template.typ, "
+        "uml.typ, main.typ, diagrams/, images/) et initialise un dépôt Git. "
+        "Les templates officiels se récupèrent avec `git clone`."
+    ),
+)
+@argument(
+    "target",
+    nargs="?",
+    default=".",
+    metavar="répertoire",
+    help="répertoire de destination (défaut : répertoire courant)",
+)
+@argument(
+    "--force",
+    "-f",
+    action="store_true",
+    help="écrase les fichiers existants d'un répertoire non vide, sans demander",
+)
+def cmd_init(args) -> int:
+    target = Path(args.target or ".").resolve()
+    target_existed = target.exists() and any(target.iterdir())
+    if target_existed and not args.force:
+        raise ArctypError(
+            f"répertoire cible non vide ({display_path(target)})\n"
+            "  passez --force pour écraser les fichiers existants."
+        )
+    target.mkdir(parents=True, exist_ok=True)
+    existing_before = (
+        {path.resolve() for path in target.rglob("*") if path.is_file()} if target_existed else set()
+    )
+
+    written = _write_base_project(target)
+    ok(f"Projet de base créé dans {display_path(target)}")
+    if target_existed and written:
+        files = [
+            f"{display_path(path)} ({'écrasé' if path.resolve() in existing_before else 'créé'})"
+            for path in written
+        ]
+        steps("Fichiers écrits :", files)
+    _print_next_steps(target)
+    return 0
+
+
+def _write_base_project(target: Path) -> list[Path]:
+    """Writes a new project's base files, then initializes Git.
+
+    Returns only the files actually written (created or with changed content)
+    — an already-identical file is not counted as overwritten.
+    """
+    written: list[Path] = []
+    for name, content in (
+        ("main.typ", BASE_MAIN_TYP),
+        ("conf.typ", BASE_CONF_TYP),
+        ("template.typ", BASE_TEMPLATE_TYP),
+        ("uml.typ", BASE_UML_TYP),
+        (".gitignore", BASE_GITIGNORE),
+    ):
+        path = target / name
+        if _write_if_changed(path, content):
+            written.append(path)
+    for folder in ("diagrams", "images"):
+        keep = target / folder / ".gitkeep"
+        keep.parent.mkdir(parents=True, exist_ok=True)
+        if _write_if_changed(keep, ""):
+            written.append(keep)
+
+    config_path = target / CONFIG_FILE
+    if _write_if_changed(config_path, project_config_content()):
+        written.append(config_path)
+
+    _git_init(target)
+    return written
+
+
+def _write_if_changed(path: Path, content: str) -> bool:
+    """Writes `content` only if it differs; True if the file was written."""
+    if path.is_file() and path.read_text(encoding="utf-8") == content:
+        return False
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def _git_init(target: Path) -> None:
+    """Initializes a Git repository in the project (best effort, message on failure)."""
+    try:
+        proc = subprocess.run(
+            ["git", "init", "-q"], cwd=target, capture_output=True, text=True
+        )
+    except FileNotFoundError as exc:
+        raise ArctypError(
+            "git introuvable dans le PATH — initialisez le dépôt manuellement (git init)."
+        ) from exc
+    if proc.returncode != 0:
+        raise ArctypError(f"échec de git init : {(proc.stderr or '').strip()}")
+    ok("Dépôt Git initialisé")
+
+
+def _print_next_steps(target: Path) -> None:
+    """Prints the next steps (cd only if the project is not here).
+
+    The last line is the bare command, for direct copy-paste.
+    """
+    next_steps = ["éditez main.typ", "arctyp watch rapport.pdf"]
+    if target != Path.cwd().resolve():
+        next_steps.insert(0, f"cd {display_path(target)}")
+    steps("Prochaines étapes :", next_steps)

arctyp/commands/uml.py

@@ -0,0 +1,38 @@
+"""`arctyp uml <file.puml>`: renders a UML diagram to SVG via the PlantUML server.
+
+The SVG is written next to the `.puml` file (`foo.puml` -> `foo.svg`), which
+lets the templates' `uml()` function load it at compile time.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from arctyp.commands._shared import PUBLIC_OPTION
+from arctyp.decorators import argument, command
+from arctyp.errors import ArctypError
+from arctyp.output import display_path, ok
+from arctyp.plantuml import render_file
+
+
+@command(
+    name="uml",
+    help="rend un diagramme UML en SVG via le serveur PlantUML",
+    description=(
+        "Envoie le fichier .puml au serveur PlantUML et écrit le SVG rendu "
+        "à côté du fichier (foo.puml -> foo.svg)."
+    ),
+)
+@argument(
+    "file",
+    metavar="fichier.puml",
+    help="chemin vers le fichier .puml",
+)
+@PUBLIC_OPTION
+def cmd_uml(args) -> int:
+    puml = Path(args.file)
+    if not puml.is_file():
+        raise ArctypError(f"fichier introuvable : {args.file}")
+    svg = render_file(puml, public=args.public)
+    ok(f"SVG rendu : {display_path(svg)}")
+    return 0

arctyp/commands/watch.py

@@ -0,0 +1,144 @@
+"""`arctyp watch <report.pdf>`: recompiles on every project change.
+
+Watches the project with `watchdog` (filesystem events, instant, no polling).
+Compiles once, then recompiles once per burst of changes (debounce) —
+Ctrl-C stops (code 130).
+
+Generated paths are excluded to avoid loops: the output PDF, `.git`, caches,
+and the `.svg`/`.png` files rendered next to the `.puml` files.
+
+`watchdog` is imported here *on demand*: loading it costs ~400 ms (system
+backends), which would be too expensive on every CLI call.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+
+from arctyp.commands._shared import PDF_ARGUMENT, PUBLIC_OPTION
+from arctyp.decorators import command
+from arctyp.output import info, ok
+from arctyp.pipeline import compile_typst, render_diagrams
+from arctyp.plantuml import find_puml_files
+from arctyp.project import project_root
+
+DEBOUNCE_SECONDS = 0.5  # silence before recompiling after a burst
+
+# Folders whose events must never trigger a recompile.
+_IGNORED_DIRS = frozenset({".git", "__pycache__", ".venv", ".arctyp"})
+
+
+@command(
+    name="watch",
+    help="recompile automatiquement à chaque modification du projet (Ctrl-C pour arrêter)",
+    description=(
+        "Compile une première fois (nom du PDF obligatoire), puis recompile "
+        "à chaque changement de fichier du projet."
+    ),
+)
+@PDF_ARGUMENT
+@PUBLIC_OPTION
+def cmd_watch(args) -> int:
+    from watchdog.events import FileSystemEventHandler
+    from watchdog.observers import Observer
+
+    project = project_root().resolve()
+    output = Path(args.pdf).resolve()
+
+    _compile(project, output, public=args.public)
+    generated = _generated_outputs(project)
+    debouncer = _Debouncer(
+        DEBOUNCE_SECONDS, _recompile(project, output, public=args.public)
+    )
+
+    class _Handler(FileSystemEventHandler):
+        def on_any_event(self, event) -> None:
+            rel = _relevant_path(event, project, output, generated)
+            if rel is not None:
+                debouncer.bump(str(rel))
+
+    observer = Observer()
+    observer.schedule(_Handler(), str(project), recursive=True)
+    observer.start()
+    info("Surveillance du projet (Ctrl-C pour arrêter)…")
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        observer.stop()
+        observer.join()
+    info("Surveillance arrêtée.")
+    return 130
+
+
+def _recompile(project: Path, output: Path, public: bool = False):
+    """Returns the recompilation function (with its own message)."""
+    def recompile(detail: str | None = None) -> None:
+        message = f"Fichier modifié : {detail} — recompilation…" if detail else "Modification détectée — recompilation…"
+        info(message)
+        _compile(project, output, public=public)
+
+    return recompile
+
+
+def _compile(project: Path, output: Path, public: bool = False) -> None:
+    """The same pipeline as `arctyp compile`: diagrams, then Typst."""
+    render_diagrams(project, public=public)
+    compile_typst(project, output)
+    ok(f"PDF généré : {output.name}")
+
+
+def _generated_outputs(project: Path) -> set[Path]:
+    """The .svg/.png rendered next to the .puml files: regenerated on every compile."""
+    outputs = set()
+    for puml in find_puml_files(project):
+        outputs.add(puml.with_suffix(".svg").resolve())
+        outputs.add(puml.with_suffix(".png").resolve())
+    return outputs
+
+
+def _relevant_path(
+    event,
+    project: Path,
+    output: Path,
+    generated: set[Path],
+) -> Path | None:
+    """Relative path if the event should recompile, None otherwise."""
+    if event.is_directory or event.event_type in ("opened", "closed"):
+        return None
+    path = Path(event.src_path).resolve()
+    try:
+        rel = path.relative_to(project)
+    except ValueError:
+        return None  # outside the project: ignored
+    if any(part in _IGNORED_DIRS for part in rel.parts):
+        return None
+    if path == output or path in generated:
+        return None
+    return rel
+
+
+class _Debouncer:
+    """Triggers `callback(detail)` once after `delay` seconds of silence.
+
+    Each `bump()` cancels the previous timer: a burst of events (an editor's
+    atomic save) triggers only one recompilation.
+    """
+
+    def __init__(self, delay: float, callback) -> None:
+        self._delay = delay
+        self._callback = callback
+        self._timer: threading.Timer | None = None
+        self._lock = threading.Lock()
+
+    def bump(self, detail: str | None = None) -> None:
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+            self._timer = threading.Timer(self._delay, lambda: self._callback(detail))
+            self._timer.daemon = True
+            self._timer.start()