yd-cli 0.3__py3-none-any.whl

yd/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: Christian Heinze
+#
+# SPDX-License-Identifier: MIT
+"""The yd synchronization tool.
+
+Do not directly import items from this module (e.g. `from yd import io`) which
+triggers `__getattr__` and thereby eager importing of the module. Instead, import
+`yd` and use attribute access.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.metadata
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from types import ModuleType
+
+    from yd import commands, execution, io, types
+else:
+
+    def __getattr__(key: str, /) -> ModuleType:
+        if key in __all__:
+            return importlib.import_module(f"{__package__}.{key}", package=__package__)
+        raise AttributeError(f"module `{__name__}` has not attribute `{key}`")
+
+
+__version__ = importlib.metadata.version("yd-cli")
+__all__ = ["__version__", "commands", "io", "execution", "types"]

yd/__main__.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: Christian Heinze
+#
+# SPDX-License-Identifier: MIT
+"""CLI entry point."""
+
+from __future__ import annotations
+
+if __name__ == "__main__":
+    from yd import cli
+
+    cli.app()

yd/cli.py

@@ -0,0 +1,484 @@
+# SPDX-FileCopyrightText: Christian Heinze
+#
+# SPDX-License-Identifier: MIT
+"""CLI."""
+
+# ruff: noqa: PLC0415
+
+from __future__ import annotations
+
+import dataclasses
+import itertools as it
+import re
+import sys
+from typing import TYPE_CHECKING, Annotated
+
+import rich.console
+import rich.highlighter
+import rich.theme
+import typer
+
+import yd
+
+if TYPE_CHECKING:
+    import enum
+    from collections.abc import Callable
+    from collections.abc import Set as AbstractSet
+
+    from rich.text import Text
+
+env: yd.types.Environment
+console: rich.console.Console
+highlighter: StrEnumHighlighter
+
+
+@dataclasses.dataclass(slots=True)
+class StrEnumHighlighter[T: enum.StrEnum](
+    # Solely defines a __call__ method wrapping the abstract method `highlight`.
+    rich.highlighter.Highlighter
+):
+    enum_type: type[T]
+
+    _: dataclasses.KW_ONLY
+    ignore: AbstractSet[T] = dataclasses.field(default_factory=set)
+    base_style_name: str | None = None
+
+    @property
+    def base_style(self) -> str:
+        return (
+            self.enum_type.__qualname__.lower()
+            if self.base_style_name is None
+            else self.base_style_name
+        )
+
+    def highlight(self, text: Text) -> None:
+        base_style, hl = self.base_style, text.highlight_regex
+        for cat in self.enum_type:
+            if cat in self.ignore:
+                continue
+            # Using `__str__` instead of `cat.name.lower()` for more flexibility.
+            hl(rf"(?P<{cat}>{cat})", style_prefix=base_style)
+
+    def create_theme_addon(self, *, styler: Callable[[T], str]) -> dict[str, str]:
+        base_style = self.base_style
+        return {
+            base_style + str(cat): styler(cat)
+            for cat in self.enum_type
+            if cat not in self.ignore
+        }
+
+
+def _action_styler(action: yd.types.Action) -> str:
+    match action:
+        case yd.types.Action.CREATE:
+            return "bold #000020 on #0050aa"
+        case yd.types.Action.COPY:
+            return "bold white on #006020"
+        case yd.types.Action.DELETE:
+            return "bold #200000 on #aa0000"
+        case yd.types.Action.HARDLINK:
+            return "bold white on #606060"
+        case yd.types.Action.ATTRUPDATE:
+            return "bold white on #606060"
+
+
+def _setup_rich_devices() -> tuple[rich.console.Console, StrEnumHighlighter]:
+    highlighter = StrEnumHighlighter(
+        yd.types.Action, ignore={yd.types.Action.ATTRUPDATE}
+    )
+    theme = rich.theme.Theme(
+        highlighter.create_theme_addon(styler=_action_styler)
+        | {
+            "progress.elapsed": "bold #ffffaa",
+            "info": "italic #000090",
+            "warning": "bold #900000",
+            "error": "bold #ff0000",
+        }
+    )
+    console = rich.console.Console(highlighter=highlighter, theme=theme)
+    return console, highlighter
+
+
+_YD_HELP = """
+Build and execute `rsync` commands from TOML configuration files.
+
+Configuration files live in `~/.config/yd/`. If `XDG_CONFIG_HOME` is set, it
+replaces only the `~/.config` part, so configurations are loaded from
+`$XDG_CONFIG_HOME/yd/`. Relative `src_home` and `target_home` paths are
+resolved from your home directory. Use `yd edit NAME` to edit an existing
+configuration, or `yd edit --new NAME` to create one; `EDITOR` must be set for
+this command. Use `yd run NAME` to execute a configuration and `yd ls` to show
+available configurations together with their descriptions.
+"""
+
+app = typer.Typer(help=_YD_HELP, no_args_is_help=True, rich_markup_mode="markdown")
+
+
+@app.callback()
+def _setup_io() -> None:
+    global env, console, highlighter  # noqa: PLW0603
+
+    import logging
+    from pathlib import Path
+
+    console, highlighter = _setup_rich_devices()
+    try:
+        env = yd.io.capture_environment()
+    except yd.types.EnvCaptureError as err:
+        console.print("Failed to capture environment.", style="error")
+        raise typer.Exit(2) from err
+
+    if env.log_level is not None:
+        logging.basicConfig(
+            filename=Path.cwd() / ".yd.log",
+            encoding="utf-8",
+            level=env.log_level,
+            force=True,
+        )
+
+
+def _description_column_width(min_width: int = 50) -> int:
+    import shutil
+
+    non_desc_with = (
+        10  # time elapsed
+        + 2  # dir symbol
+        + sum(
+            len(cat.name) + 10
+            for cat in highlighter.enum_type
+            if cat not in highlighter.ignore
+        )
+    )
+    return max(min_width, shutil.get_terminal_size().columns - non_desc_with)
+
+
+def _create_description(path: str, *, max_len: int, prefix: str = "...") -> str:
+    from pathlib import Path
+
+    if len(label := path) <= max_len:
+        return label
+
+    path_ = Path(path)
+    reversed_chosen_parts = tuple(
+        part
+        for part, cum_len in zip(
+            reversed(path_.parts),
+            it.accumulate(len(s) for s in reversed(path_.parts)),
+            strict=True,
+        )
+        if cum_len <= max_len
+    )
+    base = "/".join(reversed(reversed_chosen_parts))
+    if len(base) <= max_len:
+        return base
+    return f"{prefix}{base[-(max_len - len(prefix)) :]}"
+
+
+# Use `list` as return value since type must be available at runtime for typer to work.
+def _complete_config_name(incomplete: str, /) -> list[str]:
+    return [
+        path.stem
+        for path in env.config_dir.glob("*.toml")
+        if re.match(incomplete, path.stem, re.IGNORECASE)
+    ]
+
+
+def _read_from_stdin(opt: str, /) -> str:
+    value = sys.stdin.read().strip()
+    if not value:
+        raise typer.BadParameter(f"no input via STDIN; `{opt}` cannot be determined")
+    return value
+
+
+def _resolve_home(
+    *, src: str | None, target: str | None
+) -> tuple[str | None, str | None]:
+    if src == "-" and target == "-":
+        raise typer.BadParameter(
+            "only one of `src-home` and `target-home` can be read from stdin."
+        )
+    if src == "-":
+        return _read_from_stdin("src-home"), target
+    if target == "-":
+        return src, _read_from_stdin("target-home")
+    return src, target
+
+
+def _require_nonempty(param: typer.CallbackParam, v: str | None) -> str | None:
+    if v is None or v:
+        return v
+    raise typer.BadParameter(f"parameter `{param.name}` must not be an empty string")
+
+
+@app.command()
+def run(
+    # Considered allowing absolute path here (to skip lookup logic). However, can be
+    # handled via setting an environment variable; not extra handling needed.
+    cfg_name: Annotated[
+        str,
+        typer.Argument(
+            help="Configuration name. Must match the TOML file name without `.toml`.",
+            autocompletion=_complete_config_name,
+            callback=_require_nonempty,
+        ),
+    ],
+    *,
+    no_backup: Annotated[
+        bool,
+        typer.Option(
+            "--no-backup",
+            help="Disable backup handling for this run.",
+            rich_help_panel="Sync options",
+        ),
+    ] = False,
+    keep_newer: Annotated[
+        bool,
+        typer.Option(
+            "--keep-newer",
+            help="Skip updates when the target file is newer.",
+            rich_help_panel="Sync options",
+        ),
+    ] = False,
+    rename_speedup: Annotated[
+        bool,
+        typer.Option(
+            "--rename-speedup",
+            help="Enable rsync options tuned for rename-heavy targets."
+            " This may require more disk space on the target.",
+            rich_help_panel="Sync options",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "--dry-run",
+            help="Show what would happen without changing files.",
+        ),
+    ] = False,
+    src_home: Annotated[
+        str | None,
+        typer.Option(
+            "--src-home",
+            rich_help_panel="Location options",
+            help="Override `src_home` from the configuration."
+            " Use '-' to read the value from stdin.",
+            callback=_require_nonempty,
+        ),
+    ] = None,
+    target_home: Annotated[
+        str | None,
+        typer.Option(
+            "--target-home",
+            rich_help_panel="Location options",
+            help="Override `target_home` from the configuration."
+            " Use '-' to read the value from stdin.",
+            callback=_require_nonempty,
+        ),
+    ] = None,
+) -> int:
+    """Run a saved configuration by name."""
+    import asyncio
+    import functools
+    from pathlib import Path
+
+    import rich.progress
+    import rich.table
+
+    try:
+        cfg = yd.io.load_command_group(env.config_dir / f"{cfg_name}.toml")
+    except yd.types.ConfigLoadError as err:
+        console.print(str(err), style="error")
+        raise typer.Exit(2) from err
+
+    res_src_home, res_target_home = _resolve_home(src=src_home, target=target_home)
+    try:
+        commands = list(
+            yd.commands.create(
+                cfg,
+                env=env,
+                src_home=res_src_home,
+                target_home=res_target_home,
+                dry_run=dry_run,
+                keep_newer=keep_newer,
+                rename_speedup=rename_speedup,
+                no_backup=no_backup,
+                error_encoder=yd.io.encode_error,
+            )
+        )
+    except yd.types.CommandBuildError as err:
+        console.print(str(err), style="error")
+        raise typer.Exit(2) from err
+
+    with (
+        asyncio.Runner() as runner,
+        rich.progress.Progress(
+            rich.progress.TimeElapsedColumn(table_column=rich.table.Column(width=8)),
+            rich.progress.TextColumn(
+                ":file_folder:",
+                table_column=rich.table.Column(width=2),
+            ),
+            rich.progress.TextColumn(
+                "{task.description}",
+                table_column=rich.table.Column(width=_description_column_width()),
+            ),
+            *it.chain.from_iterable(
+                (
+                    rich.progress.TextColumn(
+                        action_name,
+                        justify="right",
+                        highlighter=highlighter,
+                        table_column=rich.table.Column(width=len(action_name)),
+                    ),
+                    rich.progress.TextColumn(
+                        f"{{task.fields[{action_name}]}}",
+                        justify="right",
+                        table_column=rich.table.Column(min_width=7),
+                    ),
+                )
+                for action_name in (
+                    str(cat)
+                    for cat in highlighter.enum_type
+                    if cat not in highlighter.ignore
+                )
+            ),
+            console=console,
+        ) as progress,
+    ):
+        template = "{action} {filename} ({transfer_bytes} bytes)"
+
+        async def show_progress(
+            item: str | yd.types.Transaction | None,
+            *,
+            counter: dict[str, int],
+            taskid: rich.progress.TaskID,
+            target: Path,
+        ) -> None:
+            match item:
+                case str() as text:
+                    console.print(text, style="info")
+                    return
+                case yd.types.Transaction() as transaction:
+                    if transaction.action is yd.types.Action.ATTRUPDATE:
+                        return
+
+                    console.print(
+                        template.format(
+                            action=transaction.action,
+                            filename=target.joinpath(transaction.filename).as_posix()
+                            if not Path(transaction.filename).is_absolute()
+                            else transaction.filename,
+                            transfer_bytes=transaction.transfer_bytes,
+                        )
+                    )
+                    counter[str(transaction.action)] += 1
+                    progress.update(
+                        taskid,
+                        **counter,  # type: ignore[ty:invalid-argument-type]
+                    )
+
+        for binary, args in commands:
+            counter = {str(action): 0 for action in yd.types.Action}
+            taskid = progress.add_task(
+                description=_create_description(
+                    args[-1], max_len=_description_column_width()
+                ),
+                **counter,  # type: ignore[ty:invalid-argument-type]
+                total=1,
+            )
+            try:
+                runner.run(
+                    yd.execution.run(
+                        binary,
+                        *args,
+                        parser_stdout=yd.io.decode_from_stdout,
+                        parser_stderr=yd.io.decode_from_stderr,
+                        consumer=functools.partial(
+                            show_progress,
+                            counter=counter,
+                            taskid=taskid,
+                            target=Path(args[-1]),
+                        ),
+                    )
+                )
+            except (yd.types.OutputParseError, yd.types.OutputConsumeError) as err:
+                console.print("Failed to handle rsync output.", style="error")
+                raise typer.Exit(2) from err
+            progress.update(taskid, completed=1)
+
+    return 0
+
+
+@app.command(name="ls")
+def list_configs() -> int:
+    """List available configurations and their descriptions."""
+    import rich.table
+
+    configs = list(yd.io.list_available_configs(env.config_dir))
+    if not configs:
+        console.print("No configurations found.", style="warning")
+        return 0
+
+    table = rich.table.Table()
+    table.add_column("Configuration", style="bold")
+    table.add_column("Description", style="bold")
+    for config in configs:
+        table.add_row(config.name, config.description or "")
+    console.print(table)
+    return 0
+
+
+@app.command()
+def edit(
+    cfg_name: Annotated[
+        str | None,
+        typer.Argument(
+            help="Configuration name. Must match the TOML file name without `.toml`.",
+            autocompletion=_complete_config_name,
+            callback=_require_nonempty,
+        ),
+    ] = None,
+    *,
+    new: Annotated[
+        bool,
+        typer.Option("--new", help="Create a new configuration before opening it."),
+    ] = False,
+) -> int:
+    """Open an existing configuration or create a new one in the editor."""
+    import contextlib
+    import subprocess
+
+    if (editor_bin := env.editor_bin) is None:
+        raise typer.BadParameter("environment variable `EDITOR` is not set")
+
+    is_nvim = False
+    with contextlib.suppress(subprocess.CalledProcessError):
+        vers = subprocess.run(
+            [editor_bin, "--version"], encoding="utf-8", capture_output=True, check=True
+        ).stdout
+        is_nvim = re.match(r"\s*NVIM", vers) is not None
+
+    config_path = env.config_dir / f"{cfg_name}.toml"
+    if config_path.exists():
+        if new:
+            raise typer.BadParameter(f"Configuration '{cfg_name}' already exists.")
+        args: tuple[str, ...] = (config_path.as_posix(),)
+        input_: str | None = None
+    elif new and is_nvim:
+        args = (
+            "-",
+            "+setlocal filetype=toml",
+            f"+file {config_path.as_posix()}",
+        )
+        input_ = yd.commands.CONFIG_TEMPLATE.lstrip()
+    elif new:
+        config_path.write_text(yd.commands.CONFIG_TEMPLATE.lstrip(), encoding="utf-8")
+        args, input_ = (config_path.as_posix(),), None
+    else:
+        raise typer.BadParameter(
+            f"Configuration '{cfg_name}' does not exist. Use '--new' to create it."
+        )
+
+    completed = subprocess.run(
+        (editor_bin, *args), input=input_, encoding="utf-8", check=False
+    )
+    return completed.returncode