morphconv 1.0.1__py3-none-any.whl

morph/history.py

@@ -0,0 +1,136 @@
+"""
+history.py — persistent conversion log.
+
+Every conversion (single or batch) appends one line to
+~/.morph_history.jsonl.  Entries record source, destination,
+route, timing, and success/failure.  The `morph history`
+subcommand reads this file back and renders a rich table.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+HISTORY_FILE = Path.home() / ".morph_history.jsonl"
+
+
+@dataclass
+class HistoryEntry:
+    ts: str
+    src_path: str
+    src_fmt: str
+    dst_path: str
+    dst_fmt: str
+    route: str
+    backend: str
+    success: bool
+    elapsed_s: float
+    mode: str = "single"          # "single" | "batch"
+    batch_id: Optional[str] = None
+    error: Optional[str] = None
+    extra: dict = field(default_factory=dict)
+
+
+def append_entry(entry: HistoryEntry) -> None:
+    """Append one entry to the history JSONL file."""
+    try:
+        with open(HISTORY_FILE, "a", encoding="utf-8") as f:
+            f.write(json.dumps(asdict(entry), ensure_ascii=False) + "\n")
+    except OSError:
+        pass  # never let history I/O break a conversion
+
+
+def read_entries(
+    *,
+    limit: int = 20,
+    failed_only: bool = False,
+    fmt_filter: Optional[str] = None,
+) -> list[HistoryEntry]:
+    """Read the last `limit` entries, optionally filtered."""
+    if not HISTORY_FILE.exists():
+        return []
+    entries: list[HistoryEntry] = []
+    try:
+        with open(HISTORY_FILE, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    d = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                entry = HistoryEntry(
+                    ts=d.get("ts", ""),
+                    src_path=d.get("src_path", ""),
+                    src_fmt=d.get("src_fmt", ""),
+                    dst_path=d.get("dst_path", ""),
+                    dst_fmt=d.get("dst_fmt", ""),
+                    route=d.get("route", ""),
+                    backend=d.get("backend", ""),
+                    success=d.get("success", True),
+                    elapsed_s=d.get("elapsed_s", 0.0),
+                    mode=d.get("mode", "single"),
+                    batch_id=d.get("batch_id"),
+                    error=d.get("error"),
+                    extra=d.get("extra", {}),
+                )
+                if failed_only and entry.success:
+                    continue
+                if fmt_filter:
+                    norm = fmt_filter.lower().lstrip(".")
+                    if norm not in (entry.src_fmt.lower(), entry.dst_fmt.lower()):
+                        continue
+                entries.append(entry)
+    except OSError:
+        return []
+    return entries[-limit:]
+
+
+def clear() -> bool:
+    """Delete the history file.  Returns True if it existed."""
+    if HISTORY_FILE.exists():
+        HISTORY_FILE.unlink()
+        return True
+    return False
+
+
+def make_entry(
+    src_path: Path,
+    src_fmt: str,
+    dst_path: Path,
+    dst_fmt: str,
+    route: str,
+    backend: str,
+    success: bool,
+    elapsed_s: float,
+    *,
+    mode: str = "single",
+    batch_id: Optional[str] = None,
+    error: Optional[str] = None,
+) -> HistoryEntry:
+    """Helper to build and return a HistoryEntry."""
+    return HistoryEntry(
+        ts=datetime.now().strftime("%Y-%m-%dT%H:%M:%S"),
+        src_path=str(src_path),
+        src_fmt=src_fmt,
+        dst_path=str(dst_path),
+        dst_fmt=dst_fmt,
+        route=route,
+        backend=backend,
+        success=success,
+        elapsed_s=round(elapsed_s, 2),
+        mode=mode,
+        batch_id=batch_id,
+        error=error,
+    )
+
+
+def generate_batch_id() -> str:
+    """Short unique id for grouping batch entries."""
+    return f"b-{datetime.now().strftime('%Y%m%d-%H%M%S')}"

morph/progress.py

@@ -0,0 +1,78 @@
+"""
+progress.py — live status while a hop runs.
+
+Every conversion function is a blocking call (subprocess.run, Pillow, a
+pandas loop, ...). To show *something* live instead of a dead terminal:
+
+  • If the spec supports real progress (currently: ffmpeg-backed hops), the
+    function is called in a background thread with a `_progress(frac, status)`
+    callback injected, and a determinate Rich progress bar tracks it.
+  • Otherwise, the function still runs in a background thread, but the
+    foreground just shows an indeterminate spinner with the backend name
+    ("via pandoc", "via ffmpeg", ...) — so it's always visible *what* is
+    doing the work, even when we can't say how far along it is.
+
+Rich's Progress has its own auto-refreshing Live display, so a plain
+`thread.join()` on the main thread is enough — no manual polling loop needed.
+"""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+
+from .registry import ConversionResult, ConverterSpec
+
+
+def run_hop(spec: ConverterSpec, input_path: Path, output_path: Path,
+            options: dict[str, Any], console: Console, *, quiet: bool = False) -> ConversionResult:
+    if quiet:
+        call_options = dict(options)
+        if spec.supports_progress:
+            call_options["_progress"] = lambda frac, status: None
+        return spec.func(input_path, output_path, **call_options)
+
+    label = f"{spec.src} → {spec.dst}"
+    tool_tag = f"[muted]via {spec.backend}[/muted]"
+
+    result_box: dict[str, Any] = {}
+    error_box: dict[str, BaseException] = {}
+
+    columns = [
+        SpinnerColumn(style="cyan"),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(bar_width=28),
+        TextColumn("[muted]{task.fields[status]}[/muted]"),
+        TimeElapsedColumn(),
+    ]
+
+    with Progress(*columns, console=console, transient=True) as progress:
+        total = 100 if spec.supports_progress else None
+        task_id = progress.add_task(f"{label}  {tool_tag}", total=total, status="")
+
+        def _on_progress(frac: float, status: str) -> None:
+            progress.update(task_id, completed=frac * 100, status=status)
+
+        def _target() -> None:
+            try:
+                call_options = dict(options)
+                if spec.supports_progress:
+                    call_options["_progress"] = _on_progress
+                result_box["result"] = spec.func(input_path, output_path, **call_options)
+            except BaseException as exc:  # noqa: BLE001 — re-raised on the main thread below
+                error_box["error"] = exc
+
+        thread = threading.Thread(target=_target, daemon=True)
+        thread.start()
+        thread.join()
+
+        if not error_box:
+            progress.update(task_id, completed=100, status="done")
+
+    if "error" in error_box:
+        raise error_box["error"]
+    return result_box["result"]

morph/registry.py

@@ -0,0 +1,236 @@
+"""
+registry.py — the heart of morph's "anything to anything" engine.
+
+Every converter (native Python or a wrapper around an external binary like
+pandoc/ffmpeg) registers itself as a directed edge: src format -> dst format.
+morph then does a breadth-first search over that graph so that even formats
+with no *direct* converter can still be reached via a chain
+(e.g. odt -> docx -> pdf), as long as every edge on the path is registered.
+
+Nothing in here knows about pandoc, ffmpeg, or pandas specifically — that
+knowledge lives in morph/converters/*.py, which import `register` from here
+and populate the graph at import time.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+
+@dataclass
+class ConversionResult:
+    """What every converter function returns."""
+    output: Path
+    rows: Optional[int] = None      # for tabular data
+    pages: Optional[int] = None     # for documents
+    duration: Optional[float] = None  # seconds, for audio/video
+    extra: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class OptionSpec:
+    """One CLI flag a converter accepts, e.g. --table-style or --no-header.
+
+    `name` must match the keyword argument the converter function expects.
+    `action` mirrors argparse: "store_true"/"store_false" for flags, None for
+    a value-taking option (parsed as `type`).
+    """
+    name: str
+    flags: tuple[str, ...]
+    help: str = ""
+    default: object = None
+    type: type = str
+    action: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ConverterSpec:
+    src: str
+    dst: str
+    func: Callable[..., ConversionResult]
+    backend: str                       # "native" | "pandoc" | "ffmpeg" | ...
+    requires_binary: Optional[str] = None
+    family: str = "data"               # data | document | image | audio | video | archive | font | ebook
+    description: str = ""
+    lossy: bool = False                # flag conversions that can't round-trip cleanly
+    options: tuple[OptionSpec, ...] = field(default_factory=tuple)
+    supports_progress: bool = False    # True if func accepts a `_progress(frac, status)` kwarg
+
+    @property
+    def key(self) -> tuple[str, str]:
+        return (self.src, self.dst)
+
+
+class Registry:
+    def __init__(self) -> None:
+        self._edges: dict[tuple[str, str], ConverterSpec] = {}
+
+    def register(
+        self,
+        src: str,
+        dst: str,
+        *,
+        backend: str,
+        requires_binary: Optional[str] = None,
+        family: str = "data",
+        description: str = "",
+        lossy: bool = False,
+        options: Optional[list[OptionSpec]] = None,
+        supports_progress: bool = False,
+    ):
+        """Decorator: register `func` as a converter for src -> dst."""
+        def deco(func: Callable[..., ConversionResult]):
+            spec = ConverterSpec(
+                src=_norm(src), dst=_norm(dst), func=func, backend=backend,
+                requires_binary=requires_binary, family=family,
+                description=description, lossy=lossy,
+                options=tuple(options or ()), supports_progress=supports_progress,
+            )
+            self._edges[spec.key] = spec
+            return func
+        return deco
+
+    def all_formats(self) -> set[str]:
+        fmts: set[str] = set()
+        for s, d in self._edges:
+            fmts.add(s)
+            fmts.add(d)
+        return fmts
+
+    def direct(self, src: str, dst: str) -> Optional[ConverterSpec]:
+        return self._edges.get((_norm(src), _norm(dst)))
+
+    def find_path(self, src: str, dst: str) -> Optional[list[ConverterSpec]]:
+        """BFS shortest conversion path (fewest hops) from src to dst."""
+        src, dst = _norm(src), _norm(dst)
+        if src == dst:
+            return []
+
+        graph: dict[str, list[ConverterSpec]] = {}
+        for spec in self._edges.values():
+            graph.setdefault(spec.src, []).append(spec)
+
+        visited = {src}
+        queue: deque[tuple[str, list[ConverterSpec]]] = deque([(src, [])])
+        while queue:
+            node, path = queue.popleft()
+            for spec in graph.get(node, []):
+                if spec.dst == dst:
+                    return path + [spec]
+                if spec.dst not in visited:
+                    visited.add(spec.dst)
+                    queue.append((spec.dst, path + [spec]))
+        return None
+
+    def reachable_targets(self, src: str) -> dict[str, list[ConverterSpec]]:
+        """Every format reachable from src, mapped to the path that gets there."""
+        src = _norm(src)
+        graph: dict[str, list[ConverterSpec]] = {}
+        for spec in self._edges.values():
+            graph.setdefault(spec.src, []).append(spec)
+
+        results: dict[str, list[ConverterSpec]] = {}
+        visited = {src}
+        queue: deque[tuple[str, list[ConverterSpec]]] = deque([(src, [])])
+        while queue:
+            node, path = queue.popleft()
+            for spec in graph.get(node, []):
+                if spec.dst not in visited:
+                    visited.add(spec.dst)
+                    new_path = path + [spec]
+                    results[spec.dst] = new_path
+                    queue.append((spec.dst, new_path))
+        return results
+
+    def combined_options(self, path: list[ConverterSpec]) -> list[OptionSpec]:
+        """All options across every hop in a path, flattened for the CLI parser."""
+        combined: list[OptionSpec] = []
+        seen_flags: set[str] = set()
+        for spec in path:
+            for opt in spec.options:
+                colliding = seen_flags & set(opt.flags)
+                if colliding:
+                    # two hops in the same chain want the same flag name — extremely
+                    # unlikely given today's converters, but fail loudly rather than
+                    # silently letting one shadow the other.
+                    raise ValueError(
+                        f"Flag collision on {colliding} between hops in this conversion path"
+                    )
+                seen_flags.update(opt.flags)
+                combined.append(opt)
+        return combined
+
+    def all_options(self) -> dict[str, list[OptionSpec]]:
+        """All options across the entire registry, grouped by family."""
+        families: dict[str, list[OptionSpec]] = {}
+        seen_names: set[str] = set()
+        
+        for spec in self._edges.values():
+            for opt in spec.options:
+                if opt.name not in seen_names:
+                    seen_names.add(opt.name)
+                    families.setdefault(spec.family, []).append(opt)
+                    
+        return families
+
+    def known_binaries(self) -> set[str]:
+        return {spec.requires_binary for spec in self._edges.values() if spec.requires_binary}
+
+    def required_binaries(self, path: list[ConverterSpec]) -> list[str]:
+        seen: list[str] = []
+        for spec in path:
+            if spec.requires_binary and spec.requires_binary not in seen:
+                seen.append(spec.requires_binary)
+        return seen
+
+    def formats_by_family(self) -> dict[str, set[str]]:
+        """All formats grouped by their converter family."""
+        families: dict[str, set[str]] = {}
+        for spec in self._edges.values():
+            families.setdefault(spec.family, set()).add(spec.src)
+            families.setdefault(spec.family, set()).add(spec.dst)
+        return families
+
+    def edges_by_family(self) -> dict[str, list[ConverterSpec]]:
+        """All direct edges grouped by family."""
+        families: dict[str, list[ConverterSpec]] = {}
+        for spec in self._edges.values():
+            families.setdefault(spec.family, []).append(spec)
+        return families
+
+    def family_backends(self) -> dict[str, set[str]]:
+        """Primary backends used by each family."""
+        result: dict[str, set[str]] = {}
+        for spec in self._edges.values():
+            result.setdefault(spec.family, set()).add(spec.backend)
+        return result
+
+
+def _norm(fmt: str) -> str:
+    return fmt.lower().lstrip(".")
+
+
+# extensions where the true format spans more than one suffix
+_COMPOUND_EXTENSIONS = {
+    ".tar.gz": "tar.gz", ".tgz": "tar.gz",
+    ".tar.bz2": "tar.bz2", ".tbz2": "tar.bz2",
+    ".tar.xz": "tar.xz", ".txz": "tar.xz",
+}
+
+
+def detect_format(path: Path) -> str:
+    """Format id for a file path, correctly handling compound extensions
+    like .tar.gz (where Path.suffix alone would only see '.gz')."""
+    name = path.name.lower()
+    for ext, fmt in _COMPOUND_EXTENSIONS.items():
+        if name.endswith(ext):
+            return fmt
+    return _norm(path.suffix)
+
+
+# Single shared instance every converter module registers against.
+registry = Registry()
+register = registry.register