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

cmem_cmemc/context.py

@@ -15,7 +15,9 @@ from shutil import which
 import click
 import cmem.cmempy.config as cmempy_config
 import urllib3
+from cmem.cmempy.config import get_cmem_base_uri
 from cmem.cmempy.health import get_di_version, get_explore_version
+from cmem_client.client import Client
 from pygments import highlight
 from pygments.formatters import get_formatter_by_name
 from pygments.lexers import get_lexer_by_name
@@ -29,9 +31,9 @@ from cmem_cmemc.exceptions import InvalidConfigurationError
 from cmem_cmemc.string_processor import StringProcessor, process_row
 from cmem_cmemc.utils import is_enabled, str_to_bool
 
-DI_TARGET_VERSION = "v25.2.0"
+DI_TARGET_VERSION = "v25.3.0"
 
-EXPLORE_TARGET_VERSION = "v25.2.0"
+EXPLORE_TARGET_VERSION = "v25.3.0"
 
 KNOWN_CONFIG_KEYS = {
     "CMEM_BASE_URI": cmempy_config.get_cmem_base_uri,
@@ -55,6 +57,34 @@ KNOWN_SECRET_KEYS = ("OAUTH_PASSWORD", "OAUTH_CLIENT_SECRET", "OAUTH_ACCESS_TOKE
 SSL_VERIFY_WARNING = "SSL verification is disabled (SSL_VERIFY=False)."
 
 
+def build_caption(
+    count: int,
+    item_name: str,
+    instance: str | None = None,
+    filtered: bool = False,
+    plural: str | None = None,
+) -> str:
+    """Build a standardized caption for table outputs.
+
+    Args:
+    ----
+        count: Number of items in the table
+        item_name: Name of the items (e.g., "file", "project", "query")
+        instance: Instance URI (if None, uses get_cmem_base_uri())
+        filtered: Whether the results are filtered
+        plural: Optional Plural form of the item_name (e.g. "queries"), with giving
+                a plural form, simply a 's' is added for plural.
+
+    Returns:
+    -------
+        Caption string in format: "X thing(s) of INSTANCE (filtered)"
+
+    """
+    term = (plural if plural else f"{item_name}s") if count != 1 else item_name
+    base = f"{count} {term} of {instance or get_cmem_base_uri()}"
+    return f"{base} (filtered)" if filtered else base
+
+
 class ApplicationContext:
     """Context of the command line interface."""
 
@@ -72,9 +102,6 @@ class ApplicationContext:
     console: Console
     console_width: int | None = None
 
-    # pylint: disable=too-many-instance-attributes
-    # pylint: disable=too-many-public-methods
-
     def __init__(
         self,
         config_file: str,
@@ -93,6 +120,11 @@ class ApplicationContext:
         self.console = Console(markup=True, emoji_variant="emoji")
         self.update_console_width()
 
+    @property
+    def client(self) -> Client:
+        """The cmem_client Client object."""
+        return Client.from_cmempy()
+
     @staticmethod
     def from_params(params: dict) -> "ApplicationContext":
         """Create an ApplicationContext instance from a dictionary.
@@ -273,9 +305,9 @@ class ApplicationContext:
             return
         if section_string not in self.get_config():
             raise InvalidConfigurationError(
-                self,
                 f"There is no connection '{section_string}' configured in "
                 f"config '{self.config_file}'.",
+                app=self,
             )
         self.connection = section_string
 
@@ -294,10 +326,10 @@ class ApplicationContext:
             config.read(self.get_config_file(), encoding="utf-8")
         except configparser.Error as error:
             raise InvalidConfigurationError(
-                self,
                 "The following config parser error needs to be fixed with your config file:\n"
                 f"{error!s}\n"
                 "You can use the 'config edit' command to fix this.",
+                app=self,
             ) from error
         except Exception as error:  # noqa: BLE001
             self.echo_debug(f"Could not read config file - provide empty config: {error!s}")
@@ -337,7 +369,6 @@ class ApplicationContext:
         2024-05-17: also allows list of strings now
         2024-05-17: new prepend_line parameter
         """
-        # pylint: disable=invalid-name
         click.echo("") if prepend_line is True else None
         messages: list[str] = [message] if isinstance(message, str) else message
         for _ in messages:
@@ -434,6 +465,7 @@ class ApplicationContext:
         )
         if caption is not None:
             table.caption = caption
+            table.min_width = len(caption)
         for header in headers:
             table.add_column(header, overflow="fold")
         for row_source in rows:
@@ -450,13 +482,11 @@ class ApplicationContext:
 
     def echo_success(self, message: str, nl: bool = True, condition: bool = True) -> None:
         """Output success message, if not suppressed by --quiet."""
-        # pylint: disable=invalid-name
         self.echo_info(message, fg="green", nl=nl, condition=condition)
 
     @staticmethod
     def echo_result(message: str, nl: bool = True) -> None:
         """Output result message, can NOT be suppressed by --quiet."""
-        # pylint: disable=invalid-name
         click.echo(message, nl=nl)
 
     def check_concrete_version(self, name: str, version: str, target_version: str) -> None:

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/graph.py

@@ -56,7 +56,7 @@ def print_group_manual_graph_recursive(
             ctx.obj.echo_info(f"{iri} a cli:CommandGroup .")
             ctx.obj.echo_info(f"{iri} rdfs:label '{prefix}{key} Command Group' .")
             ctx.obj.echo_info(f"{iri} cli:subGroupOf {sub_group_iri} .")
-            ctx.obj.echo_info(f"{iri} rdfs:comment '{comment}' .")
+            ctx.obj.echo_info(f'{iri} rdfs:comment """{comment}""" .')
             print_group_manual_graph_recursive(item, ctx=ctx, prefix=f"{prefix}{key}-")
         elif isinstance(item, click.Command):
             comment = item.get_short_help_str(limit=200)
@@ -64,7 +64,7 @@ def print_group_manual_graph_recursive(
             ctx.obj.echo_info(f"{iri} a cli:Command .")
             ctx.obj.echo_info(f"{iri} rdfs:label '{prefix}{key} Command' .")
             ctx.obj.echo_info(f"{iri} cli:group {group_iri} .")
-            ctx.obj.echo_info(f"{iri} rdfs:comment '{comment}' .")
+            ctx.obj.echo_info(f'{iri} rdfs:comment """{comment}""" .')
             for parameter in item.params:
                 print_parameter_manual_graph(parameter, ctx=ctx, prefix=f"{prefix}{key}-")
         else:

cmem_cmemc/manual_helper/multi_page.py

@@ -26,12 +26,13 @@ def get_icon_for_command_group(full_name: str) -> str:
         "admin workspace python": "material/language-python",
         "config": "material/cog-outline",
         "dataset": "eccenca/artefact-dataset",
-        "dataset resource": "eccenca/artefact-file",
         "project": "eccenca/artefact-project",
+        "project file": "eccenca/artefact-file",
         "project variable": "material/variable-box",
         "query": "eccenca/application-queries",
         "graph": "eccenca/artefact-dataset-eccencadataplatform",
         "graph imports": "material/family-tree",
+        "graph insights": "eccenca/graph-insights",
         "graph validation": "octicons/verified-16",
         "vocabulary": "eccenca/application-vocabularies",
         "vocabulary cache": "eccenca/application-vocabularies",
@@ -42,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"],
@@ -54,8 +54,8 @@ def get_tags_for_command_group(full_name: str) -> str:
         "admin workspace python": ["Python", "cmemc"],
         "config": ["Configuration", "cmemc"],
         "dataset": ["cmemc"],
-        "dataset resource": ["cmemc"],
         "project": ["Project", "cmemc"],
+        "project file": ["Files", "cmemc"],
         "project variable": ["Variables", "cmemc"],
         "query": ["SPARQL", "cmemc"],
         "graph": ["KnowledgeGraph", "cmemc"],
@@ -145,12 +145,10 @@ def get_commands_for_table_recursive(
         if isinstance(item, Command):
             command_name = item.name
             group_link = f"{prefix}/{group_name}/index.md".replace(" ", "/")
-            if group_link.startswith("/"):
-                group_link = group_link[1:]
+            group_link = group_link.removeprefix("/")
             command_anchor = f"{prefix}-{group_name}".replace(" ", "-")
             command_anchor += f"-{command_name}"
-            if command_anchor.startswith("-"):
-                command_anchor = command_anchor[1:]
+            command_anchor = command_anchor.removeprefix("-")
             command_link = f"{group_link}#{command_anchor}"
             new_command = {
                 "command_name": command_name,

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/placeholder.py

@@ -36,7 +36,7 @@ class QueryPlaceholder:
         """Prepare a list of placeholder values"""
         result = self.value_query.get_json_results()
         projection_vars = result["head"]["vars"]
-        bindings = result["results"]["bindings"]
+        bindings: list[dict] = result["results"]["bindings"]
         if "value" not in projection_vars:
             return []
 
@@ -50,7 +50,7 @@ class QueryPlaceholder:
         values_with_description = []
         for _ in bindings:
             value = str(_["value"]["value"])
-            description = str(_["description"]["value"])
+            description = _.get("description", {}).get("value", "")
             values_with_description.append((value, description))
         return values_with_description