atril 0.7.0__py3-none-any.whl

atril/__init__.py

@@ -0,0 +1,5 @@
+"""atril: gestiona una instalación local de DeepTutor y sus temarios."""
+
+from importlib.metadata import version
+
+__version__ = version("atril")

atril/__main__.py

@@ -0,0 +1,6 @@
+"""Permite ejecutar el paquete con ``python -m atril``."""
+
+from atril.main import main
+
+if __name__ == "__main__":
+    main()

atril/backup.py

@@ -0,0 +1,315 @@
+"""Copias de seguridad de la estación con restic.
+
+Se copian ``atril.toml``, ``data/`` y ``temarios/`` (no ``app/``, que se
+reconstruye con ``atril instalar``), más un *git bundle* de cada repo (el git de
+cada temario y ``[backup] repos_git``) dentro de ``data/atril/bundles/``.
+
+La contraseña de restic viene del entorno (``RESTIC_PASSWORD``,
+``RESTIC_PASSWORD_FILE`` o ``RESTIC_PASSWORD_COMMAND``), nunca de ``atril.toml``.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from atril.config.station import BackupTarget, Station
+
+PASSWORD_VARIABLES = (
+    "RESTIC_PASSWORD",
+    "RESTIC_PASSWORD_FILE",
+    "RESTIC_PASSWORD_COMMAND",
+)
+"""Variables con las que restic obtiene la contraseña del repositorio."""
+
+TAG = "atril"
+"""Etiqueta de los snapshots de atril."""
+
+EXCLUDES = ("*.part", "*.nuevo")
+"""Descargas a medias de atril: no se copian."""
+
+EXIT_NO_REPOSITORY = 10
+"""Código de restic (>= 0.17) cuando el repositorio no existe."""
+
+EXIT_WRONG_PASSWORD = 12
+"""Código de restic cuando la contraseña no abre el repositorio."""
+
+REMOTE_PREFIXES = ("rclone:", "sftp:", "s3:", "b2:", "azure:", "gs:", "rest:", "swift:")
+"""Repositorios que no son una carpeta local."""
+
+
+class BackupError(Exception):
+    """Fallo de restic o de la preparación del backup; mensaje en español."""
+
+
+@dataclass(frozen=True, slots=True)
+class Summary:
+    """Resumen de un ``restic backup``."""
+
+    snapshot: str
+    files_new: int
+    files_changed: int
+    data_added: int
+    seconds: float
+
+
+@dataclass(frozen=True, slots=True)
+class Snapshot:
+    """Snapshot de un repositorio."""
+
+    short_id: str
+    time: str
+    paths: tuple[str, ...]
+    hostname: str
+
+
+Progress = Callable[[float, int, int], None]
+"""Avance: fracción completada, bytes hechos y bytes totales."""
+
+
+def is_local(target: BackupTarget) -> bool:
+    """El repositorio es una carpeta (p. ej. un disco externo)."""
+    return not target.repo.startswith(REMOTE_PREFIXES)
+
+
+def is_reachable(target: BackupTarget) -> bool:
+    """Un repositorio local está accesible si existe su carpeta padre (disco conectado).
+
+    Los remotos se dan por accesibles: restic informará si no lo son.
+    """
+    return not is_local(target) or Path(target.repo).parent.is_dir()
+
+
+def password_configured(env: dict[str, str] | None = None) -> bool:
+    """Hay alguna forma de contraseña para restic en el entorno."""
+    environ = os.environ if env is None else env
+    return any(environ.get(name) for name in PASSWORD_VARIABLES)
+
+
+def backup_paths(station: Station) -> list[Path]:
+    """Lo que se copia de la estación (solo lo que existe)."""
+    paths = [station.root / "atril.toml", station.data_dir, station.syllabi_dir]
+    return [path for path in paths if path.exists()]
+
+
+def bundles_dir(station: Station) -> Path:
+    """Carpeta de los git bundle (dentro de ``data/``, así entran en el snapshot)."""
+    return station.data_dir / "atril" / "bundles"
+
+
+def git_repos(station: Station) -> dict[str, Path]:
+    """Repos de git a empaquetar: cada temario con ``.git`` y ``repos_git``."""
+    repos: dict[str, Path] = {}
+    if station.syllabi_dir.is_dir():
+        for folder in sorted(station.syllabi_dir.iterdir()):
+            if (folder / ".git").exists():
+                repos[f"temario-{folder.name}"] = folder
+    for repo in station.backup.git_repos:
+        repos[f"repo-{repo.name}"] = repo
+    return repos
+
+
+class Restic:
+    """Llamadas a restic para un repositorio."""
+
+    def __init__(self, target: BackupTarget, executable: str = "restic") -> None:
+        """Prepara las llamadas al repositorio de ``target``."""
+        self.target = target
+        self.executable = executable
+
+    def _command(self, *args: str) -> list[str]:
+        """Comando completo de restic con el repositorio."""
+        return [self.executable, "-r", self.target.repo, *args]
+
+    def _run(self, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+        """Ejecuta restic capturando la salida."""
+        result = subprocess.run(
+            self._command(*args),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+        if check and result.returncode != 0:
+            raise BackupError(self._explain(result))
+        return result
+
+    def _explain(self, result: subprocess.CompletedProcess[str]) -> str:
+        """Mensaje de error de restic, con pista para los casos conocidos."""
+        if result.returncode == EXIT_WRONG_PASSWORD:
+            return f"{self.target.name}: la contraseña no abre el repositorio."
+        if result.returncode == EXIT_NO_REPOSITORY:
+            return f"{self.target.name}: el repositorio no existe ({self.target.repo})."
+        lines = [line for line in result.stderr.strip().splitlines() if line.strip()]
+        detail = lines[-1] if lines else f"código {result.returncode}"
+        return f"{self.target.name}: {detail}"
+
+    def ensure_repository(self) -> bool:
+        """Inicializa el repositorio si no existe.
+
+        Returns:
+            ``True`` si se ha creado ahora.
+        """
+        result = self._run("cat", "config", check=False)
+        if result.returncode == 0:
+            return False
+        if result.returncode != EXIT_NO_REPOSITORY:
+            raise BackupError(self._explain(result))
+        self._run("init")
+        return True
+
+    def backup(self, paths: list[Path], progress: Progress | None = None) -> Summary:
+        """``restic backup`` con avance; devuelve el resumen."""
+        args = ["backup", "--json", "--tag", TAG]
+        for pattern in EXCLUDES:
+            args += ["--exclude", pattern]
+        command = self._command(*args, *(str(path) for path in paths))
+        summary: dict[str, Any] = {}
+        errors: list[str] = []
+        process = subprocess.Popen(
+            command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        for line in process.stdout or ():
+            try:
+                message = json.loads(line)
+            except ValueError:
+                continue
+            kind = message.get("message_type")
+            if kind == "status" and progress:
+                progress(
+                    float(message.get("percent_done", 0)),
+                    int(message.get("bytes_done", 0)),
+                    int(message.get("total_bytes", 0)),
+                )
+            elif kind == "summary":
+                summary = message
+            elif kind == "error":
+                errors.append(str(message.get("error", {}).get("message", message)))
+        stderr = process.stderr.read() if process.stderr else ""
+        process.wait()
+        # Código 3: snapshot hecho, pero algún fichero no se pudo leer.
+        if process.returncode not in {0, 3} or not summary:
+            detail = (errors or stderr.strip().splitlines() or ["?"])[-1]
+            raise BackupError(f"{self.target.name}: {detail}")
+        return Summary(
+            snapshot=str(summary.get("snapshot_id", ""))[:8],
+            files_new=int(summary.get("files_new", 0)),
+            files_changed=int(summary.get("files_changed", 0)),
+            data_added=int(summary.get("data_added", 0)),
+            seconds=float(summary.get("total_duration", 0)),
+        )
+
+    def forget(self, daily: int, weekly: int, monthly: int) -> None:
+        """Aplica la retención y borra los datos que ya no usa ningún snapshot."""
+        self._run(
+            "forget",
+            "--tag",
+            TAG,
+            "--keep-daily",
+            str(daily),
+            "--keep-weekly",
+            str(weekly),
+            "--keep-monthly",
+            str(monthly),
+            "--prune",
+        )
+
+    def snapshots(self) -> list[Snapshot]:
+        """Snapshots de atril, del más antiguo al más reciente."""
+        data = json.loads(self._run("snapshots", "--json", "--tag", TAG).stdout or "[]")
+        return [
+            Snapshot(
+                short_id=str(item.get("short_id", item.get("id", ""))[:8]),
+                time=str(item.get("time", ""))[:19],
+                paths=tuple(item.get("paths", [])),
+                hostname=str(item.get("hostname", "")),
+            )
+            for item in data or []
+        ]
+
+    def check(self, read_data: str | None = None) -> None:
+        """``restic check``; con ``read_data`` (p. ej. ``5%``) lee esa parte."""
+        args = ["check"]
+        if read_data:
+            args.append(f"--read-data-subset={read_data}")
+        self._run(*args)
+
+    def restore(self, snapshot: str, target: Path) -> None:
+        """Restaura un snapshot en ``target`` (con la estructura de la estación)."""
+        self._run("restore", snapshot, "--target", str(target))
+
+
+def make_bundles(station: Station, git: str = "git") -> list[tuple[str, str]]:
+    """Crea un git bundle de cada repo.
+
+    Returns:
+        Pares (nombre, resultado) para informar; un repo sin commits o inaccesible
+        se anota y se sigue.
+    """
+    folder = bundles_dir(station)
+    folder.mkdir(parents=True, exist_ok=True)
+    results = []
+    for name, repo in git_repos(station).items():
+        target = folder / f"{name}.bundle"
+        result = subprocess.run(
+            [git, "-C", str(repo), "bundle", "create", str(target), "--all"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+        if result.returncode == 0:
+            results.append((name, "ok"))
+        else:
+            lines = result.stderr.strip().splitlines()
+            results.append((name, lines[-1] if lines else "error"))
+    return results
+
+
+def find_restored_root(target: Path) -> Path | None:
+    """Carpeta restaurada con la estructura de una estación (``atril.toml`` o ``data``).
+
+    restic deja la estructura relativa al ancestro común de las rutas copiadas,
+    pero se busca a algo de profundidad por si cambia.
+    """
+    candidates = [target, *sorted(p for p in target.rglob("*") if p.is_dir())]
+    for folder in candidates:
+        looks_like_station = (folder / "atril.toml").is_file() or (
+            folder / "data"
+        ).is_dir()
+        if looks_like_station and len(folder.relative_to(target).parts) <= 6:
+            return folder
+    return None
+
+
+def swap_in(station: Station, restored: Path, keep: Path) -> list[str]:
+    """Sustituye ``atril.toml``, ``data/`` y ``temarios/`` por los restaurados.
+
+    Lo que había se mueve a ``keep`` (no se borra nada).
+
+    Returns:
+        Los elementos sustituidos.
+    """
+    keep.mkdir(parents=True, exist_ok=False)
+    replaced = []
+    for name in ("atril.toml", "data", "temarios"):
+        source = restored / name
+        if not source.exists():
+            continue
+        current = station.root / name
+        if current.exists():
+            shutil.move(current, keep / name)
+        shutil.move(source, current)
+        replaced.append(name)
+    return replaced

atril/checks.py

@@ -0,0 +1,41 @@
+"""Resultados de comprobaciones que los comandos muestran al usuario."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class Level(StrEnum):
+    """Gravedad de una comprobación."""
+
+    OK = "ok"
+    INFO = "info"
+    WARNING = "aviso"
+    ERROR = "error"
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """Resultado de una comprobación, con su mensaje en español."""
+
+    level: Level
+    message: str
+
+
+def ok(message: str) -> Finding:
+    """Comprobación superada."""
+    return Finding(Level.OK, message)
+
+
+def info(message: str) -> Finding:
+    """Dato informativo, sin valoración."""
+    return Finding(Level.INFO, message)
+
+
+def warning(message: str) -> Finding:
+    """Situación que conviene revisar pero no impide continuar."""
+    return Finding(Level.WARNING, message)
+
+
+def error(message: str) -> Finding:
+    """Situación que impide funcionar correctamente."""
+    return Finding(Level.ERROR, message)

atril/commands/__init__.py

@@ -0,0 +1 @@
+"""Comandos de la CLI, agrupados por área; ``atril.main`` los registra."""

atril/commands/_common.py

@@ -0,0 +1,115 @@
+"""Utilidades compartidas por los comandos: estación, consola Rich y errores.
+
+Toda la salida pasa por :data:`console` (y :data:`err_console` para errores). El
+texto que viene de fuera (rutas, mensajes de configuración con ``[[fuente]]``,
+líneas de comandos) se escapa para que Rich no lo interprete como markup.
+"""
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import NoReturn
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+
+from atril.checks import Finding, Level
+from atril.config import (
+    ConfigError,
+    Station,
+    Syllabus,
+    find_station,
+    load_station,
+    load_syllabi,
+    load_syllabus,
+)
+from atril.config.syllabus import KnowledgeBase
+
+console = Console(soft_wrap=True)
+"""Consola de salida normal; ``soft_wrap`` evita cortar rutas y mensajes largos."""
+
+err_console = Console(stderr=True, soft_wrap=True)
+"""Consola de errores."""
+
+_STYLE = {
+    Level.OK: ("✓", "green"),
+    Level.INFO: ("·", "dim"),
+    Level.WARNING: ("!", "yellow"),
+    Level.ERROR: ("✗", "bold red"),
+}
+
+
+def fail(message: str) -> NoReturn:
+    """Muestra ``message`` como error y termina con código 1."""
+    err_console.print(f"[bold red]Error:[/] {escape(message)}")
+    raise typer.Exit(1)
+
+
+def station_root(ctx: typer.Context) -> Path:
+    """Raíz de la estación: ``--estacion`` o búsqueda desde la carpeta actual."""
+    explicit: Path | None = ctx.obj
+    return explicit if explicit is not None else find_station(Path.cwd())
+
+
+def get_station(ctx: typer.Context) -> Station:
+    """Carga ``atril.toml``; termina con error si falta o no es válido."""
+    try:
+        return load_station(station_root(ctx))
+    except ConfigError as exc:
+        fail(str(exc))
+
+
+def get_syllabus(ctx: typer.Context, syllabus_id: str) -> Syllabus:
+    """Carga un temario por id; termina con error si no existe o no es válido."""
+    station = get_station(ctx)
+    root = station.syllabi_dir / syllabus_id
+    if not (root / "temario.toml").is_file():
+        found = sorted(
+            p.parent.name for p in station.syllabi_dir.glob("*/temario.toml")
+        )
+        names = ", ".join(found) or "ninguno"
+        fail(f"no existe el temario {syllabus_id!r} (disponibles: {names}).")
+    try:
+        return load_syllabus(root)
+    except ConfigError as exc:
+        fail(str(exc))
+
+
+def find_kb(ctx: typer.Context, kb_id: str) -> tuple[Syllabus, KnowledgeBase]:
+    """Temario y KB a partir del id de KB (único en la estación)."""
+    station = get_station(ctx)
+    try:
+        syllabi, _ = load_syllabi(station.syllabi_dir)
+    except ConfigError as exc:
+        fail(str(exc))
+    for syllabus in syllabi:
+        for kb in syllabus.knowledge_bases:
+            if kb.id == kb_id:
+                return syllabus, kb
+    known = ", ".join(kb.id for s in syllabi for kb in s.knowledge_bases) or "ninguna"
+    fail(f"no existe la KB {kb_id!r} en ningún temario (disponibles: {known}).")
+
+
+def show(findings: Iterable[Finding], title: str | None = None) -> bool:
+    """Muestra las comprobaciones, una por línea, con símbolo y color por nivel.
+
+    Args:
+        findings: Comprobaciones, en el orden en que se muestran.
+        title: Título de la sección, si lo hay.
+
+    Returns:
+        ``True`` si ninguna es un error.
+    """
+    if title:
+        console.rule(f"[bold]{escape(title)}[/]", align="left")
+    clean = True
+    for finding in findings:
+        symbol, style = _STYLE[finding.level]
+        console.print(f"  [{style}]{symbol}[/] {escape(finding.message)}")
+        clean = clean and finding.level is not Level.ERROR
+    return clean
+
+
+def success(message: str) -> None:
+    """Mensaje final de éxito."""
+    console.print(f"[bold green]{escape(message)}[/]")