cmem-client 0.5.0__py3-none-any.whl

cmem_client/components/workspace.py

@@ -0,0 +1,194 @@
+"""Corporate Memory DataIntegration (build) workspace management.
+
+This module provides the BuildWorkspace component for managing Corporate Memory's
+DataIntegration workspace. The workspace contains projects, datasets, transformations,
+and other integration artifacts organized in a hierarchical structure.
+
+The BuildWorkspace component provides high-level operations for workspace backup
+and restoration, allowing entire workspace snapshots to be exported and imported
+as ZIP archives. This is essential for deployment, migration, and disaster recovery
+scenarios.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from cmem_client.logging_utils import log_method
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from httpx import Response
+
+    from cmem_client.client import Client
+
+
+class BuildWorkspace:
+    """High-level interface for Corporate Memory DataIntegration workspace operations.
+
+    The BuildWorkspace component provides administrative and operational methods for
+    managing the Corporate Memory DataIntegration (build) workspace. It handles
+    workspace-level operations including complete backup and restoration of all
+    workspace contents as ZIP archives.
+
+    The workspace contains all DataIntegration artifacts including:
+    - Projects and their configurations
+    - Datasets and data sources
+    - Transformation workflows and mapping rules
+    - Workflow definitions and scheduling configurations
+
+    This component abstracts the complexities of the DataIntegration API and provides
+    a convenient interface for workspace-wide administrative tasks.
+
+    Attributes:
+        _client: The Corporate Memory client instance used for API communication.
+
+    Administrative Operations:
+        - Complete workspace backup and restoration
+        - Environment synchronization and migration
+        - Disaster recovery and rollback capabilities
+        - Deployment automation and CI/CD integration
+
+    See Also:
+        For individual project operations, use the repositories.projects module
+        which provides CRUD operations for specific DataIntegration projects.
+    """
+
+    _client: Client
+    """The Corporate Memory client instance used for making API requests to the DataIntegration API."""
+
+    def __init__(self, client: Client) -> None:
+        """Initialize a new BuildWorkspace component instance.
+
+        Creates a BuildWorkspace component that uses the provided client for
+        API communication with the DataIntegration workspace endpoints.
+
+        Args:
+            client: A configured Corporate Memory client instance with
+                authentication and endpoint configuration.
+
+        Note:
+            This constructor is typically called automatically by the
+            Client class when accessing the workspace property. Direct
+            instantiation is rarely needed in normal usage.
+        """
+        self._client = client
+        self.logger = logging.getLogger(f"{self._client.logger.name}.{self.__class__.__name__}")
+
+    @log_method
+    def import_from_zip(self, path: Path) -> Response:
+        """Import and restore a complete workspace backup from a ZIP archive.
+
+        Warning: This operation overwrites existing workspace content.
+        All projects, datasets, transformations, and other workspace artifacts will be
+        replaced or removed during the import process.
+
+        Restores a Corporate Memory DataIntegration workspace from a ZIP backup
+        archive created by export_to_zip(). The import process loads all workspace
+        artifacts including projects, datasets, transformations, vocabularies,
+        and configurations from the archive into the current workspace.
+
+        Args:
+            path: The file system path to the ZIP backup archive to import.
+                The file must be a valid workspace backup archive created by
+                export_to_zip() or compatible with the DataIntegration workspace format.
+
+        Returns:
+            Response: The HTTP response object from the import operation.
+                Check response.status_code for success (200) and response.json()
+                for detailed import results and any warnings or errors.
+
+        Raises:
+            HTTPError: If the import request fails due to network issues, server
+                errors, insufficient permissions, or invalid archive format.
+            OSError: If the specified backup file cannot be read due to file system
+                permissions or if the file does not exist.
+
+        Important Considerations:
+            - **Data Validation**: Invalid configurations in the archive may cause failures
+            - **Dependency Resolution**: Project dependencies must be satisfied after import
+
+        Performance Notes:
+            - Large workspace archives may take significant time to import
+            - The workspace may be partially unavailable during import
+            - Network bandwidth affects upload speed for large archives
+            - Import processing time depends on workspace complexity
+
+        Use Cases:
+            - Environment synchronization between development and production
+            - Workspace migration between Corporate Memory instances
+            - Disaster recovery from workspace backups
+            - Deployment automation and CI/CD pipeline integration
+            - Team collaboration and workspace sharing
+
+        See Also:
+            Use export_to_zip() to create workspace archives for import with this method.
+        """
+        url = self._client.config.url_build_api / "/workspace/import/xmlZip"
+        files = {"file": (path.name, path.open("rb"), "application/octet-stream")}
+        response = self._client.http.post(url=url, files=files)
+        response.raise_for_status()
+        return response
+
+    @log_method
+    def export_to_zip(self, path: Path) -> None:
+        """Export a complete backup of the workspace as a ZIP archive.
+
+        Creates a comprehensive backup of the entire Corporate Memory DataIntegration
+        workspace, including all projects, datasets, transformations, vocabularies,
+        workflows, and configurations. The backup is streamed directly to the
+        specified file path as a compressed ZIP archive.
+
+        This operation creates a point-in-time snapshot of the complete workspace
+        that can be used for:
+        - Environment migration and synchronization
+        - Disaster recovery and backup strategies
+        - Development and testing environment setup
+        - Deployment automation and CI/CD pipelines
+        - Team collaboration and workspace sharing
+
+        Args:
+            path: The file system path where the ZIP workspace archive will be saved.
+                The path should include the .zip extension and the parent directory
+                must exist and be writable.
+
+        Raises:
+            HTTPError: If the export request fails due to network issues, server
+                errors, or insufficient permissions.
+            OSError: If the specified path cannot be written to due to file system
+                permissions or disk space issues.
+
+        Performance Notes:
+            - The export is streamed directly to disk to minimize memory usage
+            - Large workspaces may take significant time to export completely
+            - Network bandwidth and storage I/O will impact export duration
+            - The operation blocks until the entire workspace is exported
+            - Export size depends on workspace complexity and resource files
+
+        Security Considerations:
+            - Workspace archives contain all project data and configurations
+            - May include database connection strings and access credentials
+            - Should be stored securely with appropriate access controls
+            - Consider encryption for sensitive workspace data
+            - Review archive contents before sharing or transferring
+
+        Use Cases:
+            - **Environment Promotion**: Move workspace from dev to production
+            - **Disaster Recovery**: Regular backups for business continuity
+            - **Team Onboarding**: Share workspace setups with new team members
+            - **CI/CD Integration**: Automated workspace deployment pipelines
+            - **Migration Support**: Transfer workspaces between instances
+            - **Version Control**: Track workspace state changes over time
+
+        See Also:
+            Use import_from_zip() to restore workspace archives created by this method.
+        """
+        url = self._client.config.url_build_api / "/workspace/export/xmlZip"
+        with (
+            path.open("wb") as download_file,
+            self._client.http.stream(method="GET", url=url) as response,
+        ):
+            for chunk in response.iter_bytes():
+                download_file.write(chunk)

cmem_client/config.py

@@ -0,0 +1,364 @@
+"""Configuration management for the Corporate Memory client.
+
+This module provides the Config class that handles all configuration aspects
+of the Corporate Memory client, including URL construction, SSL verification,
+authentication endpoints, and environment variable parsing.
+
+The Config class automatically constructs various API endpoints based on a base URL
+and provides flexible configuration through both programmatic setup and environment
+variables, making it suitable for different deployment environments.
+"""
+
+from os import getenv
+
+from cmem_client.exceptions import ClientEnvConfigError
+from cmem_client.models.url import HttpUrl
+
+
+class Config:
+    """Corporate Memory Client configuration.
+
+    The Config class manages all configuration aspects for connecting to Corporate
+    Memory instances, including URL construction, SSL verification, timeout settings,
+    and authentication endpoints. It provides both programmatic configuration and
+    automatic configuration from environment variables.
+
+    The class automatically constructs various API endpoints based on a base URL
+    and realm configuration, with support for customizing individual endpoints
+    when needed for complex deployment scenarios.
+
+    Attributes:
+        _realm_id: The Keycloak realm identifier for authentication.
+        _verify: SSL/TLS certificate verification flag.
+        _url_base: Base URL of the Corporate Memory instance.
+        _url_keycloak: Base URL of the Keycloak authentication server.
+        _url_keycloak_issuer: Keycloak realm issuer URL for token validation.
+        _url_build_api: DataIntegration (build) API endpoint URL.
+        _url_explore_api: DataPlatform (explore) API endpoint URL.
+        _url_oauth_token: OAuth token endpoint URL for authentication.
+        timeout: HTTP request timeout in seconds.
+    """
+
+    _realm_id: str = "cmem"
+    """Keycloak realm identifier, defaults to 'cmem' for standard deployments."""
+
+    _verify: bool = True
+    """SSL/TLS certificate verification flag, defaults to True for security."""
+
+    _url_base: HttpUrl
+    """Base URL of the Corporate Memory instance, used to construct other endpoints."""
+
+    _url_keycloak: HttpUrl
+    """Base URL of the Keycloak authentication server, derived from base URL if not set."""
+
+    _url_keycloak_issuer: HttpUrl
+    """Keycloak realm issuer URL, constructed from Keycloak URL and realm ID."""
+
+    _url_build_api: HttpUrl
+    """DataIntegration (build) API endpoint URL, derived from base URL if not set."""
+
+    _url_explore_api: HttpUrl
+    """DataPlatform (explore) API endpoint URL, derived from base URL if not set."""
+
+    _url_oauth_token: HttpUrl
+    """OAuth token endpoint URL, constructed from Keycloak issuer URL."""
+
+    timeout: int = 10
+    """HTTP request timeout in seconds, defaults to 10 seconds."""
+
+    def __init__(self, url_base: HttpUrl | str, realm_id: str = "cmem") -> None:
+        """Initialize a new Config instance.
+
+        Args:
+            url_base: The base URL of the Corporate Memory instance. Can be
+                provided as either an HttpUrl object or a string that will
+                be converted to HttpUrl.
+            realm_id: The Keycloak realm identifier for authentication.
+                Defaults to "cmem" for standard Corporate Memory deployments.
+        """
+        self.url_base = HttpUrl(url_base) if isinstance(url_base, str) else url_base
+        self.realm_id = realm_id
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        """Create a Config instance from environment variables.
+
+        This factory method creates a configuration by reading various environment
+        variables that specify Corporate Memory connection details. It provides
+        a convenient way to configure the client in containerized or cloud
+        environments where configuration is managed through environment variables.
+
+        Returns:
+            A Config instance configured with values from environment variables.
+
+        Raises:
+            ClientEnvConfigError: If the required CMEM_BASE_URI environment
+                variable is not set.
+
+        Environment Variables:
+            CMEM_BASE_URI (required): Base URL of the Corporate Memory instance.
+            DI_API_ENDPOINT (optional): DataIntegration API endpoint override.
+            DP_API_ENDPOINT (optional): DataPlatform API endpoint override.
+            KEYCLOAK_BASE_URI (optional): Keycloak server URL override.
+            KEYCLOAK_REALM_ID (optional): Keycloak realm identifier override.
+            OAUTH_TOKEN_URI (optional): OAuth token endpoint override.
+            SSL_VERIFY (optional): SSL certificate verification flag.
+        """
+        cmem_base_uri = getenv("CMEM_BASE_URI")
+        di_api_endpoint = getenv("DI_API_ENDPOINT")
+        dp_api_endpoint = getenv("DP_API_ENDPOINT")
+        keycloak_base_uri = getenv("KEYCLOAK_BASE_URI")
+        keycloak_realm_id = getenv("KEYCLOAK_REALM_ID")
+        oauth_token_uri = getenv("OAUTH_TOKEN_URI")
+        ssl_verify = getenv("SSL_VERIFY")
+        """
+        requests_ca_bundle = getenv("REQUESTS_CA_BUNDLE")
+        """
+
+        if not cmem_base_uri:
+            raise ClientEnvConfigError("CMEM_BASE_URI environment variable not set.")
+        config = cls(url_base=cmem_base_uri)
+
+        if ssl_verify:
+            config.verify = bool(ssl_verify)
+        if keycloak_realm_id:
+            config.realm_id = keycloak_realm_id
+        if keycloak_base_uri:
+            config.url_keycloak = HttpUrl(keycloak_base_uri)
+        if oauth_token_uri:
+            config.url_oauth_token = HttpUrl(oauth_token_uri)
+        if di_api_endpoint:
+            config.url_build_api = HttpUrl(di_api_endpoint)
+        if dp_api_endpoint:
+            config.url_explore_api = HttpUrl(dp_api_endpoint)
+        return config
+
+    @classmethod
+    def from_cmempy(cls) -> "Config":
+        """Create a Config instance from a cmempy environment."""
+        try:
+            import cmem.cmempy.config as cmempy_config  # noqa: PLC0415
+        except ImportError as error:
+            raise OSError("cmempy is not installed.") from error
+        cmem_base_uri = cmempy_config.get_cmem_base_uri()
+        di_api_endpoint = cmempy_config.get_di_api_endpoint()
+        dp_api_endpoint = cmempy_config.get_dp_api_endpoint()
+        keycloak_base_uri = cmempy_config.get_keycloak_base_uri()
+        keycloak_realm_id = cmempy_config.get_keycloak_realm_id()
+        oauth_token_uri = cmempy_config.get_oauth_token_uri()
+        ssl_verify = cmempy_config.get_ssl_verify()
+        """
+        requests_ca_bundle = getenv("REQUESTS_CA_BUNDLE")
+        """
+
+        if not cmem_base_uri:
+            raise ClientEnvConfigError("CMEM_BASE_URI environment variable not set.")
+        config = cls(url_base=cmem_base_uri)
+
+        if ssl_verify:
+            config.verify = bool(ssl_verify)
+        if keycloak_realm_id:
+            config.realm_id = keycloak_realm_id
+        if keycloak_base_uri:
+            config.url_keycloak = HttpUrl(keycloak_base_uri)
+        if oauth_token_uri:
+            config.url_oauth_token = HttpUrl(oauth_token_uri)
+        if di_api_endpoint:
+            config.url_build_api = HttpUrl(di_api_endpoint)
+        if dp_api_endpoint:
+            config.url_explore_api = HttpUrl(dp_api_endpoint)
+        return config
+
+    @property
+    def verify(self) -> bool:
+        """Get the SSL/TLS certificate verification flag.
+
+        Returns:
+            True if SSL/TLS certificates should be verified, False otherwise.
+            Defaults to True for security reasons.
+
+        Note:
+            Disabling SSL verification should only be done in development
+            environments. Production deployments should always verify certificates.
+        """
+        return self._verify
+
+    @verify.setter
+    def verify(self, value: bool) -> None:
+        """Set the SSL/TLS certificate verification flag.
+
+        Args:
+            value: True to enable SSL/TLS certificate verification,
+                False to disable it.
+
+        Warning:
+            Disabling SSL verification reduces security and should only be
+            done in development environments or with proper security measures.
+        """
+        self._verify = value
+
+    @property
+    def url_base(self) -> HttpUrl:
+        """Get the base URL of the Corporate Memory instance.
+
+        Returns:
+            The base URL from which all other API endpoints are derived.
+            This is the root URL of the Corporate Memory deployment.
+        """
+        return self._url_base
+
+    @url_base.setter
+    def url_base(self, value: HttpUrl) -> None:
+        """Set the base URL of the Corporate Memory instance.
+
+        Args:
+            value: The base URL of the Corporate Memory instance.
+                Must be a valid HttpUrl object.
+
+        Note:
+            Changing the base URL will affect the construction of all
+            derived endpoints unless they have been explicitly overridden.
+        """
+        self._url_base = value
+
+    @property
+    def url_explore_api(self) -> HttpUrl:
+        """Get the DataPlatform (explore) API endpoint URL.
+
+        Returns the URL for the DataPlatform API, which handles graph storage,
+        SPARQL queries, and semantic data exploration. If not explicitly set,
+        it defaults to the base URL with '/dataplatform/' appended.
+
+        Returns:
+            The DataPlatform API endpoint URL.
+        """
+        try:
+            return self._url_explore_api
+        except AttributeError:
+            return self.url_base / "/dataplatform/"
+
+    @url_explore_api.setter
+    def url_explore_api(self, value: HttpUrl) -> None:
+        """Set the DataPlatform (explore) API endpoint URL.
+
+        Args:
+            value: The DataPlatform API endpoint URL. This overrides the
+                default URL construction based on the base URL.
+
+        Note:
+            Setting this explicitly allows for custom API endpoint configurations
+            in complex deployment scenarios with separate DataPlatform services.
+        """
+        self._url_explore_api = value
+
+    @property
+    def url_build_api(self) -> HttpUrl:
+        """Get the DataIntegration (build) API endpoint URL.
+
+        Returns the URL for the DataIntegration API, which handles projects,
+        datasets, transformations, and data integration workflows. If not
+        explicitly set, it defaults to the base URL with '/dataintegration/' appended.
+
+        Returns:
+            The DataIntegration API endpoint URL.
+        """
+        try:
+            return self._url_build_api
+        except AttributeError:
+            return self.url_base / "/dataintegration/"
+
+    @url_build_api.setter
+    def url_build_api(self, value: HttpUrl) -> None:
+        """Set the DataIntegration (build) API endpoint URL.
+
+        Args:
+            value: The DataIntegration API endpoint URL. This overrides the
+                default URL construction based on the base URL.
+
+        Note:
+            Setting this explicitly allows for custom API endpoint configurations
+            in complex deployment scenarios with separate DataIntegration services.
+        """
+        self._url_build_api = value
+
+    @property
+    def url_keycloak(self) -> HttpUrl:
+        """Get the Keycloak authentication server base URL.
+
+        Returns the URL of the Keycloak server used for authentication and
+        authorization. If not explicitly set, it defaults to the base URL
+        with '/auth/' appended.
+
+        Returns:
+            The Keycloak server base URL.
+        """
+        try:
+            return self._url_keycloak
+        except AttributeError:
+            return self.url_base / "/auth/"
+
+    @url_keycloak.setter
+    def url_keycloak(self, value: HttpUrl) -> None:
+        """Set the Keycloak authentication server base URL.
+
+        Args:
+            value: The Keycloak server base URL. This overrides the default
+                URL construction based on the base URL.
+
+        Note:
+            Setting this explicitly allows for configurations where Keycloak
+            is deployed separately from the main Corporate Memory instance.
+        """
+        self._url_keycloak = value
+
+    @property
+    def url_keycloak_issuer(self) -> HttpUrl:
+        """Get the Keycloak realm issuer URL.
+
+        Returns the issuer URL for the specific Keycloak realm, which is used
+        for token validation and OpenID Connect flows. This URL is constructed
+        from the Keycloak base URL and the realm identifier.
+
+        Returns:
+            The Keycloak realm issuer URL.
+
+        Note:
+            This property cannot be set directly. It is automatically constructed
+            based on the Keycloak URL and realm ID. To customize it, set the
+            url_keycloak property and realm_id attribute instead.
+        """
+        try:
+            return self._url_keycloak_issuer
+        except AttributeError:
+            return self.url_keycloak / f"/realms/{self.realm_id}/"
+
+    @property
+    def url_oauth_token(self) -> HttpUrl:
+        """Get the OAuth 2.0 token endpoint URL.
+
+        Returns the URL for the OAuth 2.0 token endpoint, which is used by
+        authentication providers to obtain access tokens. If not explicitly
+        set, it defaults to the standard OpenID Connect token endpoint path
+        within the Keycloak realm.
+
+        Returns:
+            The OAuth 2.0 token endpoint URL.
+        """
+        try:
+            return self._url_oauth_token
+        except AttributeError:
+            return self.url_keycloak_issuer / "/protocol/openid-connect/token"
+
+    @url_oauth_token.setter
+    def url_oauth_token(self, value: HttpUrl) -> None:
+        """Set the OAuth 2.0 token endpoint URL.
+
+        Args:
+            value: The OAuth 2.0 token endpoint URL. This overrides the
+                default URL construction based on the Keycloak issuer URL.
+
+        Note:
+            Setting this explicitly allows for custom OAuth configurations
+            or alternative token endpoints in specialized deployment scenarios.
+        """
+        self._url_oauth_token = value

cmem_client/exceptions.py

@@ -0,0 +1,82 @@
+"""Custom exception classes for the cmem_client package.
+
+This module defines all custom exceptions used throughout the cmem_client library,
+providing specific error types for different failure scenarios such as authentication,
+configuration, and repository operations.
+"""
+
+
+class BaseError(Exception):
+    """Base exception for all cmem_client exceptions."""
+
+
+class ClientNoAuthProviderError(BaseError):
+    """Exception raised when no auth provider is given but needed."""
+
+
+class ClientEnvConfigError(BaseError):
+    """Exception raised when an environment key is missing."""
+
+
+class RepositoryItemNotFoundError(BaseError):
+    """Exception raised when a specific item is missing in a repository."""
+
+
+class RepositoryConfigError(BaseError):
+    """Exception raised when a repository configuration is invalid."""
+
+
+class RepositoryModificationError(BaseError):
+    """Exception raised when a repository modification failed or is invalid."""
+
+
+class RepositoryReadError(BaseError):
+    """Exception raised when a repository read operation failed or is invalid."""
+
+
+class MarketplaceReadError(BaseError):
+    """Exception raised when a marketplace read operation failed or is invalid."""
+
+
+class MarketplaceWriteError(BaseError):
+    """Exception raised when a marketplace write operation failed or is invalid."""
+
+
+class WorkflowReadError(BaseError):
+    """Exception raised when a workflow read operation failed or is invalid."""
+
+
+class WorkflowExecutionError(BaseError):
+    """Exception raised when a workflow execution operation failed or is invalid."""
+
+
+class GraphImportError(RepositoryModificationError):
+    """Exception raised when a vocabulary import operation fails."""
+
+
+class GraphExportError(BaseError):
+    """Exception raised when a vocabulary export operation fails."""
+
+
+class ProjectImportError(RepositoryModificationError):
+    """Exception raised when a project import operation fails."""
+
+
+class ProjectExportError(RepositoryReadError):
+    """Exception raised when a project export operation fails."""
+
+
+class PythonPackageImportError(RepositoryModificationError):
+    """Exception raised when a python plugin import fails."""
+
+
+class MarketplacePackagesImportError(RepositoryModificationError):
+    """Exception raised when a marketplace package installation fails."""
+
+
+class MarketplacePackagesDeleteError(RepositoryModificationError):
+    """Exception raised when a marketplace package deletion fails."""
+
+
+class MarketplacePackagesExportError(BaseError):
+    """Exception raised when a marketplace packages export fails."""

cmem_client/logging_utils.py

@@ -0,0 +1,49 @@
+"""Logging utilities.
+
+Note: This module uses Any for kwargs to match the stdlib logging interface signature.
+"""
+# ruff: noqa: ANN401
+
+import logging
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, ParamSpec, TypeVar
+
+GenericParameter = ParamSpec("GenericParameter")
+GenericResult = TypeVar("GenericResult")
+
+TRACE_LEVEL = 5
+logging.addLevelName(TRACE_LEVEL, "TRACE")
+
+
+def _trace_method(self: logging.Logger, message: str, *args: object, **kwargs: Any) -> None:
+    """Method to add to Logger instances for TRACE level."""
+    if self.isEnabledFor(TRACE_LEVEL):
+        self.log(TRACE_LEVEL, message, *args, **kwargs)
+
+
+def install_trace_logger() -> None:
+    """Install TRACE level logging dynamically."""
+    logging.Logger.trace = _trace_method  # type: ignore[attr-defined]
+
+    def trace_root(message: str, *args: object, **kwargs: Any) -> None:
+        logging.getLogger().log(TRACE_LEVEL, message, *args, **kwargs)
+
+    logging.trace = trace_root  # type: ignore[attr-defined]
+
+
+def log_method(method: Callable[GenericParameter, GenericResult], display_name: str | None = None):  # noqa: ANN201
+    """Wrapper to log entry and exit of methods using TRACE level.
+
+    Note: Don't use this on methods with sensitive information as they might get logged too
+    """
+    display_name = display_name or method.__name__
+
+    @wraps(method)
+    def _wrapper(self: Any, *args: Any, **kwargs: Any):  # noqa: ANN202
+        self.logger.trace(f"{display_name}() called with {args!r} and {kwargs!r}")  # type: ignore[attr-defined]
+        result = method(self, *args, **kwargs)
+        self.logger.trace(f"{display_name}() returned {result!r}")  # type: ignore[attr-defined]
+        return result
+
+    return _wrapper