pdf-tool-cli 1.1.0__py3-none-any.whl

pdftool/core/atomic.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+
+@contextmanager
+def atomic_output(target: Path) -> Iterator[Path]:
+    """Escribe una salida en el mismo directorio y publícala al terminar.
+
+    El archivo final no se crea ni se reemplaza hasta que el bloque termina sin
+    excepción. Al usar el mismo directorio, `os.replace` conserva la operación
+    como un cambio atómico dentro del mismo sistema de archivos.
+    """
+    target = Path(target)
+    fd, temporary_name = tempfile.mkstemp(
+        prefix=".pdf-tool-", suffix=target.suffix, dir=target.parent
+    )
+    os.close(fd)
+    temporary = Path(temporary_name)
+    try:
+        yield temporary
+        os.replace(temporary, target)
+    finally:
+        # Si el bloque falla, elimina el temporal; `missing_ok` también cubre
+        # el caso exitoso, donde os.replace ya lo movió al destino final.
+        temporary.unlink(missing_ok=True)
+
+
+def atomic_copy(source: Path, target: Path) -> None:
+    """Copia `source` sin dejar una salida parcial si la copia falla."""
+    with atomic_output(target) as temporary:
+        shutil.copy2(source, temporary)
+
+
+def atomic_write_text(target: Path, text: str, *, encoding: str = "utf-8") -> None:
+    """Escribe texto y publica el archivo solo cuando la escritura termina."""
+    with atomic_output(target) as temporary:
+        temporary.write_text(text, encoding=encoding)

pdftool/core/batch.py

@@ -0,0 +1,111 @@
+"""Bucle común de las herramientas por lote.
+
+Un archivo que falla no detiene el lote: queda reportado en su `FileResult`.
+La cancelación (`JobCancelled`) sí lo detiene, porque nunca se trata como un
+fallo de archivo.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pdftool.core.errors import UserError, user_message
+from pdftool.core.jobs import JobCancelled
+from pdftool.core.plugin import FileResult, Progress
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """Resultado de un archivo con avisos y cifras, además del mensaje."""
+
+    output: Path
+    message: str
+    warnings: tuple[str, ...] = ()
+    metrics: Mapping[str, float] = field(default_factory=dict)
+
+
+# Procesa una entrada y devuelve (salida, mensaje corto) o un `Outcome`.
+ProcessOne = Callable[[Path, Progress], "tuple[Path, str] | Outcome"]
+
+_log = logging.getLogger("pdftool.batch")
+
+
+def noop_progress(_p: float, _m: str) -> None:
+    pass
+
+
+def validate_inputs(inputs: Sequence[Path | str]) -> list[Path]:
+    """Normaliza las entradas y exige que haya al menos una y que existan."""
+    if not inputs:
+        raise ValueError("inputs está vacío")
+    paths = [Path(p) for p in inputs]
+    for path in paths:
+        if not path.exists():
+            raise FileNotFoundError(path)
+    return paths
+
+
+@dataclass
+class BatchResult:
+    outputs: list[Path]
+    items: list[FileResult]
+
+    @property
+    def total(self) -> int:
+        return len(self.items)
+
+
+def run_batch(
+    inputs: Sequence[Path | str],
+    process_one: ProcessOne,
+    progress: Progress = noop_progress,
+    *,
+    all_failed: str,
+) -> BatchResult:
+    """Procesa cada entrada aislando sus errores.
+
+    Con un solo archivo, su error se relanza tal cual (así el mensaje humano
+    del host lo reconoce). Con varios, solo se lanza `UserError(all_failed)`
+    si no salió ninguno. El mensaje de cada fallo ya viene traducido para el
+    usuario; el detalle técnico queda en el log.
+    """
+    paths = validate_inputs(inputs)
+    total = len(paths)
+    outputs: list[Path] = []
+    items: list[FileResult] = []
+
+    for index, path in enumerate(paths):
+
+        def scoped(
+            pct: float, msg: str, _i: int = index, _name: str = path.name
+        ) -> None:
+            label = f"[{_i + 1}/{total}] {_name}: {msg}" if total > 1 else msg
+            progress((_i + pct) / total, label)
+
+        try:
+            done = process_one(path, scoped)
+        except JobCancelled:
+            raise
+        except Exception as exc:  # este archivo falla; el lote continúa
+            if total == 1:
+                raise
+            message, detail = user_message(exc)
+            if detail is not None:
+                _log.warning("archivo %d/%d falló", index + 1, total, exc_info=exc)
+            items.append(FileResult(path, None, False, message))
+            continue
+        if not isinstance(done, Outcome):
+            done = Outcome(*done)
+        outputs.append(done.output)
+        items.append(
+            FileResult(
+                path, done.output, True, done.message, done.warnings, done.metrics
+            )
+        )
+
+    if not outputs:
+        raise UserError(all_failed)
+    return BatchResult(outputs=outputs, items=items)

pdftool/core/config.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import contextlib
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+from platformdirs import user_data_dir
+from pydantic import BaseModel, Field, ValidationError
+
+from pdftool.core.atomic import atomic_write_text
+
+APP_NAME = "pdf-tool"
+APP_AUTHOR = "juanmaAV"
+
+
+def data_dir() -> Path:
+    d = Path(user_data_dir(APP_NAME, APP_AUTHOR))
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def settings_path() -> Path:
+    return data_dir() / "settings.json"
+
+
+ThemeSetting = Literal["system", "light", "dark"]
+
+# Versión del formato de settings.json. Subirla cuando un cambio necesite
+# migrar datos guardados; los archivos sin versión son la versión 1.
+SCHEMA_VERSION = 1
+
+
+class Settings(BaseModel):
+    schema_version: int = SCHEMA_VERSION
+    theme_mode: ThemeSetting = "system"
+    # Carpeta de salida global; None → junto al original. Se guarda como texto
+    # porque el JSON no tiene tipo ruta.
+    output_dir: str | None = None
+    # Preferencias propias de cada herramienta, por `meta.id`.
+    tools: dict[str, dict[str, Any]] = Field(default_factory=dict)
+
+    def tool(self, tool_id: str) -> dict[str, Any]:
+        """Preferencias de una herramienta (se crean vacías al pedirlas)."""
+        return self.tools.setdefault(tool_id, {})
+
+
+def _recover(raw: dict[str, Any]) -> Settings:
+    """Conserva cada campo válido y deja en su default solo los inválidos."""
+    defaults = Settings()
+    kept: dict[str, Any] = {}
+    for name in Settings.model_fields:
+        if name not in raw:
+            continue
+        try:
+            Settings.model_validate({name: raw[name]})
+        except ValidationError:
+            continue
+        kept[name] = raw[name]
+    return Settings.model_validate({**defaults.model_dump(), **kept})
+
+
+def load_settings(path: Path | None = None) -> Settings:
+    path = path or settings_path()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return Settings()
+    try:
+        raw = json.loads(text)
+        if not isinstance(raw, dict):
+            raise ValueError("settings.json no es un objeto")
+    except ValueError:
+        # Ilegible: se guarda una copia antes de que el próximo guardado lo
+        # sustituya, y la app arranca con los valores por defecto.
+        with contextlib.suppress(OSError):
+            atomic_write_text(path.with_name(path.name + ".bak"), text)
+        return Settings()
+    try:
+        return Settings.model_validate(raw)
+    except ValidationError:
+        # Un campo inválido no debe llevarse por delante el resto.
+        return _recover(raw)
+
+
+def save_settings(settings: Settings, path: Path | None = None) -> None:
+    path = path or settings_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(path, settings.model_dump_json(indent=2))

pdftool/core/errors.py

@@ -0,0 +1,36 @@
+"""Traducción de excepciones a mensajes para el usuario (sin Flet).
+
+Solo `UserError` se muestra tal cual: es el canal de los mensajes de dominio,
+ya escritos en español para el usuario. Cualquier otra excepción, incluido un
+`ValueError` de una librería, recibe un mensaje genérico y conserva el detalle
+técnico para diagnóstico.
+"""
+
+from __future__ import annotations
+
+_FILE_NOT_FOUND = (
+    "No se encontró el archivo. ¿Lo moviste o borraste? Vuelve a elegirlo."
+)
+_PERMISSION = (
+    "No hay permiso para leer o guardar el archivo. Ciérralo si lo tienes "
+    "abierto o elige otra carpeta en «Guardar en»."
+)
+GENERIC_MESSAGE = (
+    "No se pudo procesar el archivo. Puede estar dañado o tener contraseña "
+    "(puedes quitarla con «Proteger PDF»)."
+)
+
+
+class UserError(ValueError):
+    """Error de dominio con un mensaje listo para mostrar al usuario."""
+
+
+def user_message(exc: BaseException) -> tuple[str, str | None]:
+    """(mensaje para el usuario, detalle técnico | None)."""
+    if isinstance(exc, UserError):
+        return str(exc), None
+    if isinstance(exc, FileNotFoundError):
+        return _FILE_NOT_FOUND, None
+    if isinstance(exc, PermissionError):
+        return _PERMISSION, None
+    return GENERIC_MESSAGE, f"{type(exc).__name__}: {exc}"

pdftool/core/jobs.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections.abc import Callable
+from concurrent.futures import CancelledError, Future, ThreadPoolExecutor, TimeoutError
+from dataclasses import dataclass, field
+
+_MAX_WORKERS = 2
+_executor_lock = threading.Lock()
+_active_jobs_lock = threading.Lock()
+_executor: ThreadPoolExecutor | None = None
+_log = logging.getLogger("pdftool.jobs")
+
+
+class JobCancelled(Exception):
+    """Señala que el resultado de un job ya no debe continuar."""
+
+
+@dataclass(eq=False)
+class JobHandle:
+    """Control cooperativo de un trabajo ejecutado en segundo plano."""
+
+    _cancel_event: threading.Event = field(default_factory=threading.Event)
+    _future: Future | None = None
+
+    def cancel(self) -> None:
+        """Cancela una tarea en cola o pide parar una que ya está ejecutándose."""
+        self._cancel_event.set()
+        if self._future is not None and self._future.cancel():
+            _unregister(self)
+
+    @property
+    def cancelled(self) -> bool:
+        return self._cancel_event.is_set()
+
+    def _set_future(self, future: Future) -> None:
+        self._future = future
+        if self.cancelled and future.cancel():
+            _unregister(self)
+
+    def join(self, timeout: float | None = None) -> None:
+        """Espera al trabajo; útil para tests y cierre controlado."""
+        if self._future is None:
+            return
+        try:
+            self._future.result(timeout=timeout)
+        except (CancelledError, TimeoutError):
+            return
+
+
+_active_jobs: set[JobHandle] = set()
+
+
+def _get_executor() -> ThreadPoolExecutor:
+    global _executor
+    with _executor_lock:
+        if _executor is None:
+            _executor = ThreadPoolExecutor(
+                max_workers=_MAX_WORKERS, thread_name_prefix="pdftool-job"
+            )
+        return _executor
+
+
+def _register(handle: JobHandle) -> None:
+    with _active_jobs_lock:
+        _active_jobs.add(handle)
+
+
+def _unregister(handle: JobHandle) -> None:
+    with _active_jobs_lock:
+        _active_jobs.discard(handle)
+
+
+def shutdown_job_executor() -> None:
+    """Cancela trabajos pendientes y libera los workers compartidos.
+
+    Los trabajos que ya están dentro de una llamada pesada no se pueden matar de
+    forma segura. Conservan la cancelación cooperativa y no volverán a notificar
+    a la UI cuando el cierre haya invalidado su handle.
+    """
+    global _executor
+    with _executor_lock:
+        executor = _executor
+        _executor = None
+    with _active_jobs_lock:
+        handles = list(_active_jobs)
+    for handle in handles:
+        handle.cancel()
+    if executor is not None:
+        executor.shutdown(wait=False, cancel_futures=True)
+
+
+def _notify(callback: Callable, value: object) -> None:
+    # Un fallo aquí es un bug de la UI: sin este registro se perdería en un
+    # Future que nadie lee y el panel quedaría en «Procesando…».
+    try:
+        callback(value)
+    except Exception:
+        _log.exception("Error en el callback de un trabajo")
+
+
+@dataclass(eq=False)
+class _Job:
+    """Estado de una ejecución: callbacks, vigencia y ritmo del progreso."""
+
+    handle: JobHandle
+    work: Callable
+    on_progress: Callable
+    on_done: Callable
+    on_error: Callable
+    is_current: Callable[[], bool] | None
+    progress_interval: float
+    clock: Callable[[], float]
+    _last_progress: float | None = None
+
+    def still_current(self) -> bool:
+        if self.handle.cancelled:
+            return False
+        return self.is_current is None or self.is_current()
+
+    def progress(self, pct: float, message: str) -> None:
+        if not self.still_current():
+            raise JobCancelled()
+        now = self.clock()
+        previous = self._last_progress
+        if previous is None or pct >= 1.0 or now - previous >= self.progress_interval:
+            self._last_progress = now
+            self.on_progress(pct, message)
+
+    def run(self) -> None:
+        try:
+            result = self.work(self.progress)
+        except JobCancelled:
+            return
+        except Exception as exc:  # se reenvía a on_error
+            if self.still_current():
+                _notify(self.on_error, exc)
+        else:
+            if self.still_current():
+                _notify(self.on_done, result)
+        finally:
+            _unregister(self.handle)
+
+
+def run_job(
+    work: Callable,
+    on_progress: Callable,
+    on_done: Callable,
+    on_error: Callable,
+    *,
+    is_current: Callable[[], bool] | None = None,
+    progress_interval: float = 0.1,
+    clock: Callable[[], float] = time.monotonic,
+) -> JobHandle:
+    """Ejecuta un trabajo en el executor compartido con cancelación cooperativa.
+
+    `work` recibe el callback de progreso y devuelve un resultado. La cola está
+    acotada en concurrencia para no crear un hilo por cada interacción; cancelar
+    un handle descarta una tarea pendiente y silencia los callbacks de una tarea
+    que ya haya empezado.
+
+    `on_progress` se limita a una llamada cada `progress_interval` segundos
+    (cada una cuesta un repintado de la UI); la primera y la final (pct >= 1)
+    siempre pasan. La cancelación se comprueba en cada llamada igualmente.
+    """
+    handle = JobHandle()
+    _register(handle)
+    job = _Job(
+        handle,
+        work,
+        on_progress,
+        on_done,
+        on_error,
+        is_current,
+        progress_interval,
+        clock,
+    )
+    try:
+        future = _get_executor().submit(job.run)
+    except RuntimeError as exc:
+        _unregister(handle)
+        if job.still_current():
+            on_error(exc)
+    else:
+        handle._set_future(future)
+    return handle

pdftool/core/logger.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import logging
+import re
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from pdftool.core.config import data_dir
+
+_LOGGER_NAME = "pdftool"
+_FORMAT = "%(asctime)s %(levelname)s %(name)s: %(message)s"
+
+_DOC_EXT = r"pdf|jpe?g|png"
+
+# Redacción por capas, aplicadas EN ORDEN sobre el texto ya formateado
+# (incluye tracebacks). El orden importa:
+#   1) rutas/archivos entre comillas simples primero: los mensajes de
+#      excepción suelen citarlas y las comillas delimitan nombres con
+#      espacios que un patrón sin comillas no podría acotar.
+#   2) rutas sin comillas, consumiendo la ruta COMPLETA (no solo el
+#      segmento de usuario) para no dejar carpetas/nombres de archivo tras
+#      el "~".
+#   3) nombres de archivo de documento sueltos (sin ruta ni comillas),
+#      incluida la cola de un nombre partido por espacios.
+_REDACTION_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    # 1) rutas o nombres citados
+    (re.compile(r"'[^'\n]*[/\\][^'\n]*'"), "'[ruta]'"),
+    (re.compile(rf"'[^'\n]*\.({_DOC_EXT})'", re.IGNORECASE), "'[archivo]'"),
+    # 2) rutas completas sin comillas
+    (re.compile(re.escape(str(Path.home())) + r"\S*"), "~"),
+    (re.compile(r"/Users/\S+"), "~"),
+    (re.compile(r"[A-Za-z]:[\\/]Users[\\/]\S+"), "~"),
+    # 3) nombres de archivo sueltos (sin ruta)
+    (re.compile(rf"\S+\.({_DOC_EXT})\b", re.IGNORECASE), "[archivo]"),
+]
+
+
+def sanitize(text: str) -> str:
+    """Redacta rutas y nombres de documentos personales de cualquier texto.
+
+    Aplica las capas de `_REDACTION_PATTERNS` en orden: primero lo citado
+    entre comillas, luego rutas completas sin comillas, y por último
+    nombres de archivo de documento sueltos. Ninguna capa debe dejar
+    filtrar carpetas ni nombres de archivo del usuario.
+    """
+    for pattern, replacement in _REDACTION_PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+class _SanitizingFormatter(logging.Formatter):
+    """Sanitiza la línea completa ya formateada (cubre también el traceback)."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        return sanitize(super().format(record))
+
+
+def log_dir() -> Path:
+    d = data_dir() / "logs"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def log_paths() -> list[Path]:
+    """Archivos de log existentes, backup primero (orden cronológico)."""
+    base = log_dir() / "pdf-tool.log"
+    backup = base.parent / (base.name + ".1")  # como lo nombra RotatingFileHandler
+    return [p for p in (backup, base) if p.exists()]
+
+
+def setup_logging() -> None:
+    """Configura el logger "pdftool" una sola vez (idempotente)."""
+    logger = logging.getLogger(_LOGGER_NAME)
+    if logger.handlers:
+        return
+    logger.setLevel(logging.INFO)
+    logger.propagate = False  # sin ruido de/para el root (pymupdf, flet)
+    # Histórico mínimo a propósito (~32 KB total): basta para diagnosticar el
+    # último fallo sin acumular una bitácora que parezca vigilancia del usuario.
+    handler = RotatingFileHandler(
+        log_dir() / "pdf-tool.log", maxBytes=16_000, backupCount=1, encoding="utf-8"
+    )
+    handler.setFormatter(_SanitizingFormatter(_FORMAT))
+    logger.addHandler(handler)

pdftool/core/naming.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from pdftool.core.errors import UserError
+
+_FORBIDDEN_NAME_CHARS = set('/\\:?|<>*"\x00')
+
+# Nombres que Windows no permite como archivo, con o sin extensión.
+_WINDOWS_RESERVED_NAMES = frozenset(
+    {"CON", "PRN", "AUX", "NUL"}
+    | {f"COM{i}" for i in range(1, 10)}
+    | {f"LPT{i}" for i in range(1, 10)}
+)
+
+
+def parse_output_name(value: str | None) -> str | None:
+    """Sanitiza el nombre de salida escrito por el usuario.
+
+    None si quedó vacío (→ nombre default); sin extensión .pdf (se añade sola
+    en la lógica). Lanza `UserError` si trae separadores de ruta o un nombre
+    reservado por Windows.
+    """
+    name = (value or "").strip()
+    if name.lower().endswith(".pdf"):
+        name = name[:-4].strip()
+    if not name:
+        return None
+    if any(c in _FORBIDDEN_NAME_CHARS for c in name):
+        raise UserError(
+            'Nombre de salida inválido: no puede contener / \\ : ? | < > * "'
+        )
+    if name.upper() in _WINDOWS_RESERVED_NAMES:
+        raise UserError(
+            f"Nombre de salida inválido: «{name}» está reservado por Windows."
+        )
+    return name
+
+
+def unique_path(candidate: Path, taken: Iterable[Path] = ()) -> Path:
+    """Primera ruta libre a partir de `candidate`, con sufijo « (n)».
+
+    Libre = no existe en disco y no está en `taken`. `taken` cubre rutas que
+    aún no se han escrito (p. ej. los archivos de entrada de un lote).
+    """
+    candidate = Path(candidate)
+    blocked = {Path(p) for p in taken}
+
+    def is_free(p: Path) -> bool:
+        return p not in blocked and not p.exists()
+
+    if is_free(candidate):
+        return candidate
+    n = 1
+    while True:
+        alt = candidate.with_name(f"{candidate.stem} ({n}){candidate.suffix}")
+        if is_free(alt):
+            return alt
+        n += 1
+
+
+def output_path(
+    input_path: Path,
+    suffix: str,
+    *,
+    stem: str | None = None,
+    out_dir: Path | None = None,
+) -> Path:
+    """`<stem>_<suffix>.pdf` en `out_dir` si se indica, o junto al original; sin pisar nada.
+
+    `stem` sobrescribe el del archivo de entrada (Comprimir lo usa para no
+    acumular sufijos al reprocesar); `None` significa "usa el del archivo de
+    entrada", pero una cadena vacía es un valor válido y se respeta tal cual.
+    Es el único punto donde se decide dónde va una salida de nombre
+    automático; `taken` garantiza que nunca sea la entrada, con independencia
+    de lo que haya en disco.
+
+    `out_dir` es `None` → junto al original; una ruta → todas las salidas van
+    allí.
+
+    `taken` solo cubre la propia entrada, no el resto de un lote: eso es
+    seguro porque cada herramienta valida que todos los archivos de entrada
+    existan en disco antes de calcular ninguna ruta de salida, y porque cada
+    salida se escribe antes de resolver la siguiente ruta, así que
+    `unique_path` ya la ve en disco.
+    """
+    p = Path(input_path)
+    carpeta = Path(out_dir) if out_dir is not None else p.parent
+    stem_final = stem if stem is not None else p.stem
+    return unique_path(carpeta / f"{stem_final}_{suffix}.pdf", taken=(p,))