firecube 0.1.4__py3-none-any.whl

firecube/cli/_formatter.py

@@ -0,0 +1,195 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Custom Click formatter for clean, grouped help output."""
+
+from __future__ import annotations
+
+import shutil
+from collections.abc import Iterable
+from inspect import cleandoc
+from typing import Any
+
+import click
+
+MAX_WIDTH = 100
+
+# Populated in main.py
+COMMAND_GROUPS: dict[str, list[dict[str, Any]]] = {}
+OPTION_GROUPS: dict[str, list[dict[str, Any]]] = {}
+
+
+class FirecubeFormatter(click.HelpFormatter):
+    """Help formatter: section headers at col 0, tight alignment."""
+
+    def __init__(
+        self,
+        width: int | None = None,
+        max_width: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        terminal_width = min(shutil.get_terminal_size((80, 24)).columns, MAX_WIDTH)
+        resolved_width = width or terminal_width
+        resolved_max_width = max_width or MAX_WIDTH
+        super().__init__(width=resolved_width, max_width=resolved_max_width, **kwargs)
+
+    def write_heading(self, heading: str) -> None:
+        """Write 'Heading:' at column 0."""
+        self.write(f"\n{heading}:\n")
+
+    def write_dl(
+        self,
+        rows: Iterable[tuple[str, str]],
+        col_max: int = 80,
+        col_spacing: int = 2,
+    ) -> None:
+        """Write definition list with tight alignment."""
+        rows_list = list(rows)
+        if not rows_list:
+            return
+
+        max_term = max((len(term) for term, _ in rows_list if term), default=0)
+        col_width = min(max_term + col_spacing, col_max)
+
+        for term, definition in rows_list:
+            if not term:
+                if definition:
+                    self.write(f"\n{definition}:\n")
+                continue
+
+            if definition:
+                self.write(f"  {term:<{col_width}}{definition}\n")
+            else:
+                self.write(f"  {term}\n")
+
+
+class FirecubeGroup(click.Group):
+    """Click Group with COMMAND_GROUPS section rendering."""
+
+    def format_help_text(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        if self.help is None:
+            return
+
+        text = cleandoc(self.help).partition("\f")[0]
+        if not text:
+            return
+
+        formatter.write_paragraph()
+        with formatter.indentation():
+            formatter.write_text(text.split("\n\n", 1)[0] if ctx.parent is None else text)
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        self.format_usage(ctx, formatter)
+        self.format_help_text(ctx, formatter)
+        self._format_commands_grouped(ctx, formatter)
+        self.format_options(ctx, formatter)
+        self.format_epilog(ctx, formatter)
+
+    def format_options(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        _patched_format_options(self, ctx, formatter)
+
+    def _format_commands_grouped(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        command_key = (ctx.command_path or ctx.info_name or self.name or "").split()[-1]
+        groups_config = COMMAND_GROUPS.get(command_key, [])
+        if not groups_config:
+            self.format_commands(ctx, formatter)
+            return
+
+        all_names = [name for group in groups_config for name in group.get("commands", [])]
+        if not all_names:
+            return
+
+        col_width = max(len(name) for name in all_names) + 2
+
+        for group in groups_config:
+            name = group.get("name", "Commands")
+            commands = group.get("commands", [])
+            if not commands:
+                continue
+
+            formatter.write_heading(name)
+            for command_name in commands:
+                command = self.get_command(ctx, command_name)
+                if command is None or command.hidden:
+                    continue
+                help_text = command.get_short_help_str(limit=formatter.width - col_width - 4)
+                formatter.write(f"  {command_name:<{col_width}}{help_text}\n")
+
+
+def _patched_format_options(
+    self: click.Command, ctx: click.Context, formatter: click.HelpFormatter
+) -> None:
+    """Render grouped options when configured for a command path."""
+    groups_config = OPTION_GROUPS.get(ctx.command_path, [])
+
+    if not groups_config:
+        options = []
+        for param in self.get_params(ctx):
+            record = param.get_help_record(ctx)
+            if record is not None:
+                options.append(record)
+        if options:
+            with formatter.section("Options"):
+                formatter.write_dl(options)
+        return
+
+    param_by_name: dict[str, click.Parameter] = {}
+    for param in self.get_params(ctx):
+        for opt in getattr(param, "opts", []):
+            param_by_name[opt] = param
+
+    used: set[int] = set()
+
+    for group in groups_config:
+        rows: list[tuple[str, str]] = []
+        for option_name in group.get("options", []):
+            param = param_by_name.get(option_name)
+            if param is None:
+                continue
+
+            param_id = id(param)
+            if param_id in used:
+                continue
+
+            used.add(param_id)
+            record = param.get_help_record(ctx)
+            if record is not None:
+                rows.append(record)
+
+        if rows:
+            with formatter.section(group.get("name", "Options")):
+                formatter.write_dl(rows)
+
+    remaining = []
+    for param in self.get_params(ctx):
+        if id(param) in used:
+            continue
+        record = param.get_help_record(ctx)
+        if record is not None:
+            remaining.append(record)
+
+    def _is_help_only(record: tuple[str, str]) -> bool:
+        opts = record[0] if isinstance(record, tuple) else str(record)
+        return "-h" in opts and "--help" in opts
+
+    non_help_remaining = [r for r in remaining if not _is_help_only(r)]
+    if non_help_remaining:
+        with formatter.section("Options"):
+            formatter.write_dl(non_help_remaining)
+
+
+def install_option_groups_patch() -> None:
+    """Monkey-patch click.Command.format_options to support OPTION_GROUPS."""
+    click.Command.format_options = _patched_format_options  # type: ignore[method-assign]
+    click.Context.formatter_class = FirecubeFormatter

firecube/cli/_product.py

@@ -0,0 +1,47 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import click
+
+from firecube.core.product.identity import ProductIdentity
+from firecube.core.product.resolver import ProductResolver
+
+
+def require_full_uri(value: str, *, option_name: str) -> None:
+    if value and "://" not in value:
+        raise click.UsageError(
+            f"{option_name} must be a full URI like 's3://bucket/path/x.zarr' or "
+            f"'file:///abs/path/x.zarr'. Bare names are no longer supported. "
+            f"Got: {value!r}"
+        )
+
+
+def resolve_product_identity(
+    value: str,
+    *,
+    format: str,
+    product_name: str,
+    option_name: str = "--product",
+) -> ProductIdentity:
+    require_full_uri(value, option_name=option_name)
+    try:
+        return ProductResolver.resolve(value, format=format, product_name=product_name)
+    except ValueError as exc:
+        raise click.UsageError(str(exc)) from exc
+
+
+def resolve_product_name(value: str, *, format: str = "zarr", product_name: str) -> str:
+    return resolve_product_identity(value, format=format, product_name=product_name).product_name

firecube/cli/_rename_hints.py

@@ -0,0 +1,123 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Click rename-hint layer.
+
+Augments :class:`click.NoSuchOption` errors with a navigation hint when the
+user types a flag that was renamed in the strict-URI refactor.
+
+This is NOT a deprecation alias - the old flag still errors out. It is a UX
+layer that helps migrating users find the new flag name.
+
+Click's native similarity-based "Did you mean ..." suggestion only fires when
+the new flag is a close string match (e.g. ``--product`` -> ``--product-name``).
+For semantic renames where the new name is unrelated (``--source`` ->
+``--input-data``), Click stays silent. This module fills that gap.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+import click
+
+# Renames Click's similarity matcher will NOT auto-suggest.
+# Layout: { old_flag: [ (command_path_prefix, new_flag_text, explanation), ... ] }
+# Most specific prefix wins.
+_RENAME_HINTS: Final[dict[str, list[tuple[tuple[str, ...], str, str]]]] = {
+    "--source": [
+        (
+            ("archive", "restore"),
+            "--archive (-a)",
+            "the .tgm artifact path was renamed to --archive in the strict-URI refactor",
+        ),
+        (
+            ("ingest",),
+            "--input-data (-i)",
+            "the plugin input flag was renamed in the strict-URI refactor; "
+            "--source is now reserved for product URIs (archive create only)",
+        ),
+    ],
+    "--target": [
+        (
+            ("archive", "create"),
+            "--archive (-a)",
+            "the .tgm artifact output was renamed to --archive; "
+            "--target now exclusively refers to product target URIs",
+        ),
+    ],
+}
+
+
+def build_command_path(ctx: click.Context | None) -> tuple[str, ...]:
+    """Build a dotted command path from a Click context chain.
+
+    Excludes the root context (whose ``info_name`` is the program name -
+    ``"firecube"`` in production, ``"cli"`` under :class:`click.testing.CliRunner`).
+    For ``firecube archive restore`` the returned tuple is ``("archive", "restore")``.
+    """
+    if ctx is None:
+        return ()
+    parts: list[str] = []
+    current: click.Context | None = ctx
+    while current is not None and current.parent is not None:
+        if current.info_name:
+            parts.append(current.info_name)
+        current = current.parent
+    return tuple(reversed(parts))
+
+
+def get_rename_hint(option_name: str, command_path: tuple[str, ...]) -> str | None:
+    """Return a hint string for a renamed flag on a specific command, or ``None``.
+
+    Matches by longest command-path prefix - ``("archive", "restore")`` wins
+    over ``("archive",)`` if both registered.
+    """
+    candidates = _RENAME_HINTS.get(option_name)
+    if not candidates:
+        return None
+    # Sort by descending path length so the most specific match wins first.
+    for path_prefix, new_flag, explanation in sorted(candidates, key=lambda entry: -len(entry[0])):
+        if command_path[: len(path_prefix)] == path_prefix:
+            return f"Use {new_flag} instead ({explanation})."
+    return None
+
+
+_INSTALLED_FLAG = "_firecube_rename_hints_installed"
+
+
+def install_rename_hints() -> None:
+    """Monkey-patch :meth:`click.Command.parse_args` once to inject rename hints.
+
+    Subsequent calls are no-ops (idempotent). Safe to call from any module init.
+    """
+    if getattr(click.Command.parse_args, _INSTALLED_FLAG, False):
+        return
+
+    original_parse_args = click.Command.parse_args
+
+    def hinted_parse_args(self: click.Command, ctx: click.Context, args: list[str]) -> list[str]:
+        try:
+            return original_parse_args(self, ctx, args)
+        except click.NoSuchOption as exc:
+            command_path = build_command_path(ctx)
+            hint = get_rename_hint(exc.option_name, command_path)
+            if hint is not None:
+                # Inject hint into the message field. format_message() will pick it up
+                # alongside Click's own "Did you mean ...?" suggestion (if any).
+                object.__setattr__(exc, "message", f"{exc.message}\n\n  Hint: {hint}")
+            raise
+
+    setattr(hinted_parse_args, _INSTALLED_FLAG, True)
+    click.Command.parse_args = hinted_parse_args  # type: ignore[method-assign]

firecube/cli/_shared_options.py

@@ -0,0 +1,247 @@
+# Copyright 2025-2026 EUMETSAT
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+import click
+
+__all__ = [
+    "archive_uri_option",
+    "config_file_option",
+    "dry_run_flag",
+    "format_option",
+    "product_filter_option",
+    "product_name_option",
+    "product_uri_option",
+    "storage_driver_option",
+    "storage_type_option",
+    "target_uri_option",
+    "workspace_option",
+    "write_mode_option",
+    "yes_flag",
+]
+
+
+def _uri_shell_complete(ctx: click.Context, param: click.Parameter, incomplete: str) -> list[Any]:
+    from click.shell_completion import CompletionItem
+
+    return [CompletionItem(incomplete, type="file")]
+
+
+def workspace_option(f: Any) -> Any:
+    return click.option(
+        "--workspace",
+        type=click.Path(path_type=Path),
+        help="workspace directory override",
+    )(f)
+
+
+def config_file_option(f: Any) -> Any:
+    return click.option(
+        "--config-file",
+        type=click.Path(path_type=Path),
+        help="Firecube TOML config file (default: ~/.config/firecube/config.toml)",
+    )(f)
+
+
+def storage_type_option(
+    f: Any = None,
+    *,
+    required: bool = True,
+    extra_help: str = "",
+) -> Any:
+    def decorator(func: Any) -> Any:
+        help_text = f"Storage locality/class. {extra_help}".strip()
+        return click.option(
+            "--storage-type",
+            "storage_type",
+            required=required,
+            type=click.Choice(["local", "s3"], case_sensitive=False),
+            help=help_text,
+        )(func)
+
+    if callable(f):
+        return decorator(f)
+    return decorator
+
+
+def storage_driver_option(
+    f: Any = None,
+    *,
+    required: bool = True,
+    extra_help: str = "",
+) -> Any:
+    def decorator(func: Any) -> Any:
+        help_text = f"Storage backend driver. {extra_help}".strip()
+        return click.option(
+            "--storage-driver",
+            "storage_driver",
+            required=required,
+            type=click.Choice(["fsspec", "obstore"], case_sensitive=False),
+            help=help_text,
+        )(func)
+
+    if callable(f):
+        return decorator(f)
+    return decorator
+
+
+def write_mode_option(
+    f: Any = None,
+    *,
+    required: bool = True,
+    extra_help: str = "",
+) -> Any:
+    def decorator(func: Any) -> Any:
+        help_text = (
+            f"Write strategy (staged=workspace-first, direct=stream to target). {extra_help}"
+        ).strip()
+        return click.option(
+            "-w",
+            "--write-mode",
+            "write_mode",
+            required=required,
+            type=click.Choice(["staged", "direct"], case_sensitive=False),
+            help=help_text,
+        )(func)
+
+    if callable(f):
+        return decorator(f)
+    return decorator
+
+
+def product_uri_option(tier: Literal["write", "inspect"]) -> Any:
+    help_text = (
+        "Firecube product URI (file:///abs/path or s3://bucket/key); storage flags inferred from URI scheme."
+        if tier == "inspect"
+        else "Firecube product URI; --storage-type must match URI scheme."
+    )
+
+    def decorator(func: Any) -> Any:
+        return click.option(
+            "-p",
+            "--product",
+            "product",
+            required=True,
+            type=str,
+            help=help_text,
+            shell_complete=_uri_shell_complete,
+        )(func)
+
+    return decorator
+
+
+def target_uri_option(tier: Literal["write", "inspect"]) -> Any:
+    help_text = (
+        "Target Firecube product URI (file:///abs/path or s3://bucket/key); storage flags inferred from URI scheme."
+        if tier == "inspect"
+        else "Target Firecube product URI; --storage-type must match URI scheme."
+    )
+
+    def decorator(func: Any) -> Any:
+        return click.option(
+            "-t",
+            "--target",
+            "target",
+            required=True,
+            type=str,
+            help=help_text,
+            shell_complete=_uri_shell_complete,
+        )(func)
+
+    return decorator
+
+
+def archive_uri_option(tier: Literal["write", "inspect"]) -> Any:
+    """Shared -a, --archive URI flag for write and inspect commands."""
+    help_text = {
+        "write": "Target archive URI; runtime decides what is supported (file:///abs/path or s3://bucket/key).",
+        "inspect": "Archive URI to inspect (file:///abs/path or s3://bucket/key).",
+    }[tier]
+
+    def decorator(func: Any) -> Any:
+        return click.option(
+            "-a",
+            "--archive",
+            "archive",
+            type=str,
+            required=True,
+            help=help_text,
+            shell_complete=_uri_shell_complete,
+        )(func)
+
+    return decorator
+
+
+def format_option(default: str = "table") -> Any:
+    def decorator(f: Any) -> Any:
+        return click.option(
+            "-f",
+            "--format",
+            "output_format",
+            type=click.Choice(["table", "json", "csv"], case_sensitive=False),
+            default=default,
+            show_default=True,
+            help="Output format.",
+        )(f)
+
+    return decorator
+
+
+def product_filter_option(required: bool = False) -> Any:
+    def decorator(f: Any) -> Any:
+        return click.option(
+            "-n",
+            "--product-name",
+            "product_name",
+            required=required,
+            help="Filter by product name.",
+        )(f)
+
+    return decorator
+
+
+def product_name_option(required: bool = True) -> Any:
+    def decorator(f: Any) -> Any:
+        return click.option(
+            "--product-name",
+            "product_name",
+            required=required,
+            help="Logical product name.",
+        )(f)
+
+    return decorator
+
+
+def dry_run_flag(f: Any) -> Any:
+    return click.option(
+        "--dry-run",
+        "dry_run",
+        is_flag=True,
+        default=False,
+        help="Show what would happen without making any changes.",
+    )(f)
+
+
+def yes_flag(f: Any) -> Any:
+    return click.option(
+        "--yes-i-really-mean-it",
+        "yes_i_really_mean_it",
+        is_flag=True,
+        default=False,
+        help="Skip confirmation prompts. Required for destructive operations in non-TTY.",
+    )(f)