zea 0.0.6__py3-none-any.whl → 0.0.7__py3-none-any.whl

zea/internal/parameters.py

@@ -10,15 +10,13 @@ See the Parameters class docstring for details on features and usage.
 
 import functools
 import inspect
-import pickle
 from copy import deepcopy
 
 import numpy as np
 
 from zea import log
-from zea.internal.cache import serialize_elements
 from zea.internal.core import Object as ZeaObject
-from zea.internal.core import _to_tensor
+from zea.internal.core import _to_tensor, hash_elements, serialize_elements
 
 
 def cache_with_dependencies(*deps):
@@ -32,15 +30,16 @@ def cache_with_dependencies(*deps):
             self._assert_dependencies_met(func.__name__)
 
             if func.__name__ in self._cache:
-                # Check if dependencies changed
-                current_hash = self._current_dependency_hash(deps)
+                # Check if dependencies changed for mutable parameters
+                current_hash = self._current_dependency_hash(func.__name__)
                 if current_hash == self._dependency_versions.get(func.__name__):
                     return self._cache[func.__name__]
+                else:
+                    self._invalidate(func.__name__)
 
             result = func(self)
-            self._computed.add(func.__name__)
             self._cache[func.__name__] = result
-            self._dependency_versions[func.__name__] = self._current_dependency_hash(deps)
+            self._dependency_versions[func.__name__] = self._current_dependency_hash(func.__name__)
             return result
 
         return property(wrapper)
@@ -48,7 +47,7 @@ def cache_with_dependencies(*deps):
     return decorator
 
 
-class MissingDependencyError(AttributeError):
+class MissingDependencyError(ValueError):
     """Exception indicating that a dependency of an attribute was not met."""
 
     def __init__(self, attribute: str, missing_dependencies: set):
@@ -58,6 +57,13 @@ class MissingDependencyError(AttributeError):
         )
 
 
+class NoDependencyError(ValueError):
+    """Exception indicating that an attribute has no dependencies defined."""
+
+    def __init__(self, name: str):
+        super().__init__(f"'{name}' is not a computed property with dependencies.")
+
+
 class Parameters(ZeaObject):
     """Base class for parameters with dependencies.
 
@@ -82,7 +88,7 @@ class Parameters(ZeaObject):
 
     - **Leaf Parameter Enforcement:** Only leaf parameters
       (those directly listed in `VALID_PARAMS`) can be set. Attempting to set a computed
-      property raises an informative `AttributeError` listing the leaf parameters
+      property raises an informative `ValueError` listing the leaf parameters
       that must be changed instead.
 
     - **Optional Dependency Parameters:** Parameters can be both set directly (as a leaf)
@@ -99,46 +105,50 @@ class Parameters(ZeaObject):
       computed properties to tensors for machine learning workflows.
 
     - **Error Reporting:** If a computed property cannot be resolved due to missing dependencies,
-      an informative `AttributeError` is raised, listing the missing parameters.
+      an informative `MissingDependencyError` is raised, listing the missing parameters.
 
     **Usage Example:**
 
-    .. code-block:: python
+    .. doctest::
 
-        class MyParams(Parameters):
-            VALID_PARAMS = {
-                "a": {"type": int, "default": 1},
-                "b": {"type": float, "default": 2.0},
-                "d": {"type": float},  # optional dependency
-            }
+        >>> class MyParams(Parameters):
+        ...     VALID_PARAMS = {
+        ...         "a": {"type": int, "default": 1},
+        ...         "b": {"type": float, "default": 2.0},
+        ...         "d": {"type": float},  # optional dependency
+        ...     }
 
-            @cache_with_dependencies("a", "b")
-            def c(self):
-                return self.a + self.b
+        ...     @cache_with_dependencies("a", "b")
+        ...     def c(self):
+        ...        return self.a + self.b
 
-            @cache_with_dependencies("a", "b")
-            def d(self):
-                if self._params.get("d") is not None:
-                    return self._params["d"]
-                return self.a * self.b
+        ...     @cache_with_dependencies("a", "b")
+        ...     def d(self):
+        ...         if self._params.get("d") is not None:
+        ...             return self._params["d"]
+        ...         return self.a * self.b
 
-
-        p = MyParams(a=3)
-        print(p.c)  # Computes and caches c
-        print(p.c)  # Returns cached value
+        >>> p = MyParams(a=3)
+        >>> print(p.c)  # Computes and caches c
+        5.0
+        >>> print(p.c)  # Returns cached value
+        5.0
 
         # Changing a parameter invalidates the cache
-        p.a = 4
-        print(p.c)  # Recomputes c
+        >>> p.a = 4
+        >>> print(p.c)  # Recomputes c, now 4 + 2.0 = 6.0
+        6.0
 
-        # You are not allowed to set computed properties
-        # p.c = 5  # Raises AttributeError
+        >>> # You are not allowed to set computed properties
+        >>> # p.c = 5  # Raises ValueError
 
-        # Now check out the optional dependency, this can be either
-        # set directly during initialization or computed from dependencies (default)
-        print(p.d)  # Returns 6 (=3 * 2.0)
-        p = MyParams(a=3, d=9.99)
-        print(p.d)  # Returns 9.99
+        >>> # Now check out the optional dependency, this can be either
+        >>> # set directly during initialization or computed from dependencies (default)
+        >>> print(p.d)  # Returns 8 (=4 * 2.0)
+        8.0
+        >>> p = MyParams(a=3, d=9.99)
+        >>> print(p.d)
+        9.99
 
     """
 
@@ -158,7 +168,6 @@ class Parameters(ZeaObject):
         # Internal state
         self._params = {}
         self._properties = self.get_properties()
-        self._computed = set()
         self._cache = {}
         self._dependency_versions = {}
 
@@ -169,7 +178,8 @@ class Parameters(ZeaObject):
         # Initialize parameters with defaults
         for param, config in self.VALID_PARAMS.items():
             if param not in kwargs and "default" in config:
-                kwargs[param] = config["default"]
+                # need to deepcopy in case default is mutable
+                kwargs[param] = deepcopy(config["default"])
 
         # Set provided parameters
         for key, value in kwargs.items():
@@ -247,7 +257,7 @@ class Parameters(ZeaObject):
     def serialized(self):
         """Compute the checksum of the object only if not already done"""
         if self._serialized is None:
-            self._serialized = pickle.dumps(self._params)
+            self._serialized = serialize_elements([self._params])
         return self._serialized
 
     @classmethod
@@ -260,42 +270,51 @@ class Parameters(ZeaObject):
     def _get_dependencies(cls, name):
         """Get the dependencies of a computed property."""
         if not cls._is_property_with_dependencies(name):
-            raise AttributeError(f"'{name}' is not a computed property with dependencies.")
+            raise NoDependencyError(name)
         return getattr(cls, name).fget._dependencies
 
-    @classmethod
-    def _find_leaf_params(cls, name, seen=None):
+    def _find_leaf_params(self, name, seen=None):
+        """Recursively find all leaf parameters that a property depends on.
+
+        If it is an optional dependency parameter, it will be included as a leaf. Not the ones it
+        depends on.
+        """
         if seen is None:
             seen = set()
         if name in seen:
             return set()
         seen.add(name)
+
+        # If the name is already a leaf parameter, return it
+        if name in self._params or name in self.VALID_PARAMS:
+            return {name}
+
         # If the name is a property with dependencies, find its leaf parameters
-        if cls._is_property_with_dependencies(name):
+        if self._is_property_with_dependencies(name):
             leaves = set()
-            for dep in cls._get_dependencies(name):
-                leaves |= cls._find_leaf_params(dep, seen)  # union
+            for dep in self._get_dependencies(name):
+                leaves |= self._find_leaf_params(dep, seen)  # union
             return leaves
-        # If it's a regular parameter, return it as a leaf
-        elif name in cls.VALID_PARAMS:
-            return {name}
-        else:
-            raise AttributeError(f"'{name}' is not a valid parameter or computed property.")
 
-    def __getattr__(self, item):
-        # First check regular params
-        if item in self._params:
-            return self._params[item]
+        raise AttributeError(f"'{name}' is not a valid parameter or computed property.")
+
+    def _has_param(self, name):
+        """Check if a parameter is set (i.e., exists in _params)."""
+        # Check for existence of _params to avoid issues during unpickling
+        return "_params" in self.__dict__ and name in self._params
 
-        # Check if it's a property
-        if item not in self._properties:
-            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{item}'. ")
+    def __getattr__(self, item):
+        """Handle attribute access for parameters only.
 
-        self._assert_dependencies_met(item)
+        Properties with dependencies are handled by cache_with_dependencies decorator.
+        Regular properties are handled by normal Python descriptor protocol.
+        """
+        # Return parameter value if it exists
+        if self._has_param(item):
+            return self._params[item]
 
-        # Return property value
-        cls_attr = getattr(self.__class__, item, None)
-        return cls_attr.__get__(self, self.__class__)
+        # Attribute not found
+        raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{item}'")
 
     def __setattr__(self, key, value):
         # Give clear error message on assignment to methods
@@ -314,7 +333,7 @@ class Parameters(ZeaObject):
         # Give clear error message on assignment to computed properties
         if self._is_property_with_dependencies(key) and key not in self.VALID_PARAMS:
             leaf_params = sorted(self._find_leaf_params(key))
-            raise AttributeError(
+            raise ValueError(
                 f"Cannot set computed property '{key}'. Only leaf parameters can be set. "
                 f"To change '{key}', set one or more of its leaf parameters: {leaf_params}"
             )
@@ -334,7 +353,9 @@ class Parameters(ZeaObject):
             del self._params[name]
             self._invalidate(name)
         elif name in self.VALID_PARAMS:
-            raise AttributeError(f"Cannot delete parameter '{name}' because it is not set.")
+            raise ValueError(f"Cannot delete parameter '{name}' because it is not set.")
+        else:
+            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'")
 
     @classmethod
     def _check_for_circular_dependencies(cls, name, seen=None):
@@ -372,7 +393,6 @@ class Parameters(ZeaObject):
     def _invalidate(self, key):
         """Invalidate a specific cached computed property and its dependencies."""
         self._cache.pop(key, None)
-        self._computed.discard(key)
         self._dependency_versions.pop(key, None)
         self._tensor_cache.pop(key, None)
         self._serialized = None  # see core object
@@ -386,9 +406,16 @@ class Parameters(ZeaObject):
         for key in self._find_all_dependents(changed_key):
             self._invalidate(key)
 
-    def _current_dependency_hash(self, deps) -> str:
-        values = [self._params.get(dep, None) for dep in deps]
-        return serialize_elements(values)
+    def _current_dependency_hash(self, key) -> str:
+        """Compute a hash representing the current state of the dependencies of key.
+
+        Mainly needed to track changes in mutable parameters.
+        """
+        if not self._is_property_with_dependencies(key):
+            raise NoDependencyError(key)
+        deps = self._find_leaf_params(key)
+        values = [self._params.get(dep) for dep in sorted(deps)]
+        return hash_elements(values)
 
     def _assert_dependencies_met(self, name):
         """Assert that all dependencies for a computed property are met."""
@@ -425,7 +452,8 @@ class Parameters(ZeaObject):
         Args:
             include ("all", or list): Only include these parameter/property names.
                 If "all", include all available parameters (i.e. their dependencies are met).
-                Default is "all".
+                If specified, will take the intersection with possible parameters, so non-existing
+                keys will be ignored. Default is "all".
             exclude (None or list): Exclude these parameter/property names.
                 If provided, these keys will be excluded from the output.
             keep_as_is (list): List of parameter/property names that should not be converted to
@@ -445,14 +473,17 @@ class Parameters(ZeaObject):
         if include == "all":
             keys = all_keys
         elif include is not None:
+            # Filter include list to only existing keys
             keys = set(include).intersection(all_keys)
         elif exclude is not None:
+            # Take all keys except those in exclude
             keys = all_keys - set(exclude)
 
         tensor_dict = {}
         # Convert parameters and computed properties to tensors
         for key in keys:
             # Get the value from params or computed properties
+            # This is essential to trigger dependency checks
             try:
                 val = getattr(self, key)
             except MissingDependencyError as exc:

zea/internal/setup_zea.py

@@ -22,14 +22,13 @@ initialization steps for you:
 By calling :func:`setup`, you can prepare your zea environment in a single step,
 ensuring that configuration, data paths, and device setup are all handled for you.
 
-.. code-block:: python
+.. doctest::
 
+    >>> # Basic usage: loads config, sets paths, initializes device
+    >>> config = setup_zea.setup(config_path="my_config.yaml")
 
-    # Basic usage: loads config, sets paths, initializes device
-    config = setup_zea.setup(config_path="my_config.yaml")
-
-    # With user creation prompt
-    config = setup_zea.setup(config_path="my_config.yaml", create_user=True)
+    >>> # With user creation prompt
+    >>> config = setup_zea.setup(config_path="my_config.yaml", create_user=True)
 
 Function Details
 ----------------

zea/internal/utils.py

@@ -0,0 +1,282 @@
+"""Utility functions used internally.
+
+These are not exposed to the public API.
+"""
+
+import functools
+import hashlib
+import inspect
+import platform
+
+import numpy as np
+
+from zea import log
+
+
+def find_key(dictionary, contains, case_sensitive=False):
+    """Find key in dictionary that contains partly the string `contains`
+
+    Args:
+        dictionary (dict): Dictionary to find key in.
+        contains (str): String which the key should contain.
+        case_sensitive (bool, optional): Whether the search is case sensitive.
+            Defaults to False.
+
+    Returns:
+        str: the key of the dictionary that contains the query string.
+
+    Raises:
+        TypeError: if not all keys are strings.
+        KeyError: if no key is found containing the query string.
+    """
+    # Assert that all keys are strings
+    if not all(isinstance(k, str) for k in dictionary.keys()):
+        raise TypeError("All keys must be strings.")
+
+    if case_sensitive:
+        key = [k for k in dictionary.keys() if contains in k]
+    else:
+        key = [k for k in dictionary.keys() if contains.lower() in k.lower()]
+
+    if len(key) == 0:
+        raise KeyError(f"Key containing '{contains}' not found in dictionary.")
+
+    return key[0]
+
+
+def find_first_nonzero_index(arr, axis, invalid_val=-1):
+    """
+    Find the index of the first non-zero element along a specified axis in a NumPy array.
+
+    Args:
+        arr (numpy.ndarray): The input array to search for the first non-zero element.
+        axis (int): The axis along which to perform the search.
+        invalid_val (int, optional): The value to assign to elements where no
+            non-zero values are found along the axis.
+
+    Returns:
+        numpy.ndarray: An array of indices where the first non-zero element
+            occurs along the specified axis. Elements with no non-zero values along
+            the axis are replaced with the 'invalid_val'.
+
+    """
+    nonzero_mask = arr != 0
+    return np.where(nonzero_mask.any(axis=axis), nonzero_mask.argmax(axis=axis), invalid_val)
+
+
+def first_not_none_item(arr):
+    """
+    Finds and returns the first non-None item in the given array.
+
+    Args:
+        arr (list): The input array.
+
+    Returns:
+        The first non-None item found in the array, or None if no such item exists.
+    """
+    non_none_items = [item for item in arr if item is not None]
+    return non_none_items[0] if non_none_items else None
+
+
+def deprecated(replacement=None):
+    """Decorator to mark a function, method, or attribute as deprecated.
+
+    Args:
+        replacement (str, optional): The name of the replacement function, method, or attribute.
+
+    Returns:
+        callable: The decorated function, method, or property.
+
+    Raises:
+        DeprecationWarning: A warning is issued when the deprecated item is called or accessed.
+
+    Example:
+        >>> from zea.internal.utils import deprecated
+        >>> class MyClass:
+        ...     @deprecated(replacement="new_method")
+        ...     def old_method(self):
+        ...         print("This is the old method.")
+        ...
+        ...     @deprecated(replacement="new_attribute")
+        ...     def __init__(self):
+        ...         self._old_attribute = "Old value"
+        ...
+        ...     @deprecated(replacement="new_property")
+        ...     @property
+        ...     def old_property(self):
+        ...         return self._old_attribute
+
+        >>> # Using the deprecated method
+        >>> obj = MyClass()
+        >>> obj.old_method()
+        This is the old method.
+        >>> # Accessing the deprecated attribute
+        >>> print(obj.old_property)
+        Old value
+        >>> # Setting value to the deprecated attribute
+        >>> obj.old_property = "New value"
+    """
+
+    def decorator(item):
+        if callable(item):
+            # If it's a function or method
+            @functools.wraps(item)
+            def wrapper(*args, **kwargs):
+                if replacement:
+                    log.deprecated(
+                        f"Call to deprecated {item.__name__}. Use {replacement} instead."
+                    )
+                else:
+                    log.deprecated(f"Call to deprecated {item.__name__}.")
+                return item(*args, **kwargs)
+
+            return wrapper
+        elif isinstance(item, property):
+            # If it's a property of a class
+            def getter(self):
+                if replacement:
+                    log.deprecated(
+                        f"Access to deprecated attribute {item.fget.__name__}, "
+                        f"use {replacement} instead."
+                    )
+                else:
+                    log.deprecated(f"Access to deprecated attribute {item.fget.__name__}.")
+                return item.fget(self)
+
+            def setter(self, value):
+                if replacement:
+                    log.deprecated(
+                        f"Setting value to deprecated attribute {item.fget.__name__}, "
+                        f"use {replacement} instead."
+                    )
+                else:
+                    log.deprecated(f"Setting value to deprecated attribute {item.fget.__name__}.")
+
+                if item.fset is None:
+                    raise AttributeError(f"{item.fget.__name__} is read-only")
+                item.fset(self, value)
+
+            def deleter(self):
+                if replacement:
+                    log.deprecated(
+                        f"Deleting deprecated attribute {item.fget.__name__}, "
+                        f"use {replacement} instead."
+                    )
+                else:
+                    log.deprecated(f"Deleting deprecated attribute {item.fget.__name__}.")
+
+                if item.fdel is None:
+                    raise AttributeError(f"{item.fget.__name__} cannot be deleted")
+                item.fdel(self)
+
+            return property(getter, setter, deleter)
+
+        else:
+            raise TypeError("Decorator can only be applied to functions, methods, or properties.")
+
+    return decorator
+
+
+def calculate_file_hash(file_path, omit_line_str=None):
+    """Calculates the hash of a file.
+
+    Args:
+        file_path (str): Path to file.
+        omit_line_str (str, optional): If this string is found in a line, the line will
+            be omitted when calculating the hash. This is useful for example
+            when the file contains the hash itself.
+
+    Returns:
+        str: The hash of the file.
+
+    """
+    hash_object = hashlib.sha256()
+    with open(file_path, "rb") as f:
+        for line in f:
+            if omit_line_str is not None and omit_line_str.encode() in line:
+                continue
+            hash_object.update(line)
+    return hash_object.hexdigest()
+
+
+def check_architecture():
+    """Checks the architecture of the system."""
+    return platform.uname()[-1]
+
+
+def get_function_args(func):
+    """Get the names of the arguments of a function."""
+    sig = inspect.signature(func)
+    return tuple(sig.parameters)
+
+
+def fn_requires_argument(fn, arg_name):
+    """Returns True if the function requires the argument 'arg_name'."""
+    params = get_function_args(fn)
+    return arg_name in params
+
+
+def find_methods_with_return_type(cls, return_type_hint: str):
+    """
+    Find all methods in a class that have the specified return type hint.
+
+    Args:
+        cls: The class to inspect.
+        return_type_hint (str): The return type hint to match.
+
+    Returns:
+        A list of method names that match the return type hint.
+    """
+    matching_methods = []
+    for name, member in inspect.getmembers(cls, predicate=inspect.isfunction):
+        annotations = getattr(member, "__annotations__", {})
+        return_annotation = annotations.get("return")
+        if return_annotation is None:
+            continue
+
+        # Convert annotation to string for comparison
+        if hasattr(return_annotation, "__name__"):
+            # For types like bool, int, str, custom classes
+            annotation_str = return_annotation.__name__
+        else:
+            # For string annotations or other types, convert to string
+            annotation_str = str(return_annotation)
+
+        if annotation_str == return_type_hint:
+            matching_methods.append(name)
+    return matching_methods
+
+
+def keep_trying(fn, args=None, required_set=None):
+    """Keep trying to run a function until it succeeds.
+
+    Args:
+        fn (callable): Function to run.
+        args (dict, optional): Arguments to pass to function.
+        required_set (set, optional): Set of required outputs.
+            If output is not in required_set, function will be rerun.
+
+    Returns:
+        Any: The output of the function if successful.
+
+    """
+    while True:
+        try:
+            out = fn(**args) if args is not None else fn()
+            if required_set is not None:
+                assert out is not None
+                assert out in required_set, f"Output {out} not in {required_set}"
+            return out
+        except Exception as e:
+            log.warning(f"Function {fn.__name__} failed with error: {e}. Retrying...")
+
+
+def reduce_to_signature(func, kwargs):
+    """Reduce the kwargs to the signature of the function."""
+    # Retrieve the argument names of the function
+    sig = inspect.signature(func)
+
+    # Filter out the arguments that are not part of the function
+    reduced_params = {key: kwargs[key] for key in sig.parameters if key in kwargs}
+
+    return reduced_params