cmem-client 0.5.0__py3-none-any.whl

cmem_client/repositories/projects.py

@@ -0,0 +1,214 @@
+"""Repository for managing Corporate Memory Build (DataIntegration) projects.
+
+Provides ProjectRepository class with CRUD operations including create, delete, and import
+functionality for projects from ZIP archives.
+"""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from io import BytesIO
+from pathlib import Path
+from shutil import rmtree
+from typing import TYPE_CHECKING, ClassVar, Literal
+from zipfile import ZipFile
+
+from pydantic import Field, TypeAdapter
+
+from cmem_client.exceptions import ProjectExportError, ProjectImportError, RepositoryModificationError
+from cmem_client.models.base import Model
+from cmem_client.models.item import ImportItem, ZipImportItem
+from cmem_client.models.project import Project
+from cmem_client.repositories.base.abc import RepositoryConfig
+from cmem_client.repositories.base.plain_list import PlainListRepository
+from cmem_client.repositories.protocols.create_item import CreateConfig, CreateItemProtocol
+from cmem_client.repositories.protocols.delete_item import DeleteConfig, DeleteItemProtocol
+from cmem_client.repositories.protocols.export_item import ExportConfig, ExportItemProtocol
+from cmem_client.repositories.protocols.import_item import ImportConfig, ImportItemProtocol
+
+if TYPE_CHECKING:
+    from httpx import Response
+
+
+class ProjectImportStatus(Model):
+    """Response of the project import status endpoint."""
+
+    project_id: str = Field(alias="projectId")
+    success: bool | None = None
+    failure_message: str | None = Field(alias="failureMessage", default=None)
+
+
+class ProjectsImportConfig(ImportConfig):
+    """Dataset Import Configuration."""
+
+    use_archive_handler: bool = False
+
+
+class ProjectsExportConfig(ExportConfig):
+    """Dataset Export Configuration."""
+
+    marshalling_plugin: Literal["xmlZip", "xmlZipWithoutResources"] = "xmlZip"
+    extract_project_zip: bool = False
+
+
+class ProjectsCreateConfig(CreateConfig):
+    """Dataset Create Configuration."""
+
+
+class ProjectsDeleteConfig(DeleteConfig):
+    """Dataset Delete Configuration."""
+
+
+class ProjectsRepository(
+    PlainListRepository, DeleteItemProtocol, CreateItemProtocol, ImportItemProtocol, ExportItemProtocol
+):
+    """Repository for Build (DataIntegration) projects.
+
+    This repository manages Build (DataIntegration) projects which are described with
+    the [Project model][cmem_client.models.project.Project].
+    """
+
+    _dict: dict[str, Project]
+    _allowed_import_items: ClassVar[list[type[ImportItem]]] = [ZipImportItem]
+    _allowed_marshalling_plugins: ClassVar[list[str]] = ["xmlZip", "xmlZipWithoutResources"]
+    _default_import_config: ProjectsImportConfig = ProjectsImportConfig()
+
+    _config = RepositoryConfig(
+        component="build",
+        fetch_data_path="/workspace/projects",
+        fetch_data_adapter=TypeAdapter(list[Project]),
+    )
+
+    def _delete_item(self, key: str, configuration: ProjectsDeleteConfig | None = None) -> None:
+        """Delete an item."""
+        _ = configuration
+        url = self._url(f"/workspace/projects/{key}")
+        response = self._client.http.delete(url)
+        response.raise_for_status()
+
+    def _create_item(self, item: Project, configuration: ProjectsCreateConfig | None = None) -> Response:
+        """Create a new project
+
+        Note: the payload of this request needs to have an 'id' field (different from model)
+        """
+        _ = configuration
+        url = self._url("/api/workspace/projects")
+        data = {"id": item.get_id(), "metaData": item.meta_data.model_dump()}
+        return self._client.http.post(url, json=data)
+
+    def _import_item_get_status(self, import_id: str) -> ProjectImportStatus:
+        """Get the status of an import item process"""
+        url = self._url(f"/api/workspace/projectImport/{import_id}/status")
+        params = {"timeout": "1000"}
+        response = self._client.http.get(url, params=params).raise_for_status()
+        return ProjectImportStatus(**response.json())
+
+    def _import_item(
+        self,
+        path: Path | None = Path(),
+        replace: bool = False,
+        key: str | None = None,
+        configuration: ProjectsImportConfig | None = None,
+    ) -> str:
+        """Import project ZIP archive to the repository (concrete implementation)
+
+        This method is responsible for importing the item from the server.
+        It needs to return the key of the imported item.
+        """
+        if path is None:
+            raise ProjectImportError("Path must be specified.")
+
+        if configuration is None:
+            configuration = ProjectsImportConfig()
+
+        # use a temporary zip file always to ensure zip and directory functionality
+        with tempfile.NamedTemporaryFile(suffix=".zip" if path.is_dir() else path.suffix, delete=False) as tmp:
+            if path.is_dir():
+                shutil.make_archive(
+                    tmp.name.removesuffix(".zip"),
+                    "zip",
+                    base_dir=path.name,
+                    root_dir=str(path.parent.absolute()),
+                )
+                uploaded_file = Path(tmp.name)
+            else:
+                shutil.copyfile(path, tmp.name)
+                uploaded_file = Path(tmp.name)
+
+        # 1. the project file upload
+        upload_url = self._url("/api/workspace/projectImport")
+        with uploaded_file.open(mode="rb") as file:
+            upload_response = self._client.http.post(upload_url, files={"file": file}).raise_for_status()
+            project_import_id = upload_response.json()["projectImportId"]
+
+        # unlink the temporary file again
+        Path.unlink(Path(uploaded_file))
+
+        # 2. the validation of the uploaded file
+        validation_url = self._url(f"/api/workspace/projectImport/{project_import_id}")
+        # projectId, label, marshallerId, projectAlreadyExists
+        self._client.http.get(validation_url).raise_for_status()
+
+        # 3. the asynchronous execution of the project import
+        import_url = self._url(f"/api/workspace/projectImport/{project_import_id}")
+        params = {
+            "overwriteExisting": "true" if replace else "false",
+            "generateNewId": "true" if not key else "false",
+            "newProjectId": key if key else None,
+        }
+        self._client.http.post(import_url, params=params).raise_for_status()
+
+        # 4. wait until finished
+        import_status = self._import_item_get_status(import_id=project_import_id)
+        while not import_status.success:
+            import_status = self._import_item_get_status(import_id=project_import_id)
+        if import_status.success:
+            self.fetch_data()
+            return import_status.project_id
+        raise RepositoryModificationError(import_status.failure_message)
+
+    def _export_item(
+        self, key: str, path: Path | None, replace: bool = False, configuration: ProjectsExportConfig | None = None
+    ) -> Path:
+        """Export a project to a specified file path
+
+        Args:
+            key: The key of the project to export
+            path: The path to which the project gets exported to
+            replace: If True, replace the existing project with a new one.
+            configuration: Optional configuration for export
+
+        Returns:
+            Path to the exported file
+        """
+        if path is None:
+            raise ProjectExportError("Path must be specified.")
+
+        if configuration is None:
+            configuration = ProjectsExportConfig()
+
+        if configuration.marshalling_plugin not in self._allowed_marshalling_plugins:
+            raise ProjectExportError(f"Invalid marshalling plugin '{configuration.marshalling_plugin}'")
+
+        url = self._url(f"/workspace/projects/{key}/export/{configuration.marshalling_plugin}")
+        extracted_project = self._client.http.get(url).raise_for_status()
+
+        if not extracted_project.content:
+            raise ProjectExportError(f"Export returned empty content for project '{key}'")
+
+        if configuration.extract_project_zip:
+            if path.exists() and not replace:
+                raise ProjectExportError(f"Directory '{path}' already exists. Use replace=True to overwrite.")
+            if path.exists():
+                rmtree(path)
+            path.mkdir(parents=True)
+            with ZipFile(BytesIO(extracted_project.content), "r") as zip_file:
+                zip_file.extractall(path)
+        else:
+            if path.exists() and not replace:
+                raise ProjectExportError(f"File '{path}' already exists. Use replace=True to overwrite.")
+            with path.open(mode="wb") as file:
+                file.write(extracted_project.content)
+
+        return path

cmem_client/repositories/protocols/__init__.py

@@ -0,0 +1,15 @@
+"""Protocol interfaces for repository operations.
+
+This package defines protocol interfaces that repositories can implement to
+provide consistent operations. Protocols
+allow for type-safe composition of repository functionality without requiring
+inheritance from concrete base classes.
+
+Available protocols:
+- CreateItemProtocol: For repositories that can create new items
+- DeleteItemProtocol: For repositories that can delete existing items
+- ImportItemProtocol: For repositories that can import items from files
+
+Repositories mix and match these protocols based on their capabilities,
+ensuring consistent interfaces across different resource types.
+"""

cmem_client/repositories/protocols/create_item.py

@@ -0,0 +1,125 @@
+"""Protocol interface for repository item creation operations.
+
+This module defines the CreateItemProtocol that repositories can implement
+to provide item creation capabilities. It includes comprehensive error handling
+for different API response formats and automatic repository refresh after
+successful creation.
+
+The protocol handles both DataIntegration (build) and DataPlatform (explore)
+API error formats, providing consistent error reporting across different
+Corporate Memory components.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from http import HTTPStatus
+from typing import TYPE_CHECKING, Protocol, TypeVar, runtime_checkable
+
+from httpx import HTTPError, Response
+from pydantic import ValidationError
+
+from cmem_client.exceptions import RepositoryModificationError
+from cmem_client.logging_utils import log_method
+from cmem_client.models.base import Model
+from cmem_client.models.error import ErrorResult, Problem
+from cmem_client.repositories.base.abc import ItemType, RepositoryConfig
+
+if TYPE_CHECKING:
+    from cmem_client.client import Client
+
+
+class CreateConfig(Model, ABC):
+    """Abstract base class for repository item creation configurations."""
+
+
+CreateItemConfig_contra = TypeVar("CreateItemConfig_contra", bound=CreateConfig, contravariant=True)
+
+
+@runtime_checkable
+class CreateItemProtocol(Protocol[ItemType, CreateItemConfig_contra]):
+    """Protocol which allows for creation of new items"""
+
+    _client: Client
+    _dict: dict[str, ItemType]
+    _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"""
+
+    @log_method
+    def create_item(
+        self, item: ItemType, skip_if_existing: bool = False, configuration: CreateItemConfig_contra | None = None
+    ) -> None:
+        """Create (add) a new item to the repository
+
+        Args:
+            item (ItemType): The item to add to the repository
+            skip_if_existing (bool, optional): If true, creating already existing items will be ignored
+            configuration (CreateItemConfig_contra | None): Optional configuration
+
+        Raises:
+            RepositoryModificationError: if an error occurs while creating the item
+            HTTPError: for any other http error
+        """
+        _ = configuration
+        if item.get_id() in self._dict:
+            if not skip_if_existing:
+                raise RepositoryModificationError(f"Item with id {item.get_id()} already exists.")
+            self.logger.info("Item '%s' already exists. Not creating new item.", item.get_id())
+            return
+        response = self._create_item(item)
+        if isinstance(response, Response):
+            self.raise_modification_error(response)
+        self.fetch_data()
+
+    def raise_modification_error(self, response: Response) -> None:
+        """Raise an exception if needed"""
+        if response.status_code == HTTPStatus.CREATED:
+            return
+
+        # some endpoint return OK instead of CREATED
+        # - /api/python/installPackageByName
+        if response.status_code == HTTPStatus.OK:
+            return
+
+        if self._config.component == "explore":
+            try:
+                problem = Problem.model_validate_json(response.content)
+                raise RepositoryModificationError(problem.get_exception_message())
+            except ValidationError as error:
+                raise RepositoryModificationError(response.content) from error
+
+        if self._config.component == "build":
+            try:
+                error_result = ErrorResult.model_validate_json(response.content)
+                raise RepositoryModificationError(f"{error_result.title}: {error_result.detail}")
+            except ValidationError as error:
+                raise RepositoryModificationError(response.content) from error
+
+        try:
+            response.raise_for_status()
+        except HTTPError as error:
+            raise RepositoryModificationError(str(error)) from error
+
+    @abstractmethod
+    def _create_item(self, item: ItemType, configuration: CreateItemConfig_contra | None = None) -> Response | None:
+        """Create (add) a new item to the repository (concrete implementation)
+
+        Args:
+            item (ItemType): The item to add to the repository
+            configuration (CreateItemConfig_contra | None): Optional configuration
+
+        Return:
+            Response: The response from the update request
+        """

cmem_client/repositories/protocols/delete_item.py

@@ -0,0 +1,95 @@
+"""Protocol interface for repository item deletion operations.
+
+This module defines the DeleteItemProtocol that repositories can implement
+to provide item deletion capabilities. It includes validation to ensure items
+exist before deletion and provides both individual and bulk deletion methods.
+
+The protocol implements the Python __delitem__ method to support standard
+dictionary-style deletion syntax while providing comprehensive error handling
+for HTTP communication failures.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Protocol, TypeVar, runtime_checkable
+
+from httpx import HTTPError
+
+from cmem_client.exceptions import RepositoryModificationError
+from cmem_client.logging_utils import log_method
+from cmem_client.models.base import Model
+from cmem_client.repositories.base.abc import ItemType
+
+if TYPE_CHECKING:
+    from cmem_client.client import Client
+
+
+class DeleteConfig(Model, ABC):
+    """Abstract base class for repository item deletion configurations."""
+
+
+DeleteItemConfig_contra = TypeVar("DeleteItemConfig_contra", bound=DeleteConfig, contravariant=True)
+
+
+@runtime_checkable
+class DeleteItemProtocol(Protocol[ItemType, DeleteItemConfig_contra]):
+    """Protocol which allows for deletion of items"""
+
+    _client: Client
+    _dict: dict[str, ItemType]
+    _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
+
+    def __delitem__(self, key: str) -> None:
+        """Delete an item from the repository"""
+        self.delete_item(key)
+
+    @log_method
+    def delete_item(
+        self, key: str, skip_if_missing: bool = False, configuration: DeleteItemConfig_contra | None = None
+    ) -> None:
+        """Delete an item from the repository
+
+        Args:
+            key (str): The key of the item to delete
+            skip_if_missing (bool, optional): If True, it is ignored if the deleted item even exists
+            configuration (DeleteItemConfig, optional): Optional configuration for deletion
+
+        Raises:
+            RepositoryModificationError: if an error occurs while creating the item
+            HTTPError: for any other http error
+        """
+        _ = configuration
+        if key not in self._dict:
+            if not skip_if_missing:
+                raise RepositoryModificationError(f"Repository item '{key}' does not exists.")
+            self.logger.info("Item '%s' does not exists, therefore not deleting.", key)
+            return
+        try:
+            self._delete_item(key=key)
+        except HTTPError as error:
+            raise RepositoryModificationError(f"Error on deleting repository item '{key}'.") from error
+
+        del self._dict[key]
+
+    @abstractmethod
+    def _delete_item(self, key: str, configuration: DeleteItemConfig_contra | None = None) -> None:
+        """Delete an item from the repository (concrete implementation)
+
+        This method is responsible for deleting the item from the server.
+        """
+
+    def delete_all(self) -> None:
+        """Delete all items from the repository"""
+        if hasattr(self, "fetch_data"):
+            self.fetch_data()
+        for key in list(self._dict):
+            self.delete_item(key=key)

cmem_client/repositories/protocols/export_item.py

@@ -0,0 +1,114 @@
+"""Protocol interface for repository item export operations.
+
+This module defines the ExportItemProtocol that repositories can implement
+to support exporting items to files.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Protocol, TypeVar, runtime_checkable
+
+from httpx import HTTPError
+
+from cmem_client.exceptions import RepositoryItemNotFoundError, RepositoryReadError
+from cmem_client.logging_utils import log_method
+from cmem_client.models.base import Model
+from cmem_client.repositories.base.abc import ItemType
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from cmem_client.client import Client
+
+
+class ExportConfig(Model, ABC):
+    """Abstract base class for Export Item Configuration Objects"""
+
+
+ExportItemConfig_contra = TypeVar("ExportItemConfig_contra", bound=ExportConfig, contravariant=True)
+
+
+@runtime_checkable
+class ExportItemProtocol(Protocol[ItemType, ExportItemConfig_contra]):
+    """Protocol which allows for exporting of items to a file path.
+
+    This protocol defines the interface that repositories must implement to support
+    exporting items to files. It provides both a public interface method and requires
+    implementation of a concrete export method.
+
+    Attributes:
+        _dict: Dictionary mapping item keys to repository items.
+    """
+
+    _client: Client
+    _dict: dict[str, ItemType]
+    _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
+
+    @log_method
+    def export_item(
+        self,
+        key: str,
+        path: Path | None = None,
+        replace: bool = False,
+        configuration: ExportItemConfig_contra | None = None,
+    ) -> Path:
+        """Export an item from the repository to a file path.
+
+        Args:
+            key: The key identifying the item to export.
+            path: The target file path for export. If None, a path will be generated.
+            replace: Whether to replace existing files at the target path.
+            configuration: Optional configuration for export behavior.
+
+        Returns:
+            The actual path where the item was exported.
+
+        Raises:
+            RepositoryItemNotFoundError: If the specified item key is not found.
+            RepositoryReadError: If there's an error during export or path mismatch.
+        """
+        if key not in self._dict:
+            raise RepositoryItemNotFoundError(f"Repository item '{key}' not found.")
+        try:
+            new_path = self._export_item(path=path, key=key, replace=replace, configuration=configuration)
+        except HTTPError as error:
+            raise RepositoryReadError(f"Error on exporting repository item '{key}'.") from error
+        if path and path != new_path:
+            raise RepositoryReadError(
+                f"Repository export returned different path than requested: '{path}' != `{new_path}`"
+            )
+        if path:
+            return path
+
+        return new_path
+
+    @abstractmethod
+    def _export_item(
+        self, key: str, path: Path | None, replace: bool = False, configuration: ExportItemConfig_contra | None = None
+    ) -> Path:
+        """Export an item from the repository (concrete implementation).
+
+        This method must be implemented by concrete repository classes to handle
+        the actual export operation. It performs the low-level work of writing
+        the item data to the specified file path.
+
+        Args:
+            key: The key identifying the item to export.
+            path: The file path where the item should be exported. If None, a path
+                should be generated by the implementation.
+            replace: Whether to replace existing files at the target path.
+            configuration: Optional configuration for export behavior.
+
+        Returns:
+            The actual path where the item was exported. This may differ from the
+            input path if the implementation generates a different filename.
+        """