digitalhub 0.11.0b7__py3-none-any.whl → 0.13.0__py3-none-any.whl

digitalhub/entities/_processors/utils.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing
@@ -22,23 +26,36 @@ def parse_identifier(
     entity_id: str | None = None,
 ) -> tuple[str, str, str | None, str | None, str | None]:
     """
-    Parse entity identifier.
+    Parse and validate entity identifier into its components.
+
+    Processes an entity identifier that can be either a full entity key
+    (store://) or a simple entity name. When using a simple name,
+    additional parameters must be provided for proper identification.
 
     Parameters
     ----------
     identifier : str
-        Entity key (store://...) or entity name.
-    project : str
-        Project name.
-    entity_type : str
-        Entity type.
-    entity_id : str
-        Entity ID.
+        The entity identifier to parse. Can be either a full entity key
+        (store://project/entity_type/kind/name:id) or a simple entity name.
+    project : str, optional
+        The project name. Required when identifier is not a full key.
+    entity_type : str, optional
+        The entity type. Required when identifier is not a full key.
+    entity_kind : str, optional
+        The entity kind specification.
+    entity_id : str, optional
+        The entity version identifier.
 
     Returns
     -------
     tuple[str, str, str | None, str | None, str | None]
-        Project name, entity type, entity kind, entity name, entity ID.
+        A tuple containing (project_name, entity_type, entity_kind,
+        entity_name, entity_id) parsed from the identifier.
+
+    Raises
+    ------
+    ValueError
+        If identifier is not a full key and project or entity_type is None.
     """
     if not identifier.startswith("store://"):
         if project is None or entity_type is None:
@@ -52,19 +69,29 @@ def get_context_from_identifier(
     project: str | None = None,
 ) -> Context:
     """
-    Get context from project.
+    Retrieve context instance from entity identifier or project name.
+
+    Extracts project information from the identifier and returns the
+    corresponding context. If the identifier is not a full key, the
+    project parameter must be provided explicitly.
 
     Parameters
     ----------
     identifier : str
-        Entity key (store://...) or entity name.
-    project : str
-        Project name.
+        The entity identifier to extract context from. Can be either
+        a full entity key (store://...) or a simple entity name.
+    project : str, optional
+        The project name. Required when identifier is not a full key.
 
     Returns
     -------
     Context
-        Context.
+        The context instance associated with the identified project.
+
+    Raises
+    ------
+    EntityError
+        If identifier is not a full key and project parameter is None.
     """
     if not identifier.startswith("store://"):
         if project is None:
@@ -79,19 +106,26 @@ def get_context_from_project(
     project: str,
 ) -> Context:
     """
-    Check if the given project is in the context.
-    Otherwise try to get the project from remote.
-    Finally return the client.
+    Retrieve context for a project, fetching from remote if necessary.
+
+    Attempts to get the project context from the local cache first.
+    If the project is not found locally, tries to fetch it from the
+    remote backend and create the context.
 
     Parameters
     ----------
     project : str
-        Project name.
+        The name of the project to get context for.
 
     Returns
     -------
     Context
-        Context.
+        The context instance for the specified project.
+
+    Raises
+    ------
+    ContextError
+        If the project cannot be found locally or remotely.
     """
     try:
         return get_context(project)
@@ -101,19 +135,28 @@ def get_context_from_project(
 
 def get_context_from_remote(
     project: str,
-) -> Client:
+) -> Context:
     """
-    Get context from remote.
+    Fetch project context from remote backend and create local context.
+
+    Retrieves project information from the remote backend, builds the
+    project entity locally, and returns the corresponding context.
+    Used when a project is not available in the local context cache.
 
     Parameters
     ----------
     project : str
-        Project name.
+        The name of the project to fetch from remote.
 
     Returns
     -------
-    Client
-        Client.
+    Context
+        The context instance created from the remote project data.
+
+    Raises
+    ------
+    ContextError
+        If the project is not found on the remote backend.
     """
     try:
         client = get_client()
@@ -131,23 +174,28 @@ def _read_base_entity(
     **kwargs,
 ) -> dict:
     """
-    Read object from backend.
+    Read entity data from the backend API.
+
+    Internal utility function that performs a base-level entity read
+    operation through the client API. Builds the appropriate API
+    endpoint and retrieves the entity data as a dictionary.
 
     Parameters
     ----------
     client : Client
-        Client instance.
+        The client instance to use for the API request.
     entity_type : str
-        Entity type.
+        The type of entity to read (e.g., 'project', 'function').
     entity_name : str
-        Entity name.
+        The name identifier of the entity to retrieve.
     **kwargs : dict
-        Parameters to pass to the API call.
+        Additional parameters to pass to the API call, such as
+        version specifications or query filters.
 
     Returns
     -------
     dict
-        Object instance.
+        Dictionary containing the entity data retrieved from the backend.
     """
     api = client.build_api(
         ApiCategories.BASE.value,

digitalhub/entities/artifact/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/entities/artifact/_base/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/entities/artifact/_base/builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing

digitalhub/entities/artifact/_base/entity.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing

digitalhub/entities/artifact/_base/spec.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities._base.material.spec import MaterialSpec, MaterialValidator

digitalhub/entities/artifact/_base/status.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities._base.material.status import MaterialStatus

digitalhub/entities/artifact/artifact/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/entities/artifact/artifact/builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities._commons.enums import EntityKinds

digitalhub/entities/artifact/artifact/entity.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing

digitalhub/entities/artifact/artifact/spec.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from typing import Optional

digitalhub/entities/artifact/artifact/status.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities._base.material.status import MaterialStatus

digitalhub/entities/artifact/crud.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing
@@ -307,6 +311,7 @@ def delete_artifact(
     project: str | None = None,
     entity_id: str | None = None,
     delete_all_versions: bool = False,
+    cascade: bool = True,
     **kwargs,
 ) -> dict:
     """
@@ -322,6 +327,8 @@ def delete_artifact(
         Entity ID.
     delete_all_versions : bool
         Delete all versions of the named entity. If True, use entity name instead of entity key as identifier.
+    cascade : bool
+        Cascade delete.
     **kwargs : dict
         Parameters to pass to the API call.
 
@@ -346,5 +353,6 @@ def delete_artifact(
         project=project,
         entity_id=entity_id,
         delete_all_versions=delete_all_versions,
+        cascade=cascade,
         **kwargs,
     )

digitalhub/entities/artifact/utils.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from typing import Any
@@ -11,16 +15,23 @@ def eval_source(
     source: str | list[str] | None = None,
 ) -> Any:
     """
-    Evaluate if source is local.
+    Evaluate whether the source is local or remote.
+
+    Determines if the provided source(s) reference local files or
+    remote resources. This evaluation affects how the artifact
+    will be processed and stored.
 
     Parameters
     ----------
-    source : str | list[str]
-        Source(s).
+    source : str, list[str], or None, optional
+        The source specification(s) to evaluate. Can be a single
+        source string, a list of source strings, or None.
 
     Returns
     -------
-    None
+    Any
+        The result of the local source evaluation, indicating
+        whether the source is local or remote.
     """
     return eval_local_source(source)
 
@@ -33,25 +44,33 @@ def process_kwargs(
     **kwargs,
 ) -> dict:
     """
-    Process spec kwargs.
+    Process and enhance specification parameters for artifact creation.
+
+    Processes the keyword arguments for artifact specification, handling
+    path generation and UUID assignment. If no path is provided, generates
+    a unique path based on project, entity type, name, and source.
 
     Parameters
     ----------
     project : str
-        Project name.
+        The name of the project.
     name : str
-        Object name.
-    source : str
-        Source(s).
-    path : str
-        Destination path of the entity. If not provided, it's generated.
+        The name of the artifact entity.
+    source : str or list[str]
+        The source specification(s) for the artifact content.
+        Can be a single source or multiple sources.
+    path : str, optional
+        The destination path for the artifact entity.
+        If None, a path will be automatically generated.
     **kwargs : dict
-        Spec parameters.
+        Additional specification parameters to be processed
+        and passed to the artifact creation.
 
     Returns
     -------
     dict
-        Kwargs updated.
+        The updated kwargs dictionary with processed path
+        and UUID information included.
     """
     if path is None:
         uuid = build_uuid()

digitalhub/entities/builders.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities.artifact.artifact.builder import ArtifactArtifactBuilder

digitalhub/entities/dataitem/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/entities/dataitem/_base/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/entities/dataitem/_base/builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing

digitalhub/entities/dataitem/_base/entity.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing

digitalhub/entities/dataitem/_base/spec.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities._base.material.spec import MaterialSpec, MaterialValidator

digitalhub/entities/dataitem/_base/status.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities._base.material.status import MaterialStatus

digitalhub/entities/dataitem/crud.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing
@@ -127,8 +131,16 @@ def log_dataitem(
         cleanup = True
 
     source = eval_source(source, data, kind, name, project)
-    data = eval_data(project, kind, source, data, file_format, engine)
-    kwargs = process_kwargs(project, name, kind, source=source, data=data, path=path, **kwargs)
+    data = eval_data(kind, source, data, file_format, engine)
+    kwargs = process_kwargs(
+        project,
+        name,
+        kind,
+        source=source,
+        data=data,
+        path=path,
+        **kwargs,
+    )
     obj = context_processor.log_material_entity(
         source=source,
         project=project,
@@ -325,6 +337,7 @@ def delete_dataitem(
     project: str | None = None,
     entity_id: str | None = None,
     delete_all_versions: bool = False,
+    cascade: bool = True,
     **kwargs,
 ) -> dict:
     """
@@ -340,6 +353,8 @@ def delete_dataitem(
         Entity ID.
     delete_all_versions : bool
         Delete all versions of the named entity. If True, use entity name instead of entity key as identifier.
+    cascade : bool
+        Cascade delete.
     **kwargs : dict
         Parameters to pass to the API call.
 
@@ -364,5 +379,6 @@ def delete_dataitem(
         project=project,
         entity_id=entity_id,
         delete_all_versions=delete_all_versions,
+        cascade=cascade,
         **kwargs,
     )

digitalhub/entities/dataitem/dataitem/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/entities/dataitem/dataitem/builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities._commons.enums import EntityKinds

digitalhub/entities/dataitem/dataitem/entity.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing

digitalhub/entities/dataitem/dataitem/spec.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities.dataitem._base.spec import DataitemSpec, DataitemValidator

digitalhub/entities/dataitem/dataitem/status.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities.dataitem._base.status import DataitemStatus

digitalhub/entities/dataitem/iceberg/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/entities/dataitem/iceberg/builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities._commons.enums import EntityKinds

digitalhub/entities/dataitem/iceberg/entity.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import typing

digitalhub/entities/dataitem/iceberg/spec.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities.dataitem._base.spec import DataitemSpec, DataitemValidator

digitalhub/entities/dataitem/iceberg/status.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities.dataitem._base.status import DataitemStatus

digitalhub/entities/dataitem/table/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0

digitalhub/entities/dataitem/table/builder.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities._commons.enums import EntityKinds

digitalhub/entities/dataitem/table/entity.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import shutil
@@ -89,14 +93,14 @@ class DataitemTable(Dataitem):
             DataFrame.
         """
         if self._query is not None:
-            df = get_store(self.project, self.spec.path).query(
+            df = get_store(self.spec.path).query(
                 self._query,
                 self.spec.path,
                 engine,
             )
             self._query = None
             return df
-        return get_store(self.project, self.spec.path).read_df(
+        return get_store(self.spec.path).read_df(
             self.spec.path,
             file_format,
             engine,
@@ -128,7 +132,7 @@ class DataitemTable(Dataitem):
         str
             Path to the written dataframe.
         """
-        return get_store(self.project, self.spec.path).write_df(
+        return get_store(self.spec.path).write_df(
             df,
             self.spec.path,
             extension=extension,

digitalhub/entities/dataitem/table/models.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from enum import Enum

digitalhub/entities/dataitem/table/spec.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from pydantic import Field

digitalhub/entities/dataitem/table/status.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.entities.dataitem._base.status import DataitemStatus

digitalhub/entities/dataitem/table/utils.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from digitalhub.utils.generic_utils import dump_json