digitalhub 0.13.0b3__py3-none-any.whl → 0.13.0b4__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/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/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.")
@@ -69,24 +92,32 @@ 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:
@@ -108,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:
@@ -147,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
     -------
@@ -167,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/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/stores/credentials/enums.py

@@ -36,6 +36,7 @@ class CredsEnvVar(Enum):
     """
     Supported credential environment variables.
     """
+
     # S3
     S3_ENDPOINT_URL = "AWS_ENDPOINT_URL"
     S3_ACCESS_KEY_ID = "AWS_ACCESS_KEY_ID"

digitalhub/stores/data/api.py

@@ -37,7 +37,7 @@ def get_default_store(project: str) -> str:
     var = StoreEnv.DEFAULT_FILES_STORE.value
 
     context = get_context(project)
-    store = context.config.get(var.lower())
+    store = context.config.get(var.lower().replace("dhcore_", ""))
     if store is not None:
         return store
 

digitalhub/stores/data/builder.py

@@ -21,6 +21,20 @@ if typing.TYPE_CHECKING:
 
 
 class StoreInfo:
+    """
+    Container for store class and configurator information.
+
+    Holds store class references and their associated configurators
+    for registration and instantiation in the store builder system.
+
+    Attributes
+    ----------
+    _store : Store
+        The store class to be instantiated.
+    _configurator : Configurator or None
+        The configurator class for store configuration, if required.
+    """
+
     def __init__(self, store: Store, configurator: Configurator | None = None) -> None:
         self._store = store
         self._configurator = configurator
@@ -28,7 +42,19 @@ class StoreInfo:
 
 class StoreBuilder:
     """
-    Store builder class.
+    Store factory and registry for managing data store instances.
+
+    Provides registration, instantiation, and caching of data store
+    instances based on URI schemes. Supports various store types
+    including S3, SQL, local, and remote stores with their respective
+    configurators.
+
+    Attributes
+    ----------
+    _builders : dict[str, StoreInfo]
+        Registry of store types mapped to their StoreInfo instances.
+    _instances : dict[str, Store]
+        Cache of instantiated store instances by store type.
     """
 
     def __init__(self) -> None:
@@ -41,6 +67,31 @@ class StoreBuilder:
         store: Store,
         configurator: Configurator | None = None,
     ) -> None:
+        """
+        Register a store type with its class and optional configurator.
+
+        Adds a new store type to the builder registry, associating it
+        with a store class and optional configurator for later instantiation.
+
+        Parameters
+        ----------
+        store_type : str
+            The unique identifier for the store type (e.g., 's3', 'sql').
+        store : Store
+            The store class to register for this type.
+        configurator : Configurator, optional
+            The configurator class for store configuration.
+            If None, the store will be instantiated without configuration.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        StoreError
+            If the store type is already registered in the builder.
+        """
         if store_type not in self._builders:
             self._builders[store_type] = StoreInfo(store, configurator)
         else:
@@ -48,17 +99,28 @@ class StoreBuilder:
 
     def get(self, uri: str) -> Store:
         """
-        Get a store instance by URI, building it if necessary.
+        Get or create a store instance based on URI scheme.
+
+        Determines the appropriate store type from the URI scheme,
+        instantiates the store if not already cached, and returns
+        the store instance. Store instances are cached for reuse.
 
         Parameters
         ----------
         uri : str
-            URI to parse.
+            The URI to parse for determining the store type.
+            The scheme (e.g., 's3://', 'sql://') determines which
+            store type to instantiate.
 
         Returns
         -------
         Store
-            The store instance.
+            The store instance appropriate for handling the given URI.
+
+        Raises
+        ------
+        KeyError
+            If no store is registered for the URI scheme.
         """
         store_type = map_uri_scheme(uri)