cmem-client 0.5.0__py3-none-any.whl

cmem_client/models/__init__.py

@@ -0,0 +1,16 @@
+"""Pydantic data models for Corporate Memory entities.
+
+This package contains all data models used throughout the cmem_client library,
+implementing structured data validation and serialization using Pydantic v2.
+These models represent various Corporate Memory entities and API responses.
+
+Key model categories:
+- Base models: Common base classes and interfaces
+- Business entities: Projects, datasets, graphs, access conditions
+- Authentication: Token models for OAuth flows
+- API responses: Error models and result sets
+- Utilities: URL handling and validation
+
+All models inherit from either Model (for general data) or ReadRepositoryItem
+(for entities that can be retrieved from repositories).
+"""

cmem_client/models/access_condition.py

@@ -0,0 +1,147 @@
+"""Access control and authorization models for Corporate Memory.
+
+This module defines models for managing access conditions in Corporate Memory,
+which control user and group permissions for graphs, actions, and other resources.
+Access conditions form the foundation of Corporate Memory's authorization system.
+
+The AccessCondition model supports both static permissions (defined at creation)
+and dynamic permissions (computed via SPARQL queries), providing flexible
+access control patterns for different organizational needs.
+
+Access conditions can grant various permissions including graph read/write access,
+action execution rights, and management permissions for other access conditions.
+"""
+
+from datetime import datetime
+
+from pydantic import Field
+
+from cmem_client.models.base import Model, ReadRepositoryItem
+from cmem_client.repositories.base.paged_list import PageDescription
+
+NS_AC = "http://eccenca.com/ac/"
+NS_ACTION = "https://vocab.eccenca.com/auth/Action/"
+
+
+class AccessCondition(Model, ReadRepositoryItem):
+    """An access condition"""
+
+    iri: str = Field(description="The IRI of the access condition.", examples=[f"{NS_AC}my-condition"])
+    name: str = Field(description="A short name to identify the access condition.", examples=["My Access Condition"])
+    comment: str | None = Field(
+        default=None,
+        description="An optional description to provide more context information of the access condition.",
+        examples=["This condition is of me ..."],
+    )
+    requires_account: str | None = Field(
+        alias="requiresAccount",
+        default=None,
+        description="A specific account IRI required by the access condition.",
+        examples=["http://eccenca.com/admin"],
+    )
+    requires_group: list[str] = Field(
+        alias="requiresGroup",
+        default=[],
+        description="The groups (IRI) the account must be member of to meet the access condition.",
+        examples=[["http://eccenca.com/elds-admins"]],
+    )
+    readable_graphs: list[str] = Field(
+        alias="readableGraphs",
+        default=[],
+        description="Grants read access to a graph - list of Graph IRIs.",
+        examples=[["https://vocab.eccenca.com/shacl/", "https://vocab.eccenca.com/auth/AllGraphs"]],
+    )
+    writable_graphs: list[str] = Field(
+        alias="writableGraphs",
+        default=[],
+        description="Grants read/write access to a graph - list of Graph IRIs.",
+        examples=[["https://vocab.eccenca.com/shacl/", "https://vocab.eccenca.com/auth/AllGraphs"]],
+    )
+    allowed_actions: list[str] = Field(
+        alias="allowedActions",
+        default=[],
+        description="Grants permission to execute an action - list of Action IRIs.",
+        examples=[[f"{NS_ACTION}Build", f"{NS_ACTION}AllActions"]],
+    )
+    grant_allowed_actions: list[str] = Field(
+        alias="grantAllowedActions",
+        default=[],
+        description="Grants management of conditions granting action allowance for actions matching"
+        " the defined pattern.",
+        examples=[[f"{NS_ACTION}Build*", "*"]],
+    )
+    grant_read_patterns: list[str] = Field(
+        alias="grantReadPatterns",
+        default=[],
+        description="Grants management of conditions granting read access on graphs matching the defined pattern.",
+        examples=[["https://example.org/*", "*"]],
+    )
+    grant_write_patterns: list[str] = Field(
+        alias="grantWritePatterns",
+        default=[],
+        description="Grants management of conditions granting write access on graphs matching the defined pattern.",
+        examples=[["https://example.org/*", "*"]],
+    )
+    query: str | None = Field(
+        alias="dynamicAccessConditionQuery",
+        default=None,
+        description="A SPARQL SELECT query which returns the following projection variables: user, group,"
+        " readGraph, and writeGraph.",
+        examples=[
+            """
+PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+PREFIX dct: <http://purl.org/dc/terms/>
+PREFIX void: <http://rdfs.org/ns/void#>
+
+SELECT  ?user ?group ?readGraph ?writeGraph
+WHERE
+{
+  GRAPH ?writeGraph {
+    ?writeGraph rdf:type void:Dataset .
+    ?writeGraph dct:creator ?user .
+  }
+}
+        """
+        ],
+    )
+    creator: str | None = Field(
+        default=None,
+        description="The IRI of the account which created the access condition.",
+        examples=["http://eccenca.com/admin"],
+    )
+    created: datetime | None = Field(
+        default=None, description="The time when the access condition was created.", examples=["2025-09-12T09:09:48Z"]
+    )
+
+    def get_id(self) -> str:
+        """Get the IRI of the access condition"""
+        return self.iri
+
+    def set_iri(self, local_name: str) -> None:
+        """Set the IRI of the access condition based on a new local name
+
+        this just adds the namespace prefix
+        """
+        self.iri = f"{NS_AC}{local_name}"
+
+    def get_create_request(self) -> dict:
+        """Create a CreateAccessConditionRequest dict
+
+        This object is used to create new access condition.
+        """
+        if not self.get_id().startswith(NS_AC):
+            raise ValueError(f"Access condition ID must start with '{NS_AC}'")
+        data = self.model_dump(by_alias=True)
+        data["staticId"] = self.get_id().replace(NS_AC, "")
+        for key in ["iri", "creator", "created"]:
+            # remove not needed keys if present
+            if key in data:
+                del data[key]
+        return data
+
+
+class AccessConditionResultSet(Model):
+    """An access condition result set"""
+
+    content: list[AccessCondition]
+    page: PageDescription

cmem_client/models/base.py

@@ -0,0 +1,30 @@
+"""Base model classes for all cmem_client data models.
+
+This module provides the foundational model classes that all other models
+inherit from, establishing common patterns for data validation, serialization,
+and repository interactions.
+
+The Model class serves as the base for all Pydantic models in the library,
+while ReadRepositoryItem provides an additional interface for entities that
+can be retrieved from repositories and have identifiable IDs.
+"""
+
+from abc import ABC, abstractmethod
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Model(BaseModel):
+    """Base model for all cmem-client models."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ReadRepositoryItem(BaseModel, ABC):
+    """Abstract base class for items of a read repository"""
+
+    model_config = ConfigDict(extra="allow")
+
+    @abstractmethod
+    def get_id(self) -> str:
+        """Get the id of the item."""

cmem_client/models/dataset.py

@@ -0,0 +1,32 @@
+"""Corporate Memory dataset models for data integration.
+
+This module defines models for representing datasets within Corporate Memory
+projects. Datasets are data sources or sinks used in data integration workflows,
+connecting to various external systems through plugins.
+
+The Dataset model represents the configuration and metadata of datasets within
+the DataIntegration environment, including their association with projects
+and the plugins that handle their data access.
+"""
+
+from pydantic import Field
+
+from cmem_client.models.base import Model, ReadRepositoryItem
+
+
+class Dataset(ReadRepositoryItem):
+    """A Dataset Description (Build)"""
+
+    id: str
+    project_id: str = Field(alias="projectId")
+    plugin_id: str = Field(alias="pluginId")
+
+    def get_id(self) -> str:
+        """Get the ID of the dataset"""
+        return f"{self.project_id}:{self.id}"
+
+
+class DatasetSearchResultSet(Model):
+    """A dataset search result set"""
+
+    results: list[Dataset]

cmem_client/models/error.py

@@ -0,0 +1,67 @@
+"""Error response models for Corporate Memory API error handling.
+
+This module defines models for parsing and handling error responses from
+both the DataIntegration (build) and DataPlatform (explore) APIs. Different
+API endpoints return different error response formats, and these models
+provide a unified way to handle them.
+
+The Problem model handles DataPlatform API errors, while ErrorResult handles
+DataIntegration API errors. Both include methods for generating human-readable
+error messages for debugging and user feedback.
+"""
+
+from typing import Literal
+
+from pydantic import Field
+
+from cmem_client.models.base import Model
+
+
+class Violation(Model):
+    """A data violation, communicated with a problem"""
+
+    field: str
+    message: str
+
+
+class Problem(Model):
+    """A problem, communicated by the server
+
+    This type of response is returned by the explore APIs (DataPlatform)
+    """
+
+    type: str
+    title: str
+    status: int
+    details: str = Field(default="")
+    violations: list[Violation] = Field(default=[])
+
+    def get_exception_message(self) -> str:
+        """Get error message"""
+        text = f"{self.title} ({self.status}) - "
+        if self.details:
+            text += f" {self.details}"
+        if len(self.violations) > 0:
+            text += f" with {len(self.violations)} violation(s) -"
+            for violation in self.violations:
+                text += f" {violation.message} ({violation.field})"
+        return text
+
+
+class ErrorResultIssue(Model):
+    """An issue listed with an ErrorResult"""
+
+    type: Literal["Error", "Warning", "Info"]
+    message: str
+    id: str
+
+
+class ErrorResult(Model):
+    """An error result, communicated by the server
+
+    returned by the build APIs (DataIntegration)
+    """
+
+    title: str
+    detail: str
+    issues: list[ErrorResultIssue] | None

cmem_client/models/graph.py

@@ -0,0 +1,26 @@
+"""RDF graph models for Corporate Memory knowledge graphs.
+
+This module defines models for representing RDF graphs in Corporate Memory's
+DataPlatform (explore) environment. Graphs contain semantic data and are
+the primary storage units for knowledge graphs.
+
+The Graph model includes metadata about graph permissions, assigned semantic
+classes, and access control, providing the foundation for graph-based
+operations in the explore APIs.
+"""
+
+from pydantic import Field
+
+from cmem_client.models.base import Model, ReadRepositoryItem
+
+
+class Graph(Model, ReadRepositoryItem):
+    """A graph"""
+
+    iri: str
+    writeable: bool
+    assigned_classes: list[str] = Field(alias="assignedClasses")
+
+    def get_id(self) -> str:
+        """Get the IRI of the graph"""
+        return self.iri

cmem_client/models/item.py

@@ -0,0 +1,143 @@
+"""ImportItem base class and inherited classes"""
+
+import tempfile
+import zipfile
+from abc import ABC, abstractmethod
+from pathlib import Path
+from types import TracebackType
+from typing import ClassVar
+
+from cmem_client.models.base import Model
+
+
+class ImportItem(ABC, Model):
+    """Abstract base class for different import source types.
+
+    Each concrete implementation represents a different source type
+    (file, directory, zip, etc.) and knows how to prepare itself
+    for import by providing a Path to a directory or file.
+    """
+
+    import_type: ClassVar[str]
+
+    def __init__(self, source: Path | str) -> None:
+        """Initialize the import item with its source.
+
+        Args:
+            source: Source path or identifier for the import
+        """
+        super().__init__()
+        self.source = Path(source) if isinstance(source, str) else source
+        self._prepared_path: Path | None = None
+        self._cleanup_needed: bool = False
+
+    @abstractmethod
+    def prepare(self) -> Path:
+        """Prepare the import source and return a path to import from.
+
+        This method transforms the source into a format suitable for import.
+        For example:
+        - Zip files are extracted to a temp directory
+        - Directories are returned as-is
+
+        Returns:
+            Path to directory or file ready for import
+        """
+
+    @abstractmethod
+    def cleanup(self) -> None:
+        """Clean up any temporary resources created during preparation."""
+
+    def __enter__(self) -> Path:
+        """Context manager entry. Prepare the import source."""
+        self._prepared_path = self.prepare()
+        return self._prepared_path
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Context manager exit. Cleanup resources."""
+        self.cleanup()
+
+    @classmethod
+    def detect(cls, source: Path) -> type["ImportItem"]:
+        """Detect the appropriate ImportItem type for the given source.
+
+        Args:
+            source: Path to analyze
+
+        Returns:
+            The appropriate ImportItem subclass
+        """
+        if source.is_dir():
+            return DirectoryImportItem
+        if zipfile.is_zipfile(source):
+            return ZipImportItem
+        return FileImportItem
+
+
+class DirectoryImportItem(ImportItem):
+    """Import from a directory - no transformation needed."""
+
+    import_type = "directory"
+
+    def prepare(self) -> Path:
+        """Return directory path as-is."""
+        return self.source
+
+    def cleanup(self) -> None:
+        """No cleanup needed for directories."""
+
+
+class FileImportItem(ImportItem):
+    """Import from a single file, copy to temp directory."""
+
+    import_type = "file"
+
+    def prepare(self) -> Path:
+        """Copy file to a temporary directory."""
+        return self.source
+
+    def cleanup(self) -> None:
+        """Remove temporary directory."""
+
+
+class ZipImportItem(ImportItem):
+    """Import from a zip archive - extract to temp directory."""
+
+    import_type = "zip"
+
+    def __init__(self, source: Path | str) -> None:
+        super().__init__(source)
+        self._temp_dir: tempfile.TemporaryDirectory[str] | None = None
+
+    def prepare(self) -> Path:
+        """Extract zip to temporary directory."""
+        self._temp_dir = tempfile.TemporaryDirectory()
+        temp_path = Path(self._temp_dir.name)
+        with zipfile.ZipFile(self.source, "r") as zipf:
+            zipf.extractall(temp_path)
+        self._cleanup_needed = True
+        return temp_path
+
+    def cleanup(self) -> None:
+        """Remove temporary directory."""
+        if self._temp_dir:
+            self._temp_dir.cleanup()
+            self._temp_dir = None
+
+
+def create_import_item(source: Path) -> ImportItem:
+    """Factory function to create appropriate ImportItem instance.
+
+    Args:
+        source: Path to the import source
+
+    Returns:
+        Appropriate ImportItem instance based on source type
+    """
+    item_class = ImportItem.detect(source)
+    return item_class(source)

cmem_client/models/logging_config.py

@@ -0,0 +1,51 @@
+"""Models for the configuration of the logging module"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+LogLevel = Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+class FormatterConfig(BaseModel):
+    """Formatter configuration."""
+
+    format: str
+    datefmt: str | None = None
+
+
+class HandlerConfig(BaseModel):
+    """Handler configuration."""
+
+    class_: str = Field(..., alias="class")
+    level: LogLevel | None
+    formatter: str | None
+    filename: str | None
+
+
+class LoggerConfig(BaseModel):
+    """Logger configuration."""
+
+    level: LogLevel | None
+    handlers: list[str] | None
+
+
+class LoggingConfig(BaseModel):
+    """Logging configuration. Allows for extra fields but validates the most common fields."""
+
+    version: int = 1
+    disable_existing_loggers: bool
+    formatters: dict[str, FormatterConfig] | None
+    handlers: dict[str, HandlerConfig] | None
+    loggers: dict[str, LoggerConfig] | None
+    root: LoggerConfig | None
+
+    model_config = {"extra": "allow"}
+
+    @classmethod
+    @field_validator("version")
+    def check_version(cls, v: int) -> int:
+        """Ensure version is always 1."""
+        if v != 1:
+            raise ValueError("Logging config version must be 1")
+        return v

cmem_client/models/package.py

@@ -0,0 +1,35 @@
+"""Marketplace package models."""
+
+from eccenca_marketplace_client.package_version import PackageVersion
+from pydantic import ConfigDict
+
+from cmem_client.models.base import Model, ReadRepositoryItem
+
+
+class PackageMetadata(Model):
+    """Package metadata."""
+
+    name: str
+    description: str
+    comment: str | None = None
+
+
+class Package(ReadRepositoryItem):
+    """Installed marketplace package.
+
+    Represents a package installed in Corporate Memory with all its
+    metadata, file specifications, and version information as stored
+    in the marketplace catalog graph.
+    """
+
+    package_version: PackageVersion
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, str_strip_whitespace=True, extra="forbid")
+
+    def get_id(self) -> str:
+        """Get the package identifier.
+
+        Returns:
+            The package_id which uniquely identifies this package.
+        """
+        return str(self.package_version.manifest.package_id)

cmem_client/models/project.py

@@ -0,0 +1,46 @@
+"""Corporate Memory project models and metadata.
+
+This module defines models for representing Corporate Memory DataIntegration
+projects, including their metadata such as labels, descriptions, and tags.
+
+Projects are the primary organizational unit in Corporate Memory's build
+environment, containing datasets, transformations, and other integration
+components. The Project model provides validation and serialization for
+project data exchanged with the DataIntegration API.
+"""
+
+from typing import Any
+
+from pydantic import Field
+
+from cmem_client.models.base import Model, ReadRepositoryItem
+
+
+class ProjectMetaData(Model):
+    """Project Meta Data"""
+
+    label: str | None = None
+    description: str | None = None
+    tags: list[str] | None = None
+
+
+def default_metadata() -> ProjectMetaData:
+    """Get the current UTC datetime"""
+    # empty string is not allowed by DI, so model_post_init will change this to the ID
+    return ProjectMetaData(label="")
+
+
+class Project(ReadRepositoryItem):
+    """A Build (DataIntegration) Project"""
+
+    name: str
+    meta_data: ProjectMetaData = Field(alias="metaData", default_factory=default_metadata)
+
+    def model_post_init(self, context: Any, /) -> None:  # noqa: ANN401, ARG002
+        """Set the label to the name if needed"""
+        if self.meta_data.label == "":
+            self.meta_data.label = self.name
+
+    def get_id(self) -> str:
+        """Get the ID of the project"""
+        return self.name

cmem_client/models/python_package.py

@@ -0,0 +1,26 @@
+"""Python package models."""
+
+from eccenca_marketplace_client.fields import PyPiIdentifier
+from pydantic import ConfigDict
+
+from cmem_client.models.base import ReadRepositoryItem
+
+
+class PythonPackage(ReadRepositoryItem):
+    """Installed python package.
+
+    Represents a python package installed in Corporate Memory
+    """
+
+    name: PyPiIdentifier
+    version: str | None = None
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, str_strip_whitespace=True, extra="forbid")
+
+    def get_id(self) -> str:
+        """Get the package identifier.
+
+        Returns:
+            The python pypi name which uniquely identifies this package.
+        """
+        return str(self.name)

cmem_client/models/token.py

@@ -0,0 +1,40 @@
+"""Authentication token models for OAuth 2.0 flows.
+
+This module provides models for handling OAuth 2.0 tokens, particularly
+Keycloak tokens used in Corporate Memory authentication. It includes
+automatic JWT parsing and expiration checking functionality.
+
+The KeycloakToken model handles token lifecycle management, including
+automatically parsing JWT contents and providing expiration checking
+to support token refresh logic in authentication providers.
+"""
+
+from datetime import UTC, datetime
+
+import jwt
+from pydantic import Field
+
+from cmem_client.models.base import Model
+
+
+def default_factory_now() -> datetime:
+    """Get the current UTC datetime"""
+    return datetime.now(tz=UTC)
+
+
+class KeycloakToken(Model):
+    """A Keycloak token"""
+
+    access_token: str
+    expires_in: int
+    expires: datetime = Field(default_factory=default_factory_now)  # will be overwritten
+    jwt: dict = Field(default_factory=dict)
+
+    def model_post_init(self, context, /) -> None:  # noqa: ANN001, ARG002
+        """Do the post init"""
+        self.jwt = jwt.decode(self.access_token, options={"verify_signature": False})
+        self.expires = datetime.fromtimestamp(self.jwt["exp"], tz=UTC)
+
+    def is_expired(self) -> bool:
+        """Check if token is expired"""
+        return datetime.now(tz=UTC) >= self.expires