cloudsmith-cli 1.20.0__py3-none-any.whl

cloudsmith_cli/cli/commands/metadata.py

@@ -0,0 +1,503 @@
+"""CLI/Commands - Manage metadata attached to packages."""
+
+import json
+
+import click
+
+from ...core.api.metadata import (
+    create_metadata as api_create_metadata,
+    delete_metadata as api_delete_metadata,
+    get_metadata as api_get_metadata,
+    list_metadata as api_list_metadata,
+    update_metadata as api_update_metadata,
+)
+from ...core.api.packages import get_package_slug_perm as api_get_package_slug_perm
+from ...core.pagination import paginate_results
+from .. import command, decorators, utils, validators
+from ..exceptions import handle_api_exceptions
+from ..metadata_common import (
+    attach_metadata_options,
+    require_metadata_content_type,
+    resolve_metadata_content,
+)
+from ..utils import maybe_spinner
+from .main import main
+
+_METADATA_HEADERS = [
+    "Slug",
+    "Content type",
+    "Classification",
+    "Source kind",
+    "Source identity",
+]
+
+
+def _format_metadata_row(entry):
+    return [
+        click.style(entry.get("slug_perm") or "", fg="cyan"),
+        click.style(entry.get("content_type") or "", fg="yellow"),
+        click.style(str(entry.get("classification", "")), fg="magenta"),
+        click.style(str(entry.get("source_kind", "")), fg="blue"),
+        click.style(entry.get("source_identity") or "", fg="green"),
+    ]
+
+
+def _echo_action(message, use_stderr):
+    """Print an in-progress status message."""
+    click.echo(message, nl=False, err=use_stderr)
+
+
+def _print_metadata_table(opts, entries, page_info=None, page_all=False):
+    """Print a list of metadata entries as a table or JSON."""
+    if utils.maybe_print_as_json(
+        opts, list(entries), page_info=None if page_all else page_info
+    ):
+        return
+
+    rows = [
+        _format_metadata_row(e)
+        for e in sorted(entries, key=lambda e: e.get("slug_perm") or "")
+    ]
+
+    if rows:
+        click.echo()
+        utils.pretty_print_table(_METADATA_HEADERS, rows)
+
+    click.echo()
+
+    num_results = len(rows)
+    list_suffix = f"metadata entr{'ies' if num_results != 1 else 'y'}"
+    utils.pretty_print_list_info(
+        num_results=num_results,
+        page_info=None if page_all else page_info,
+        suffix=f"{list_suffix} retrieved" if page_all else f"{list_suffix} visible",
+        page_all=page_all,
+    )
+
+
+def _print_metadata_entry(opts, entry):
+    """Print a single metadata entry as a table + indented JSON content."""
+    if utils.maybe_print_as_json(opts, entry):
+        return
+
+    click.echo()
+    utils.pretty_print_table(_METADATA_HEADERS, [_format_metadata_row(entry)])
+    click.echo()
+
+    content = entry.get("content")
+    if content is not None:
+        click.secho("Content:", bold=True)
+        click.echo(json.dumps(content, indent=2, sort_keys=True))
+
+
+@main.group(name="metadata", cls=command.AliasGroup)
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.pass_context
+def metadata_(ctx, opts):  # pylint: disable=unused-argument
+    """
+    Manage package metadata.
+    """
+
+
+@metadata_.command(name="list", aliases=["ls"])
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_cli_list_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.argument(
+    "owner_repo_package",
+    metavar="OWNER/REPO/PACKAGE",
+    callback=validators.validate_owner_repo_package,
+)
+@click.argument("metadata_slug_perm", required=False, default=None)
+@click.option(
+    "--source-kind",
+    "source_kind",
+    default=None,
+    help=(
+        "Filter by source kind name (one of: unknown, system, upstream, "
+        "custom, third_party). Ignored when METADATA_SLUG_PERM is given."
+    ),
+)
+@click.option(
+    "--classification",
+    "classification",
+    default=None,
+    help=(
+        "Filter by classification name (one of: unknown, intrinsic, security, "
+        "provenance, sbom, generic). Ignored when METADATA_SLUG_PERM is given."
+    ),
+)
+@click.pass_context
+def list_metadata(
+    ctx,
+    opts,
+    owner_repo_package,
+    metadata_slug_perm,
+    page,
+    page_size,
+    page_all,
+    source_kind,
+    classification,
+):
+    """
+    List package metadata.
+
+    OWNER/REPO/PACKAGE: target package.
+
+    METADATA_SLUG_PERM (optional): fetch one metadata entry. Pagination and
+    filters are ignored.
+
+    \b
+    Examples:
+            $ cloudsmith metadata list your-org/your-repo/your-pkg
+            $ cloudsmith metadata list your-org/your-repo/your-pkg --classification provenance
+            $ cloudsmith metadata list your-org/your-repo/your-pkg meta-slug-perm
+    """
+    owner, repo, package = owner_repo_package
+    use_stderr = utils.should_use_stderr(opts)
+
+    if metadata_slug_perm:
+        _echo_action(
+            "Fetching metadata %(metadata)s for %(package)s ... "
+            % {
+                "metadata": click.style(metadata_slug_perm, bold=True),
+                "package": click.style(package, bold=True),
+            },
+            use_stderr,
+        )
+
+        context_msg = "Could not fetch package metadata."
+        with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+            with maybe_spinner(opts):
+                slug_perm = api_get_package_slug_perm(
+                    owner=owner, repo=repo, identifier=package
+                )
+                entry = api_get_metadata(slug_perm, metadata_slug_perm)
+
+        click.secho("OK", fg="green", err=use_stderr)
+        _print_metadata_entry(opts, entry)
+        return
+
+    _echo_action(
+        "Listing metadata for %(package)s ... "
+        % {"package": click.style(package, bold=True)},
+        use_stderr,
+    )
+
+    context_msg = "Could not list package metadata."
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            slug_perm = api_get_package_slug_perm(
+                owner=owner, repo=repo, identifier=package
+            )
+            entries, page_info = paginate_results(
+                api_list_metadata,
+                page_all=page_all,
+                page=page,
+                page_size=page_size,
+                package_slug_perm=slug_perm,
+                source_kind=source_kind,
+                classification=classification,
+            )
+
+    click.secho("OK", fg="green", err=use_stderr)
+    _print_metadata_table(opts, entries, page_info=page_info, page_all=page_all)
+
+
+@metadata_.command(name="add")
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.argument(
+    "owner_repo_package",
+    metavar="OWNER/REPO/PACKAGE",
+    callback=validators.validate_owner_repo_package,
+)
+@click.option(
+    "--content-type",
+    "content_type",
+    required=True,
+    help=(
+        "Content type for metadata content (for example, 'application/json'). "
+        "Content type is immutable after creation."
+    ),
+)
+@click.option(
+    "--file",
+    "content_file",
+    type=click.Path(
+        exists=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+        allow_dash=True,
+    ),
+    default=None,
+    help="Read metadata content from a JSON file. Use '-' for stdin.",
+)
+@click.option(
+    "--content",
+    "inline_content",
+    default=None,
+    help="Set metadata content from inline JSON. Cannot be used with --file.",
+)
+@click.option(
+    "--source-identity",
+    "source_identity",
+    default=None,
+    help=(
+        "Identifier for the metadata source. " "Defaults to 'cloudsmith-cli@<version>'."
+    ),
+)
+@click.pass_context
+def add_metadata(
+    ctx,
+    opts,
+    owner_repo_package,
+    content_type,
+    content_file,
+    inline_content,
+    source_identity,
+):
+    """
+    Attach metadata to a package.
+
+    OWNER/REPO/PACKAGE: target package.
+
+    Exactly one of --file or --content must be provided.
+    Content type is set on creation and cannot be changed.
+
+    \b
+    Examples:
+        $ cloudsmith metadata add your-org/your-repo/your-pkg \\
+            --content-type application/json \\
+            --content '{"foo": "bar"}'
+        $ cat metadata.json | cloudsmith metadata add your-org/your-repo/your-pkg \\
+            --content-type application/json \\
+            --file -
+        $ cloudsmith metadata add your-org/your-repo/your-pkg \\
+            --content-type application/vnd.jfrog.buildinfo+json \\
+            --file buildinfo.json
+    """
+    owner, repo, package = owner_repo_package
+    use_stderr = utils.should_use_stderr(opts)
+
+    metadata = resolve_metadata_content(
+        content_file=content_file,
+        inline_content=inline_content,
+        required=True,
+        file_option_name="--file",
+        content_option_name="--content",
+    )
+    require_metadata_content_type(
+        content_type=content_type,
+        content_provided=metadata.provided,
+        option_name="--content-type",
+    )
+    metadata = attach_metadata_options(
+        metadata,
+        content_type=content_type,
+        source_identity=source_identity,
+    )
+
+    _echo_action(
+        "Attaching metadata to %(package)s ... "
+        % {"package": click.style(package, bold=True)},
+        use_stderr,
+    )
+
+    context_msg = "Could not attach metadata."
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            slug_perm = api_get_package_slug_perm(
+                owner=owner, repo=repo, identifier=package
+            )
+            entry = api_create_metadata(
+                slug_perm,
+                content=metadata.content,
+                content_type=metadata.content_type,
+                source_identity=metadata.source_identity,
+            )
+
+    click.secho("OK", fg="green", err=use_stderr)
+    _print_metadata_entry(opts, entry)
+
+
+@metadata_.command(name="update")
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.argument(
+    "owner_repo_package",
+    metavar="OWNER/REPO/PACKAGE",
+    callback=validators.validate_owner_repo_package,
+)
+@click.argument("metadata_slug_perm")
+@click.option(
+    "--file",
+    "content_file",
+    type=click.Path(
+        exists=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+        allow_dash=True,
+    ),
+    default=None,
+    help="Read replacement metadata content from a JSON file. Use '-' for stdin.",
+)
+@click.option(
+    "--content",
+    "inline_content",
+    default=None,
+    help=(
+        "Set replacement metadata content from inline JSON. Cannot be used with "
+        "--file."
+    ),
+)
+@click.option(
+    "--source-identity",
+    "source_identity",
+    default=None,
+    help="Update the metadata source identity.",
+)
+@click.pass_context
+def update_metadata(
+    ctx,
+    opts,
+    owner_repo_package,
+    metadata_slug_perm,
+    content_file,
+    inline_content,
+    source_identity,
+):
+    """
+    Update package metadata.
+
+    OWNER/REPO/PACKAGE: target package.
+    METADATA_SLUG_PERM: permanent slug for the metadata entry.
+
+    Content type cannot be changed after creation.
+
+    \b
+    Examples:
+        $ cloudsmith metadata update your-org/your-repo/your-pkg meta-slug \\
+            --content '{"foo": "baz"}'
+        $ cat metadata.json | cloudsmith metadata update your-org/your-repo/your-pkg meta-slug \\
+            --file -
+    """
+    owner, repo, package = owner_repo_package
+    use_stderr = utils.should_use_stderr(opts)
+
+    metadata = resolve_metadata_content(
+        content_file=content_file,
+        inline_content=inline_content,
+        required=False,
+        file_option_name="--file",
+        content_option_name="--content",
+    )
+
+    patch_kwargs = {}
+    if metadata.provided:
+        patch_kwargs["content"] = metadata.content
+    if source_identity is not None:
+        patch_kwargs["source_identity"] = source_identity
+    if not patch_kwargs:
+        raise click.UsageError(
+            "Nothing to update. Provide --file, --content, or --source-identity."
+        )
+
+    _echo_action(
+        "Updating metadata %(metadata)s for %(package)s ... "
+        % {
+            "metadata": click.style(metadata_slug_perm, bold=True),
+            "package": click.style(package, bold=True),
+        },
+        use_stderr,
+    )
+
+    context_msg = "Could not update package metadata."
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            slug_perm = api_get_package_slug_perm(
+                owner=owner, repo=repo, identifier=package
+            )
+            entry = api_update_metadata(slug_perm, metadata_slug_perm, **patch_kwargs)
+
+    click.secho("OK", fg="green", err=use_stderr)
+    _print_metadata_entry(opts, entry)
+
+
+@metadata_.command(name="remove", aliases=["rm"])
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.argument(
+    "owner_repo_package",
+    metavar="OWNER/REPO/PACKAGE",
+    callback=validators.validate_owner_repo_package,
+)
+@click.argument("metadata_slug_perm")
+@click.option(
+    "-y",
+    "--yes",
+    default=False,
+    is_flag=True,
+    help="Skip confirmation prompt.",
+)
+@click.pass_context
+def remove_metadata(ctx, opts, owner_repo_package, metadata_slug_perm, yes):
+    """
+    Remove package metadata.
+
+    OWNER/REPO/PACKAGE: target package.
+    METADATA_SLUG_PERM: permanent slug for the metadata entry.
+
+    \b
+    Example:
+            $ cloudsmith metadata remove your-org/your-repo/your-pkg meta-slug
+    """
+    owner, repo, package = owner_repo_package
+    use_stderr = utils.should_use_stderr(opts)
+
+    remove_args = {
+        "metadata": click.style(metadata_slug_perm, bold=True),
+        "package": click.style(package, bold=True),
+    }
+
+    prompt = "remove metadata %(metadata)s from package %(package)s" % remove_args
+    if not utils.confirm_operation(prompt, assume_yes=yes, err=use_stderr):
+        return
+
+    _echo_action(
+        "Removing metadata %(metadata)s from %(package)s ... " % remove_args,
+        use_stderr,
+    )
+
+    context_msg = "Could not remove package metadata."
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            slug_perm = api_get_package_slug_perm(
+                owner=owner, repo=repo, identifier=package
+            )
+            api_delete_metadata(slug_perm, metadata_slug_perm)
+
+    click.secho("OK", fg="green", err=use_stderr)
+
+    result_payload = {"deleted": True, "slug_perm": metadata_slug_perm}
+    if utils.maybe_print_as_json(opts, result_payload):
+        return
+
+    click.echo()
+    click.secho(
+        "Metadata removed: %(slug)s."
+        % {"slug": click.style(metadata_slug_perm, bold=True)}
+    )

cloudsmith_cli/cli/commands/metrics/__init__.py

@@ -0,0 +1,2 @@
+from .entitlements import usage as entitlement_usage
+from .packages import usage as package_usage

cloudsmith_cli/cli/commands/metrics/command.py

@@ -0,0 +1,20 @@
+"""CLI/Commands - Import all metric commands."""
+
+import click
+
+from ... import command, decorators
+from ..main import main
+
+
+@main.group(cls=command.AliasGroup, name="metrics", aliases=[])
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.pass_context
+def metrics(ctx, opts):  # pylink: disable=unused-argument
+    """
+    Retrieve Metrics.
+
+    See the help for subcommands for more information on each.
+    """

cloudsmith_cli/cli/commands/metrics/entitlements.py

@@ -0,0 +1,148 @@
+"""CLI/Commands - retrieve metrics."""
+
+import click
+
+from ....core.api import metrics as api
+from ... import decorators, utils, validators
+from ...exceptions import handle_api_exceptions
+from ...utils import maybe_spinner
+from .command import metrics
+
+
+def _print_activity_table(opts, data):
+    """Print token activity as a table."""
+    utils.pretty_print_table(
+        headers=["Active", "Inactive", "Total"],
+        rows=[
+            [
+                click.style(str(getattr(data, k, 0)), fg="green")
+                for k in ("active", "inactive", "total")
+            ]
+        ],
+        title="Activity Summary (Active = Has Downloads)",
+    )
+
+    click.echo()
+
+
+def _print_metrics_table(opts, data):
+    """Print metrics as a table."""
+    category_keys = {"Bandwidth": "bandwidth", "Downloads": "downloads"}
+
+    metrics_keys = {
+        "Average": "average",
+        "Lowest": "lowest",
+        "Highest": "highest",
+        "Total": "total",
+    }
+
+    headers = ["Metric"]
+    headers.extend(metrics_keys.keys())
+    rows = []
+
+    for category_header, category_key in category_keys.items():
+        category_data = getattr(data, category_key)
+        cols = [category_header]
+        for metric_key in metrics_keys.values():
+            metric_data = getattr(category_data, metric_key, {})
+            if hasattr(metric_data, "display"):
+                value = getattr(metric_data, "display")
+            else:
+                value = getattr(metric_data, "value")
+            value = str(value or 0)
+            cols.append(click.style(value, fg="green"))
+        rows.append(cols)
+
+    utils.pretty_print_table(headers=headers, rows=rows, title="Entitlement Metrics")
+
+    click.echo()
+
+
+@metrics.command(name="entitlements", aliases=["ents", "tokens"])
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.argument(
+    "owner_repo",
+    metavar="OWNER or OWNER/REPO",
+    callback=validators.validate_required_owner_optional_repo,
+    default="",
+    required=True,
+)
+@click.option(
+    "--tokens",
+    type=str,
+    required=False,
+    help=(
+        "A comma separated list of entitlement token identifiers (i.e. slug_perm) or "
+        "token secrets. If a list is not specified then all entitlement tokens will "
+        "be included for a given namespace or repository."
+    ),
+)
+@click.option(
+    "--start",
+    type=str,
+    required=False,
+    help=(
+        "Include metrics from and including this UTC date or UTC datetime. "
+        "For example '2020-12-31' or '2021-12-13T00:00:00Z'."
+    ),
+)
+@click.option(
+    "--finish",
+    type=str,
+    required=False,
+    help=(
+        "Include metrics upto and including this UTC date or UTC datetime. "
+        "For example '2020-12-31' or '2021-12-13T00:00:00Z'."
+    ),
+)
+@click.pass_context
+def usage(ctx, opts, owner_repo, tokens, start, finish):
+    """
+    Retrieve token usage metrics.
+
+    OWNER/REPO: Specify the OWNER namespace (i.e user or org) and repository to retrieve the
+    metrics for that namespace/repository combination.
+
+    If REPO isn't specified, all repositories will be included from the
+    OWNER namespace.
+    """
+
+    use_stderr = utils.should_use_stderr(opts)
+
+    click.echo("Getting usage metrics ... ", nl=False, err=use_stderr)
+
+    owner = None
+    repo = None
+
+    if isinstance(owner_repo, list) and len(owner_repo) == 2:
+        owner, repo = owner_repo
+    elif len(owner_repo) == 1:
+        owner = owner_repo[0]
+        repo = None
+
+    data = None
+    context_msg = "Failed to get list of metrics!"
+    data = {}
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            if owner and repo:
+                data = api.get_repository_entitlements_metrics(
+                    owner=owner, repo=repo, tokens=tokens, start=start, finish=finish
+                )
+            elif owner:
+                data = api.get_namespace_entitlements_metrics(
+                    owner=owner, repo=repo, tokens=tokens, start=start, finish=finish
+                )
+
+    click.secho("OK", fg="green", err=use_stderr)
+
+    if utils.maybe_print_as_json(opts, data):
+        return
+
+    click.echo()
+
+    _print_activity_table(opts, data)
+    _print_metrics_table(opts, data)