cmem-cmemc 25.5.0rc1__py3-none-any.whl → 26.1.0rc1__py3-none-any.whl

cmem_cmemc/commands/graph_insights.py

@@ -1,6 +1,6 @@
 """Graph Insights command group"""
 
-from typing import TYPE_CHECKING
+import time
 
 import click
 from click import Argument, Context
@@ -11,10 +11,17 @@ from requests import HTTPError
 
 from cmem_cmemc.command import CmemcCommand
 from cmem_cmemc.command_group import CmemcGroup
-from cmem_cmemc.completion import NOT_SORTED, finalize_completion, graph_uris
+from cmem_cmemc.completion import (
+    NOT_SORTED,
+    finalize_completion,
+    graph_uris,
+    suppress_completion_errors,
+)
+from cmem_cmemc.context import ApplicationContext, build_caption
 from cmem_cmemc.exceptions import CmemcError
 from cmem_cmemc.object_list import (
     DirectListPropertyFilter,
+    DirectMultiValuePropertyFilter,
     DirectValuePropertyFilter,
     ObjectList,
     transform_lower,
@@ -22,11 +29,30 @@ from cmem_cmemc.object_list import (
 from cmem_cmemc.string_processor import GraphLink, TimeAgo
 from cmem_cmemc.utils import get_graphs_as_dict, struct_to_table
 
-if TYPE_CHECKING:
-    from cmem_cmemc.context import ApplicationContext
 
+def get_api_url(path: str = "") -> str:
+    """Get URLs of the graph insights API.
+
+    Constructs the full URL for accessing graph insights API endpoints by combining
+    the DataPlatform API endpoint with the semspect extension base path and an
+    optional resource path.
+
+    Args:
+        path: The API resource path to append to the base URL. Defaults to an empty
+            string for the root endpoint.
+
+    Returns:
+        The complete URL for the specified graph insights API endpoint.
+
+    Example:
+        >>> get_api_url()
+        'https://example.com/dataplatform/api/ext/semspect'
+        >>> get_api_url("/snapshot/status")
+        'https://example.com/dataplatform/api/ext/semspect/snapshot/status'
 
-API_BASE = get_dp_api_endpoint() + "/api/ext/semspect"
+    """
+    base_url = get_dp_api_endpoint() + "/api/ext/semspect"
+    return f"{base_url}{path}"
 
 
 def is_available() -> bool:
@@ -38,7 +64,7 @@ def is_available() -> bool:
     }
     """
     try:
-        data: dict[str, bool] = get_json(API_BASE)
+        data: dict[str, bool] = get_json(get_api_url())
     except HTTPError:
         return False
     return bool(data["isActive"] is True and data["isUserAllowed"] is True)
@@ -46,23 +72,27 @@ def is_available() -> bool:
 
 def check_availability(ctx: click.Context) -> None:
     """Check availability of graph insights endpoints or raise an exception"""
+    _ = ctx
     if is_available():
         return
-    app: ApplicationContext = ctx.obj
-    raise CmemcError(app, "Graph Insights is not available.")
+    raise CmemcError("Graph Insights is not available.")
 
 
 def get_snapshots(ctx: click.Context) -> list[dict[str, str | bool | list[str]]]:
     """Get the snapshot list (all snapshots)"""
     check_availability(ctx)
     data: list[dict[str, str | bool | list[str]]] = get_json(
-        API_BASE + "/snapshot/status", params={"includeManagementOnly": True}
+        get_api_url("/snapshot/status"), params={"includeManagementOnly": True}
     )
     return data
 
 
+@suppress_completion_errors
 def complete_snapshot_ids(ctx: Context, param: Argument, incomplete: str) -> list[CompletionItem]:  # noqa: ARG001
     """Provide auto-completion for snapshot Ids"""
+    ApplicationContext.set_connection_from_params(ctx.find_root().params)
+    if not is_available():
+        return []
     snapshots = get_snapshots(ctx)
     snapshots = sorted(
         snapshots, key=lambda snapshot: snapshot["updateInfoTimestamp"], reverse=True
@@ -102,6 +132,17 @@ snapshot_list = ObjectList(
             description="Snapshots with a specific affected graph (main or sub-graphs).",
             property_key="allGraphsSynced",
         ),
+        DirectValuePropertyFilter(
+            name="valid",
+            description="Snapshots with a specific validity indicator.",
+            property_key="isValid",
+            transform=transform_lower,
+        ),
+        DirectMultiValuePropertyFilter(
+            name="ids",
+            description="Internal filter for multiple snapshot IDs.",
+            property_key="databaseId",
+        ),
     ],
 )
 
@@ -147,21 +188,26 @@ def list_command(ctx: Context, filter_: tuple[tuple[str, str]], id_only: bool, r
         main_graph = _["mainGraphSynced"]
         updated = _["updateInfoTimestamp"]
         status = _["status"]
+        is_valid = _["isValid"]
         if main_graph not in graphs:
             main_graph = rf"\[missing: {main_graph}]"
-        table.append([id_, main_graph, updated, status])
+        table.append([id_, main_graph, updated, status, is_valid])
 
+    filtered = len(filter_) > 0
     app.echo_info_table(
         table,
-        headers=["ID", "Main Graph", "Updated", "Status"],
+        headers=["ID", "Main Graph", "Updated", "Status", "Valid"],
         sort_column=0,
         cell_processing={1: GraphLink(), 2: TimeAgo()},
-        empty_table_message="No graph insight snapshots found.",
+        caption=build_caption(len(table), "graph insight snapshot", filtered=filtered),
+        empty_table_message="No graph insight snapshots found for these filters."
+        if filtered
+        else "No graph insight snapshots found.",
     )
 
 
 @click.command(cls=CmemcCommand, name="delete")
-@click.argument("SNAPSHOT_ID", type=str, shell_complete=complete_snapshot_ids, required=False)
+@click.argument("snapshot_ids", nargs=-1, type=click.STRING, shell_complete=complete_snapshot_ids)
 @click.option(
     "--filter",
     "filter_",
@@ -173,49 +219,87 @@ def list_command(ctx: Context, filter_: tuple[tuple[str, str]], id_only: bool, r
 @click.option("-a", "--all", "all_", is_flag=True, help="Delete all snapshots.")
 @click.pass_context
 def delete_command(
-    ctx: Context, snapshot_id: str | None, filter_: tuple[tuple[str, str]], all_: bool
+    ctx: Context, snapshot_ids: tuple[str], filter_: tuple[tuple[str, str]], all_: bool
 ) -> None:
-    """Delete a graph insight snapshot.
+    """Delete graph insight snapshots.
 
     Graph Insight Snapshots are identified by an ID.
-    To get a list of existing snapshots,
-    execute the `graph insights list` command or use tab-completion.
+
+    Warning: Snapshots will be deleted without prompting.
+
+    Note: Snapshots can be listed by using the `graph insights list` command.
     """
     check_availability(ctx)
     app: ApplicationContext = ctx.obj
-    if snapshot_id is None and not filter_ and not all_:
-        raise click.UsageError("Either provide a snapshot ID or a filter, or use the --all flag.")
+
+    # Validation: require at least one selection method
+    if not snapshot_ids and not filter_ and not all_:
+        raise click.UsageError(
+            "Either provide at least one snapshot ID, "
+            "use a --filter option, or use the --all flag."
+        )
+
+    if snapshot_ids and (all_ or filter_):
+        raise click.UsageError("Either specify snapshot IDs OR use a --filter or the --all option.")
 
     if all_:
         app.echo_info("Deleting all snapshots ... ", nl=False)
-        request(method="DELETE", uri=f"{API_BASE}/snapshot")
-        app.echo_success("done")
+        request(method="DELETE", uri=get_api_url("/snapshot"))
+        app.echo_success("deleted")
         return
 
-    all_snapshots = get_snapshots(ctx)
-    all_snapshot_ids = [_["databaseId"] for _ in all_snapshots]
+    # Get snapshots to delete based on selection method
     filter_to_apply = list(filter_) if filter_ else []
-    if snapshot_id:
-        filter_to_apply.append(("id", snapshot_id))
+    if snapshot_ids:
+        # Use internal multi-value filter for multiple IDs
+        filter_to_apply.append(("ids", ",".join(snapshot_ids)))
     snapshots_to_delete = snapshot_list.apply_filters(ctx=ctx, filter_=filter_to_apply)
-    if not snapshots_to_delete:
-        raise click.UsageError("No snapshots found to delete.")
 
-    for _ in snapshots_to_delete:
-        id_to_delete = _["databaseId"]
-        if id_to_delete not in all_snapshot_ids:
-            raise click.UsageError(f"Snapshot ID '{id_to_delete}' does not exist.")
-    for _ in snapshots_to_delete:
-        id_to_delete = _["databaseId"]
-        app.echo_info(f"Deleting snapshot {id_to_delete} ... ", nl=False)
-        request(method="DELETE", uri=f"{API_BASE}/snapshot/{id_to_delete}")
-        app.echo_success("done")
+    if not snapshots_to_delete and snapshot_ids:
+        raise CmemcError(
+            f"Snapshot ID(s) {', '.join(snapshot_ids)} not found. "
+            "Use the 'graph insights list' command to get a list of existing snapshots."
+        )
+
+    if not snapshots_to_delete and not snapshot_ids:
+        raise CmemcError("No snapshots found to delete.")
+
+    # Avoid double removal as well as sort IDs
+    ids_to_delete = sorted({_["databaseId"] for _ in snapshots_to_delete}, key=lambda v: v.lower())
+    count = len(ids_to_delete)
+
+    # Delete each snapshot
+    for current, id_to_delete in enumerate(ids_to_delete, start=1):
+        current_string = str(current).zfill(len(str(count)))
+        app.echo_info(f"Delete snapshot {current_string}/{count}: {id_to_delete} ... ", nl=False)
+        request(method="DELETE", uri=get_api_url(f"/snapshot/{id_to_delete}"))
+        app.echo_success("deleted")
+
+
+def wait_for_snapshot(snapshot_id: str, polling_interval: int) -> None:
+    """Poll until the snapshot reaches 'DONE' status."""
+    while True:
+        snapshot: dict[str, str | bool | list[str]] = get_json(
+            get_api_url(f"/snapshot/status/{snapshot_id}")
+        )
+        if snapshot.get("status") == "DONE":
+            break
+        time.sleep(polling_interval)
 
 
 @click.command(cls=CmemcCommand, name="create")
 @click.argument("iri", type=click.STRING, shell_complete=graph_uris)
+@click.option("--wait", is_flag=True, help="Wait until snapshot creation is done.")
+@click.option(
+    "--polling-interval",
+    type=click.IntRange(min=0, max=60),
+    show_default=True,
+    default=1,
+    help="How many seconds to wait between status polls. Status polls are"
+    " cheap, so a higher polling interval is most likely not needed.",
+)
 @click.pass_context
-def create_command(ctx: Context, iri: str) -> None:
+def create_command(ctx: Context, iri: str, wait: bool, polling_interval: int) -> None:
     """Create or update a graph insight snapshot.
 
     Create a graph insight snapshot for a given graph.
@@ -225,8 +309,14 @@ def create_command(ctx: Context, iri: str) -> None:
     check_availability(ctx)
     app: ApplicationContext = ctx.obj
     app.echo_info(f"Create / Update graph snapshot for graph {iri} ... ", nl=False)
-    request(method="POST", uri=f"{API_BASE}/snapshot", params={"contextGraph": iri})
-    app.echo_success("started")
+    snapshot_id = request(
+        method="POST", uri=get_api_url("/snapshot"), params={"contextGraph": iri}
+    ).text
+    app.echo_success("started", nl=not wait)
+    if wait:
+        app.echo_info(" ... ", nl=False)
+        wait_for_snapshot(snapshot_id, polling_interval)
+        app.echo_success("created")
 
 
 @click.command(cls=CmemcCommand, name="update")
@@ -240,9 +330,23 @@ def create_command(ctx: Context, iri: str) -> None:
     multiple=True,
 )
 @click.option("-a", "--all", "all_", is_flag=True, help="Delete all snapshots.")
+@click.option("--wait", is_flag=True, help="Wait until snapshot creation is done.")
+@click.option(
+    "--polling-interval",
+    type=click.IntRange(min=0, max=60),
+    show_default=True,
+    default=1,
+    help="How many seconds to wait between status polls. Status polls are"
+    " cheap, so a higher polling interval is most likely not needed.",
+)
 @click.pass_context
-def update_command(
-    ctx: Context, snapshot_id: str | None, filter_: tuple[tuple[str, str]], all_: bool
+def update_command(  # noqa: PLR0913
+    ctx: Context,
+    snapshot_id: str | None,
+    filter_: tuple[tuple[str, str]],
+    all_: bool,
+    wait: bool,
+    polling_interval: int,
 ) -> None:
     """Update a graph insight snapshot.
 
@@ -259,24 +363,24 @@ def update_command(
         filter_to_apply.append(("id", snapshot_id))
     snapshots_to_update = snapshot_list.apply_filters(ctx=ctx, filter_=filter_to_apply)
 
-    all_snapshots = get_snapshots(ctx)
-    all_snapshot_ids = [_["databaseId"] for _ in all_snapshots]
-
     if all_:
         snapshots_to_update = get_snapshots(ctx)
 
-    if not snapshots_to_update:
-        raise click.UsageError("No snapshots found to delete.")
+    if not snapshots_to_update and snapshot_id:
+        raise CmemcError(f"Snapshot ID '{snapshot_id}' does not exist.")
+
+    if not snapshots_to_update and not snapshot_id:
+        raise CmemcError("No snapshots found to update.")
 
-    for _ in snapshots_to_update:
-        id_to_update = _["databaseId"]
-        if id_to_update not in all_snapshot_ids:
-            raise click.UsageError(f"Snapshot ID '{id_to_update}' does not exist.")
     for _ in snapshots_to_update:
         id_to_update = _["databaseId"]
         app.echo_info(f"Update snapshot {id_to_update} ... ", nl=False)
-        request(method="PUT", uri=f"{API_BASE}/snapshot/{snapshot_id}")
-        app.echo_success("started")
+        request(method="PUT", uri=get_api_url(f"/snapshot/{id_to_update}"))
+        app.echo_success("started", nl=not wait)
+        if wait:
+            app.echo_info(" ... ", nl=False)
+            wait_for_snapshot(id_to_update, polling_interval)
+            app.echo_success("updated")
 
 
 @click.command(cls=CmemcCommand, name="inspect")
@@ -288,7 +392,7 @@ def inspect_command(ctx: Context, snapshot_id: str, raw: bool) -> None:
     check_availability(ctx)
     app: ApplicationContext = ctx.obj
     snapshot: dict[str, str | bool | list[str]] = get_json(
-        f"{API_BASE}/snapshot/status/{snapshot_id}"
+        get_api_url(f"/snapshot/status/{snapshot_id}")
     )
     if raw:
         app.echo_info_json(snapshot)

cmem_cmemc/commands/metrics.py

@@ -1,17 +1,19 @@
 """metrics commands for cmem command line interface."""
 
 import click
-from click import Argument, ClickException, Context, UsageError
+from click import Argument, Context, UsageError
 from click.shell_completion import CompletionItem
 from cmem.cmempy.api import request
-from cmem.cmempy.config import get_cmem_base_uri, get_di_api_endpoint, get_dp_api_endpoint
+from cmem.cmempy.config import get_di_api_endpoint, get_dp_api_endpoint
 from prometheus_client.parser import text_string_to_metric_families
 from requests import HTTPError
 
 from cmem_cmemc import completion
 from cmem_cmemc.command import CmemcCommand
 from cmem_cmemc.command_group import CmemcGroup
-from cmem_cmemc.context import ApplicationContext
+from cmem_cmemc.completion import suppress_completion_errors
+from cmem_cmemc.context import ApplicationContext, build_caption
+from cmem_cmemc.exceptions import CmemcError
 from cmem_cmemc.object_list import (
     DirectValuePropertyFilter,
     ObjectList,
@@ -94,6 +96,7 @@ metrics_list = ObjectList(
 )
 
 
+@suppress_completion_errors
 def _complete_metrics_id(ctx: Context, param: Argument, incomplete: str) -> list[CompletionItem]:  # noqa: ARG001
     """Prepare a list of metric identifier."""
     ApplicationContext.set_connection_from_params(ctx.find_root().params)
@@ -101,6 +104,7 @@ def _complete_metrics_id(ctx: Context, param: Argument, incomplete: str) -> list
     return completion.finalize_completion(candidates=candidates, incomplete=incomplete)
 
 
+@suppress_completion_errors
 def _complete_metric_label_filter(
     ctx: Context,
     param: Argument,  # noqa: ARG001
@@ -141,11 +145,11 @@ def _filter_samples(family: dict, label_filter: tuple[tuple[str, str], ...]) ->
         sample_labels = sample[1]
         for name, value in label_filter:
             if name not in labels:
-                raise ClickException(
+                raise CmemcError(
                     f"The metric '{family_name}' does " f"not have a label named '{name}'."
                 )
             if value not in labels[name]:
-                raise ClickException(
+                raise CmemcError(
                     f"The metric '{family_name}' does "
                     f"not have a label '{name}' with the value '{value}'."
                 )
@@ -157,7 +161,6 @@ def _filter_samples(family: dict, label_filter: tuple[tuple[str, str], ...]) ->
     return samples
 
 
-# pylint: disable-msg=too-many-arguments
 @click.command(cls=CmemcCommand, name="get")
 @click.argument("metric_id", required=True, type=click.STRING, shell_complete=_complete_metrics_id)
 @click.option(
@@ -214,7 +217,7 @@ def get_command(
         return
 
     if len(samples) == 0:
-        raise ClickException(
+        raise CmemcError(
             "No data - the given label combination filtered out "
             f"all available samples of the metric {metric_id}."
         )
@@ -308,12 +311,15 @@ def list_command(
         ]
         for _ in data
     ]
+    filtered = len(filter_) > 0
     app.echo_info_table(
         table,
         headers=["ID", "Type", "L", "S", "Documentation"],
         sort_column=0,
-        caption=f"{len(table)} metrics families of {get_cmem_base_uri()}",
-        empty_table_message="No metrics families available.",
+        caption=build_caption(len(table), "metric", filtered=filtered),
+        empty_table_message="No metrics found for these filters."
+        if filtered
+        else "No metrics available.",
     )
 
 

cmem_cmemc/commands/migration.py

@@ -8,8 +8,12 @@ from click.shell_completion import CompletionItem
 
 from cmem_cmemc.command import CmemcCommand
 from cmem_cmemc.command_group import CmemcGroup
-from cmem_cmemc.completion import check_option_in_params, finalize_completion
-from cmem_cmemc.context import ApplicationContext
+from cmem_cmemc.completion import (
+    check_option_in_params,
+    finalize_completion,
+    suppress_completion_errors,
+)
+from cmem_cmemc.context import ApplicationContext, build_caption
 from cmem_cmemc.migrations.access_conditions_243 import (
     MoveAccessConditionsToNewGraph,
     RenameAuthVocabularyResources,
@@ -65,6 +69,7 @@ def get_migrations(ctx: click.Context) -> list[dict]:  # noqa: ARG001
     return data
 
 
+@suppress_completion_errors
 def complete_migration_ids(ctx: Context, param: Argument, incomplete: str) -> list[CompletionItem]:
     """Prepare a list of migration recipe IDs"""
     ApplicationContext.set_connection_from_params(ctx.find_root().params)
@@ -153,12 +158,15 @@ def list_command(
         ]
         for _ in data
     ]
+    filtered = len(filter_) > 0
     app.echo_info_table(
         table,
         headers=["ID", "Description", "Tags", "First Version"],
         sort_column=3,
-        caption=f"{len(table)} migration(s)",
-        empty_table_message="No migrations available.",
+        caption=build_caption(len(table), "migration", filtered=filtered),
+        empty_table_message="No migrations found for these filters."
+        if filtered
+        else "No migrations available.",
     )