digitalhub 0.13.4__py3-none-any.whl → 0.14.0__py3-none-any.whl

digitalhub/entities/artifact/crud.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 import typing
 
 from digitalhub.entities._commons.enums import EntityTypes
-from digitalhub.entities._processors.context import context_processor
+from digitalhub.entities._processors.processors import context_processor
 from digitalhub.entities.artifact._base.entity import Artifact
 from digitalhub.entities.artifact.utils import eval_source, process_kwargs
 from digitalhub.utils.types import SourcesOrListOfSources
@@ -132,7 +132,6 @@ def get_artifact(
     identifier: str,
     project: str | None = None,
     entity_id: str | None = None,
-    **kwargs,
 ) -> Artifact:
     """
     Get object from backend.
@@ -145,8 +144,6 @@ def get_artifact(
         Project name.
     entity_id : str
         Entity ID.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -168,14 +165,12 @@ def get_artifact(
         entity_type=ENTITY_TYPE,
         project=project,
         entity_id=entity_id,
-        **kwargs,
     )
 
 
 def get_artifact_versions(
     identifier: str,
     project: str | None = None,
-    **kwargs,
 ) -> list[Artifact]:
     """
     Get object versions from backend.
@@ -186,8 +181,6 @@ def get_artifact_versions(
         Entity key (store://...) or entity name.
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -207,11 +200,20 @@ def get_artifact_versions(
         identifier=identifier,
         entity_type=ENTITY_TYPE,
         project=project,
-        **kwargs,
     )
 
 
-def list_artifacts(project: str, **kwargs) -> list[Artifact]:
+def list_artifacts(
+    project: str,
+    q: str | None = None,
+    name: str | None = None,
+    kind: str | None = None,
+    user: str | None = None,
+    state: str | None = None,
+    created: str | None = None,
+    updated: str | None = None,
+    version: str | None = None,
+) -> list[Artifact]:
     """
     List all latest version objects from backend.
 
@@ -219,8 +221,22 @@ def list_artifacts(project: str, **kwargs) -> list[Artifact]:
     ----------
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
+    q : str
+        Query string to filter objects.
+    name : str
+        Object name.
+    kind : str
+        Kind of the object.
+    user : str
+        User that created the object.
+    state : str
+        Object state.
+    created : str
+        Creation date filter.
+    updated : str
+        Update date filter.
+    version : str
+        Object version, default is latest.
 
     Returns
     -------
@@ -234,18 +250,36 @@ def list_artifacts(project: str, **kwargs) -> list[Artifact]:
     return context_processor.list_context_entities(
         project=project,
         entity_type=ENTITY_TYPE,
-        **kwargs,
+        q=q,
+        name=name,
+        kind=kind,
+        user=user,
+        state=state,
+        created=created,
+        updated=updated,
+        version=version,
     )
 
 
-def import_artifact(file: str) -> Artifact:
+def import_artifact(
+    file: str | None = None,
+    key: str | None = None,
+    reset_id: bool = False,
+    context: str | None = None,
+) -> Artifact:
     """
-    Import object from a YAML file and create a new object into the backend.
+    Import an object from a YAML file or from a storage key.
 
     Parameters
     ----------
     file : str
-        Path to YAML file.
+        Path to the YAML file.
+    key : str
+        Entity key (store://...).
+    reset_id : bool
+        Flag to determine if the ID of executable entities should be reset.
+    context : str
+        Project name to use for context resolution.
 
     Returns
     -------
@@ -256,7 +290,12 @@ def import_artifact(file: str) -> Artifact:
     --------
     >>> obj = import_artifact("my-artifact.yaml")
     """
-    return context_processor.import_context_entity(file)
+    return context_processor.import_context_entity(
+        file,
+        key,
+        reset_id,
+        context,
+    )
 
 
 def load_artifact(file: str) -> Artifact:
@@ -312,7 +351,6 @@ def delete_artifact(
     entity_id: str | None = None,
     delete_all_versions: bool = False,
     cascade: bool = True,
-    **kwargs,
 ) -> dict:
     """
     Delete object from backend.
@@ -326,11 +364,10 @@ def delete_artifact(
     entity_id : str
         Entity ID.
     delete_all_versions : bool
-        Delete all versions of the named entity. If True, use entity name instead of entity key as identifier.
+        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.
 
     Returns
     -------
@@ -354,5 +391,4 @@ def delete_artifact(
         entity_id=entity_id,
         delete_all_versions=delete_all_versions,
         cascade=cascade,
-        **kwargs,
     )

digitalhub/entities/artifact/utils.py

@@ -6,9 +6,9 @@ from __future__ import annotations
 
 from typing import Any
 
-from digitalhub.entities._base.entity._constructors.uuid import build_uuid
 from digitalhub.entities._base.material.utils import build_log_path_from_source, eval_local_source
 from digitalhub.entities._commons.enums import EntityTypes
+from digitalhub.entities._constructors.uuid import build_uuid
 
 
 def eval_source(
@@ -23,7 +23,7 @@ def eval_source(
 
     Parameters
     ----------
-    source : str, list[str], or None, optional
+    source : str, list[str], or None
         The source specification(s) to evaluate. Can be a single
         source string, a list of source strings, or None.
 
@@ -59,7 +59,7 @@ def process_kwargs(
     source : str or list[str]
         The source specification(s) for the artifact content.
         Can be a single source or multiple sources.
-    path : str, optional
+    path : str
         The destination path for the artifact entity.
         If None, a path will be automatically generated.
     **kwargs : dict

digitalhub/entities/dataitem/crud.py

@@ -8,7 +8,7 @@ import typing
 from typing import Any
 
 from digitalhub.entities._commons.enums import EntityTypes
-from digitalhub.entities._processors.context import context_processor
+from digitalhub.entities._processors.processors import context_processor
 from digitalhub.entities.dataitem.utils import clean_tmp_path, eval_data, eval_source, post_process, process_kwargs
 from digitalhub.utils.types import SourcesOrListOfSources
 
@@ -87,6 +87,7 @@ def log_dataitem(
     data: Any | None = None,
     path: str | None = None,
     file_format: str | None = None,
+    read_df_params: dict | None = None,
     engine: str | None = "pandas",
     **kwargs,
 ) -> Dataitem:
@@ -108,7 +109,9 @@ def log_dataitem(
     path : str
         Destination path of the dataitem. If not provided, it's generated.
     file_format : str
-        Extension of the file.
+        Extension of the file source (parquet, csv, json, xlsx, txt).
+    read_df_params : dict
+        Parameters to pass to the dataframe reader.
     engine : str
         Dataframe engine (pandas, polars, etc.).
     **kwargs : dict
@@ -131,7 +134,7 @@ def log_dataitem(
         cleanup = True
 
     source = eval_source(source, data, kind, name, project)
-    data = eval_data(kind, source, data, file_format, engine)
+    data = eval_data(kind, source, data, file_format, read_df_params, engine)
     kwargs = process_kwargs(
         project,
         name,
@@ -158,7 +161,6 @@ def get_dataitem(
     identifier: str,
     project: str | None = None,
     entity_id: str | None = None,
-    **kwargs,
 ) -> Dataitem:
     """
     Get object from backend.
@@ -171,8 +173,6 @@ def get_dataitem(
         Project name.
     entity_id : str
         Entity ID.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -194,14 +194,12 @@ def get_dataitem(
         entity_type=ENTITY_TYPE,
         project=project,
         entity_id=entity_id,
-        **kwargs,
     )
 
 
 def get_dataitem_versions(
     identifier: str,
     project: str | None = None,
-    **kwargs,
 ) -> list[Dataitem]:
     """
     Get object versions from backend.
@@ -212,8 +210,6 @@ def get_dataitem_versions(
         Entity key (store://...) or entity name.
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
 
     Returns
     -------
@@ -233,11 +229,20 @@ def get_dataitem_versions(
         identifier=identifier,
         entity_type=ENTITY_TYPE,
         project=project,
-        **kwargs,
     )
 
 
-def list_dataitems(project: str, **kwargs) -> list[Dataitem]:
+def list_dataitems(
+    project: str,
+    q: str | None = None,
+    name: str | None = None,
+    kind: str | None = None,
+    user: str | None = None,
+    state: str | None = None,
+    created: str | None = None,
+    updated: str | None = None,
+    version: str | None = None,
+) -> list[Dataitem]:
     """
     List all latest version objects from backend.
 
@@ -245,8 +250,22 @@ def list_dataitems(project: str, **kwargs) -> list[Dataitem]:
     ----------
     project : str
         Project name.
-    **kwargs : dict
-        Parameters to pass to the API call.
+    q : str
+        Query string to filter objects.
+    name : str
+        Object name.
+    kind : str
+        Kind of the object.
+    user : str
+        User that created the object.
+    state : str
+        Object state.
+    created : str
+        Creation date filter.
+    updated : str
+        Update date filter.
+    version : str
+        Object version, default is latest.
 
     Returns
     -------
@@ -260,18 +279,36 @@ def list_dataitems(project: str, **kwargs) -> list[Dataitem]:
     return context_processor.list_context_entities(
         project=project,
         entity_type=ENTITY_TYPE,
-        **kwargs,
+        q=q,
+        name=name,
+        kind=kind,
+        user=user,
+        state=state,
+        created=created,
+        updated=updated,
+        version=version,
     )
 
 
-def import_dataitem(file: str) -> Dataitem:
+def import_dataitem(
+    file: str | None = None,
+    key: str | None = None,
+    reset_id: bool = False,
+    context: str | None = None,
+) -> Dataitem:
     """
-    Import object from a YAML file and create a new object into the backend.
+    Import an object from a YAML file or from a storage key.
 
     Parameters
     ----------
     file : str
-        Path to YAML file.
+        Path to the YAML file.
+    key : str
+        Entity key (store://...).
+    reset_id : bool
+        Flag to determine if the ID of executable entities should be reset.
+    context : str
+        Project name to use for context resolution.
 
     Returns
     -------
@@ -282,7 +319,12 @@ def import_dataitem(file: str) -> Dataitem:
     --------
     >>> obj = import_dataitem("my-dataitem.yaml")
     """
-    return context_processor.import_context_entity(file)
+    return context_processor.import_context_entity(
+        file,
+        key,
+        reset_id,
+        context,
+    )
 
 
 def load_dataitem(file: str) -> Dataitem:
@@ -352,7 +394,8 @@ def delete_dataitem(
     entity_id : str
         Entity ID.
     delete_all_versions : bool
-        Delete all versions of the named entity. If True, use entity name instead of entity key as identifier.
+        Delete all versions of the named entity.
+        If True, use entity name instead of entity key as identifier.
     cascade : bool
         Cascade delete.
     **kwargs : dict

digitalhub/entities/dataitem/table/entity.py

@@ -4,9 +4,7 @@
 
 from __future__ import annotations
 
-import shutil
 import typing
-from pathlib import Path
 from typing import Any
 
 from digitalhub.entities._base.material.utils import refresh_decorator
@@ -120,13 +118,17 @@ class DataitemTable(Dataitem):
         Write DataFrame as parquet/csv/table into dataitem spec.path.
         keyword arguments will be passed to the DataFrame reader function such as
         pandas's to_csv or to_parquet.
+        Note that by default the index is dropped when writing the dataframe. To
+        keep the index, you can pass index=True as a keyword argument.
+        If the dataitem path is a SQL scheme, the dataframe will be written to the
+        table specified in the path (sql://<database_name>(/<schema_name>)/<table_name>).
 
         Parameters
         ----------
         df : Any
             DataFrame to write.
         extension : str
-            Extension of the file.
+            Extension of the file (supported parquet and csv).
         **kwargs : dict
             Keyword arguments passed to the write_df function.
 
@@ -134,6 +136,25 @@ class DataitemTable(Dataitem):
         -------
         str
             Path to the written dataframe.
+
+        Examples
+        --------
+        >>> import digitalhub as dh
+        >>> import pandas as pd
+        >>>
+        >>> p = dh.get_project("my_project")
+        >>> df = pd.read_df("data/my_data.csv")
+        >>> di = p.new_dataitem(
+        ...     name="my_dataitem",
+        ...     kind="table",
+        ...     path="s3://my-bucket/my-data.parquet",
+        ... )
+        >>> di.write_df(
+        ...     df,
+        ...     extension="parquet",
+        ...     index=True,
+        ... )
+        's3://my-bucket/my-data.parquet'
         """
         return get_store(self.spec.path).write_df(
             df,
@@ -141,22 +162,3 @@ class DataitemTable(Dataitem):
             extension=extension,
             **kwargs,
         )
-
-    @staticmethod
-    def _clean_tmp_path(pth: Path | None, clean: bool) -> None:
-        """
-        Clean temporary path.
-
-        Parameters
-        ----------
-        pth : Path | None
-            Path to clean.
-        clean : bool
-            If True, the path will be cleaned.
-
-        Returns
-        -------
-        None
-        """
-        if pth is not None and clean:
-            shutil.rmtree(pth)

digitalhub/entities/dataitem/utils.py

@@ -9,9 +9,9 @@ import typing
 from typing import Any
 
 from digitalhub.context.api import get_context
-from digitalhub.entities._base.entity._constructors.uuid import build_uuid
 from digitalhub.entities._base.material.utils import build_log_path_from_source, eval_local_source
 from digitalhub.entities._commons.enums import EntityKinds, EntityTypes
+from digitalhub.entities._constructors.uuid import build_uuid
 from digitalhub.stores.data.api import get_store
 from digitalhub.stores.readers.data.api import get_reader_by_object
 from digitalhub.utils.enums import FileExtensions
@@ -41,17 +41,17 @@ def eval_source(
 
     Parameters
     ----------
-    source : SourcesOrListOfSources, optional
+    source : SourcesOrListOfSources
         The source specification(s) for the dataitem. Can be file paths,
         URLs, or other source identifiers.
-    data : Any, optional
+    data : Any
         The data object to process (e.g., DataFrame). Alternative to source.
         Exactly one of source or data must be provided.
-    kind : str, optional
+    kind : str
         The kind of dataitem being created (e.g., 'table').
-    name : str, optional
+    name : str
         The name of the dataitem, used for generating file paths.
-    project : str, optional
+    project : str
         The project name, used for context and path generation.
 
     Returns
@@ -89,6 +89,7 @@ def eval_data(
     source: SourcesOrListOfSources,
     data: Any | None = None,
     file_format: str | None = None,
+    read_df_params: dict | None = None,
     engine: str | None = None,
 ) -> Any:
     """
@@ -104,13 +105,13 @@ def eval_data(
         how data should be processed.
     source : SourcesOrListOfSources
         The source specification(s) to load data from.
-    data : Any, optional
+    data : Any
         Pre-loaded data object. If provided, may be returned directly
         depending on the dataitem kind.
-    file_format : str, optional
+    file_format : str
         The file format specification for reading the source
         (e.g., 'parquet', 'csv').
-    engine : str, optional
+    engine : str
         The engine to use for reading the data (e.g., 'pandas', 'polars').
 
     Returns
@@ -121,10 +122,13 @@ def eval_data(
     """
     if kind == EntityKinds.DATAITEM_TABLE.value:
         if data is None:
+            if read_df_params is None:
+                read_df_params = {}
             return get_store(source).read_df(
                 source,
                 file_format=file_format,
                 engine=engine,
+                **read_df_params,
             )
     return data
 
@@ -155,10 +159,10 @@ def process_kwargs(
         The kind of dataitem being created (e.g., 'table').
     source : SourcesOrListOfSources
         The source specification(s) for the dataitem content.
-    data : Any, optional
+    data : Any
         The data object for schema extraction and processing.
         Used as an alternative to source for table dataitems.
-    path : str, optional
+    path : str
         The destination path for the dataitem entity.
         If None, a path will be automatically generated.
     **kwargs : dict
@@ -197,10 +201,6 @@ def clean_tmp_path(pth: SourcesOrListOfSources) -> None:
     pth : SourcesOrListOfSources
         The path or list of paths to clean up. Can be file paths
         or directory paths that need to be removed.
-
-    Returns
-    -------
-    None
     """
     if isinstance(pth, list):
         for p in pth:

digitalhub/entities/function/_base/entity.py

@@ -9,7 +9,7 @@ from concurrent.futures import ThreadPoolExecutor
 
 from digitalhub.entities._base.executable.entity import ExecutableEntity
 from digitalhub.entities._commons.enums import EntityTypes, Relationship
-from digitalhub.factory.factory import factory
+from digitalhub.factory.entity import entity_factory
 from digitalhub.utils.exceptions import BackendError
 
 if typing.TYPE_CHECKING:
@@ -76,8 +76,8 @@ class Function(ExecutableEntity):
             Run instance.
         """
         # Get task and run kind
-        task_kind = factory.get_task_kind_from_action(self.kind, action)
-        run_kind = factory.get_run_kind(self.kind)
+        task_kind = entity_factory.get_task_kind_from_action(self.kind, action)
+        run_kind = entity_factory.get_run_kind_from_action(self.kind, action)
 
         # Create or update new task
         task = self._get_or_create_task(task_kind)