osbot-utils 1.80.0__py3-none-any.whl → 1.82.0__py3-none-any.whl

osbot_utils/base_classes/Type_Safe.py

@@ -361,3 +361,5 @@ def serialize_to_dict(obj):
         return data
     else:
         raise TypeError(f"Type {type(obj)} not serializable")
+        #return f"UNSERIALIZABLE({type(obj).__name__})"             # todo: see if there are valid use cases for this
+

osbot_utils/helpers/generators/Generator_Context_Manager.py

@@ -0,0 +1,21 @@
+from osbot_utils.helpers.generators.Model__Generator_State import Model__Generator_State
+
+
+class Generator_Context_Manager:
+    def __init__(self, manager, generator_func):
+        self.manager = manager
+        self.generator_func = generator_func
+        self.target_id = None
+
+    def __enter__(self):
+        self.target_id = self.manager.add(self.generator_func)                  # Add the generator to the manager
+        return self.manager.generator(self.target_id).target                    # Return the generator's reference
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        with self.manager.lock:
+            generator = self.manager.generator(self.target_id)
+            if generator and generator.state == Model__Generator_State.RUNNING:
+                generator.state = Model__Generator_State.COMPLETED
+
+
+        #self.manager.cleanup()

osbot_utils/helpers/generators/Generator_Manager.py

@@ -0,0 +1,115 @@
+import threading
+from _thread                                                    import RLock                              # Reentrant lock for thread-safe access
+from types                                                      import GeneratorType
+from typing                                                     import Dict                               # Typing imports for type hints
+from typing                                                     import Union
+from osbot_utils.base_classes.Type_Safe                         import Type_Safe                          # Type_Safe base class for type-safe attributes
+from osbot_utils.helpers.Random_Guid                            import Random_Guid                        # Helper for generating unique IDs
+from osbot_utils.helpers.generators.Generator_Context_Manager   import Generator_Context_Manager
+from osbot_utils.helpers.generators.Model__Generator_State      import Model__Generator_State
+from osbot_utils.helpers.generators.Model__Generator_Target     import Model__Generator_Target
+from osbot_utils.utils.Lists                                    import list_group_by
+
+
+class Generator_Manager(Type_Safe):                                                                        # Class for managing multiple generator targets
+    generators: Dict[Random_Guid, Model__Generator_Target]                                                 # Dictionary mapping target IDs to generator targets
+    lock      : RLock                               = None                                                 # Reentrant lock for thread-safe access to shared data
+
+    def __init__(self, **kwargs):                                                                          # Constructor method
+        super().__init__(**kwargs)
+        self.lock = threading.RLock()                                                                      # return an object of type _thread.RLock
+
+
+    def active(self) -> Dict[Random_Guid, Model__Generator_Target]:                                        # Method to get all active (running) generators
+        with self.lock:                                                                                    # Acquire the lock for thread-safe access
+            return {k: v for k, v in self.generators.items() if v.state == Model__Generator_State.RUNNING} # Return a dictionary of running generators
+
+    def add(self, target: GeneratorType) -> Random_Guid:                                                   # Method to add a new generator to the manager
+        with self.lock:                                                                                    # Acquire the lock for thread-safe access
+            existing_target_id = self.target_id(target)                                                     # Check if the target already exists
+            if existing_target_id:                                                                         # If the target already exists
+                raise ValueError(f"In Generator_Manager.add_generator, "                                   # Raise an error with the ID of the existing target
+                                 f"target already exists with ID: {existing_target_id}")
+
+            generator = Model__Generator_Target(target=target, state=Model__Generator_State.RUNNING)       # Create a new Generator_Target with RUNNING state
+            self.generators[generator.target_id] = generator                                               # Add the generator to the dictionary
+            return generator.target_id                                                                     # Return the unique ID of the added generator
+
+    def capture(self, generator_func: GeneratorType):                                                      # Use this method to manage a generator's lifecycle via a context manager.
+        return Generator_Context_Manager(self, generator_func)
+
+    def cleanup(self) -> int:                                                                              # Method to remove all completed or stopped generators
+        with self.lock:                                                                                    # Acquire the lock for thread-safe access
+            cleaned_count = 0                                                                              # Counter for the number of generators cleaned up
+            for target_id in list(self.generators.keys()):                                                 # Iterate over the keys of the dictionary
+                generator = self.generator(target_id)                                                      # Get the generator by its ID
+                if generator and generator.state in [Model__Generator_State.STOPPED,
+                                                     Model__Generator_State.COMPLETED]:                    # Check if the generator is stopped or completed
+                    self.generators.pop(target_id, None)                                                   # Remove the generator from the dictionary
+                    cleaned_count += 1                                                                     # Increment the cleaned count
+            return cleaned_count                                                                           # Return the total number of cleaned generators
+
+    def find_generator(self, target: GeneratorType) -> Model__Generator_Target:
+        with self.lock:
+            for generator in list(self.generators.values()):
+                if generator.target == target:
+                    return generator
+
+    def generator(self, target_id: Random_Guid) -> Model__Generator_Target:                                # Method to get a generator by its ID
+        with self.lock:                                                                                    # Acquire the lock for thread-safe access
+            return self.generators.get(target_id)                                                          # Return the generator or None if it doesn't exist
+
+    def remove(self, target_id: Random_Guid) -> bool:                                                      # Method to remove a generator if it is stopped or completed
+        with self.lock:                                                                                    # Acquire the lock for thread-safe access
+            generator = self.generator(target_id)                                                          # Get the generator by its ID
+            if not generator:                                                                              # If the generator doesn't exist
+                return False                                                                               # Silently return False
+            if generator.state in [Model__Generator_State.STOPPED, Model__Generator_State.COMPLETED]:      # Check if the generator is in a removable state
+                del self.generators[target_id]                                                             # Remove the generator from the dictionary
+                return True                                                                                # Return True to indicate successful removal
+            return False                                                                                   # Return False if the generator was not removable
+
+    def should_stop(self, target_id: Random_Guid) -> bool:                                                 # Method to check if a generator should stop
+        with self.lock:                                                                                    # Acquire the lock for thread-safe access
+            generator = self.generator(target_id)                                                          # Get the generator by its ID
+            if not generator:                                                                              # If the generator doesn't exist
+                raise ValueError(f"In Generator_Manager.should_stop, "                                     # Raise an error indicating missing generator
+                                 f"Generator with ID {target_id} does not exist.")
+            return generator.state != Model__Generator_State.RUNNING                                       # Return True if the generator is not running
+
+    def stop(self, target_id: Random_Guid) -> bool:                                                        # Method to stop a running generator
+        with self.lock:                                                                                    # Acquire the lock for thread-safe access
+            generator = self.generator(target_id)                                                          # Get the generator by its ID
+            if generator and generator.state == Model__Generator_State.RUNNING:                            # If the generator is running
+                generator.state = Model__Generator_State.STOPPING                                          # Set its state to STOPPING
+                return True                                                                                # Return True to indicate the generator is stopping
+            return False                                                                                   # Return False if the generator could not be stopped
+
+    def stop_all(self) -> int:                                                                             # Method to stop all running generators
+        with self.lock:                                                                                    # Acquire the lock for thread-safe access
+            stopped_count = 0                                                                              # Counter for the number of generators stopped
+            for target_id in list(self.generators.keys()):                                                 # Iterate over the keys of the dictionary
+                if self.stop(target_id):                                                                   # Attempt to stop each generator
+                    stopped_count += 1                                                                     # Increment the stopped count if successful
+            return stopped_count                                                                           # Return the total number of stopped generators
+
+    def status(self):
+        items = []
+        for _, generator in self.generators.items():
+            item = dict(target_method_name = generator.target.__name__,
+                        target_state       = generator.state.value,
+                        target_id          = generator.target_id )
+            items.append(item)
+        items__by_state = list_group_by(items, 'target_state')
+        result = {}
+        for state, items in items__by_state.items():
+            result[state] = len(items)
+        result['data'] = items__by_state
+        return result
+
+
+    def target_id(self, target: GeneratorType) -> Union[Random_Guid, None]:                                # Method to get the ID of a specific generator
+        with self.lock:                                                                                    # Acquire the lock for thread-safe access
+            for generator in list(self.generators.values()):                                               # Iterate over the generator targets
+                if generator.target == target:                                                             # Check if the target matches
+                    return generator.target_id                                                             # Return the matching target's ID

osbot_utils/helpers/generators/Model__Generator_State.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+class Model__Generator_State(Enum):                                         # Enum representing possible states of a generator
+    CREATED   : str = "created"                                             # Initial state when the generator is created
+    RUNNING   : str = "running"                                             # State when the generator is actively running
+    STOPPING  : str = "stopping"                                            # State when the generator is in the process of stopping
+    STOPPED   : str = "stopped"                                             # State when the generator is fully stopped
+    COMPLETED : str = "completed"                                           # State when the generator has completed its execution
+    ERROR     : str = "error"                                               # State when the generator encounters an error
+

osbot_utils/helpers/generators/Model__Generator_Target.py

@@ -0,0 +1,10 @@
+from types                                                  import GeneratorType
+from osbot_utils.base_classes.Type_Safe                     import Type_Safe
+from osbot_utils.helpers.Random_Guid                        import Random_Guid
+from osbot_utils.helpers.generators.Model__Generator_State  import Model__Generator_State
+
+
+class Model__Generator_Target(Type_Safe):                                   # Class representing a generator target and its metadata
+    target_id : Random_Guid                                                 # Unique ID for the generator target
+    target    : GeneratorType          = None                               # The generator instance being managed
+    state     : Model__Generator_State = Model__Generator_State.CREATED     # Current state of the generator (default is CREATED)

osbot_utils/version

@@ -1 +1 @@
-v1.80.0
+v1.82.0

{osbot_utils-1.80.0.dist-info → osbot_utils-1.82.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: osbot_utils
-Version: 1.80.0
+Version: 1.82.0
 Summary: OWASP Security Bot - Utils
 Home-page: https://github.com/owasp-sbot/OSBot-Utils
 License: MIT
@@ -23,7 +23,7 @@ Description-Content-Type: text/markdown
 
 Powerful Python util methods and classes that simplify common apis and tasks.
 
-![Current Release](https://img.shields.io/badge/release-v1.80.0-blue)
+![Current Release](https://img.shields.io/badge/release-v1.82.0-blue)
 [![codecov](https://codecov.io/gh/owasp-sbot/OSBot-Utils/graph/badge.svg?token=GNVW0COX1N)](https://codecov.io/gh/owasp-sbot/OSBot-Utils)
 
 

{osbot_utils-1.80.0.dist-info → osbot_utils-1.82.0.dist-info}/RECORD

@@ -2,7 +2,7 @@ osbot_utils/__init__.py,sha256=DdJDmQc9zbQUlPVyTJOww6Ixrn9n4bD3ami5ItQfzJI,16
 osbot_utils/base_classes/Cache_Pickle.py,sha256=kPCwrgUbf_dEdxUz7vW1GuvIPwlNXxuRhb-H3AbSpII,5884
 osbot_utils/base_classes/Kwargs_To_Disk.py,sha256=HHoy05NC_w35WcT-OnSKoSIV_cLqaU9rdjH0_KNTM0E,1096
 osbot_utils/base_classes/Kwargs_To_Self.py,sha256=weFNsBfBNV9W_qBkN-IdBD4yYcJV_zgTxBRO-ZlcPS4,141
-osbot_utils/base_classes/Type_Safe.py,sha256=lAWsPoNGoLIrzjJ5xIHP_rlpTmeTP0eXbvnBKGEB1s0,22335
+osbot_utils/base_classes/Type_Safe.py,sha256=ozt5ydM6iHKX-Xkj_h3CJQ0QhUFf91xEWkUL3vANBLU,22454
 osbot_utils/base_classes/Type_Safe__List.py,sha256=iWyoc2xjHkTJrZTVnPse9Rljte2tF67oNq8yA7jnAhY,5996
 osbot_utils/base_classes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 osbot_utils/context_managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -169,6 +169,11 @@ osbot_utils/helpers/flows/models/Flow_Run__Event.py,sha256=-F_H_Tq119qa9tk8IoX5U
 osbot_utils/helpers/flows/models/Flow_Run__Event_Data.py,sha256=Xvv_vtOL-siSdt5nkRCLA7uHxlsA3bTm7ZD_EOkCVAU,405
 osbot_utils/helpers/flows/models/Flow_Run__Event_Type.py,sha256=-iHKNQ-Ar2UfiCraFYQNHdBQ9fNcTTRoh3kRpXRS_Gc,375
 osbot_utils/helpers/flows/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+osbot_utils/helpers/generators/Generator_Context_Manager.py,sha256=STpCn2Zh5G2TmyYMjeLMjfpkSYUUeU6mzV_O6Hu4g4Q,863
+osbot_utils/helpers/generators/Generator_Manager.py,sha256=eQzyZVxZjglzPmoxLJ7ib1pD8187YcKBIr7mljpSUF4,11731
+osbot_utils/helpers/generators/Model__Generator_State.py,sha256=cS9tigdBIAvexip2VC8B0meegslzlu-cOosTDiEpe54,903
+osbot_utils/helpers/generators/Model__Generator_Target.py,sha256=JKa_PEQeVNZDSMBAobADaor4zXAhM_XWPHrQ2NMApZs,819
+osbot_utils/helpers/generators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 osbot_utils/helpers/html/Dict_To_Css.py,sha256=u6B4Mx7PXr-gDrTrs1hgknnvsZVK4Fic5LqedKjo-lk,1097
 osbot_utils/helpers/html/Dict_To_Html.py,sha256=OlRSaDGOeseBNTxRB2ho5whqEacMXeAXWOfeVSEYqC4,3355
 osbot_utils/helpers/html/Dict_To_Tags.py,sha256=L8O8c0RPzP92EfeACk3pjXJfnlz-Rg38o2Gf9tS2UfM,3745
@@ -306,8 +311,8 @@ osbot_utils/utils/Toml.py,sha256=-_Yv5T8ZhGGoDSSoNEdFhSsXiK_JPjGkPijm4JoeHSk,166
 osbot_utils/utils/Version.py,sha256=Ww6ChwTxqp1QAcxOnztkTicShlcx6fbNsWX5xausHrg,422
 osbot_utils/utils/Zip.py,sha256=pR6sKliUY0KZXmqNzKY2frfW-YVQEVbLKiyqQX_lc-8,14052
 osbot_utils/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-osbot_utils/version,sha256=kZW8YcxtUgv8JJ5SMq_RAgJKr-SRwTryyrVMJjtd39o,8
-osbot_utils-1.80.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-osbot_utils-1.80.0.dist-info/METADATA,sha256=GIgAeq1697iuS-tNNl4zTwOz4xA3-GzE2cX__pZc0fg,1317
-osbot_utils-1.80.0.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-osbot_utils-1.80.0.dist-info/RECORD,,
+osbot_utils/version,sha256=e35OcH4nQ1oWf1FG09fvfF_3Ok_im-bbOEnUGv2vOi0,8
+osbot_utils-1.82.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+osbot_utils-1.82.0.dist-info/METADATA,sha256=xKqrIfMr1ibNv8sycCvTDPeSYEHhChKdpwk-ioqvzFs,1317
+osbot_utils-1.82.0.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+osbot_utils-1.82.0.dist-info/RECORD,,