cmem-cmemc 24.3.2__py3-none-any.whl → 25.1.0__py3-none-any.whl

cmem_cmemc/__init__.py

@@ -1,160 +1 @@
-"""The main command line interface."""
-
-import contextlib
-import os
-import sys
-import traceback
-from importlib.resources import open_text
-from subprocess import CalledProcessError  # nosec
-
-import click
-import requests.exceptions
-
-from cmem_cmemc import completion
-from cmem_cmemc.command_group import CmemcGroup
-from cmem_cmemc.commands import (
-    admin,
-    config,
-    dataset,
-    graph,
-    project,
-    query,
-    vocabulary,
-    workflow,
-)
-from cmem_cmemc.context import CONTEXT
-from cmem_cmemc.exceptions import InvalidConfigurationError
-from cmem_cmemc.manual_helper.graph import print_manual_graph
-from cmem_cmemc.manual_helper.multi_page import create_multi_page_documentation
-from cmem_cmemc.manual_helper.single_page import print_manual
-from cmem_cmemc.utils import check_python_version, extract_error_message, get_version
-
-CMEMC_VERSION = get_version()
-
-# this will output a custom zsh completion function
-if os.environ.get("_CMEMC_COMPLETE", "") == "zsh_source":
-    with open_text("cmem_cmemc", "_cmemc.zsh") as zsh_output:
-        CONTEXT.echo_info(zsh_output.read())
-    sys.exit(0)
-
-version = sys.version_info
-PYTHON_VERSION = f"{version.major}.{version.minor}.{version.micro}"
-check_python_version(ctx=CONTEXT)
-
-# set the user-agent environment for the http request headers
-os.environ["CMEM_USER_AGENT"] = f"cmemc/{CMEMC_VERSION} (Python {PYTHON_VERSION})"
-
-# https://github.com/pallets/click/blob/master/examples/complex/complex/cli.py
-CONTEXT_SETTINGS = {"auto_envvar_prefix": "CMEMC", "help_option_names": ["-h", "--help"]}
-
-
-@click.group(name="cmemc", cls=CmemcGroup, context_settings=CONTEXT_SETTINGS)
-@click.option(
-    "-c",
-    "--connection",
-    type=click.STRING,
-    shell_complete=completion.connections,
-    help="Use a specific connection from the config file.",
-)
-@click.option(
-    "--config-file",
-    shell_complete=completion.ini_files,
-    type=click.Path(readable=True, allow_dash=False, dir_okay=False),
-    default=CONTEXT.config_file_default,
-    show_default=True,
-    help="Use this config file instead of the default one.",
-)
-@click.option("-q", "--quiet", is_flag=True, help="Suppress any non-error info messages.")
-@click.option(
-    "-d", "--debug", is_flag=True, help="Output debug messages and stack traces after errors."
-)
-@click.version_option(
-    version=CMEMC_VERSION,
-    message="%(prog)s, version %(version)s, " f"running under python {PYTHON_VERSION}",
-)
-@click.pass_context
-def cli(
-    ctx: click.core.Context, debug: bool, quiet: bool, config_file: str, connection: str
-) -> None:
-    """Eccenca Corporate Memory Control (cmemc).
-
-    cmemc is the eccenca Corporate Memory Command Line Interface (CLI).
-
-    Available commands are grouped by affecting resource type (such as graph,
-    project and query).
-    Each command and group has a separate --help screen for detailed
-    documentation.
-    In order to see possible commands in a group, simply
-    execute the group command without further parameter (e.g. cmemc project).
-
-    If your terminal supports colors, these coloring rules are applied:
-    Groups are colored in white; Commands which change data are colored in
-    red; all other commands as well as options are colored in green.
-
-    Please also have a look at the cmemc online documentation:
-
-                        https://eccenca.com/go/cmemc
-
-    cmemc is © 2025 eccenca GmbH, licensed under the Apache License 2.0.
-    """
-    ctx.obj = CONTEXT
-    # hidden feature: 'CMEMC_MANUAL=true cmemc -q config list' will output
-    #     the whole markdown manual
-    if os.getenv("CMEMC_MANUAL_DIR"):
-        create_multi_page_documentation(ctx, str(os.getenv("CMEMC_MANUAL_DIR")))
-        ctx.exit()
-    # hidden feature: 'CMEMC_MANUAL=true cmemc -q config list' will output
-    #     the whole markdown manual
-    if os.getenv("CMEMC_MANUAL"):
-        print_manual(ctx)
-        ctx.exit()
-    # hidden feature: 'CMEMC_MANUAL_GRAPH=true cmemc -q config list' will
-    # output the documentation graph
-    if os.getenv("CMEMC_MANUAL_GRAPH"):
-        print_manual_graph(ctx, get_version())
-        ctx.exit()
-    ctx.obj.set_quiet(quiet)
-    ctx.obj.set_debug(debug)
-    ctx.obj.set_config_file(config_file)
-    try:
-        ctx.obj.set_connection(connection)
-    except InvalidConfigurationError:
-        # if config is broken still allow for "config edit"
-        # means: do not forward this exception if "config edit"
-        if " ".join(sys.argv).find("config edit") == -1:
-            raise
-
-
-cli.add_command(admin.admin)
-cli.add_command(config.config)
-cli.add_command(dataset.dataset)
-cli.add_command(graph.graph)
-cli.add_command(project.project)
-cli.add_command(query.query)
-cli.add_command(vocabulary.vocabulary)
-cli.add_command(workflow.workflow)
-
-
-def main() -> None:
-    """Start the command line interface."""
-    try:
-        cli()  # pylint: disable=no-value-for-parameter
-    except (
-        OSError,
-        CalledProcessError,
-        requests.exceptions.HTTPError,
-        requests.exceptions.ConnectionError,
-        ValueError,
-        NotImplementedError,
-        KeyError,
-    ) as error:
-        if CONTEXT.is_completing():
-            # if currently autocompleting -> silently die with exit 1
-            sys.exit(1)
-        CONTEXT.echo_debug(traceback.format_exc())
-        CONTEXT.echo_error(extract_error_message(error))
-        with contextlib.suppress(
-            requests.exceptions.ConnectionError, requests.exceptions.HTTPError
-        ):
-            CONTEXT.check_versions()
-        sys.exit(1)
+"""cmem_cmemc module"""

cmem_cmemc/cli.py

@@ -0,0 +1,138 @@
+"""The main command line interface."""
+
+import os
+import sys
+import traceback
+from importlib.resources import open_text
+from os import environ as env
+
+import click
+
+from cmem_cmemc import completion
+from cmem_cmemc.command_group import CmemcGroup
+from cmem_cmemc.commands import (
+    admin,
+    config,
+    dataset,
+    graph,
+    manual,
+    project,
+    query,
+    vocabulary,
+    workflow,
+)
+from cmem_cmemc.context import ApplicationContext
+from cmem_cmemc.exceptions import CmemcError
+from cmem_cmemc.utils import check_python_version, extract_error_message, get_version
+
+CMEMC_VERSION = get_version()
+
+# this will output a custom zsh completion function
+if os.environ.get("_CMEMC_COMPLETE", "") == "zsh_source":
+    with open_text("cmem_cmemc", "_cmemc.zsh") as zsh_output:
+        click.secho(zsh_output.read())
+    sys.exit(0)
+
+version = sys.version_info
+PYTHON_VERSION = f"{version.major}.{version.minor}.{version.micro}"
+check_python_version(ctx=ApplicationContext)
+
+# set the user-agent environment for the http request headers
+os.environ["CMEM_USER_AGENT"] = f"cmemc/{CMEMC_VERSION} (Python {PYTHON_VERSION})"
+
+# https://github.com/pallets/click/blob/master/examples/complex/complex/cli.py
+CONTEXT_SETTINGS = {"auto_envvar_prefix": "CMEMC", "help_option_names": ["-h", "--help"]}
+
+
+@click.group(name="cmemc", cls=CmemcGroup, context_settings=CONTEXT_SETTINGS)
+@click.option(
+    "-c",
+    "--connection",
+    type=click.STRING,
+    shell_complete=completion.connections,
+    help="Use a specific connection from the config file.",
+)
+@click.option(
+    "--config-file",
+    shell_complete=completion.ini_files,
+    type=click.Path(readable=True, allow_dash=False, dir_okay=False),
+    default=ApplicationContext.DEFAULT_CONFIG_FILE,
+    show_default=f"Using {env['CMEMC_CONFIG_FILE']} "
+    f"instead of {ApplicationContext.DEFAULT_CONFIG_FILE}"
+    if "CMEMC_CONFIG_FILE" in env
+    else ApplicationContext.DEFAULT_CONFIG_FILE,
+    help="Use this config file instead of the default one.",
+)
+@click.option("-q", "--quiet", is_flag=True, help="Suppress any non-error info messages.")
+@click.option(
+    "-d", "--debug", is_flag=True, help="Output debug messages and stack traces after errors."
+)
+@click.option(
+    "--external-http-timeout",
+    default=ApplicationContext.DEFAULT_EXTERNAL_HTTP_TIMEOUT,
+    type=int,
+    show_default=True,
+    help="Timeout in seconds for external HTTP requests.",
+)
+@click.version_option(
+    version=CMEMC_VERSION,
+    message="%(prog)s, version %(version)s, " f"running under python {PYTHON_VERSION}",
+)
+@click.pass_context
+def cli(  # noqa: PLR0913
+    ctx: click.core.Context,
+    debug: bool,
+    quiet: bool,
+    config_file: str,
+    connection: str,
+    external_http_timeout: int,
+) -> None:
+    """Eccenca Corporate Memory Control (cmemc).
+
+    cmemc is the eccenca Corporate Memory Command Line Interface (CLI).
+
+    Available commands are grouped by affecting resource type (such as graph,
+    project and query).
+    Each command and group has a separate --help screen for detailed
+    documentation.
+    In order to see possible commands in a group, simply
+    execute the group command without further parameter (e.g. cmemc project).
+
+    If your terminal supports colors, these coloring rules are applied:
+    Groups are colored in white; Commands which change data are colored in
+    red; all other commands as well as options are colored in green.
+
+    Please also have a look at the cmemc online documentation:
+
+                        https://eccenca.com/go/cmemc
+
+    cmemc is © 2025 eccenca GmbH, licensed under the Apache License 2.0.
+    """
+    _ = connection, debug, quiet, config_file, external_http_timeout
+    if " ".join(sys.argv).find("config edit") != -1:
+        app = ApplicationContext(config_file=config_file, debug=debug, quiet=quiet)
+    else:
+        app = ApplicationContext.from_params(params=ctx.params)
+    ctx.obj = app
+
+
+cli.add_command(admin.admin)
+cli.add_command(config.config)
+cli.add_command(dataset.dataset)
+cli.add_command(graph.graph)
+cli.add_command(project.project)
+cli.add_command(query.query)
+cli.add_command(vocabulary.vocabulary)
+cli.add_command(workflow.workflow)
+cli.add_command(manual.manual_command)
+
+
+def main() -> None:
+    """Start the command line interface."""
+    try:
+        cli()  # pylint: disable=no-value-for-parameter
+    except CmemcError as error:
+        app: ApplicationContext = error.app
+        app.echo_debug(traceback.format_exc())
+        app.echo_error(extract_error_message(error))
+        sys.exit(1)

cmem_cmemc/command.py

@@ -1,7 +1,15 @@
 """cmemc Click Command"""
 
+from subprocess import CalledProcessError
+from typing import Any
+
+import click
+import requests
 from click_help_colors import HelpColorsCommand
 
+from cmem_cmemc.exceptions import CmemcError
+from cmem_cmemc.utils import extract_error_message
+
 
 class CmemcCommand(HelpColorsCommand):
     """Wrapper click.Command class to have a single extension point.
@@ -18,3 +26,31 @@ class CmemcCommand(HelpColorsCommand):
         kwargs.setdefault("help_headers_color", self.color_for_headers)
         kwargs.setdefault("help_options_color", self.color_for_options)
         super().__init__(*args, **kwargs)
+
+    def invoke(self, ctx: click.core.Context) -> Any:  # noqa: ANN401
+        """Execute the command and handles known exceptions by wrapping them in a CmemcError.
+
+        This method overrides the default Click command invocation to catch a predefined
+        set of exceptions (such as OSError, HTTPError, ValueError, etc.) and re-raises them
+        as a unified CmemcError. This allows consistent error handling and messaging across
+        all CLI commands.
+
+        Args:
+            ctx (click.core.Context): The Click context for the command.
+
+        Raises:
+            CmemcError: Wraps any of the caught exceptions and attaches context-specific data.
+
+        """
+        try:
+            return super().invoke(ctx)
+        except (
+            OSError,
+            CalledProcessError,
+            requests.exceptions.HTTPError,
+            requests.exceptions.ConnectionError,
+            ValueError,
+            NotImplementedError,
+            KeyError,
+        ) as e:
+            raise CmemcError(ctx.obj, extract_error_message(e, True)) from e

cmem_cmemc/commands/admin.py

@@ -4,6 +4,7 @@ from datetime import datetime, timezone
 
 import click
 import jwt
+from click import ClickException
 from cmem.cmempy.api import get_access_token, get_token
 from cmem.cmempy.config import get_cmem_base_uri
 from cmem.cmempy.health import get_complete_status_info
@@ -43,7 +44,7 @@ def _check_cmem_license(app: ApplicationContext, data: dict, exit_1: str) -> Non
         cmem_license_end = license_["validDate"]
         output = f"Your Corporate Memory license expired on {cmem_license_end}."
         if exit_1 in ("error", "always"):
-            raise ValueError(output)
+            raise ClickException(output)
         app.echo_error(output)
 
 
@@ -59,7 +60,7 @@ def _check_graphdb_license(app: ApplicationContext, data: dict, months: int, exi
         graphdb_license_end = data["explore"]["info"]["store"]["licenseExpiration"]
         output = f"Your GraphDB license expires on {graphdb_license_end}."
         if exit_1 == "always":
-            raise ValueError(output)
+            raise ClickException(output)
         app.echo_warning(output)
 
 
@@ -123,7 +124,7 @@ def status_command(  # noqa: C901, PLR0912
         app.echo_debug(_["explore"]["error"])
 
     if exit_1 in ("always", "error") and (_["overall"]["healthy"] != "UP"):
-        raise ValueError(
+        raise ClickException(
             f"One or more major status flags are DOWN or UNKNOWN: {_!r}",
         )
     if raw:
@@ -135,19 +136,19 @@ def status_command(  # noqa: C901, PLR0912
             app.echo_info(table[0][1])
             return
         if len(table) == 0:
-            raise ValueError(f"No values for key(s): {key}")
+            raise ClickException(f"No values for key(s): {key}")
         app.echo_info_table(table, headers=["Key", "Value"], sort_column=0)
         return
     app.check_versions()
     _workspace_config = _["explore"]["info"].get("workspaceConfiguration", {})
     if _workspace_config.get("workspacesToMigrate"):
         if exit_1 == "always":
-            raise ValueError(WARNING_MIGRATION)
+            raise ClickException(WARNING_MIGRATION)
         app.echo_warning(WARNING_MIGRATION)
 
     if _["shapes"]["version"] not in (_["explore"]["version"], "UNKNOWN"):
         if exit_1 == "always":
-            raise ValueError(WARNING_SHAPES)
+            raise ClickException(WARNING_SHAPES)
         app.echo_warning(WARNING_SHAPES)
 
     _check_cmem_license(app=app, data=_, exit_1=exit_1)

cmem_cmemc/commands/client.py

@@ -1,6 +1,7 @@
 """Keycloak client management commands"""
 
 import click
+from click import ClickException, UsageError
 from cmem.cmempy.config import get_keycloak_base_uri, get_keycloak_realm_id
 from cmem.cmempy.keycloak.client import (
     generate_client_secret,
@@ -61,11 +62,11 @@ def secret_command(app: ApplicationContext, client_id: str, generate: bool, outp
     """
     if not output and not generate:
         app.echo_info(click.get_current_context().get_help())
-        raise ValueError("You need to use '--output' or '--generate' as an option.")
+        raise UsageError("You need to use '--output' or '--generate' as an option.")
 
     clients = get_client_by_client_id(client_id)
     if not clients:
-        raise ValueError(NO_CLIENT_ERROR.format(client_id))
+        raise ClickException(NO_CLIENT_ERROR.format(client_id))
 
     if generate:
         if not output:
@@ -105,7 +106,7 @@ def open_command(app: ApplicationContext, client_ids: tuple[str]) -> None:
         client_id_map = {c["clientId"]: c["id"] for c in clients}
         for _ in client_ids:
             if _ not in client_id_map:
-                raise ValueError(NO_CLIENT_ERROR.format(_))
+                raise ClickException(NO_CLIENT_ERROR.format(_))
             client_id = client_id_map[_]
             open_user_uri = f"{open_client_base_uri}/{client_id}/settings"
 

cmem_cmemc/commands/config.py

@@ -1,6 +1,7 @@
 """configuration commands for cmem command line interface."""
 
 import click
+from click import ClickException
 
 from cmem_cmemc.command import CmemcCommand
 from cmem_cmemc.command_group import CmemcGroup
@@ -25,7 +26,7 @@ def list_command(app: ApplicationContext) -> None:
 
     Example: cmemc config list | parallel --jobs 5 cmemc -c {} admin status
     """
-    for section_string in sorted(app.config, key=str.casefold):
+    for section_string in sorted(app.get_config(), key=str.casefold):
         if section_string != "DEFAULT":
             app.echo_result(section_string)
 
@@ -59,7 +60,7 @@ def get_command(app: ApplicationContext, key: str) -> None:
     value = KNOWN_CONFIG_KEYS[key]()
     app.echo_debug(f"Type of {key} value is {type(value)}")
     if value is None:
-        raise ValueError(f"Configuration key {key} is not used in this configuration.")
+        raise ClickException(f"Configuration key {key} is not used in this configuration.")
     app.echo_info(str(value))
 
 

cmem_cmemc/commands/dataset.py

@@ -5,7 +5,7 @@ import re
 
 import click
 import requests.exceptions
-from click import UsageError
+from click import ClickException, UsageError
 from cmem.cmempy.config import get_cmem_base_uri
 from cmem.cmempy.workspace import get_task_plugin_description, get_task_plugins
 from cmem.cmempy.workspace.projects.datasets.dataset import (
@@ -28,6 +28,7 @@ from cmem_cmemc.command_group import CmemcGroup
 from cmem_cmemc.commands.resource import resource
 from cmem_cmemc.completion import get_dataset_file_mapping
 from cmem_cmemc.context import ApplicationContext
+from cmem_cmemc.exceptions import CmemcError
 from cmem_cmemc.parameter_types.path import ClickSmartPath
 from cmem_cmemc.smart_path import SmartPath as Path
 from cmem_cmemc.utils import check_or_select_project, struct_to_table
@@ -67,11 +68,11 @@ def _get_datasets_filtered(
 
     Raises:
     ------
-        ValueError
+        UsageError
 
     """
     if filter_name not in DATASET_FILTER_TYPES:
-        raise ValueError(
+        raise UsageError(
             f"{filter_name} is an unknown filter name. " f"Use one of {DATASET_FILTER_TYPES}."
         )
     # filter by project ID
@@ -99,14 +100,14 @@ def _validate_and_split_dataset_id(dataset_id: str) -> tuple[str, str]:
 
     Raises:
     ------
-        ValueError: in case the dataset ID is not splittable
+        ClickException: in case the dataset ID is not splittable
 
     """
     try:
         project_part = dataset_id.split(":")[0]
         dataset_part = dataset_id.split(":")[1]
     except IndexError as error:
-        raise ValueError(
+        raise ClickException(
             f"{dataset_id} is not a valid dataset ID. Use the "
             "'dataset list' command to get a list of existing datasets."
         ) from error
@@ -170,7 +171,7 @@ def _upload_file_resource(
     """
     exist = resource_exist(project_name=project_id, resource_name=remote_file_name)
     if exist and not replace:
-        raise ValueError(
+        raise ClickException(
             f"A file resource with the name '{remote_file_name}' already "
             "exists in this project. \n"
             "Please rename the file or use the '--replace' "
@@ -234,7 +235,7 @@ def _get_read_only_out_of_parameter(parameter_dict: dict) -> bool:
         return True
     if read_only in ("false", False, "False"):
         return False
-    raise ValueError(f"readOnly parameter should be 'true' or 'false' - was {read_only!r}")
+    raise ClickException(f"readOnly parameter should be 'true' or 'false' - was {read_only!r}")
 
 
 def _extend_parameter_with_metadata(
@@ -298,7 +299,7 @@ def _check_or_set_dataset_type(
                 dataset_type = type_
                 break
         if not dataset_type:
-            raise ValueError("Missing parameter. Please specify a dataset " "type with '--type'.")
+            raise UsageError("Missing parameter. Please specify a dataset " "type with '--type'.")
         app.echo_warning(
             "Missing dataset type (--type) - based on the used file name, "
             f"this type is assumed: {dataset_type}"
@@ -374,7 +375,7 @@ def _check_or_select_dataset_type(app: ApplicationContext, dataset_type: str) ->
 
     Raises:
     ------
-        ValueError: If type is not known
+        CmemcError: If type is not known
 
     Returns:
     -------
@@ -385,7 +386,7 @@ def _check_or_select_dataset_type(app: ApplicationContext, dataset_type: str) ->
         app.echo_debug(f"check type {dataset_type}")
         plugin = get_task_plugin_description(dataset_type)
     except requests.exceptions.HTTPError as error:
-        raise ValueError(f"Unknown dataset type: {dataset_type}.") from error
+        raise CmemcError(app, f"Unknown dataset type: {dataset_type}.") from error
     else:
         return dataset_type, plugin
 
@@ -494,14 +495,14 @@ def delete_command(
             "Please use '--filter project XXX' instead."
         )
     if dataset_ids == () and not all_ and not filter_:
-        raise ValueError(
+        raise UsageError(
             "Either specify at least one dataset ID"
             " or use a --filter option,"
             " or use the --all option to delete all datasets."
         )
 
     if dataset_ids and (all_ or filter_):
-        raise ValueError("Either specify a dataset ID OR" " use a --filter or the --all option.")
+        raise UsageError("Either specify a dataset ID OR" " use a --filter or the --all option.")
 
     if all_ or filter_:
         # in case --all or --filter is given, a list of datasets is fetched
@@ -562,11 +563,11 @@ def download_command(
     try:
         file = project["data"]["parameters"]["file"]
     except KeyError as no_file_resource:
-        raise ValueError(
-            f"The dataset {dataset_id} has no associated file resource."
+        raise CmemcError(
+            app, f"The dataset {dataset_id} has no associated file resource."
         ) from no_file_resource
     if Path(output_path).exists() and replace is not True:
-        raise ValueError(
+        raise UsageError(
             f"Target file {click.format_filename(output_path)} already "
             "exists. Use --replace in case you want to replace it."
         )
@@ -752,7 +753,7 @@ def create_command(  # noqa: PLR0913
 
     # file required but not given
     if "file" in plugin["required"] and not dataset_file and "file" not in parameter_dict:
-        raise ValueError(
+        raise UsageError(
             f"The dataset type {dataset_type} is file based, so you need "
             "to specify a file with the create command."
         )
@@ -896,7 +897,7 @@ def open_command(app: ApplicationContext, dataset_ids: tuple[str]) -> None:
             app.echo_debug(f"Open {_}: {full_url}")
             click.launch(full_url)
         else:
-            raise ValueError(f"Dataset '{_}' not found.")
+            raise ClickException(f"Dataset '{_}' not found.")
 
 
 @click.group(cls=CmemcGroup)