cmem-cmemc 25.6.0__py3-none-any.whl → 26.1.0rc1__py3-none-any.whl

cmem_cmemc/exceptions.py

@@ -2,6 +2,8 @@
 
 from typing import TYPE_CHECKING
 
+from click.globals import get_current_context
+
 if TYPE_CHECKING:
     from cmem_cmemc.context import ApplicationContext
 
@@ -9,8 +11,12 @@ if TYPE_CHECKING:
 class CmemcError(ValueError):
     """Base exception for CMEM-CMEMC-related errors."""
 
-    def __init__(self, app: "ApplicationContext", *args: str):
-        super().__init__(*args)
+    def __init__(self, message: str, app: "ApplicationContext | None" = None):
+        super().__init__(message)
+        if app is None:
+            ctx = get_current_context(silent=True)
+            if ctx and hasattr(ctx, "obj"):
+                app = ctx.obj
         self.app = app
 
 

cmem_cmemc/manual_helper/multi_page.py

@@ -43,7 +43,6 @@ def get_icon_for_command_group(full_name: str) -> str:
 
 def get_tags_for_command_group(full_name: str) -> str:
     """Get list of tags for a command group name as markdown head section."""
-    # pylint: disable=consider-using-join
     tags = {
         "admin": ["cmemc"],
         "admin metrics": ["cmemc"],

cmem_cmemc/object_list.py

@@ -1,4 +1,4 @@
-"""Filterable object list."""
+"""Filterable object list with enhanced filter types."""
 
 import re
 from abc import ABC, abstractmethod
@@ -9,7 +9,11 @@ from typing import Literal
 from click import Argument, Context, UsageError
 from click.shell_completion import CompletionItem
 
-from cmem_cmemc.completion import finalize_completion, get_completion_args
+from cmem_cmemc.completion import (
+    finalize_completion,
+    get_completion_args,
+    suppress_completion_errors,
+)
 from cmem_cmemc.context import ApplicationContext
 from cmem_cmemc.title_helper import TitleHelper
 
@@ -19,6 +23,7 @@ class Filter(ABC):
 
     name: str
     description: str
+    hidden: bool = False  # If True, filter is hidden from help text and shell completion
 
     @abstractmethod
     def is_filtered(self, object_: dict, value: str) -> bool:
@@ -82,6 +87,16 @@ def transform_lower(ctx: Filter, value: str) -> str:  # noqa: ARG001
     return value.lower()
 
 
+def transform_list_none(ctx: Filter, value: list) -> list:  # noqa: ARG001
+    """Transform: do nothing"""
+    return value
+
+
+def transform_extract_labels(ctx: Filter, value: list) -> list:  # noqa: ARG001
+    """Transform: extract label values from list of dictionaries"""
+    return [item["label"] for item in value if isinstance(item, dict) and "label" in item]
+
+
 class DirectValuePropertyFilter(Filter):
     """Class to create a filter based on direct properties of an object.
 
@@ -202,6 +217,118 @@ class DirectValuePropertyFilter(Filter):
         raise NotImplementedError(f"Completion method {self.completion_method} not implemented.")
 
 
+class MultiFieldPropertyFilter(Filter):
+    """Filter that searches across multiple object fields with a single value.
+
+    This filter can search fields either:
+    1. Individually (match_mode="any") - matches if ANY field matches
+    2. Concatenated (match_mode="concat") - matches against all fields joined together
+
+    The "any" mode is more flexible and typically what users expect - e.g.,
+    searching "workflow" will match if it appears in name OR label OR description.
+
+    The "concat" mode is useful when you need to match patterns that span fields,
+    though this is less common in practice.
+
+    Example:
+        # Search for regex in ANY of: name, label, or description
+        filter = MultiFieldPropertyFilter(
+            name="regex",
+            description="Search in name, label, or description",
+            property_keys=["name", "label", "description"],
+            compare=compare_regex,
+            match_mode="any"  # This is the default
+        )
+
+    """
+
+    name: str
+    description: str
+    property_keys: list[str]
+    separator: str
+    compare: Callable[[Filter, str, str], bool]
+    match_mode: Literal["any", "concat"]
+    fixed_completion: list[CompletionItem]
+    fixed_completion_only: bool
+
+    def __init__(  # noqa: PLR0913
+        self,
+        name: str,
+        description: str,
+        property_keys: list[str],
+        separator: str = " ",
+        compare: Callable[[Filter, str, str], bool] = compare_regex,
+        match_mode: Literal["any", "concat"] = "any",
+        fixed_completion: list[CompletionItem] | None = None,
+        fixed_completion_only: bool = False,
+    ):
+        """Create a multi-field filter.
+
+        Args:
+            name: The name of the filter
+            description: The description of the filter
+            property_keys: List of property keys to search across
+            separator: String to use when joining field values (default: space)
+            compare: Comparison function (default: case-insensitive regex)
+            match_mode: "any" to match if ANY field matches (OR logic),
+                       "concat" to match against concatenated fields
+            fixed_completion: A fixed list of CompletionItem objects used for value completion
+            fixed_completion_only: Raise an UsageError if a value is not from fixed completion
+
+        """
+        self.name = name
+        self.description = description
+        self.property_keys = property_keys
+        self.separator = separator
+        self.compare = compare
+        self.match_mode = match_mode
+        if fixed_completion is not None:
+            self.fixed_completion = fixed_completion
+        else:
+            self.fixed_completion = []
+        self.fixed_completion_only = fixed_completion_only
+
+    def is_filtered(self, object_: dict, value: str) -> bool:
+        """Return True if comparison matches based on match_mode.
+
+        - "any" mode: Returns True if value matches ANY field (OR logic)
+        - "concat" mode: Returns True if value matches concatenated fields
+        """
+        # Validate fixed_completion_only constraint
+        fixed_values = [_.value for _ in self.fixed_completion]
+        if self.fixed_completion_only and value not in fixed_values:
+            raise UsageError(
+                f"'{value}' is not a correct filter value for filter '{self.name}'. "
+                f"Use one of {', '.join(fixed_values)}."
+            )
+
+        # Collect all field values
+        field_values = [
+            str(object_[key])
+            for key in self.property_keys
+            if key in object_ and object_[key] is not None
+        ]
+        if not field_values:
+            return False
+
+        if self.match_mode == "any":
+            # Match if ANY individual field matches (OR logic)
+            return any(self.compare(self, field_value, value) for field_value in field_values)
+        # Match against concatenated string
+        combined_value = self.separator.join(field_values)
+        return bool(self.compare(self, combined_value, value))
+
+    def complete_values(self, objects: list[dict], incomplete: str) -> list[CompletionItem]:
+        """Provide completion items for filter values.
+
+        Returns fixed_completion if available, otherwise no completion.
+        """
+        _ = objects, incomplete
+        if self.fixed_completion:
+            return self.fixed_completion
+        return []
+
+
 class DirectListPropertyFilter(Filter):
     """Class to create filter based on direct list properties of an object
 
@@ -213,6 +340,7 @@ class DirectListPropertyFilter(Filter):
     description: str
     property_key: str
     title_helper: TitleHelper | None
+    transform: Callable[[Filter, list], list]
 
     def __init__(
         self,
@@ -220,6 +348,7 @@ class DirectListPropertyFilter(Filter):
         description: str,
         property_key: str,
         title_helper: TitleHelper | None = None,
+        transform: Callable[[Filter, list], list] = transform_list_none,
     ):
         """Create the new filter
 
@@ -232,11 +361,15 @@ class DirectListPropertyFilter(Filter):
         title_helper:
             (Optional) TitleHelper instance which will be used to provide
             resource titles as descriptions of completions candidates
+        transform:
+            (Optional) Transform function to apply to the list before filtering/completion.
+            Receives the filter instance and the list, returns a transformed list.
         """
         self.name = name
         self.description = description
         self.property_key = property_key
         self.title_helper = title_helper
+        self.transform = transform
 
     def is_filtered(self, object_: dict, value: str) -> bool:
         """Return True if the object is filtered (stays in list)."""
@@ -246,7 +379,8 @@ class DirectListPropertyFilter(Filter):
             return False  # key value is None
         if not isinstance(object_[self.property_key], list):
             return False  # key value is not a list
-        return value in [str(_) for _ in object_[self.property_key]]
+        transformed_list = self.transform(self, object_[self.property_key])
+        return value in [str(_) for _ in transformed_list]
 
     def complete_values(self, objects: list[dict], incomplete: str) -> list[CompletionItem]:
         """Provide completion items for filter values"""
@@ -258,13 +392,100 @@ class DirectListPropertyFilter(Filter):
                 continue  # key value is None
             if not isinstance(object_[self.property_key], list):
                 continue  # key value is not a list
-            candidates.extend([str(_) for _ in object_[self.property_key]])
+            transformed_list = self.transform(self, object_[self.property_key])
+            candidates.extend([str(_) for _ in transformed_list])
         if self.title_helper:
             self.title_helper.get(list(set(candidates)))
             candidates = [(_, self.title_helper.get(_)) for _ in candidates]
         return finalize_completion(candidates=candidates, incomplete=incomplete)
 
 
+class DirectMultiValuePropertyFilter(Filter):
+    """Filter that matches when object property equals ANY value in a delimiter-separated string.
+
+    This filter accepts a single string containing multiple values separated by a delimiter
+    (comma by default) and returns True if the object's property matches any of them.
+    Typically used as a hidden internal filter for multi-ID operations.
+
+    Missing keys or Null values are treated as no match.
+
+    Example:
+        filter = DirectMultiValuePropertyFilter("ids", "IDs filter", "iri", delimiter=",")
+        # Pass comma-separated values: "id1,id2,id3"
+        # Matches objects where iri equals "id1" OR "id2" OR "id3"
+
+    """
+
+    name: str
+    description: str
+    property_key: str
+    transform: Callable[[Filter, str], str]
+    hidden: bool = True
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        property_key: str,
+        transform: Callable[[Filter, str], str] = transform_none,
+        delimiter: str = ",",
+    ):
+        """Create a new multi-value filter.
+
+        Args:
+            name: The name of the filter (used as identifier)
+            description: The description of the filter (used in filter name completion)
+            property_key: The key of the property which is compared
+            transform: Optional value transformation function (e.g., to lowercase)
+            delimiter: String delimiter for splitting multiple values (default: ",")
+
+        """
+        self.name = name
+        self.description = description
+        self.property_key = property_key
+        self.transform = transform
+        self.delimiter = delimiter
+
+    def is_filtered(self, object_: dict, value: str) -> bool:
+        """Return True if object property matches ANY value in delimiter-separated string.
+
+        Args:
+            object_: The object to filter
+            value: Delimiter-separated string of values (e.g., "val1,val2,val3")
+
+        Returns:
+            True if object's property value matches any of the provided values (OR logic)
+
+        """
+        if self.property_key not in object_ or object_[self.property_key] is None:
+            return False
+
+        input_values = value.split(self.delimiter)
+
+        obj_val = str(object_[self.property_key])
+
+        input_values = [v.strip() for v in input_values]
+
+        return obj_val in input_values
+
+    def complete_values(self, objects: list[dict], incomplete: str) -> list[CompletionItem]:
+        """Provide completion items for filter values.
+
+        Note: Hidden filters return no completions.
+
+        Args:
+            objects: List of objects (unused for hidden filters)
+            incomplete: Incomplete value being typed (unused for hidden filters)
+
+        Returns:
+            Empty list (hidden filters provide no completion)
+
+        """
+        # Hidden filters provide no completion
+        _ = objects, incomplete
+        return []
+
+
 class ObjectList:
     """Filterable object list"""
 
@@ -303,10 +524,14 @@ class ObjectList:
         self.filters = {}
 
     def get_filter_help_text(self) -> str:
-        """Get help text for the filter option."""
+        """Get help text for the filter option.
+
+        Hidden filters are excluded from the help text.
+        """
+        visible_filters = [name for name in self.filters if not self.filters[name].hidden]
         return (
             f"Filter {self.name} by one of the following filter names and a "
-            f"corresponding value: {', '.join(self.filters.keys())}."
+            f"corresponding value: {', '.join(visible_filters)}."
         )
 
     def get_filter_names(self) -> list[str]:
@@ -336,6 +561,7 @@ class ObjectList:
             filtered = the_filter.filter_list(value=filter_value, objects=filtered)
         return filtered
 
+    @suppress_completion_errors
     def complete_values(
         self,
         ctx: Context,
@@ -350,11 +576,12 @@ class ObjectList:
         last_argument = args[len(args) - 1]
 
         if last_argument == "--filter":
-            # complete filter names and descriptions
+            # complete filter names and descriptions (hide hidden filters)
             candidates = [
                 (name, self.get_filter(name).description)
                 for name in self.get_filter_names()
                 if name not in previous_filter_names  # do not show already used filters
+                and not self.get_filter(name).hidden  # hide hidden filters
             ]
             return finalize_completion(
                 candidates=candidates,

cmem_cmemc/string_processor.py

@@ -4,9 +4,11 @@ from abc import ABC, abstractmethod
 from datetime import datetime, timezone
 from urllib.parse import quote
 
-import timeago
-from cmem.cmempy.config import get_cmem_base_uri
-from humanize import naturalsize
+from cmem.cmempy.config import get_cmem_base_uri, get_di_api_endpoint
+from cmem.cmempy.workflow.workflow import get_workflow_editor_uri
+from cmem.cmempy.workspace import get_task_plugins
+from cmem.cmempy.workspace.search import list_items
+from humanize import naturalsize, naturaltime
 
 from cmem_cmemc.title_helper import TitleHelper
 from cmem_cmemc.utils import get_graphs_as_dict
@@ -40,13 +42,13 @@ class TimeAgo(StringProcessor):
             return ""
         try:
             stamp = datetime.fromisoformat(str(text))
-            return str(timeago.format(stamp, datetime.now(tz=timezone.utc)))
+            return str(naturaltime(stamp, when=datetime.now(tz=timezone.utc)))
         except (ValueError, TypeError):
             pass
         try:
             text_as_int = int(text)
             stamp = datetime.fromtimestamp(text_as_int / 1000, tz=timezone.utc)
-            return str(timeago.format(stamp, datetime.now(tz=timezone.utc)))
+            return str(naturaltime(stamp, when=datetime.now(tz=timezone.utc)))
         except ValueError:
             return text
 
@@ -71,6 +73,28 @@ class GraphLink(StringProcessor):
         return f"[link={link}]{label}[/link]" if label else text
 
 
+class QueryLink(StringProcessor):
+    """Create a query link from a query IRI cell
+
+    "Visit my [link=https://www.willmcgugan.com]blog[/link]!"
+    """
+
+    def __init__(self, catalog_graph: str, queries: dict):
+        self.catalog_graph = catalog_graph
+        self.queries = queries
+
+    def process(self, text: str) -> str:
+        """Process a single string content and output the processed string."""
+        # Find the query entry from the queries dict
+        query_entry = self.queries.get(text)
+        if query_entry:
+            # Use the SparqlQuery's get_editor_url method for consistent URL generation
+            link = query_entry.get_editor_url(graph=self.catalog_graph)
+            label = query_entry.label
+            return f"[link={link}]{label}[/link]"
+        return text
+
+
 class ResourceLink(StringProcessor):
     """Create a resource link from an IRI cell
 
@@ -89,6 +113,119 @@ class ResourceLink(StringProcessor):
         return f"[link={link}]{label}[/link]"
 
 
+class ProjectLink(StringProcessor):
+    """Create a project link from a project ID cell
+
+    "Visit my [link=https://www.willmcgugan.com]blog[/link]!"
+    """
+
+    def __init__(self, projects: dict):
+        self.projects = projects
+        self.base = get_di_api_endpoint() + "/workbench/projects/"
+
+    def process(self, text: str) -> str:
+        """Process a single string content and output the processed string."""
+        project = self.projects.get(text)
+        if project:
+            link = self.base + text
+            label = project["metaData"].get("label", text)
+            return f"[link={link}]{label}[/link]"
+        return text
+
+
+class WorkflowLink(StringProcessor):
+    """Create a workflow link from a workflow ID cell
+
+    "Visit my [link=https://www.willmcgugan.com]blog[/link]!"
+    """
+
+    def __init__(self, workflows: dict):
+        self.workflows = workflows
+        self.base_uri = get_workflow_editor_uri()
+
+    def process(self, text: str) -> str:
+        """Process a single string content and output the processed string."""
+        workflow = self.workflows.get(text)
+        if workflow:
+            project_id, task_id = text.split(":")
+            link = self.base_uri.format(project_id, task_id)
+            label = workflow["label"]
+            return f"[link={link}]{label}[/link]"
+        return text
+
+
+class DatasetTypeLink(StringProcessor):
+    """Create a documentation link from a dataset type (pluginId) cell
+
+    Links to the Corporate Memory dataset documentation.
+    Example: "json" -> "[link=https://documentation.eccenca.com/latest/build/reference/dataset/json/]JSON[/link]"
+    """
+
+    def __init__(
+        self, base_url: str = "https://documentation.eccenca.com/latest/build/reference/dataset/"
+    ):
+        self.base_url = base_url
+        self.type_labels: dict[str, str] = {}
+        # Dataset types that don't have documentation pages
+        self.undocumented_types = {"variableDataset"}
+        # Import here to avoid circular imports
+
+        plugins = get_task_plugins()
+        for plugin_id, plugin in plugins.items():
+            if plugin["taskType"] == "Dataset":
+                self.type_labels[plugin_id] = plugin["title"]
+
+    def process(self, text: str) -> str:
+        """Process a dataset type and create a documentation link if available."""
+        if not text:
+            return text
+
+        # Use the title if available, otherwise fall back to the text
+        label = self.type_labels.get(text, text)
+
+        # Only create link if this type is not in the undocumented list
+        if text not in self.undocumented_types:
+            link = f"{self.base_url}{text}/"
+            return f"[link={link}]{label}[/link]"
+
+        return label
+
+
+class DatasetLink(StringProcessor):
+    """Create a workspace link from a dataset ID cell
+
+    Links to the Corporate Memory workspace dataset page and displays the dataset label.
+    Example: "project:dataset" ->
+        "[link=https://cmem.example.com/workspaces/datasets/...]Dataset Label[/link]"
+    """
+
+    def __init__(self) -> None:
+        self.cmem_base_uri = get_cmem_base_uri()
+        self.dataset_urls: dict[str, str] = {}
+        self.dataset_labels: dict[str, str] = {}
+        # Build a mapping of dataset_id -> URL path and label
+        datasets = list_items(item_type="dataset")["results"]
+        for dataset in datasets:
+            dataset_id = dataset["projectId"] + ":" + dataset["id"]
+            url_path = dataset["itemLinks"][0]["path"]
+            self.dataset_urls[dataset_id] = url_path
+            self.dataset_labels[dataset_id] = dataset["label"]
+
+    def process(self, text: str) -> str:
+        """Process a dataset ID and create a workspace link with label if available."""
+        if not text:
+            return text
+
+        # Check if we have a URL for this dataset ID
+        if text in self.dataset_urls:
+            full_url = self.cmem_base_uri + self.dataset_urls[text]
+            label = self.dataset_labels.get(text, text)
+            return f"[link={full_url}]{label}[/link]"
+
+        # If no URL found, return the text as-is
+        return text
+
+
 def process_row(row: list[str], hints: dict[int, StringProcessor]) -> list[str]:
     """Process all cells in a row according to the StringProcessors"""
     processed_row = []

cmem_cmemc/title_helper.py

@@ -1,9 +1,12 @@
 """Title helper functions."""
 
 import json
+from typing import ClassVar
 
 from cmem.cmempy.api import get_json
 from cmem.cmempy.config import get_dp_api_endpoint
+from cmem.cmempy.workspace import get_task_plugins
+from cmem.cmempy.workspace.projects.project import get_projects
 
 
 class TitleHelper:
@@ -39,3 +42,50 @@ class TitleHelper:
                 output[title["iri"]] = title["title"]
 
         return output[iri] if isinstance(iri, str) else output
+
+
+class ProjectTitleHelper(TitleHelper):
+    """Title helper for project IDs with class-level caching."""
+
+    _labels_cache: ClassVar[dict[str, str]] = {}
+    _cache_initialized: ClassVar[bool] = False
+
+    def get(self, project_id: str | list[str]) -> str | dict[str, str]:
+        """Get the label of a project (or list of projects)."""
+        # Fetch all project labels once at class level
+        if not ProjectTitleHelper._cache_initialized:
+            projects = get_projects()
+            for project in projects:
+                ProjectTitleHelper._labels_cache[project["name"]] = project["metaData"].get(
+                    "label", ""
+                )
+            ProjectTitleHelper._cache_initialized = True
+
+        # Build and return output
+        if isinstance(project_id, str):
+            return ProjectTitleHelper._labels_cache.get(project_id, "")
+        return {pid: ProjectTitleHelper._labels_cache.get(pid, "") for pid in project_id}
+
+
+class DatasetTypeTitleHelper(TitleHelper):
+    """Title helper for dataset types with class-level caching."""
+
+    _labels_cache: ClassVar[dict[str, str]] = {}
+    _cache_initialized: ClassVar[bool] = False
+
+    def get(self, plugin_id: str | list[str]) -> str | dict[str, str]:
+        """Get the description of a dataset type (or list of types)."""
+        # Fetch all plugin descriptions once at class level
+        if not DatasetTypeTitleHelper._cache_initialized:
+            plugins = get_task_plugins()
+            for pid, plugin in plugins.items():
+                if plugin["taskType"] == "Dataset":
+                    title = plugin["title"]
+                    description = plugin["description"].partition("\n")[0]
+                    DatasetTypeTitleHelper._labels_cache[pid] = f"{title}: {description}"
+            DatasetTypeTitleHelper._cache_initialized = True
+
+        # Build and return output
+        if isinstance(plugin_id, str):
+            return DatasetTypeTitleHelper._labels_cache.get(plugin_id, plugin_id)
+        return {pid: DatasetTypeTitleHelper._labels_cache.get(pid, pid) for pid in plugin_id}

cmem_cmemc/utils.py

@@ -12,7 +12,7 @@ from typing import TYPE_CHECKING
 from zipfile import BadZipFile, ZipFile
 
 import requests
-from click import Argument, ClickException
+from click import Argument
 from cmem.cmempy.dp.proxy.graph import get_graphs_list
 from cmem.cmempy.queries import QueryCatalog
 from cmem.cmempy.workspace.projects.project import get_projects
@@ -20,6 +20,7 @@ from prometheus_client import Metric
 
 from cmem_cmemc.config_parser import PureSectionConfigParser
 from cmem_cmemc.constants import NAMESPACES
+from cmem_cmemc.exceptions import CmemcError
 from cmem_cmemc.smart_path import SmartPath
 
 if TYPE_CHECKING:
@@ -246,7 +247,7 @@ def split_task_id(task_id: str) -> tuple[str, str]:
         project_part = task_id.split(":")[0]
         task_part = task_id.split(":")[1]
     except IndexError as error:
-        raise ClickException(f"{task_id} is not a valid task ID.") from error
+        raise CmemcError(f"{task_id} is not a valid task ID.") from error
     return project_part, task_part
 
 
@@ -303,13 +304,13 @@ def check_or_select_project(app: "ApplicationContext", project_id: str | None =
         return project_name
 
     if len(projects) == 0:
-        raise ClickException(
+        raise CmemcError(
             "There are no projects available. "
             "Please create a project with 'cmemc project create'."
         )
 
     # more than one project
-    raise ClickException(
+    raise CmemcError(
         "There is more than one project available so you need to "
         "specify the project with '--project'."
     )
@@ -391,10 +392,10 @@ def get_query_text(file_or_uri: str, required_projections: set) -> str:
     """
     sparql_query = QueryCatalog().get_query(file_or_uri)
     if sparql_query is None:
-        raise ClickException(f"{file_or_uri} is neither a readable file nor a query URI.")
+        raise CmemcError(f"{file_or_uri} is neither a readable file nor a query URI.")
 
     if sparql_query.get_placeholder_keys():
-        raise ClickException("Placeholder queries are not supported.")
+        raise CmemcError("Placeholder queries are not supported.")
 
     result = sparql_query.get_json_results()
     projected_vars = set(result["head"]["vars"])
@@ -402,7 +403,7 @@ def get_query_text(file_or_uri: str, required_projections: set) -> str:
     missing_projections = required_projections - projected_vars
     if missing_projections:
         missing = ", ".join(missing_projections)
-        raise ClickException(f"Select query must include projections for: {missing}")
+        raise CmemcError(f"Select query must include projections for: {missing}")
     txt: str = sparql_query.text
     return txt