cloudsmith-cli 1.20.0__py3-none-any.whl

cloudsmith_cli/cli/utils.py

@@ -0,0 +1,267 @@
+"""CLI - Utilities."""
+
+import json
+import platform
+from contextlib import contextmanager
+from datetime import date, datetime
+
+import click
+from click_spinner import spinner
+from rich.console import Console
+from rich.table import Table
+
+from ..core.api.version import get_version as get_api_version
+from ..core.version import get_version as get_cli_version
+from .table import make_table
+
+
+def make_user_agent(prefix=None):
+    """Get a suitable user agent for identifying the CLI process."""
+    prefix = (prefix or platform.platform(terse=1)).strip().lower()
+    return f"cloudsmith-cli/{prefix} cli:{get_cli_version()} api:{get_api_version()}"
+
+
+def pretty_print_list_info(num_results, page_info=None, suffix="", page_all=False):
+    """Print information about list results."""
+    if page_all:
+        click.echo(
+            "Results: %(num_results)d %(suffix)s"
+            % {
+                "num_results": num_results,
+                "suffix": suffix,
+            }
+        )
+    elif page_info and page_info.page is not None and page_info.page_size is not None:
+        start = (page_info.page - 1) * page_info.page_size + 1
+        end = min(start + num_results - 1, page_info.count or 0)
+        click.echo(
+            "Results: %(start)d-%(end)d (%(count)d) of %(total)d %(suffix)s "
+            "(page: %(page)d/%(pages)d, page size: %(page_size)d)"
+            % {
+                "start": start,
+                "end": end,
+                "count": num_results,
+                "total": page_info.count or 0,
+                "suffix": suffix,
+                "page": page_info.page,
+                "pages": page_info.page_total or 1,
+                "page_size": page_info.page_size,
+            }
+        )
+    else:
+        click.echo(
+            "Results: %(num_results)d %(suffix)s"
+            % {"num_results": num_results, "suffix": suffix}
+        )
+
+
+def fmt_datetime(value):
+    """Convert a datetime value to string."""
+    if isinstance(value, (date, datetime)):
+        return value.isoformat().replace("+00:00", "Z")
+    return value
+
+
+def fmt_bool(value):
+    """Convert a boolean value to string."""
+    if isinstance(value, bool):
+        return str(value).lower()
+    return value
+
+
+def pretty_print_table(headers, rows, title=None):
+    """Pretty print a table from headers and rows."""
+    table = make_table(headers=headers, rows=rows)
+
+    def pretty_print_row(styled, plain):
+        """Pretty print a row."""
+        click.secho(
+            " | ".join(
+                v + " " * (table.column_widths[k] - len(plain[k]))
+                for k, v in enumerate(styled)
+            )
+        )
+
+    if title:
+        click.secho(title, fg="white", bold=True)
+        click.secho("-" * 80, fg="yellow")
+
+    pretty_print_row(table.headers, table.plain_headers)
+    for k, row in enumerate(table.rows):
+        pretty_print_row(row, table.plain_rows[k])
+
+
+def rich_print_table(headers, rows, title=None, show_lines=False):
+    """Rich table from headers and rows."""
+    console = Console()
+    table = Table(title=title, show_lines=show_lines)
+
+    for header in headers:
+        if isinstance(header, dict):
+            table.add_column(
+                header.get("header", ""),
+                justify=header.get("justify", "left"),
+                style=header.get("style", "none"),
+                no_wrap=header.get("no_wrap", False),
+            )
+        else:
+            table.add_column(str(header))
+
+    for row in rows:
+        table.add_row(*row)
+
+    console.print(table)
+
+
+def print_rate_limit_info(opts, rate_info):
+    """Tell the user when we're being rate limited."""
+    if not rate_info:
+        return
+
+    show_info = (
+        opts.always_show_rate_limit or rate_info.interval > opts.rate_limit_warning
+    )
+
+    if not show_info:
+        return
+
+    click.echo(err=True)
+    click.secho(
+        "Throttling (rate limited) for: %(throttle)s seconds ... "
+        % {"throttle": click.style(str(rate_info.interval), reverse=True)},
+        err=True,
+        reset=False,
+    )
+
+
+def json_serializer(obj):
+    """JSON serializer for objects not serializable by default."""
+
+    # convert date/datetime objects to strings
+    if isinstance(obj, (datetime, date)):
+        return fmt_datetime(obj)
+    raise TypeError("Type %s not serializable." % type(obj))
+
+
+def maybe_print_as_json(opts, data, page_info=None):
+    """Maybe print data as JSON."""
+    if opts.output not in ("json", "pretty_json"):
+        return False
+
+    # Attempt to convert the data to dicts (usually from API objects)
+    try:
+        data = data.to_dict()
+    except AttributeError:
+        pass
+
+    if isinstance(data, list):
+        for k, item in enumerate(data):
+            try:
+                data[k] = item.to_dict()
+            except AttributeError:
+                pass
+
+    root = {"data": data}
+
+    if page_info is not None and page_info.is_valid:
+        meta = root["meta"] = {}
+        meta["pagination"] = page_info.as_dict(num_results=len(data))
+
+    try:
+        if opts.output == "pretty_json":
+            dump = json.dumps(root, indent=4, sort_keys=True, default=json_serializer)
+        else:
+            dump = json.dumps(root, sort_keys=True, default=json_serializer)
+    except (TypeError, ValueError) as e:
+        click.secho(f"Failed to convert to JSON: {str(e)}", fg="red", err=True)
+        return True
+
+    click.echo(dump)
+    return True
+
+
+def maybe_truncate_string(data, max_len=50):
+    """Maybe truncate a string"""
+    if data is not None and len(data) > max_len:
+        return data[: max_len - 3] + "..."
+    return data
+
+
+def maybe_truncate_list(data, max_len=5):
+    """Maybe truncate list"""
+    if data is not None and len(data) > max_len:
+        return data[:max_len] + ["..."]
+    return data
+
+
+def maybe_unstyle_prompt(prompt, err=False):
+    """Strip ANSI styling from a prompt when the target stream is not a TTY.
+
+    As of click 8.4, ``click.prompt``/``click.confirm`` pass the prompt text
+    straight to the (readline-backed) prompt function instead of routing it
+    through ``echo()``. This means click's ``should_strip_ansi`` logic no
+    longer fires for prompt text, so any ANSI codes baked into the prompt via
+    ``click.style(..., bold=True)`` leak raw into non-TTY output (piped
+    output, CI logs, captured streams). Restore the pre-8.4 behaviour by
+    unstyling the prompt ourselves when the destination stream isn't a TTY.
+
+    Applying ``click.unstyle`` to plain text is a harmless no-op.
+    """
+    stream = click.get_text_stream("stderr" if err else "stdout")
+    if not stream.isatty():
+        prompt = click.unstyle(prompt)
+    return prompt
+
+
+def confirm_operation(prompt, prefix=None, assume_yes=False, err=False):
+    """Prompt the user for confirmation for dangerous actions."""
+    if assume_yes:
+        return True
+
+    prefix = prefix or click.style(
+        "Are you %s certain you want to" % (click.style("absolutely", bold=True))
+    )
+
+    prompt = maybe_unstyle_prompt(f"{prefix} {prompt}?", err=err)
+
+    answered = click.confirm(prompt, err=err)
+
+    # click.confirm reads input via input() which relies on terminal line
+    # discipline to echo typed characters. In non-TTY contexts (CI logs,
+    # piped stdin, captured output) the answer is invisible next to the
+    # prompt, so echo the resolved value explicitly.
+    if not click.get_text_stream("stdin").isatty():
+        click.echo("y" if answered else "N", err=err)
+
+    if answered:
+        return True
+
+    click.echo(err=err)
+    click.secho("OK, phew! Close call. :-)", fg="green", err=err)
+    return False
+
+
+@contextmanager
+def maybe_spinner(opts):
+    """Only activate the spinner if not in debug mode or using json output."""
+    if should_use_stderr(opts) or get_output_format(opts) in ("json", "pretty_json"):
+        # No spinner
+        yield
+    else:
+        with spinner() as spin:
+            yield spin
+
+
+def get_output_format(opts):
+    """Get the output format from opts."""
+    return getattr(opts, "output", None)
+
+
+def should_use_stderr(opts):
+    """Check if stdout should be avoided for informational messages."""
+    return get_output_format(opts) in ("json", "pretty_json")
+
+
+def maybe_print_status_json(opts, status_dict):
+    """Maybe print a status dict as JSON."""
+    return maybe_print_as_json(opts, status_dict)

cloudsmith_cli/cli/validators.py

@@ -0,0 +1,378 @@
+"""CLI - Validators."""
+
+import base64
+from datetime import datetime
+from urllib.parse import urlsplit
+
+import click
+from click.core import ParameterSource
+
+from .types import ExpandPath
+
+CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
+BAD_API_HEADERS = ("user-agent", "host")
+API_HEADER_TRANSFORMS = {}
+PUBLIC_API_HOST_SUFFIXES = ("cloudsmith.io", "cloudsmith.com")
+
+
+class IntOrWildcard(click.ParamType):
+    """Custom Click type that accepts integers or '*' wildcard (converted to -1)."""
+
+    name = "integer or *"
+
+    def convert(self, value, param, ctx):
+        # Already converted
+        if isinstance(value, int):
+            return value
+
+        # Handle wildcard
+        if value == "*":
+            return -1
+
+        # Try to convert to integer
+        try:
+            return int(value)
+        except ValueError:
+            self.fail(f"{value!r} is not a valid integer or '*'", param, ctx)
+
+
+def transform_api_header_authorization(param, value):
+    """Transform a username:password value into a base64 string."""
+    try:
+        username, password = value.split(":", 1)
+    except ValueError:
+        raise click.BadParameter(
+            "Authorization header needs to be Authorization=username:password",
+            param=param,
+        )
+
+    value = f"{username.strip()}:{password}"
+    value = base64.b64encode(bytes(value.encode()))
+    return "Basic %s" % value.decode("utf-8")
+
+
+API_HEADER_TRANSFORMS["Authorization"] = transform_api_header_authorization
+
+
+def validate_api_headers(param, value):
+    """Validate that API headers is a CSV of k=v pairs."""
+    # pylint: disable=unused-argument
+    if not value:
+        return None
+
+    headers = {}
+    for kv in value.split(","):
+        try:
+            k, v = kv.split("=", 1)
+            k = k.strip()
+
+            for bad_header in BAD_API_HEADERS:
+                if bad_header == k:
+                    raise click.BadParameter(
+                        f"{bad_header} is not an allowed header",
+                        param=param,
+                    )
+
+            if k in API_HEADER_TRANSFORMS:
+                transform_func = API_HEADER_TRANSFORMS[k]
+                v = transform_func(param, v)
+        except ValueError:
+            raise click.BadParameter(
+                "Values need to be a CSV of key=value pairs", param=param
+            )
+
+        headers[k] = v
+
+    return headers
+
+
+def host_matches_suffixes(url, suffixes):
+    """True if url's hostname equals or is a subdomain of one of the suffixes.
+
+    Parsing the hostname (rather than substring-matching the URL) ensures
+    userinfo, port, and path components cannot smuggle a host past the check.
+    """
+    hostname = (urlsplit(url).hostname or "").lower()
+    return bool(hostname) and any(
+        hostname == suffix or hostname.endswith(f".{suffix}") for suffix in suffixes
+    )
+
+
+def is_trusted_api_host(host, extra_suffixes=()):
+    """True if host is an allowed Cloudsmith host (or matches an extra suffix)."""
+    return host_matches_suffixes(host, PUBLIC_API_HOST_SUFFIXES + tuple(extra_suffixes))
+
+
+def validate_untrusted_api_host(host, extra_suffixes=()):
+    """Raise if an api_host from an untrusted config is not an allowed host."""
+    if is_trusted_api_host(host, extra_suffixes):
+        return
+    raise click.UsageError(
+        f'api_host "{host}" is set by a config file in the current directory '
+        "and is not an allowed Cloudsmith host. Allowed hosts must be under "
+        "*.cloudsmith.io or *.cloudsmith.com. To use a custom host, set it via "
+        "--api-host, the CLOUDSMITH_API_HOST environment variable, an explicit "
+        "--config-file, or your user-level config."
+    )
+
+
+def validate_untrusted_api_proxy(proxy, allowed_suffixes=()):
+    """Raise if an api_proxy from an untrusted config is not an allowed proxy."""
+    if host_matches_suffixes(proxy, allowed_suffixes):
+        return
+    raise click.UsageError(
+        f'api_proxy "{proxy}" is set by a config file in the current directory '
+        "and is not an allowed proxy. To use a proxy, set it via --api-proxy, "
+        "the CLOUDSMITH_API_PROXY environment variable, an explicit "
+        "--config-file, or your user-level config."
+    )
+
+
+def validate_slashes(
+    param, value, minimum=2, maximum=None, form=None, allow_blank=False
+):
+    """Ensure that parameter has slashes and minimum parts."""
+    try:
+        value = value.split("/")
+    except ValueError:
+        value = None
+
+    if value:
+        if len(value) < minimum:
+            value = None
+        elif maximum and len(value) > maximum:
+            value = None
+
+    if not value:
+        form = form or "/".join("VALUE" for _ in range(minimum))
+        raise click.BadParameter(f"Must be in the form of {form}", param=param)
+
+    value = [v.strip() for v in value]
+    if not allow_blank and not all(value):
+        raise click.BadParameter("Individual values cannot be blank", param=param)
+
+    return value
+
+
+def validate_optional_owner_repo(ctx, param, value):
+    """Ensure that owner/repo is formatted correctly, where owner and repo are optional."""
+    # pylint: disable=unused-argument
+    form = "OWNER/REPO"
+
+    return validate_slashes(
+        param, value, minimum=0, maximum=2, form=form, allow_blank=True
+    )
+
+
+def validate_required_owner_optional_repo(ctx, param, value):
+    """Ensure that owner/repo is formatted correctly, where owner is required and repo is optional."""
+    form = "OWNER[/REPO]"
+    return validate_slashes(param, value, minimum=1, maximum=2, form=form)
+
+
+def validate_owner(ctx, param, value):
+    """Ensure that owner is formatted correctly."""
+    # pylint: disable=unused-argument
+    form = "OWNER"
+    return validate_slashes(param, value, minimum=1, maximum=1, form=form)
+
+
+def validate_owner_repo(ctx, param, value):
+    """Ensure that owner/repo is formatted correctly."""
+    # pylint: disable=unused-argument
+    form = "OWNER/REPO"
+    return validate_slashes(param, value, minimum=2, maximum=2, form=form)
+
+
+def validate_owner_repo_package(ctx, param, value):
+    """Ensure that owner/repo/package is formatted correctly."""
+    # pylint: disable=unused-argument
+    form = "OWNER/REPO/PACKAGE"
+    return validate_slashes(param, value, minimum=3, maximum=3, form=form)
+
+
+def validate_owner_repo_slug_perm(ctx, param, value):
+    """Ensure that owner/repo/slug_perm is formatted correctly."""
+    # pylint: disable=unused-argument
+    form = "OWNER/REPO/SLUG_PERM"
+    return validate_slashes(param, value, minimum=3, maximum=3, form=form)
+
+
+def validate_owner_repo_distro(ctx, param, value):
+    """Ensure that owner/repo/distro/version is formatted correctly."""
+    # pylint: disable=unused-argument
+    form = "OWNER/REPO/DISTRO[/RELEASE]"
+    return validate_slashes(param, value, minimum=3, maximum=4, form=form)
+
+
+def validate_page(ctx, param, value):
+    """Ensure that a valid value for page is chosen."""
+    # pylint: disable=unused-argument
+    if value == 0:
+        raise click.BadParameter(
+            "Page is not zero-based, please set a value to 1 or higher.", param=param
+        )
+    return value
+
+
+def validate_page_size(ctx, param, value):
+    """Ensure that a valid value for page size is chosen.
+
+    The IntOrWildcard type already converts '*' to -1 and validates integers.
+    """
+    # pylint: disable=unused-argument
+    if value == 0:
+        raise click.BadParameter("Page size must be non-zero or unset.", param=param)
+    return value
+
+
+def enforce_page_all_exclusive(ctx, wildcard_used=False):
+    """Order-independent mutual exclusivity check for pagination options.
+
+    Raises click.BadParameter bound to the --page-all option if it was used
+    together with explicit --page or --page-size. "Explicit" means supplied
+    via command line, environment variable, or prompt (Click ParameterSource).
+
+    Args:
+        ctx: Click context
+        wildcard_used: If True, validates even if --page-all wasn't explicitly passed
+                      (used when --page-size '*' or -1 was used)
+    """
+    page_all = ctx.params.get("page_all")
+    if not page_all and not wildcard_used:
+        return
+
+    explicit_sources = {
+        src
+        for src in (
+            ParameterSource.COMMANDLINE,
+            ParameterSource.ENVIRONMENT,
+            getattr(ParameterSource, "PROMPT", None),
+        )
+        if src is not None
+    }
+
+    page_explicit = ctx.get_parameter_source("page") in explicit_sources
+    # When checking wildcard usage, don't count page_size as conflicting with itself
+    size_source = ctx.get_parameter_source("page_size")
+    size_explicit = size_source in explicit_sources and not (
+        wildcard_used and size_source == ParameterSource.COMMANDLINE
+    )
+
+    if page_explicit or size_explicit:
+        page_all_param = next(
+            (p for p in ctx.command.params if p.name == "page_all"), None
+        )
+        error_msg = "Cannot be used with --page (-p) or --page-size (-l). (--show-all is an alias for --page-all)"
+        if wildcard_used:
+            error_msg = "Wildcard '*' or -1 in --page-size cannot be used with --page (-p). Use --page-all instead."
+        raise click.BadParameter(
+            error_msg,
+            param=page_all_param,
+        )
+
+
+def validate_optional_timestamp(ctx, param, value):
+    """Ensure that a valid value for a timestamp is used."""
+
+    if value:
+        try:
+            return datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(
+                hour=0, minute=0, second=0
+            )
+        except ValueError:
+            raise click.BadParameter(
+                f"{param.name} must be a valid utc timestamp formatted as `%Y-%m-%dT%H:%M:%SZ` e.g. `2020-12-31T00:00:00Z`",
+                param=param,
+            )
+
+    return value
+
+
+def validate_bandwidth_unit(ctx, param, value):
+    """Ensure that a valid value for bandwidth unit is used."""
+
+    units = [
+        "Byte",
+        "Kilobyte",
+        "Megabyte",
+        "Gigabyte",
+        "Terabyte",
+        "Petabyte",
+        "Exabyte",
+        "Zettabyte",
+        "Yottabyte",
+    ]
+
+    if value:
+        for unit in units:
+            if value.lower() == unit.lower():
+                return unit
+
+        raise click.BadParameter(
+            "Bandwidth unit must be one of the allowed values "
+            "(Byte, Kilobyte, Megabyte, Gigabyte, Terabyte, Petabyte, "
+            "Exabyte, Zettabyte, Yottabyte).",
+            param=param,
+        )
+
+    return value
+
+
+def validate_scheduled_reset_period(ctx, param, value):
+    """Ensure that a valid value for scheduled reset period is used."""
+
+    periods = [
+        "Never Reset",
+        "Daily",
+        "Weekly",
+        "Fortnightly",
+        "Monthly",
+        "Bi-Monthly",
+        "Quarterly",
+        "Every 6 months",
+        "Annual",
+    ]
+
+    if value:
+        for period in periods:
+            if value.lower() == period.lower():
+                return period
+
+        raise click.BadParameter(
+            "The refresh token period must be one of the allowed values "
+            "(Never reset, Daily, Weekly, Fortnightly, Monthly "
+            "Bi-Monthly, Quarterly, Every 6 months, Annual).",
+            param=param,
+        )
+
+    return value
+
+
+def validate_extra_files_parameter(ctx, param, value):
+    """Validate and resolve paths for all extra files."""
+
+    if not value:
+        return []
+
+    path_obj = ExpandPath(
+        exists=True,
+        dir_okay=False,
+        writable=False,
+        resolve_path=True,
+    )
+
+    files = []
+    for v in value:
+        for path in v.split(","):
+            path = path.strip()
+            if not path:
+                continue
+
+            try:
+                resolved_path = path_obj.convert(path, param, ctx)
+                files.append(resolved_path)
+            except click.BadParameter as e:
+                raise click.BadParameter(f"Invalid file path '{path}': {e}")
+
+    return files