digitalhub 0.13.0b3__py3-none-any.whl → 0.14.0b0__py3-none-any.whl

digitalhub/stores/client/dhcore/params_builder.py

@@ -12,18 +12,12 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
     """
     Parameter builder for DHCore client API calls.
 
-    This class constructs HTTP request parameters for different DHCore API
-    operations, handling the specific parameter formats and query structures
-    required by the DigitalHub Core backend. It supports both base-level
-    operations (like project management) and context-level operations
-    (entity operations within projects).
-
-    The builder handles various parameter transformations including:
-    - Query parameter formatting for different operations
-    - Search filter construction for Solr-based searches
-    - Cascade deletion options
-    - Versioning parameters
-    - Entity sharing parameters
+    Constructs HTTP request parameters for DHCore API operations, handling
+    parameter formats and query structures for both base-level operations
+    (project management) and context-level operations (entity operations
+    within projects). Supports query parameter formatting, search filter
+    construction for Solr-based searches, cascade deletion options,
+    versioning parameters, and entity sharing parameters.
 
     Methods
     -------
@@ -39,36 +33,27 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
         """
         Build HTTP request parameters for DHCore API calls.
 
-        Routes parameter building to the appropriate method based on the
-        API category (base or context operations) and applies operation-specific
-        parameter transformations.
+        Routes parameter building to appropriate method based on API category
+        (base or context operations) and applies operation-specific transformations.
+        Acts as dispatcher, initializing parameter dictionaries with 'params' key
+        for query parameters.
 
         Parameters
         ----------
         category : str
-            The API category, either 'base' for project-level operations
-            or 'context' for entity operations within projects.
+            API category: 'base' for project-level operations or 'context'
+            for entity operations within projects.
         operation : str
-            The specific API operation being performed (create, read, update,
-            delete, list, search, etc.).
+            Specific API operation (create, read, update, delete, list, search, etc.).
         **kwargs : dict
-            Raw parameters to be transformed into proper HTTP request format.
-            May include entity identifiers, filter criteria, pagination
-            options, etc.
+            Raw parameters to transform including entity identifiers, filter
+            criteria, pagination options, etc.
 
         Returns
         -------
         dict
-            Formatted parameters dictionary ready for HTTP request, typically
-            containing a 'params' key with query parameters and other
-            request-specific parameters.
-
-        Notes
-        -----
-        This method acts as a dispatcher, routing to either base or context
-        parameter building based on the category. All parameter dictionaries
-        are initialized with a 'params' key for query parameters if not
-        already present.
+            Formatted parameters dictionary with 'params' key for query parameters
+            and other request-specific parameters.
         """
         if category == ApiCategories.BASE.value:
             return self.build_parameters_base(operation, **kwargs)
@@ -78,18 +63,18 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
         """
         Build parameters for base-level API operations.
 
-        Constructs HTTP request parameters for operations that work at the
-        base level of the API, typically project-level operations and
-        entity sharing functionality.
+        Constructs HTTP request parameters for project-level operations and
+        entity sharing functionality. Handles CASCADE (boolean to lowercase string),
+        SHARE (user parameter to query params), and UNSHARE (requires unshare=True
+        and entity id).
 
         Parameters
         ----------
         operation : str
-            The API operation being performed. Supported operations:
-            - DELETE: Project deletion with optional cascade
-            - SHARE: Entity sharing/unsharing with users
+            API operation: DELETE (project deletion with optional cascade)
+            or SHARE (entity sharing/unsharing with users).
         **kwargs : dict
-            Operation-specific parameters including:
+            Operation-specific parameters:
             - cascade (bool): For DELETE, whether to cascade delete
             - user (str): For SHARE, target user for sharing
             - unshare (bool): For SHARE, whether to unshare instead
@@ -98,15 +83,7 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
         Returns
         -------
         dict
-            Formatted parameters with 'params' containing query parameters
-            and other request-specific parameters.
-
-        Notes
-        -----
-        Parameter transformations:
-        - CASCADE: Boolean values are converted to lowercase strings
-        - SHARE: User parameter is moved to query params
-        - UNSHARE: Requires both unshare=True and entity id
+            Formatted parameters with 'params' containing query parameters.
         """
         kwargs = self._set_params(**kwargs)
         if operation == BackendOperations.DELETE.value:
@@ -123,23 +100,22 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
         """
         Build parameters for context-level API operations.
 
-        Constructs HTTP request parameters for operations that work within
-        a specific context (project), including entity management and
-        search functionality.
+        Constructs HTTP request parameters for entity management and search within
+        projects. Handles search filters via 'filter' parameter, pagination with
+        'page' and 'size', result ordering with 'sort' parameter. READ supports
+        embedded entity inclusion, DELETE requires entity 'id' parameter.
 
         Parameters
         ----------
         operation : str
-            The API operation being performed. Supported operations:
-            - SEARCH: Search entities with filtering and pagination
-            - READ_MANY: Retrieve multiple entities with pagination
-            - DELETE: Delete specific entity by ID
-            - READ: Read specific entity by ID (with optional embedded)
+            API operation: SEARCH (search entities with filtering), READ_MANY
+            (retrieve multiple with pagination), DELETE (delete by ID),
+            READ (read by ID with optional embedded).
         **kwargs : dict
-            Operation-specific parameters including:
+            Operation-specific parameters:
             - params (dict): Search filters and conditions
             - page (int): Page number for pagination (default: 0)
-            - size (int): Number of items per page (default: 20)
+            - size (int): Items per page (default: 20)
             - order_by (str): Field to order results by
             - order (str): Order direction ('asc' or 'desc')
             - embedded (bool): For READ, whether to include embedded entities
@@ -148,19 +124,8 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
         Returns
         -------
         dict
-            Formatted parameters with 'params' containing query parameters
-            and other request-specific parameters like 'id' for entity operations.
-
-        Notes
-        -----
-        Search and pagination:
-        - Filters are applied via 'filter' parameter in query string
-        - Pagination uses 'page' and 'size' parameters
-        - Results can be ordered using 'sort' parameter format
-
-        Entity operations:
-        - READ: Supports embedded entity inclusion via 'embedded' param
-        - DELETE: Requires entity 'id' parameter
+            Formatted parameters with 'params' for query parameters and
+            other request-specific parameters like 'id' for entity operations.
         """
         kwargs = self._set_params(**kwargs)
 
@@ -249,27 +214,20 @@ class ClientDHCoreParametersBuilder(ClientParametersBuilder):
         """
         Initialize parameter dictionary with query parameters structure.
 
-        Ensures that the parameter dictionary has a 'params' key for
-        HTTP query parameters. This is a utility method used by all
-        parameter building methods to guarantee consistent structure.
+        Ensures parameter dictionary has 'params' key for HTTP query parameters,
+        guaranteeing consistent structure for all parameter building methods.
 
         Parameters
         ----------
         **kwargs : dict
-            Keyword arguments to be formatted. May be empty or contain
-            various parameters for API operations.
+            Keyword arguments to format. May be empty or contain various
+            parameters for API operations.
 
         Returns
         -------
         dict
             Parameters dictionary with guaranteed 'params' key containing
-            an empty dict if not already present.
-
-        Notes
-        -----
-        This method is called at the beginning of all parameter building
-        methods to ensure consistent dictionary structure for query
-        parameter handling.
+            empty dict if not already present.
         """
         if not kwargs:
             kwargs = {}

digitalhub/stores/client/dhcore/utils.py

@@ -23,36 +23,30 @@ def set_dhcore_env(
     client_id: str | None = None,
 ) -> None:
     """
-    Function to set environment variables for DHCore config.
+    Set DHCore environment variables and reload client configuration.
 
-    Sets the environment variables for DHCore configuration and
-    reloads the client configurator to use the new settings.
-    Note that if the environment variable is already set, it
-    will be overwritten.
+    Updates environment variables for DHCore configuration and automatically
+    reloads the client configurator to apply new settings. Overwrites existing
+    environment variables if already set.
 
     Parameters
     ----------
     endpoint : str, optional
-        The endpoint URL of the DHCore backend.
+        DHCore backend endpoint URL.
     user : str, optional
-        The username for basic authentication.
+        Username for basic authentication.
     password : str, optional
-        The password for basic authentication.
+        Password for basic authentication.
     access_token : str, optional
-        The OAuth2 access token.
+        OAuth2 access token.
     refresh_token : str, optional
-        The OAuth2 refresh token.
+        OAuth2 refresh token.
     client_id : str, optional
-        The OAuth2 client identifier.
+        OAuth2 client identifier.
 
     Returns
     -------
     None
-
-    Notes
-    -----
-    After setting the environment variables, this function automatically
-    reloads the client configurator to apply the new configuration.
     """
     if endpoint is not None:
         os.environ[CredsEnvVar.DHCORE_ENDPOINT.value] = endpoint
@@ -73,11 +67,10 @@ def set_dhcore_env(
 
 def refresh_token() -> None:
     """
-    Function to refresh the OAuth2 access token.
+    Refresh the current OAuth2 access token.
 
-    Attempts to refresh the current OAuth2 access token using the
-    refresh token stored in the client configuration. This function
-    requires that the client be configured with OAuth2 authentication.
+    Uses the refresh token stored in client configuration to obtain a new
+    access token. Requires OAuth2 authentication configuration.
 
     Returns
     -------
@@ -86,8 +79,7 @@ def refresh_token() -> None:
     Raises
     ------
     ClientError
-        If the client is not properly configured or if the token
-        refresh fails.
+        If client not properly configured or token refresh fails.
     """
     client: ClientDHCore = get_client(local=False)
     client._configurator.check_config()

digitalhub/stores/client/local/client.py

@@ -207,7 +207,16 @@ class ClientLocal(Client):
 
             else:
                 name = obj.get("name", entity_id)
-                self._db[entity_type][name][entity_id] = obj
+                container = self._db[entity_type][name]
+                container[entity_id] = obj
+
+                # Keep the "latest" pointer consistent when updating the latest entity
+                try:
+                    if container.get("latest", {}).get("id") == entity_id:
+                        container["latest"] = obj
+                except AttributeError:
+                    # In case "latest" is malformed, ignore and continue
+                    pass
 
         except KeyError:
             msg = self._format_msg(3, entity_type=entity_type, entity_id=entity_id)
@@ -253,55 +262,51 @@ class ClientLocal(Client):
 
                 # Name is optional and extracted from kwargs
                 # "params": {"name": <name>}
-                name = kwargs.get("params", {}).get("name")
+                name_param = kwargs.get("params", {}).get("name")
 
-                # Delete by name
-                if entity_id is None and name is not None:
-                    self._db[entity_type].pop(name, None)
+                # Delete by name (remove the whole named container)
+                if entity_id is None and name_param is not None:
+                    self._db[entity_type].pop(name_param, None)
                     return {"deleted": True}
 
                 # Delete by id
-                for _, v in self._db[entity_type].items():
+                found_name: str | None = None
+                container: dict | None = None
+                for n, v in self._db[entity_type].items():
                     if entity_id in v:
-                        v.pop(entity_id)
-
-                        # Handle latest
-                        if v["latest"]["id"] == entity_id:
-                            name = v["latest"].get("name", entity_id)
-                            v.pop("latest")
-                            reset_latest = True
+                        found_name = n
+                        container = v
                         break
                 else:
                     raise KeyError
 
-                if name is not None:
-                    # Pop name if empty
-                    if not self._db[entity_type][name]:
-                        self._db[entity_type].pop(name)
-
-                    # Handle latest
-                    elif reset_latest:
-                        latest_uuid = None
-                        latest_date = None
-                        for k, v in self._db[entity_type][name].items():
-                            # Get created from metadata. If tzinfo is None, set it to UTC
-                            # If created is not in ISO format, use fallback
-                            fallback = datetime.fromtimestamp(0, timezone.utc)
-                            try:
-                                current_created = datetime.fromisoformat(v.get("metadata", {}).get("created"))
-                                if current_created.tzinfo is None:
-                                    current_created = current_created.replace(tzinfo=timezone.utc)
-                            except ValueError:
-                                current_created = fallback
-
-                            # Update latest date and uuid
-                            if latest_date is None or current_created > latest_date:
-                                latest_uuid = k
-                                latest_date = current_created
-
-                        # Set new latest
-                        if latest_uuid is not None:
-                            self._db[entity_type][name]["latest"] = self._db[entity_type][name][latest_uuid]
+                # Remove the entity from the container
+                assert container is not None  # for type checkers
+                container.pop(entity_id)
+
+                # Handle latest pointer if needed
+                if container.get("latest", {}).get("id") == entity_id:
+                    # Remove stale latest
+                    container.pop("latest", None)
+                    reset_latest = True
+
+                # If container is now empty, drop it entirely
+                if not container:
+                    assert found_name is not None
+                    self._db[entity_type].pop(found_name, None)
+                # Otherwise, recompute latest if required
+                elif reset_latest:
+                    latest_uuid = None
+                    latest_date = None
+                    for k, v in container.items():
+                        # Parse creation time from metadata; tolerate various formats
+                        current_created = self._safe_parse_created(v)
+                        if latest_date is None or current_created > latest_date:
+                            latest_uuid = k
+                            latest_date = current_created
+
+                    if latest_uuid is not None:
+                        container["latest"] = container[latest_uuid]
 
         except KeyError:
             msg = self._format_msg(3, entity_type=entity_type, entity_id=entity_id)
@@ -330,7 +335,10 @@ class ClientLocal(Client):
         # "params": {"name": <name>}
         name = kwargs.get("params", {}).get("name")
         if name is not None:
-            return [self._db[entity_type][name]["latest"]]
+            try:
+                return [self._db[entity_type][name]["latest"]]
+            except KeyError:
+                return []
 
         try:
             # If no name is provided, get latest objects
@@ -343,7 +351,7 @@ class ClientLocal(Client):
         if kind is not None:
             listed_objects = [obj for obj in listed_objects if obj["kind"] == kind]
 
-        # If function is provided, return objects by function
+        # If function/task is provided, return objects by function/task
         spec_params = ["function", "task"]
         for i in spec_params:
             p = kwargs.get("params", {}).get(i)
@@ -489,14 +497,15 @@ class ClientLocal(Client):
         """
         # Deepcopy to avoid modifying the original object
         project = deepcopy(obj)
-        spec = project.get("spec", {})
+        # Ensure spec exists on the returned project
+        spec = project.setdefault("spec", {})
 
         # Get all entities associated with the project specs
         projects_entities = [k for k, _ in self._db.items() if k not in ["projects", "runs", "tasks"]]
 
         for entity_type in projects_entities:
             # Get all objects of the entity type for the project
-            objs = self._db[entity_type]
+            objs = self._db.get(entity_type, {})
 
             # Set empty list
             spec[entity_type] = []
@@ -521,6 +530,29 @@ class ClientLocal(Client):
 
         return project
 
+    @staticmethod
+    def _safe_parse_created(obj: dict) -> datetime:
+        """
+        Safely parse the creation datetime of an object.
+
+        - Accepts ISO format with optional 'Z'.
+        - If tzinfo is missing, assume UTC.
+        - Falls back to epoch if missing/invalid.
+        """
+        created_raw = obj.get("metadata", {}).get("created")
+        fallback = datetime.fromtimestamp(0, timezone.utc)
+        if not created_raw or not isinstance(created_raw, str):
+            return fallback
+        try:
+            # Support trailing 'Z'
+            ts = created_raw.replace("Z", "+00:00")
+            dt = datetime.fromisoformat(ts)
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            return dt
+        except Exception:
+            return fallback
+
     ##############################
     # Utils
     ##############################

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/credentials/ini_module.py

@@ -146,19 +146,3 @@ def set_current_profile(environment: str) -> None:
 
     except Exception as e:
         raise ClientError(f"Failed to write env file: {e}")
-
-
-def read_env_from_file() -> str | None:
-    """
-    Read the current credentials profile name from the .dhcore.ini file.
-
-    Returns
-    -------
-    str or None
-        Name of the current credentials profile, or None if not found.
-    """
-    try:
-        cfg = load_file()
-        return cfg["DEFAULT"]["current_environment"]
-    except Exception:
-        return None

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)