halib 0.2.29__tar.gz → 0.2.30__tar.gz

{halib-0.2.29 → halib-0.2.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: halib
-Version: 0.2.29
+Version: 0.2.30
 Summary: Small library for common tasks
 Author: Hoang Van Ha
 Author-email: hoangvanhauit@gmail.com
@@ -57,11 +57,11 @@ Dynamic: summary
 
 ## v0.2.x (Experiment & Core Updates)
 
-### **v0.2.29**
+### **v0.2.30**
 
 - ✨ **New Feature:**: add `common.common.log_func` as decorator to log function entry, exit, with execution time and arguments.
 
-- 🚀 **Improvement:**: enhance `utils.dict.DictUtils` with `deep_remove` and `prune` function
+- 🚀 **Improvement:**: enhance `utils.dict.DictUtils` with `deep_exclude/include` and `prune` function
 
 ### **v0.2.28**
 

{halib-0.2.29 → halib-0.2.30}/README.md

@@ -2,11 +2,11 @@
 
 ## v0.2.x (Experiment & Core Updates)
 
-### **v0.2.29**
+### **v0.2.30**
 
 - ✨ **New Feature:**: add `common.common.log_func` as decorator to log function entry, exit, with execution time and arguments.
 
-- 🚀 **Improvement:**: enhance `utils.dict.DictUtils` with `deep_remove` and `prune` function
+- 🚀 **Improvement:**: enhance `utils.dict.DictUtils` with `deep_exclude/include` and `prune` function
 
 ### **v0.2.28**
 

{halib-0.2.29 → halib-0.2.30}/halib/utils/dict.py

@@ -136,9 +136,9 @@ class DictUtils:
         return full_hash[:length]
 
     @staticmethod
-    def deep_remove(
+    def deep_exclude(
         d: Dict[str, Any],
-        keys_to_remove: List[str],
+        keys_to_exclude: List[str],
         in_place: bool = False,
         sep: str = ".",
     ) -> Dict[str, Any]:
@@ -147,7 +147,7 @@ class DictUtils:
 
         Args:
             d: The dictionary to filter.
-            keys_to_remove: A list of flattened keys to remove (e.g., ['model.layers.dropout']).
+            keys_to_exclude: A list of flattened keys to exclude (e.g., ['model.layers.dropout']).
             in_place: If True, modifies the dictionary directly.
                       If False, creates and modifies a deep copy, leaving the original untouched.
             sep: Separator used in the dot-notation keys (default: ".").
@@ -157,7 +157,7 @@ class DictUtils:
 
         Example:
             >>> data = {'a': {'b': 1, 'c': 2}}
-            >>> DictUtils.deep_remove(data, ['a.b'], in_place=False)
+            >>> DictUtils.deep_exclude(data, ['a.b'], in_place=False)
             {'a': {'c': 2}}
         """
         # 1. Handle the copy logic based on the in_place flag
@@ -167,7 +167,7 @@ class DictUtils:
             target_dict = copy.deepcopy(d)
 
         # 2. Iterate over each dot-notation key we want to delete
-        for flat_key in keys_to_remove:
+        for flat_key in keys_to_exclude:
             parts = flat_key.split(sep)
 
             # 3. Traverse to the parent container of the key we want to delete
@@ -191,6 +191,94 @@ class DictUtils:
 
         return target_dict
 
+    @staticmethod
+    def deep_include(
+        d: Dict[str, Any],
+        keys_to_include: List[str],
+        in_place: bool = False,
+        sep: str = ".",
+    ) -> Dict[str, Any]:
+        """
+        Filters a nested dictionary to keep ONLY the specified dot-notation paths.
+
+        Args:
+            d: The dictionary to filter.
+            keys_to_include: A list of flattened keys to include (e.g., ['a.b.c']).
+            in_place: If True, modifies the original dictionary.
+            sep: Separator used in the dot-notation keys.
+
+        Returns:
+            The filtered dictionary.
+        """
+        # 1. Create a fresh container for the keys we want to preserve
+        # Unlike deep_remove, it's often cleaner to build a new dict
+        # than to delete everything else.
+        new_dict = {}
+
+        for flat_key in keys_to_include:
+            parts = flat_key.split(sep)
+
+            # Pointers to traverse both dictionaries
+            current_source = d
+            current_target = new_dict
+
+            for i, part in enumerate(parts):
+                if isinstance(current_source, dict) and part in current_source:
+                    # Move down the source
+                    current_source = current_source[part]
+
+                    # If we are at the leaf of the 'keep' path, copy the value
+                    if i == len(parts) - 1:
+                        current_target[part] = copy.deepcopy(current_source)
+                    else:
+                        # If the path doesn't exist in our new_dict yet, create it
+                        if part not in current_target or not isinstance(
+                            current_target[part], dict
+                        ):
+                            current_target[part] = {}
+                        current_target = current_target[part]
+                else:
+                    # The path to keep doesn't exist in the source, skip it
+                    break
+
+        # 2. Handle the in_place logic
+        if in_place:
+            d.clear()
+            d.update(new_dict)
+            return d
+
+        return new_dict
+
+    @staticmethod
+    def apply_exclusion_mask(
+        d: Dict[str, Any],
+        config_mask: Dict[str, Any],
+        in_place: bool = False,
+        sep: str = ".",
+    ) -> Dict[str, Any]:
+        """
+        Uses a dictionary 'mask' to define what to throw away.
+        """
+        # Assuming your DictUtils.flatten returns a dict of {path: value}
+        flatten_dict = DictUtils.flatten(config_mask, sep=sep)
+        paths_to_exclude = list(flatten_dict.keys())
+        return DictUtils.deep_exclude(d, paths_to_exclude, in_place=in_place, sep=sep)
+
+    @staticmethod
+    def apply_inclusion_mask(
+        d: Dict[str, Any],
+        config_mask: Dict[str, Any],
+        in_place: bool = False,
+        sep: str = ".",
+    ) -> Dict[str, Any]:
+        """
+        Renamed from 'deep_keep_by_config'.
+        Uses a dictionary 'mask' to define what to allow.
+        """
+        flatten_dict = DictUtils.flatten(config_mask, sep=sep)
+        paths_to_include = list(flatten_dict.keys())
+        return DictUtils.deep_include(d, paths_to_include, in_place=in_place, sep=sep)
+
     @staticmethod
     def prune(d: Any, prune_values: Tuple[Any, ...] = (None, {}, [], "")) -> Any:
         """

{halib-0.2.29 → halib-0.2.30}/halib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: halib
-Version: 0.2.29
+Version: 0.2.30
 Summary: Small library for common tasks
 Author: Hoang Van Ha
 Author-email: hoangvanhauit@gmail.com
@@ -57,11 +57,11 @@ Dynamic: summary
 
 ## v0.2.x (Experiment & Core Updates)
 
-### **v0.2.29**
+### **v0.2.30**
 
 - ✨ **New Feature:**: add `common.common.log_func` as decorator to log function entry, exit, with execution time and arguments.
 
-- 🚀 **Improvement:**: enhance `utils.dict.DictUtils` with `deep_remove` and `prune` function
+- 🚀 **Improvement:**: enhance `utils.dict.DictUtils` with `deep_exclude/include` and `prune` function
 
 ### **v0.2.28**
 

{halib-0.2.29 → halib-0.2.30}/setup.py

@@ -8,7 +8,7 @@ with open("requirements.txt", "r", encoding="utf-8") as f:
 
 setuptools.setup(
     name="halib",
-    version="0.2.29",
+    version="0.2.30",
     author="Hoang Van Ha",
     author_email="hoangvanhauit@gmail.com",
     description="Small library for common tasks",