digitalhub 0.12.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

digitalhub/entities/_processors/utils.py

@@ -26,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:
@@ -56,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:
@@ -83,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)
@@ -105,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()
@@ -135,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/crud.py

@@ -311,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:
     """
@@ -326,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.
 
@@ -350,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

@@ -15,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)
 
@@ -37,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/dataitem/crud.py

@@ -131,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,
@@ -329,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:
     """
@@ -344,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.
 
@@ -368,5 +379,6 @@ def delete_dataitem(
         project=project,
         entity_id=entity_id,
         delete_all_versions=delete_all_versions,
+        cascade=cascade,
         **kwargs,
     )

digitalhub/entities/dataitem/table/entity.py

@@ -93,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,
@@ -132,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/utils.py

@@ -33,16 +33,39 @@ def eval_source(
     project: str | None = None,
 ) -> Any:
     """
-    Evaluate if source is local.
+    Evaluate and process data source for dataitem creation.
+
+    Determines the appropriate source handling based on whether a source
+    path or data object is provided. For table dataitems with data objects,
+    writes the data to a Parquet file and returns the file path.
 
     Parameters
     ----------
-    source : SourcesOrListOfSources
-        Source(s).
+    source : SourcesOrListOfSources, optional
+        The source specification(s) for the dataitem. Can be file paths,
+        URLs, or other source identifiers.
+    data : Any, optional
+        The data object to process (e.g., DataFrame). Alternative to source.
+        Exactly one of source or data must be provided.
+    kind : str, optional
+        The kind of dataitem being created (e.g., 'table').
+    name : str, optional
+        The name of the dataitem, used for generating file paths.
+    project : str, optional
+        The project name, used for context and path generation.
 
     Returns
     -------
-    None
+    Any
+        The processed source. Returns the original source if provided,
+        or the path to a generated file if data was processed.
+
+    Raises
+    ------
+    ValueError
+        If both source and data are provided or both are None.
+    NotImplementedError
+        If the specified kind is not supported for data processing.
     """
     if (source is None) == (data is None):
         raise ValueError("You must provide source or data.")
@@ -62,7 +85,6 @@ def eval_source(
 
 
 def eval_data(
-    project: str,
     kind: str,
     source: SourcesOrListOfSources,
     data: Any | None = None,
@@ -70,28 +92,36 @@ def eval_data(
     engine: str | None = None,
 ) -> Any:
     """
-    Evaluate data is loaded.
+    Evaluate and load data from source or return provided data.
+
+    For table dataitems, loads data from the source using the appropriate
+    store and reader. For other kinds, returns the data as-is.
 
     Parameters
     ----------
-    project : str
-        Project name.
-    source : str
-        Source(s).
-    data : Any
-        Dataframe to log. Alternative to source.
-    file_format : str
-        Extension of the file.
-    engine : str
-        Engine to use.
+    kind : str
+        The kind of dataitem (e.g., 'table') that determines
+        how data should be processed.
+    source : SourcesOrListOfSources
+        The source specification(s) to load data from.
+    data : Any, optional
+        Pre-loaded data object. If provided, may be returned directly
+        depending on the dataitem kind.
+    file_format : str, optional
+        The file format specification for reading the source
+        (e.g., 'parquet', 'csv').
+    engine : str, optional
+        The engine to use for reading the data (e.g., 'pandas', 'polars').
 
     Returns
     -------
-    None
+    Any
+        The loaded data object for table dataitems, or the original
+        data parameter for other kinds.
     """
     if kind == EntityKinds.DATAITEM_TABLE.value:
         if data is None:
-            return get_store(project, source).read_df(
+            return get_store(source).read_df(
                 source,
                 file_format=file_format,
                 engine=engine,
@@ -109,29 +139,37 @@ def process_kwargs(
     **kwargs,
 ) -> dict:
     """
-    Process spec kwargs.
+    Process and enhance specification parameters for dataitem creation.
+
+    Processes the keyword arguments for dataitem specification, handling
+    schema extraction for table dataitems and path generation. Extracts
+    schema information from data objects when available.
 
     Parameters
     ----------
     project : str
-        Project name.
+        The name of the project.
     name : str
-        Object name.
+        The name of the dataitem entity.
     kind : str
-        Kind the object.
+        The kind of dataitem being created (e.g., 'table').
     source : SourcesOrListOfSources
-        Source(s).
-    data : Any
-        Dataframe to log. Alternative to source.
-    path : str
-        Destination path of the entity. If not provided, it's generated.
+        The source specification(s) for the dataitem content.
+    data : Any, optional
+        The data object for schema extraction and processing.
+        Used as an alternative to source for table dataitems.
+    path : str, optional
+        The destination path for the dataitem entity.
+        If None, a path will be automatically generated.
     **kwargs : dict
-        Spec parameters.
+        Additional specification parameters to be processed
+        and passed to the dataitem creation.
 
     Returns
     -------
     dict
-        Kwargs updated.
+        The updated kwargs dictionary with processed path,
+        UUID, and schema information included.
     """
     if data is not None:
         if kind == EntityKinds.DATAITEM_TABLE.value:
@@ -148,12 +186,17 @@ def process_kwargs(
 
 def clean_tmp_path(pth: SourcesOrListOfSources) -> None:
     """
-    Clean temporary path.
+    Clean up temporary files and directories.
+
+    Removes temporary files or directories created during dataitem
+    processing. Handles both single paths and lists of paths,
+    ignoring any errors that occur during cleanup.
 
     Parameters
     ----------
     pth : SourcesOrListOfSources
-        Path to clean.
+        The path or list of paths to clean up. Can be file paths
+        or directory paths that need to be removed.
 
     Returns
     -------
@@ -168,19 +211,25 @@ def clean_tmp_path(pth: SourcesOrListOfSources) -> None:
 
 def post_process(obj: Dataitem, data: Any) -> Dataitem:
     """
-    Post process object.
+    Post-process dataitem object with additional metadata and previews.
+
+    Enhances the dataitem object with additional information extracted
+    from the data. For table dataitems, generates and stores a data
+    preview in the object's status.
 
     Parameters
     ----------
     obj : Dataitem
-        The object.
+        The dataitem object to post-process and enhance.
     data : Any
-        The data.
+        The data object used to generate previews and extract
+        additional metadata information.
 
     Returns
     -------
     Dataitem
-        The object.
+        The enhanced dataitem object with updated status information
+        and saved changes.
     """
     if obj.kind == EntityKinds.DATAITEM_TABLE.value:
         reader = get_reader_by_object(data)

digitalhub/entities/model/crud.py

@@ -310,6 +310,7 @@ def delete_model(
     project: str | None = None,
     entity_id: str | None = None,
     delete_all_versions: bool = False,
+    cascade: bool = True,
     **kwargs,
 ) -> dict:
     """
@@ -325,6 +326,8 @@ def delete_model(
         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.
 
@@ -349,5 +352,6 @@ def delete_model(
         project=project,
         entity_id=entity_id,
         delete_all_versions=delete_all_versions,
+        cascade=cascade,
         **kwargs,
     )

digitalhub/entities/model/utils.py

@@ -15,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 model
+    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)
 
@@ -37,25 +44,33 @@ def process_kwargs(
     **kwargs,
 ) -> dict:
     """
-    Process spec kwargs.
+    Process and enhance specification parameters for model creation.
+
+    Processes the keyword arguments for model 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 containing the model.
     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 model entity.
+    source : str or list[str]
+        The source specification(s) for the model content.
+        Can be a single source or multiple sources.
+    path : str, optional
+        The destination path for the model entity.
+        If None, a path will be automatically generated.
     **kwargs : dict
-        Spec parameters.
+        Additional specification parameters to be processed
+        and passed to the model 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/project/_base/entity.py

@@ -2092,8 +2092,6 @@ class Project(Entity):
         --------
         >>> objs = project.list_runs()
         """
-        if kwargs is None:
-            kwargs = {}
         return list_runs(self.name, **kwargs)
 
     def delete_run(

digitalhub/entities/run/_base/entity.py

@@ -147,7 +147,7 @@ class Run(UnversionedEntity):
         None
         """
         if not self.spec.local_execution:
-            return context_processor.stop_run(self.project, self.ENTITY_TYPE, self.id)
+            return context_processor.stop_entity(self.project, self.ENTITY_TYPE, self.id)
 
     def resume(self) -> None:
         """
@@ -158,7 +158,7 @@ class Run(UnversionedEntity):
         None
         """
         if not self.spec.local_execution:
-            return context_processor.resume_run(self.project, self.ENTITY_TYPE, self.id)
+            return context_processor.resume_entity(self.project, self.ENTITY_TYPE, self.id)
 
     def log_metric(
         self,