hcs-core 0.1.250__py3-none-any.whl → 0.1.316__py3-none-any.whl

hcs_core/ctxp/jsondot.py

@@ -13,15 +13,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-import json
-import os.path
-import copy
-import time
-import random
-import portalocker
-from typing import Any
-
-
 """
 jsondot is utility to make json/dict object accessible in the "." way.
 
@@ -44,133 +35,323 @@ print(my_dict.key1.key2)
 """
 
 
+import copy
+import json
+import os.path
+import random
+import time
+from typing import Any, Dict, Optional, Union
+
+
 class dotdict(dict):
-    """dot.notation access to dictionary attributes"""
+    """dot.notation access to dictionary attributes with enhanced safety.
+
+    A dictionary subclass that provides attribute-style access to its elements
+    while maintaining compatibility with regular dict operations.
+
+    Examples:
+        >>> d = dotdict({'a': 1, 'b': {'c': 2}})
+        >>> d.a
+        1
+        >>> d.b.c
+        2
+        >>> d.b.c = 3
+        >>> d.b.c
+        3
+    """
 
     __getattr__ = dict.get
     __setattr__ = dict.__setitem__
     __delattr__ = dict.__delitem__
 
-    def __lt__(self, other):
-        # to support tuple-based sort. (dotdict_a < dotdict_b)
-        return True
+    def __lt__(self, other: Union[dict, "dotdict"]) -> bool:
+        """Support proper sorting by comparing underlying dictionaries."""
+        if isinstance(other, dict):
+            return dict(self) < dict(other)
+        return NotImplemented
 
-    def __deepcopy__(self, memo=None):
-        # To workaround deepcopy with some python version
+    def __eq__(self, other: Union[dict, "dotdict"]) -> bool:
+        """Support equality comparison with other dictionaries."""
+        if isinstance(other, dict):
+            return dict(self) == dict(other)
+        return NotImplemented
+
+    def __deepcopy__(self, memo: Optional[Dict] = None) -> "dotdict":
+        """Support deep copying of the dictionary.
+
+        Args:
+            memo: Memoization dictionary for handling circular references
+
+        Returns:
+            A deep copy of the dotdict instance
+        """
         new = {}
         for key in self.keys():
             new[key] = copy.deepcopy(self[key], memo=memo)
-        return new
+        return dotdict(new)
+
+    def __repr__(self) -> str:
+        """Return a string representation of the dictionary.
 
+        Returns:
+            A string showing this is a dotdict instance with its contents
+        """
+        return dict.__repr__(self)
 
-# TODO: how to remove the lib-specific dependency from this utility class?
-# Register the represent_dict function with SafeDumper
-def _represent_dict(dumper, data):
-    return dumper.represent_dict(data.items())
+    # def __getstate__(self):
+    #     """Return state for serialization - just return the underlying dict"""
+    #     return dict(self)
 
+    # def __setstate__(self, state):
+    #     """Restore state from serialization"""
+    #     self.update(state)
 
-import yaml
+    # def __reduce_ex__(self, protocol):
+    #     return dict, (dict(self),)
 
-yaml.SafeDumper.add_representer(dotdict, _represent_dict)
+    # def __getattribute__(self, name):
+    #     """Make this look like a plain dict to introspection"""
+    #     if name in ('__getstate__', '__setstate__', '__reduce__', '__reduce_ex__', '__class__'):
+    #         return getattr(dict, name)
+    #     return super().__getattribute__(name)
+
+
+def _yaml_interoperability() -> None:
+    """Set up YAML serialization support for dotdict objects.
+
+    Registers a custom representer with PyYAML to properly serialize
+    dotdict objects as regular dictionaries. This ensures dotdict
+    objects can be seamlessly used with YAML operations.
+
+    Note:
+        This function is automatically called during module initialization.
+    """
+    try:
+        import yaml
+
+        def _represent_dict(dumper: yaml.SafeDumper, data: dotdict) -> yaml.nodes.MappingNode:
+            return dumper.represent_dict(data.items())
+
+        yaml.SafeDumper.add_representer(dotdict, _represent_dict)
+    except ImportError:
+        pass  # PyYAML not available, silently skip registration
 
 
 def dotify(target: Any) -> Any:
-    """Deeply convert an object from dict to dotdict"""
+    """Deeply convert an object from dict to dotdict.
 
-    # If already dotified, skip
-    if isinstance(target, dotdict):
-        return target
-    if isinstance(target, list):
-        for i in range(len(target)):
-            target[i] = dotify(target[i])
-        return target
-    if isinstance(target, dict):
-        for k in target:
-            target[k] = dotify(target[k])
-        return dotdict(target)
+    Recursively converts all nested dictionaries to dotdict instances
+    while preserving other data types. Handles circular references safely.
 
-    # Return unchanged
-    return target
+    Args:
+        target: The object to convert
+
+    Returns:
+        The converted object with all dicts replaced by dotdict instances
+
+    Raises:
+        RecursionError: If maximum recursion depth is exceeded
+    """
+    # Handle circular references with recursion depth check
+    if getattr(dotify, "_depth", 0) > getattr(dotify, "_max_depth", 1000):
+        raise RecursionError("Maximum recursion depth exceeded")
+
+    dotify._depth = getattr(dotify, "_depth", 0) + 1
+    try:
+        if isinstance(target, dotdict):
+            return target
+        if isinstance(target, list):
+            return [dotify(item) for item in target]
+        if isinstance(target, dict):
+            return dotdict({k: dotify(v) for k, v in target.items()})
+        return target
+    finally:
+        dotify._depth -= 1
 
 
 def undot(target: Any) -> Any:
-    """Deeply convert an object from dotdict to plain dictd"""
-    if isinstance(target, list):
-        for i in range(len(target)):
-            target[i] = undot(target[i])
+    """Deeply convert an object from dotdict to plain dict.
+
+    Recursively converts all nested dotdict instances to regular dictionaries
+    while preserving other data types. Handles circular references safely.
+
+    Args:
+        target: The object to convert
+
+    Returns:
+        The converted object with all dotdict instances replaced by plain dicts
+
+    Raises:
+        RecursionError: If maximum recursion depth is exceeded
+    """
+    # Handle circular references with recursion depth check
+    if getattr(undot, "_depth", 0) > getattr(undot, "_max_depth", 1000):
+        raise RecursionError("Maximum recursion depth exceeded")
+
+    undot._depth = getattr(undot, "_depth", 0) + 1
+    try:
+        if isinstance(target, list):
+            return [undot(item) for item in target]
+        if isinstance(target, dict):
+            return {k: undot(v) for k, v in target.items()}
         return target
-    if isinstance(target, dict):
-        ret = {}
-        for k in target:
-            ret[k] = undot(target[k])
-        return ret
-    return target
+    finally:
+        undot._depth -= 1
 
 
-def _is_primitive(obj):
-    return isinstance(obj, str) or isinstance(obj, bool) or isinstance(obj, int) or isinstance(obj, float)
+def _is_primitive(obj: Any) -> bool:
+    """Check if the object is a primitive type.
+
+    Determines if an object is a basic Python type that doesn't need
+    conversion when serializing/deserializing.
+
+    Args:
+        obj: Any Python object
+
+    Returns:
+        bool: True if the object is a primitive type (str, bool, int, float, None)
+    """
+    return obj is None or isinstance(obj, (str, bool, int, float))
 
 
 def plain(target: Any) -> Any:
-    """Deeply convert a dotdict from dict"""
+    """Convert a complex object structure to plain Python types.
+
+    Recursively converts all objects to their basic Python equivalents,
+    making the structure suitable for serialization. Handles nested
+    dictionaries, lists, and primitive types.
+
+    Args:
+        target: The object to convert
+
+    Returns:
+        The converted object with all complex types replaced by basic Python types
+
+    Examples:
+        >>> d = dotdict({'a': 1, 'b': {'c': 2}})
+        >>> plain(d)
+        {'a': 1, 'b': {'c': 2}}
+    """
     if _is_primitive(target):
         return target
-
     if isinstance(target, list):
-        for i in range(len(target)):
-            target[i] = plain(target[i])
-        return target
+        return [plain(item) for item in target]
     if isinstance(target, dict):
-        for k in target:
-            target[k] = plain(target[k])
-        return dict(target)
+        return {k: plain(v) for k, v in target.items()}
+    return target
 
 
 def parse(text: str) -> dotdict:
-    dict = json.loads(text)
-    return dotify(dict)
+    """Parse a JSON string into a dotdict object.
+
+    Args:
+        text: JSON string to parse
+
+    Returns:
+        dotdict: The parsed and converted data
+
+    Raises:
+        JSONDecodeError: If the string contains invalid JSON
+        TypeError: If input is not a string
+    """
+    if not isinstance(text, str):
+        raise TypeError("Input must be a string")
+    try:
+        dict_data = json.loads(text)
+        return dotify(dict_data)
+    except json.JSONDecodeError as e:
+        raise Exception(f"Invalid JSON: {str(e)}") from e
 
 
-def _lock_with_retry(file, for_read: bool):
-    if for_read:
-        flags = portalocker.LockFlags.SHARED
-    else:
-        flags = portalocker.LockFlags.EXCLUSIVE  # | portalocker.LockFlags.NON_BLOCKING
+def _lock_with_retry(file: str, for_read: bool, max_retry: int = 6, initial_backoff: float = 0.05) -> None:
+    """Attempt to lock a file with retries using exponential backoff.
+
+    Args:
+        file: File handle to lock
+        for_read: If True, acquire shared lock; if False, acquire exclusive lock
+        max_retry: Maximum number of retry attempts
+        initial_backoff: Initial backoff time in seconds
+
+    Raises:
+        Exception: If unable to acquire lock after max retries
+        portalocker.LockException: If locking fails
+    """
+    import portalocker
+
+    flags = portalocker.LockFlags.SHARED if for_read else portalocker.LockFlags.EXCLUSIVE
 
-    max_retry = 6
     retry = 0
-    backoff_seconds = 0.05
+    backoff_seconds = initial_backoff
     while True:
         try:
             portalocker.lock(file, flags)
             return
-        except Exception as e:
+        except portalocker.LockException as e:
             retry += 1
             if retry > max_retry:
-                raise Exception(f"Fail locking file {file}") from e
+                raise Exception(f"Failed to acquire lock for file {file} after {max_retry} attempts") from e
             random_delay = backoff_seconds + random.uniform(0, 0.1)
             time.sleep(random_delay)
-            backoff_seconds += backoff_seconds
+            backoff_seconds *= 2
+
 
+def load(file: str, default: Any = None, lock: bool = False) -> dotdict:
+    """Load and parse a JSON file into a dotdict object.
 
-def load(file: str, default: Any = None, lock: bool = False) -> Any:
+    Args:
+        file: Path to the JSON file
+        default: Value to return if file doesn't exist
+        lock: Whether to use file locking
+
+    Returns:
+        dotdict: The loaded and converted data
+
+    Raises:
+        FileNotFoundError: If file doesn't exist and no default provided
+        JSONDecodeError: If file contains invalid JSON
+        IOError: If file access fails
+    """
     try:
         if not os.path.exists(file):
+            if default is None:
+                raise FileNotFoundError(f"File not found: {file}")
             return dotify(default)
+
         with open(file) as json_file:
             if lock:
                 _lock_with_retry(json_file, True)
             dict = json.load(json_file)
         return dotify(dict)
+    except json.JSONDecodeError as e:
+        raise Exception(f"Invalid JSON in file {file}: {str(e)}") from e
+    except IOError as e:
+        raise Exception(f"Error accessing file {file}: {str(e)}") from e
     except Exception as e:
-        raise Exception(f"Error loading file {file}") from e
+        raise Exception(f"Unexpected error loading file {file}: {str(e)}") from e
+
 
+def save(data: dict, file: str, pretty: bool = True, lock: bool = False) -> None:
+    """Save data as JSON to a file with optional pretty printing and locking.
 
-def save(data: dict, file, format=True, lock: bool = False) -> None:
-    with open(file, "w") as outfile:
-        if lock:
-            _lock_with_retry(outfile, False)
-        if format:
-            json.dump(data, outfile, indent="\t", default=vars)
-        else:
-            json.dump(data, outfile)
+    Args:
+        data: Dictionary data to save
+        file: Path to the output JSON file
+        pretty: If True, format JSON with indentation
+        lock: Whether to use file locking
+
+    Raises:
+        IOError: If file access fails
+        TypeError: If data contains non-serializable objects
+    """
+    try:
+        os.makedirs(os.path.dirname(file), exist_ok=True)
+        with open(file, "w") as outfile:
+            if lock:
+                _lock_with_retry(outfile, False)
+            json.dump(data, outfile, indent="\t" if pretty else None, default=vars)
+    except IOError as e:
+        raise Exception(f"Error writing to file {file}: {str(e)}") from e
+    except TypeError as e:
+        raise Exception(f"Error serializing data to JSON: {str(e)}") from e
+    except Exception as e:
+        raise Exception(f"Unexpected error saving file {file}: {str(e)}") from e

hcs_core/ctxp/logger.py

@@ -13,14 +13,17 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
+import logging
 import os
 import re
-import logging
-import coloredlogs
 from logging.handlers import RotatingFileHandler
 
+import coloredlogs
+
 LOG_FORMAT_SIMPLE = "%(levelname).4s %(asctime)s %(name)-16s %(message)s"
-LOG_FORMAT_LONG = "%(color_on)s%(asctime)s.%(msecs)03d [%(process)-5d:%(threadName)-12s] %(levelname)-7s [%(name)-16s] %(message)s%(color_off)s"
+LOG_FORMAT_LONG = (
+    "%(color_on)s%(asctime)s.%(msecs)03d [%(process)-5d:%(threadName)-12s] %(levelname)-7s [%(name)-16s] %(message)s%(color_off)s"
+)
 DATE_FORMAT_SIMPLE = "%H:%M:%S"
 
 
@@ -132,9 +135,7 @@ def setup(
         )
 
 
-def setup_console_output(
-    logger, console_log_output, console_log_level, console_log_color, console_log_mask, log_line_template, date_fmt
-):
+def setup_console_output(logger, console_log_output, console_log_level, console_log_color, console_log_mask, log_line_template, date_fmt):
     if not date_fmt:
         date_fmt = coloredlogs.DEFAULT_DATE_FORMAT
     coloredlogs.install(

hcs_core/ctxp/profile.py

@@ -13,15 +13,16 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from copy import deepcopy
+import os
 import pathlib
 import shutil
-import os
+from copy import deepcopy
 from typing import Any
-from .util import panic, CtxpException
-from .jsondot import dotdict, dotify
+
 from . import state
-from .data_util import load_data_file, save_data_file
+from .data_util import deep_set_attr, load_data_file, save_data_file
+from .jsondot import dotdict, dotify
+from .util import CtxpException, panic
 
 _repo_path: str = None
 _active_profile_name: str = None
@@ -31,6 +32,8 @@ _auth_cache: dict = None
 
 def _set_active_profile_name(name):
     global _active_profile_name
+    if _active_profile_name == name:
+        return
     _active_profile_name = name
     state.set("active_profile", name)
 
@@ -50,8 +53,8 @@ def path(profile_name: str = None) -> str:
     return os.path.join(_repo_path, profile_name)
 
 
-def create(name: str, data: dict, auto_use: bool = True):
-    if exists(name):
+def create(name: str, data: dict, auto_use: bool = True, overwrite: bool = False):
+    if not overwrite and exists(name):
         if auto_use:
             use(name)
         raise CtxpException("Profile already exists: " + name)
@@ -60,7 +63,7 @@ def create(name: str, data: dict, auto_use: bool = True):
     save_data_file(data, file(name), "yaml", 0o600)
     if auto_use:
         use(name)
-    return get(name)
+    return get(name, reload=True)
 
 
 def copy(from_name: str, to_name: str, overwrite: bool = True):
@@ -72,15 +75,14 @@ def copy(from_name: str, to_name: str, overwrite: bool = True):
     create(to_name, deepcopy(data), auto_use=False)
 
 
-def current(reload: bool = False, exit_on_failure=True, exclude_secret: bool = False) -> dict:
+def current(reload: bool = False, exit_on_failure: bool = True, exclude_secret: bool = False) -> dict:
     """Get content of the current active profile"""
+
     profile_name = name()
     data = get(profile_name, reload)
 
     if data is None and exit_on_failure:
-        panic(
-            "Profile not set. Use 'hcs profile use [profile-name]' to choose one, or use 'hcs profile init' to create default profiles."
-        )
+        panic("Profile not set. Use 'hcs profile use [profile-name]' to choose one, or use 'hcs profile init' to create default profiles.")
 
     if exclude_secret:
         data = dotdict(dict(data))
@@ -94,7 +96,6 @@ def current(reload: bool = False, exit_on_failure=True, exclude_secret: bool = F
 
 def save():
     """Save the current profile"""
-    global _data
     if _data is None:
         return
     write(name(), _data)
@@ -123,6 +124,8 @@ def use(name: str) -> str:
         return
 
     _set_active_profile_name(name)
+    global _data
+    _data = _load_data_file_with_env_overrides(name, None)
     return name
 
 
@@ -138,6 +141,7 @@ def delete(profile_name: str = None) -> None:
 
     if profile_name is None:
         profile_name = name()
+
     global _active_profile_name, _data
     if _active_profile_name == profile_name:
         _active_profile_name = "default"
@@ -152,14 +156,39 @@ def get(profile_name: str, reload: bool = False, default=None) -> dotdict:
         global _data
         if _data is not None and not reload:
             return _data
-        data = load_data_file(file(profile_name), default=default)
-        if data is not None:
-            data = dotify(data)
-            _data = data
+        data = _load_data_file_with_env_overrides(profile_name, default)
+        _data = data
+    else:
+        data = _load_data_file_with_env_overrides(profile_name, default)
+    return data
+
+
+def _load_data_file_with_env_overrides(profile_name: str, default: dict) -> dict:
+
+    from ._init import app_name
+
+    my_name = app_name()
+
+    # Apply environment variables as defaults
+    env_prefix = my_name + "_profile_"
+    if os.environ.get(env_prefix + "mode") == "ENV":
+        if default:
+            data = dict(default)
+        else:
+            data = {}
     else:
         data = load_data_file(file(profile_name), default=default)
-        if data is not None:
-            data = dotify(data)
+        if data is None:
+            return
+
+    for key, value in os.environ.items():
+        if key.startswith(env_prefix):
+            # Strip prefix to get profile key
+            profile_key = key[len(env_prefix) :]
+            profile_key = profile_key.replace("_", ".")
+            deep_set_attr(data, profile_key, value, raise_on_not_found=False)
+
+    data = dotify(data)
     return data
 
 
@@ -194,8 +223,11 @@ class auth:
         if json.dumps(data) == json.dumps(_auth_cache):
             return
         _auth_cache = deepcopy(data)
-        file_name = auth._file_name()
-        save_data_file(data, file_name, "yaml", 0o600)
+        if os.environ.get("CTXP_AUTH_PERSIST", "true").lower() == "false":
+            pass
+        else:
+            file_name = auth._file_name()
+            save_data_file(data, file_name, "yaml", 0o600)
 
     @staticmethod
     def delete() -> None:

hcs_core/ctxp/profile_store.py

@@ -16,6 +16,7 @@ limitations under the License.
 # Profile_store provides a utility method to create profile-scoped fstore
 
 import os
+
 from . import profile
 from .fstore import fstore
 from .util import CtxpException

hcs_core/ctxp/recent.py

@@ -31,7 +31,7 @@ def all():
     return _recent
 
 
-def require(provided, k: str):
+def require(k: str, provided):
     if not k:
         raise Exception("Missing 'key' in recent.require(current, key).")
 
@@ -79,9 +79,9 @@ def of(k: str):
 
 class helper:
     @staticmethod
-    def default_list(array: list, name: str):
+    def default_list(array: list, name: str, field_name: str = "id"):
         with of(name) as r:
             if len(array) == 1:
-                r.set(array[0]["id"])
+                r.set(array[0][field_name])
             else:
                 r.unset()

hcs_core/ctxp/state.py

@@ -13,9 +13,10 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
+import os
 import pathlib
 from typing import Any
-import os
+
 from . import jsondot
 
 
@@ -30,7 +31,7 @@ class _StateFile:
             self._cache = jsondot.load(self._path, {}, lock=True)
         return self._cache
 
-    def get(self, key: str, default: Any, reload: bool = False):
+    def get(self, key: str, default: Any = None, reload: bool = False):
         return self._data(reload).get(key, default)
 
     def set(self, key: str, value: Any):
@@ -46,7 +47,7 @@ def init(store_path: str, name: str):
     _file = _StateFile(os.path.join(store_path, name))
 
 
-def get(key: str, default: Any, reload: bool = False):
+def get(key: str, default: Any = None, reload: bool = False):
     return _file.get(key=key, default=default, reload=reload)