multicloud-cli 0.1.0__py3-none-any.whl

multicloud_cli/catalog.py

@@ -0,0 +1,311 @@
+"""``mctl catalog``: find servers and prices in the Multicloud catalog.
+
+These commands call ``/api/v1/catalog/...`` (the catalog belongs to the platform, not to one organization). An API
+key needs the ``catalog`` scope. The key comes from ``mctl auth`` (or ``MULTICLOUD_API_KEY``, which needs no org);
+a stored key is found by ``--org``/``MULTICLOUD_ORG`` or the saved config. An SSO sign-in needs no org.
+The filter options of ``catalog search`` carry the API parameter name verbatim (``--min-vcpus`` and ``--min_vcpus``).
+"""
+import json
+import sys
+from typing import Any, Dict, List, Optional
+
+import click
+
+from . import api, exitcodes
+from .orgopt import org_group
+from .output import dump as _dump, json_option, no_headers_option, plain as _plain, quiet_option, run, table as _table
+
+SCOPE = "catalog"
+
+# One entry per field of the catalog API's ServerFilter: the API name, the type, the help.
+# The contract test fails when this list and the API drift apart, in either direction.
+FILTERS = [
+    ("provider", str, "Cloud provider (case-insensitive)"),
+    ("region", str, "Region name; a regex such as 'eu-.*' works"),
+    ("instance_type", str, "Instance type; a regex such as 't3.*' works"),
+    ("min_vcpus", int, "Minimum number of vCPUs"),
+    ("max_vcpus", int, "Maximum number of vCPUs"),
+    ("min_memory_gb", float, "Minimum RAM in GB"),
+    ("max_memory_gb", float, "Maximum RAM in GB"),
+    ("min_storage_gb", float, "Minimum storage in GB"),
+    ("max_storage_gb", float, "Maximum storage in GB"),
+    ("max_price_per_hour", float, "Maximum price per hour in USD"),
+    ("max_price_per_month", float, "Maximum estimated price per month in USD"),
+    ("processor_architecture", str, "CPU architecture (x86_64, arm64)"),
+    ("processor_vendor", str, "Processor vendor"),
+    ("processor_min_ghz", float, "Minimum processor speed in GHz"),
+    ("min_single_core_benchmark", float, "Minimum single-core benchmark score"),
+    ("min_multi_core_benchmark", float, "Minimum multi-core benchmark score"),
+    ("accelerator_name", str, "GPU name; a regex such as 'A100.*' works"),
+    ("accelerator_vendor", str, "GPU vendor"),
+    ("min_accelerator_count", int, "Minimum number of GPUs"),
+    ("min_accelerator_memory_gb", float, "Minimum memory per GPU in GB"),
+    ("min_total_accelerator_memory_gb", float, "Minimum total GPU memory in GB"),
+    ("has_accelerator", bool, "Only servers with a GPU (--has-accelerator) or without one (--no-accelerator)"),
+    ("min_accelerator_fraction", float, "Minimum GPU fraction (1 = whole GPUs only)"),
+    ("price_type", str, "SPOT or ON_DEMAND"),
+    ("max_risk", int, "Maximum preemption risk of spot servers, 0-5 (servers with unknown risk are left out)"),
+    ("min_availability_score", int, "Minimum spot availability score, 1-10"),
+    ("sort_by", str, "Field to sort by (default: price_per_hour)"),
+    ("sort_order", str, "asc or desc (default: asc)"),
+]
+
+
+class CatalogError(exitcodes.CliError):
+    pass
+
+
+def _call(org, path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    try:
+        return api.call("GET", org, path, scope=SCOPE, org_scoped=False, params=params)
+    except api.ApiError as ex:
+        text = str(ex)
+        if ex.status == 403 and "scope" not in text:
+            # An SSO sign-in: the API key hint of api.call does not apply.
+            text += " (HTTP 403. An API key with the 'catalog' scope can read the catalog.)"
+        raise CatalogError(text, ex.exit_code)
+
+
+@click.group(cls=org_group("catalog_org"))
+@click.option("--org", default=None, help="Organization slug (default: MULTICLOUD_ORG)")
+@click.pass_context
+def catalog(ctx, org):
+    """Find servers and prices (sign in first: mctl auth login)."""
+    ctx.ensure_object(dict)
+    ctx.obj["catalog_org"] = org
+
+
+def _run(ctx, fn):
+    return run(ctx.obj.get("catalog_org"), fn, (CatalogError, api.ApiError))
+
+
+def _one_output(as_json: bool, quiet: bool) -> None:
+    if as_json and quiet:
+        raise click.UsageError("Use --json or -q, not both.")
+
+
+def _dash(value, fmt: str = "") -> str:
+    return "-" if value is None else format(value, fmt)
+
+
+def _number(value) -> str:
+    """A metric value without exponent form (1234567.5, not 1.23457e+06)."""
+    if isinstance(value, float):
+        return f"{value:.4f}".rstrip("0").rstrip(".")
+    return _dash(value)
+
+
+def _price(value) -> str:
+    return _dash(value, ".4f")
+
+
+def _gpu(s: Dict[str, Any]) -> str:
+    name = s.get("accelerator_name")
+    if not name:
+        return "-"
+    count = s.get("accelerator_count")
+    return f"{count}x {name}" if count else str(name)
+
+
+def _footer(data: Dict[str, Any]) -> None:
+    meta = data.get("metadata") or {}
+    if meta and not meta.get("total_results"):
+        click.echo("0 results.", err=True)
+    elif meta:
+        click.echo(f"Page {meta.get('current_page')} of {meta.get('total_pages')}, "
+                   f"{meta.get('total_results')} results.", err=True)
+
+
+def format_servers(servers: List[Dict[str, Any]], headers: bool = True) -> str:
+    return _table(("ID", "PROVIDER", "REGION", "TYPE", "VCPU", "MEM_GB", "GPU", "PRICE/H", "PRICE_TYPE"), [
+        (str(s.get("catalog_id")), str(s.get("provider") or "-"), str(s.get("region") or "-"),
+         str(s.get("instance_type") or "-"), _dash(s.get("vcpus")), _dash(s.get("memory_gb"), "g"), _gpu(s),
+         _price(s.get("price_per_hour")), str(s.get("price_type") or "-"))
+        for s in servers], headers)
+
+
+def _filter_options(fn):
+    """One option per ServerFilter field. The click parameter name is the API name verbatim; the option has a
+    hyphenated spelling (--min-vcpus) and the API spelling (--min_vcpus). ``has_accelerator`` is a tri-state."""
+    for name, kind, help_ in reversed(FILTERS):
+        dashed = name.replace("_", "-")
+        if kind is bool:
+            decls = ["--has-accelerator/--no-accelerator", "--has_accelerator/--no_accelerator", name]
+            opt = click.option(*decls, default=None, help=help_)
+        else:
+            decls = [f"--{dashed}"] + ([f"--{name}"] if dashed != name else []) + [name]
+            opt = click.option(*decls, type=kind, default=None, help=help_)
+        fn = opt(fn)
+    return fn
+
+
+def _query(given: Dict[str, Any]) -> Dict[str, Any]:
+    """The query parameters: only what the user gave, a bool as true or false."""
+    return {k: ("true" if v is True else "false" if v is False else v) for k, v in given.items() if v is not None}
+
+
+page_option = click.option("--page", type=click.IntRange(1, 1000), default=None, help="Page number (default: 1)")
+per_page_option = click.option("--per-page", "--per_page", "per_page", type=click.IntRange(1, 100), default=None,
+                               help="Results per page, 1-100 (default: 20)")
+
+
+@catalog.command()
+@_filter_options
+@page_option
+@per_page_option
+@json_option
+@quiet_option
+@no_headers_option
+@click.pass_context
+def search(ctx, page, per_page, as_json, quiet, no_headers, **filters):
+    """Search servers and prices. Only the options you give are sent."""
+    _one_output(as_json, quiet)
+    params = _query({**filters, "page": page, "per_page": per_page})
+    data = _run(ctx, lambda org: _call(org, "/catalog/servers", params))
+    if as_json:
+        return _dump(data)
+    if quiet:
+        for s in data.get("data", []):
+            if s.get("catalog_id") is not None:
+                click.echo(s["catalog_id"])
+        return
+    click.echo(format_servers(data.get("data", []), not no_headers))
+    _footer(data)
+
+
+def _readable(s: Dict[str, Any]) -> str:
+    cpu = " ".join(str(x) for x in (s.get("processor_vendor"), s.get("processor_architecture")) if x)
+    if s.get("processor_max_speed_ghz") is not None:
+        cpu += f" {s['processor_max_speed_ghz']:g} GHz"
+    gpu = _gpu(s) if s.get("accelerator_name") else None
+    if gpu and s.get("accelerator_memory_mb"):
+        gpu += f" ({s['accelerator_memory_mb'] / 1024:g} GB each)"
+    lines = [
+        f"Server {s.get('catalog_id')} ({s.get('provider')} {s.get('region')} {s.get('instance_type')})",
+        ("Zone", s.get("zone")),
+        ("vCPUs", s.get("vcpus")),
+        ("Memory", None if s.get("memory_gb") is None else f"{s['memory_gb']:g} GB"),
+        ("Storage", None if s.get("storage_gb") is None else f"{s['storage_gb']:g} GB"),
+        ("Processor", cpu.strip() or None),
+        ("GPU", gpu),
+        ("Price type", s.get("price_type")),
+        ("Price per hour", None if s.get("price_per_hour") is None else f"{s['price_per_hour']:.4f} USD"),
+        ("Price per month", None if s.get("price_per_month") is None else f"{s['price_per_month']:.2f} USD"),
+        ("Risk", s.get("risk")),
+        ("Risk source", s.get("risk_source")),
+        ("Availability score", s.get("availability_score")),
+        ("Launch score", s.get("launch_score")),
+        ("Single-core benchmark", s.get("single_core_benchmark")),
+        ("Multi-core benchmark", s.get("multi_core_benchmark")),
+        ("Updated", s.get("updated_at")),
+    ]
+    return "\n".join(line if isinstance(line, str) else f"{line[0]}: {line[1]}"
+                     for line in lines if isinstance(line, str) or line[1] not in (None, ""))
+
+
+@catalog.command()
+@click.argument("catalog_id", type=int, metavar="ID")
+@json_option
+@click.pass_context
+def show(ctx, catalog_id, as_json):
+    """Show one server listing (the ID is in the first column of: mctl catalog search)."""
+    data = _run(ctx, lambda org: _call(org, f"/catalog/servers/{catalog_id}"))
+    if as_json:
+        return _dump(data)
+    click.echo(_readable(data.get("data") or {}))
+
+
+@catalog.command()
+@click.argument("catalog_ids", type=int, nargs=-1, metavar="ID ID...")
+@json_option
+@no_headers_option
+@click.pass_context
+def compare(ctx, catalog_ids, as_json, no_headers):
+    """Compare two or more server listings by ID, metric by metric."""
+    catalog_ids = tuple(dict.fromkeys(catalog_ids))  # the API drops a repeated ID
+    if len(catalog_ids) < 2:
+        raise click.UsageError("Give at least two different IDs to compare.")
+    data = _run(ctx, lambda org: _call(org, "/catalog/compare-servers", {"catalog_ids": list(catalog_ids)}))
+    if as_json:
+        return _dump(data)
+    servers = data.get("data") or []
+    metrics: List[str] = []
+    for s in servers:
+        for m in s.get("comparisonResults") or []:
+            if m.get("metric") not in metrics:
+                metrics.append(m.get("metric"))
+    header = ("METRIC", *(str(s.get("catalog_id")) for s in servers))
+    rows = []
+    for metric in metrics:
+        cells = []
+        for s in servers:
+            found = [m.get("value") for m in s.get("comparisonResults") or [] if m.get("metric") == metric]
+            cells.append(_number(found[0]) if found else "-")
+        rows.append((str(metric), *cells))
+    if servers:
+        click.echo(_table(header, rows, not no_headers))
+    meta = data.get("metadata") or {}
+    for key, text in (("notFoundIds", "Not found"), ("invalidIds", "Invalid")):
+        if meta.get(key):
+            click.echo(f"{text}: {', '.join(str(i) for i in meta[key])}.", err=True)
+    if not servers:
+        click.echo("Error: none of the IDs was found.", err=True)
+        sys.exit(exitcodes.NOT_FOUND)
+
+
+@catalog.command()
+@click.option("--provider", default=None, help="Cloud provider")
+@click.option("--region", default=None, help="Region name")
+@click.option("--zone", default=None, help="Zone name")
+@click.option("--sort-by", "--sort_by", "sort_by", default=None, help="provider, region or zone")
+@click.option("--sort-order", "--sort_order", "sort_order", default=None, help="asc or desc")
+@page_option
+@per_page_option
+@json_option
+@quiet_option
+@no_headers_option
+@click.pass_context
+def locations(ctx, provider, region, zone, sort_by, sort_order, page, per_page, as_json, quiet, no_headers):
+    """List the locations (provider, region, zone) of the catalog."""
+    _one_output(as_json, quiet)
+    params = _query(dict(provider=provider, region=region, zone=zone, sort_by=sort_by, sort_order=sort_order,
+                         page=page, per_page=per_page))
+    data = _run(ctx, lambda org: _call(org, "/catalog/locations", params))
+    if as_json:
+        return _dump(data)
+    if quiet:
+        for loc in data.get("data", []):
+            if loc.get("id") is not None:
+                click.echo(loc["id"])
+        return
+    click.echo(_table(("ID", "PROVIDER", "REGION", "ZONE", "NAME"), [
+        (str(loc.get("id")), str(loc.get("provider") or "-"), str(loc.get("region") or "-"),
+         str(loc.get("zone") or "-"), str(loc.get("display_name") or "-")) for loc in data.get("data", [])],
+        not no_headers))
+    _footer(data)
+
+
+@catalog.command()
+@json_option
+@click.pass_context
+def providers(ctx, as_json):
+    """List the cloud providers of the catalog."""
+    data = _run(ctx, lambda org: _call(org, "/catalog/providers"))
+    names = data.get("body") or []
+    if as_json:
+        return click.echo(json.dumps(names, indent=2))
+    for name in names:
+        click.echo(name)
+
+
+@catalog.command(name="field-values")
+@json_option
+@click.pass_context
+def field_values(ctx, as_json):
+    """List the values the filters accept (providers, processor architectures, vendors, price types)."""
+    data = _run(ctx, lambda org: _call(org, "/catalog/field-values"))
+    if as_json:
+        return _dump(data)
+    for key in sorted(_plain(data)):
+        values = data[key] if isinstance(data[key], list) else [] if data[key] is None else [data[key]]
+        click.echo(f"{key}: {', '.join(str(v) for v in values)}")