cmem-client 0.5.0__py3-none-any.whl

cmem_client/models/url.py

@@ -0,0 +1,34 @@
+"""HTTP URL validation and manipulation utilities.
+
+This module provides the HttpUrl class, which extends httpx.URL with additional
+validation and path manipulation capabilities. It ensures URLs are well-formed
+and provides convenient methods for building API endpoints.
+
+The HttpUrl class is used throughout the configuration system to construct
+various Corporate Memory API endpoints from base URLs.
+"""
+
+from httpx import URL
+
+
+class HttpUrl(URL):
+    """A http(s) URL"""
+
+    def __init__(self, url: str) -> None:
+        if str(URL(url)) != url:
+            raise ValueError(f"URL '{url}' not well formed. Use '{URL(url)!s}' instead.")
+        super().__init__(url)
+
+    def __truediv__(self, other: str) -> "HttpUrl":
+        """Add or extend a Path in the url
+
+        Examples:
+            >>> HttpUrl("https://example.com/") / "/path/to/file.txt"
+            HttpUrl('https://example.com/path/to/file.txt')
+        """
+        path = self.path
+        if path.endswith("/") and other.startswith("/"):
+            other = other[1:]
+        if not path.endswith("/") and not other.startswith("/"):
+            other = f"/{other}"
+        return HttpUrl(f"{self!s}{other}")

cmem_client/models/workflow.py

@@ -0,0 +1,80 @@
+"""Workflow models"""
+
+from __future__ import annotations
+
+from datetime import datetime  # noqa: TC003  # Pydantic needs this at runtime
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import Field, PrivateAttr
+
+from cmem_client.exceptions import BaseError
+
+if TYPE_CHECKING:
+    from cmem_client.client import Client
+
+from cmem_client.models.base import Model, ReadRepositoryItem
+
+ACTIVITY_NAME = Literal["ExecuteDefaultWorkflow", "ExecuteLocalWorkflow", "ExecuteWorkflowWithPayload"]
+
+
+class WorkflowStatus(Model):
+    """Workflow execution status"""
+
+    status_name: str = Field(description="Status name (Idle, Running, Finished)", alias="statusName")
+    concrete_status: str = Field(description="Concrete status (Successful, Failed, Cancelled)", alias="concreteStatus")
+    progress: int | None = Field(description="Progress percentage (0-100)")
+    failed: bool = Field(description="Whether the workflow has failed")
+    message: str = Field(description="Status message")
+    last_update_time: int = Field(description="Last update time", alias="lastUpdateTime")
+    project: str = Field(description="Project ID")
+    task: str = Field(description="Task")
+    activity: str = Field(description="Activity")
+    activity_label: str = Field(description="Activity label", alias="activityLabel")
+    queue_time: datetime | None = Field(default=None, description="Queue time", alias="queueTime")
+    start_time: datetime | None = Field(default=None, description="Start time", alias="startTime")
+    is_running: bool = Field(description="Whether the workflow is currently running", alias="isRunning")
+    runtime: int | None = Field(default=None, description="Runtime")
+    cancelled: bool | None = Field(default=None, description="Cancelled")
+    exception_message: str | None = Field(default=None, description="Exception message", alias="exceptionMessage")
+
+
+class Workflow(Model, ReadRepositoryItem):
+    """A workflow"""
+
+    _client: Client | None = PrivateAttr(default=None)
+
+    id: str = Field(description="Workflow ID", alias="id")
+    label: str = Field(description="Workflow label")
+    project_id: str = Field(description="Project ID", alias="projectId")
+    project_label: str = Field(description="Project label", alias="projectLabel")
+    variable_inputs: list[str] = Field(description="Workflow variable inputs", alias="variableInputs")
+    variable_outputs: list[str] = Field(description="Workflow variable outputs", alias="variableOutputs")
+    warnings: list[str] = Field(description="Workflow warnings")
+
+    def get_id(self) -> str:
+        """Get the workflow ID"""
+        return f"{self.project_id}:{self.id}"
+
+    def set_client(self, client: Client) -> None:
+        """Set the client for this workflow"""
+        self._client = client
+
+    def execute(self, activity_name: ACTIVITY_NAME = "ExecuteDefaultWorkflow") -> None:
+        """Execute the workflow"""
+        if self._client is None:
+            raise BaseError("Client is not set")
+        self._client.workflows.execute(self.get_id(), activity_name)
+
+    def execute_wait_for_completion(
+        self, activity_name: ACTIVITY_NAME = "ExecuteDefaultWorkflow", sleep_time: int = 1
+    ) -> None:
+        """Execute the workflow waiting for completion"""
+        if self._client is None:
+            raise BaseError("Client is not set")
+        self._client.workflows.execute_wait_for_completion(self.get_id(), activity_name, sleep_time)
+
+    def get_status(self, activity_name: ACTIVITY_NAME = "ExecuteDefaultWorkflow") -> WorkflowStatus:
+        """Get the status of the workflow execution."""
+        if self._client is None:
+            raise BaseError("Client is not set")
+        return self._client.workflows.get_status(self.get_id(), activity_name)

cmem_client/repositories/__init__.py

@@ -0,0 +1,15 @@
+"""Data access layer implementing the repository pattern for Corporate Memory resources.
+
+This package provides repository classes for managing different types of Corporate Memory
+entities through a consistent interface. Repositories handle data fetching, caching,
+CRUD operations, and API communication for various resource types.
+
+Key repository categories:
+- Resource repositories: Projects, datasets, graphs, access conditions
+- Base classes: Common functionality and abstract base classes
+- Protocols: Interface definitions for repository operations
+
+Repositories follow the repository pattern, providing an abstraction layer between
+the business logic and the Corporate Memory APIs, with support for both DataIntegration
+(build) and DataPlatform (explore) endpoints.
+"""

cmem_client/repositories/access_conditions.py

@@ -0,0 +1,62 @@
+"""Repository for managing access conditions in Corporate Memory.
+
+Provides AccessConditionRepository class for managing authorization access conditions
+with CRUD operations including create and delete functionality.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import TypeAdapter
+
+from cmem_client.models.access_condition import AccessCondition, AccessConditionResultSet
+from cmem_client.repositories.base.abc import RepositoryConfig
+from cmem_client.repositories.base.paged_list import PagedListRepository
+from cmem_client.repositories.protocols.create_item import CreateConfig, CreateItemProtocol
+from cmem_client.repositories.protocols.delete_item import DeleteConfig, DeleteItemProtocol
+
+if TYPE_CHECKING:
+    from httpx import Response
+
+    from cmem_client.client import Client
+
+
+class AccessConditionsCreateConfig(CreateConfig):
+    """Access condition creation config."""
+
+
+class AccessConditionsDeleteConfig(DeleteConfig):
+    """Access conditions delete config."""
+
+
+class AccessConditionsRepository(PagedListRepository, DeleteItemProtocol, CreateItemProtocol):
+    """Repository for managing authorization access conditions.
+
+    This repository manages access conditions that control authorization for resources
+    in Corporate Memory. Access conditions are described with the
+    [AccessCondition model][cmem_client.models.access_condition.AccessCondition].
+
+    The repository extends PagedListRepository and implements protocols for creating
+    and deleting access conditions.
+    """
+
+    _dict: dict[str, AccessCondition]
+    _client: Client
+    _config = RepositoryConfig(
+        component="explore",
+        fetch_data_path="/api/authorization",  # used for all requests, not just fetch
+        fetch_data_adapter=TypeAdapter(AccessConditionResultSet),
+    )
+
+    def _delete_item(self, key: str, configuration: AccessConditionsDeleteConfig | None = None) -> None:
+        _ = configuration
+        response = self._client.http.delete(url=self._url_fetch_data, params={"resource": key})
+        response.raise_for_status()
+
+    def _create_item(
+        self, item: AccessCondition, configuration: AccessConditionsCreateConfig | None = None
+    ) -> Response:
+        # Send a CreateAccessConditionRequest instead of an AccessCondition
+        _ = configuration
+        return self._client.http.post(url=self._url_fetch_data, json=item.get_create_request())

cmem_client/repositories/base/__init__.py

@@ -0,0 +1,12 @@
+"""Base classes and infrastructure for repository implementations.
+
+This package provides the foundational classes and utilities for building
+repository implementations in the cmem_client library. It includes:
+
+- Abstract base classes defining repository interfaces
+- Configuration classes for different repository types
+- Concrete implementations for common data access patterns
+
+Repositories abstract the details of API communication and provide a
+consistent, dictionary-like interface for accessing Corporate Memory resources.
+"""

cmem_client/repositories/base/abc.py

@@ -0,0 +1,138 @@
+"""Abstract base classes and configuration for CMEM repositories.
+
+This module provides the foundational classes for building repositories in the CMEM client:
+
+- RepositoryConfig: Configuration class that defines component type, fetch paths, and data adapters
+- Repository: Abstract base class implementing a lazy-loading, read-only, dictionary-like interface
+  for accessing CMEM resources with automatic data fetching and caching capabilities
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import ItemsView, Iterator, KeysView, Mapping, ValuesView
+from typing import TYPE_CHECKING, Generic, Literal, TypeVar
+
+from cmem_client.exceptions import RepositoryConfigError
+from cmem_client.models.base import ReadRepositoryItem
+
+if TYPE_CHECKING:
+    from pydantic import TypeAdapter
+
+    from cmem_client.client import Client
+    from cmem_client.models.url import HttpUrl
+
+ItemType = TypeVar("ItemType", bound=ReadRepositoryItem)
+KeysViewType = KeysView[str]
+ItemsViewType = ItemsView[str, ItemType]
+ValuesViewType = ValuesView[ItemType]
+
+
+class RepositoryConfig:
+    """Configuration class for a read repository.
+
+    This class defines the essential configuration parameters needed to set up
+    a repository that can fetch data from CMEM components:
+
+    - component: Specifies whether to use the "build" or "explore" API endpoint
+    - fetch_data_path: The specific API path for retrieving repository data
+    - fetch_data_adapter: Pydantic TypeAdapter for deserializing the API response
+    """
+
+    component: Literal["build", "explore"]
+    fetch_data_path: str
+    fetch_data_adapter: TypeAdapter
+
+    def __init__(
+        self,
+        component: Literal["build", "explore"],
+        fetch_data_path: str,
+        fetch_data_adapter: TypeAdapter,
+    ) -> None:
+        self.component = component
+        self.fetch_data_path = fetch_data_path
+        self.fetch_data_adapter = fetch_data_adapter
+
+
+class Repository(ABC, Mapping, Generic[ItemType]):
+    """ABC of a lazy loading, read-only, dictionary-mimicking repository"""
+
+    _dict: dict[str, ItemType]
+    """the dict"""
+
+    _client: Client
+    _config: RepositoryConfig
+
+    _logger: logging.Logger
+
+    @property
+    def logger(self) -> logging.Logger:
+        """Gets the client logger"""
+        if not hasattr(self, "_logger"):
+            self._logger = logging.getLogger(f"{self._client.logger.name}.{self.__class__.__name__}")
+        return self._logger
+
+    @abstractmethod
+    def fetch_data(self) -> None:
+        """Fetch new data and update the repository"""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+        self.fetch_data()
+        self._post_init()
+
+    def _post_init(self) -> None:
+        """Additional code to initialize the repository."""
+
+    @property
+    def _url_fetch_data(self) -> HttpUrl:
+        """Get the endpoint url for fetching the repository data"""
+        return self._url_base / self._config.fetch_data_path
+
+    @property
+    def _url_base(self) -> HttpUrl:
+        """Get the base url for the repository"""
+        match self._config.component:
+            case "build":
+                return self._client.config.url_build_api
+            case "explore":
+                return self._client.config.url_explore_api
+            case _:
+                raise RepositoryConfigError(f"Unknown component ID: {self._config.component}")
+
+    def _url(self, path: str) -> HttpUrl:
+        """Get the url for a path (based on the component)"""
+        return self._url_base / path
+
+    def __len__(self) -> int:
+        """Get the number of items in the repository"""
+        return len(self._dict)
+
+    def __getitem__(self, key: str) -> ItemType:
+        """Get an item by key (ID or IRI, depending on the type)"""
+        return self._dict[key]
+
+    def __iter__(self) -> Iterator[ItemType]:
+        """Get the iterator over the items in the repository"""
+        return iter(self._dict)  # type: ignore[arg-type]
+
+    def __repr__(self) -> str:
+        """Get a string representation of the repository"""
+        return repr(self._dict)
+
+    def __contains__(self, key: object) -> bool:
+        """Check if an item is in the repository"""
+        return key in self.keys()
+
+    def keys(self) -> KeysViewType:
+        """Get the keys of the repository"""
+        return self._dict.keys()
+
+    def values(self) -> ValuesViewType:
+        """Get the values of the repository"""
+        return self._dict.values()
+
+    def items(self) -> ItemsViewType:
+        """Get the items of the repository"""
+        return self._dict.items()

cmem_client/repositories/base/paged_list.py

@@ -0,0 +1,63 @@
+"""Repository implementation for paginated API endpoints.
+
+This module provides PagedListRepository, a repository implementation that
+handles paginated API responses commonly used in Corporate Memory's DataPlatform
+(explore) APIs. It automatically fetches all pages of results and provides
+a unified dictionary-like interface.
+
+The PagedListRepository is typically used for endpoints that return results
+in a paginated format with metadata about page size, number, and totals.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic
+
+from pydantic import Field
+
+from cmem_client.logging_utils import log_method
+from cmem_client.models.base import Model
+from cmem_client.repositories.base.abc import ItemType, Repository, RepositoryConfig
+
+if TYPE_CHECKING:
+    from cmem_client.client import Client
+
+
+class PageDescription(Model):
+    """A description of a paged list.
+
+    {"size":10,"number":0,"totalElements":0,"totalPages":0}
+    """
+
+    size: int
+    number: int
+    total_elements: int = Field(alias="totalElements")
+    total_pages: int = Field(alias="totalPages")
+
+
+class PagedListRepository(Repository, Generic[ItemType]):
+    """Repository that uses a paged list endpoint."""
+
+    _dict: dict[str, ItemType]
+    _client: Client
+    _config: RepositoryConfig
+
+    @log_method
+    def fetch_data(self) -> None:
+        """Fetch a paged list from a JSON endpoint via a type adapter.
+
+        Use this method to fetch data if your result set is a pageable spring endpoint.
+        """
+        items = {}
+        page = 0
+        while True:
+            response = self._client.http.get(self._url_fetch_data, params={"page": page})
+            response.raise_for_status()
+            content = response.content.decode(encoding="utf-8")
+            result_set = self._config.fetch_data_adapter.validate_json(content)
+            for item in result_set.content:
+                items[item.get_id()] = item
+            if len(result_set.content) < result_set.page.size:
+                break
+            page += 1
+        self._dict = items

cmem_client/repositories/base/plain_list.py

@@ -0,0 +1,39 @@
+"""Repository implementation for simple list API endpoints.
+
+This module provides PlainListRepository, a repository implementation for
+API endpoints that return a simple array of objects without pagination.
+It's commonly used with Corporate Memory's DataIntegration (build) APIs
+that provide straightforward list responses.
+
+The PlainListRepository fetches the entire list in a single request and
+provides dictionary-like access to the items by their ID.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic
+
+from cmem_client.logging_utils import log_method
+from cmem_client.repositories.base.abc import ItemType, Repository, RepositoryConfig
+
+if TYPE_CHECKING:
+    from cmem_client.client import Client
+
+
+class PlainListRepository(Repository, Generic[ItemType]):
+    """Subclass of a ReadRepository that uses a plain list endpoint."""
+
+    _dict: dict[str, ItemType]
+    _client: Client
+    _config: RepositoryConfig
+
+    @log_method
+    def fetch_data(self) -> None:
+        """Fetch simple list from a JSON endpoint via a type adapter
+
+        Use this method to fetch data when your result set is an array of objects.
+        """
+        response = self._client.http.get(self._url_fetch_data)
+        response.raise_for_status()
+        content = response.content.decode(encoding="utf-8")
+        self._dict = {item.get_id(): item for item in self._config.fetch_data_adapter.validate_json(content)}

cmem_client/repositories/base/task_search.py

@@ -0,0 +1,70 @@
+"""Repository implementation for Corporate Memory task search endpoints.
+
+This module provides TaskSearchRepository, a specialized repository that uses
+Corporate Memory's DataIntegration task search API to find and retrieve items.
+The search functionality allows for flexible querying with filters, facets,
+and text search capabilities.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Generic, Literal
+
+from cmem_client.repositories.base.abc import ItemType, Repository, RepositoryConfig
+
+if TYPE_CHECKING:
+    from pydantic import TypeAdapter
+
+    from cmem_client.client import Client
+
+
+class TaskSearchRepositoryConfig(RepositoryConfig):
+    """Configuration class for a Task Search read repository"""
+
+    component: Literal["build", "explore"]
+    fetch_data_path: str
+    fetch_data_adapter: TypeAdapter
+    item_type: str
+
+    def __init__(
+        self,
+        fetch_data_adapter: TypeAdapter,
+        item_type: str,
+        component: Literal["build", "explore"] = "build",
+        fetch_data_path: str = "/api/workspace/searchItems",
+    ) -> None:
+        self.item_type = item_type
+        super().__init__(component, fetch_data_path, fetch_data_adapter)
+
+
+class TaskSearchRepository(Repository, Generic[ItemType]):
+    """Subclass of a ReadRepository that uses the task search endpoint."""
+
+    _dict: dict[str, ItemType]
+    _client: Client
+    _config: TaskSearchRepositoryConfig
+
+    def fetch_data(self) -> None:
+        """Fetch a list from the DI task search endpoint via a type adapter."""
+        search_config = {
+            "limit": 1000000,
+            "offset": 0,
+            "itemType": self._config.item_type,
+            "project": None,
+            "textQuery": "",
+            "facets": None,
+            "addTaskParameters": True,
+        }
+        response = self._client.http.post(
+            self._url_fetch_data,
+            content=json.dumps(search_config),
+            headers={"Content-Type": "application/json"},
+        )
+        response.raise_for_status()
+        content = response.content.decode(encoding="utf-8")
+        items = {}
+        result_set = self._config.fetch_data_adapter.validate_json(content)
+        for item in result_set.results:
+            items[item.get_id()] = item
+        self._dict = items

cmem_client/repositories/datasets.py

@@ -0,0 +1,36 @@
+"""Repository for managing Corporate Memory datasets within projects.
+
+This module provides the DatasetRepository class for managing datasets in
+Corporate Memory's DataIntegration (build) environment. Datasets represent
+data sources and sinks used in integration workflows, configured through
+various plugins.
+"""
+
+from __future__ import annotations
+
+from pydantic import TypeAdapter
+
+from cmem_client.models.dataset import Dataset, DatasetSearchResultSet
+from cmem_client.repositories.base.task_search import (
+    TaskSearchRepository,
+    TaskSearchRepositoryConfig,
+)
+from cmem_client.repositories.protocols.delete_item import DeleteConfig, DeleteItemProtocol
+
+
+class DatasetDeleteConfig(DeleteConfig):
+    """Dataset deletion configuration."""
+
+
+class DatasetsRepository(TaskSearchRepository, DeleteItemProtocol):
+    """Repository for datasets."""
+
+    _dict: dict[str, Dataset]
+    _config = TaskSearchRepositoryConfig(fetch_data_adapter=TypeAdapter(DatasetSearchResultSet), item_type="dataset")
+
+    def _delete_item(self, key: str, configuration: DatasetDeleteConfig | None = None) -> None:
+        _ = configuration
+        to_delete: Dataset = self._dict[key]
+        url = self._url(f"/workspace/projects/{to_delete.project_id}/datasets/{to_delete.id}")
+        response = self._client.http.delete(url)
+        response.raise_for_status()

cmem_client/repositories/graph_imports.py

@@ -0,0 +1,93 @@
+"""Repository for managing Graph Imports"""
+
+from cmem_client.exceptions import RepositoryModificationError
+from cmem_client.models.base import ReadRepositoryItem
+from cmem_client.repositories.base.abc import Repository
+from cmem_client.repositories.protocols.create_item import CreateConfig, CreateItemProtocol
+from cmem_client.repositories.protocols.delete_item import DeleteConfig, DeleteItemProtocol
+
+GRAPH_IMPORTS_LIST_SPARQL = """
+PREFIX owl: <http://www.w3.org/2002/07/owl#>
+
+SELECT ?from_graph ?to_graph
+WHERE
+{
+  GRAPH ?from_graph {
+    ?from_graph owl:imports ?to_graph
+  }
+}
+"""
+
+GRAPH_IMPORTS_CREATE_SPARQL = """
+PREFIX owl: <http://www.w3.org/2002/07/owl#>
+
+INSERT DATA {{
+  GRAPH <{from_graph}> {{
+    <{from_graph}> owl:imports <{to_graph}> .
+  }}
+}}
+"""
+
+GRAPH_IMPORTS_DELETE_SPARQL = """
+PREFIX owl: <http://www.w3.org/2002/07/owl#>
+
+DELETE DATA {{
+  GRAPH <{from_graph}> {{
+    <{from_graph}> owl:imports <{to_graph}> .
+  }}
+}}
+"""
+
+
+class GraphImportsCreateConfig(CreateConfig):
+    """Graph Imports creation configuration"""
+
+
+class GraphImportsDeleteConfig(DeleteConfig):
+    """Graph Imports deletion configuration."""
+
+
+class GraphImport(ReadRepositoryItem):
+    """Graph Import Repository Item"""
+
+    from_graph: str
+    to_graph: str
+
+    def get_id(self) -> str:
+        """Get the id of the item."""
+        return f"{self.from_graph}::::{self.to_graph}"
+
+
+class GraphImportsRepository(Repository, CreateItemProtocol, DeleteItemProtocol):
+    """Repository for managing Graph Imports"""
+
+    _dict: dict[str, GraphImport]
+
+    def fetch_data(self) -> None:
+        """Fetch new data and update the repository"""
+        items = {}
+        results = self._client.store.sparql.query(GRAPH_IMPORTS_LIST_SPARQL)
+        for result in results:
+            graph_import = GraphImport(
+                from_graph=str(result.from_graph),  # type: ignore[union-attr]
+                to_graph=str(result.to_graph),  # type: ignore[union-attr]
+            )
+            items[graph_import.get_id()] = graph_import
+        self._dict = items
+
+    def _create_item(self, item: GraphImport, configuration: GraphImportsCreateConfig | None = None) -> None:
+        """Create (add) a new graph import"""
+        _ = configuration
+        if item.from_graph not in self._client.graphs:
+            raise RepositoryModificationError(f"Graph does not exist: {item.from_graph} (from_graph).")
+        if item.to_graph not in self._client.graphs:
+            raise RepositoryModificationError(f"Graph does not exist: {item.to_graph} (to_graph).")
+        query = GRAPH_IMPORTS_CREATE_SPARQL.format(from_graph=item.from_graph, to_graph=item.to_graph)
+        self._client.store.sparql.update(query)
+
+    def _delete_item(self, key: str, configuration: GraphImportsDeleteConfig | None = None) -> None:
+        """Delete a graph import"""
+        _ = configuration
+        from_graph, to_graph = key.split("::::", maxsplit=2)
+        query = GRAPH_IMPORTS_DELETE_SPARQL.format(from_graph=from_graph, to_graph=to_graph)
+        self._client.store.sparql.update(query)