osbot-utils 1.44.0__tar.gz → 1.45.0__tar.gz

{osbot_utils-1.44.0 → osbot_utils-1.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: osbot_utils
-Version: 1.44.0
+Version: 1.45.0
 Summary: OWASP Security Bot - Utils
 Home-page: https://github.com/owasp-sbot/OSBot-Utils
 License: MIT
@@ -22,7 +22,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.44.0-blue)
+![Current Release](https://img.shields.io/badge/release-v1.45.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.44.0 → osbot_utils-1.45.0}/README.md

@@ -2,7 +2,7 @@
 
 Powerful Python util methods and classes that simplify common apis and tasks.
 
-![Current Release](https://img.shields.io/badge/release-v1.44.0-blue)
+![Current Release](https://img.shields.io/badge/release-v1.45.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.44.0 → osbot_utils-1.45.0}/osbot_utils/base_classes/Type_Safe.py

@@ -10,17 +10,17 @@ from decimal                                    import Decimal
 from enum                                       import Enum, EnumMeta
 from typing                                     import List
 from osbot_utils.base_classes.Type_Safe__List   import Type_Safe__List
-from osbot_utils.helpers.Random_Guid import Random_Guid
+from osbot_utils.helpers.Random_Guid            import Random_Guid
 from osbot_utils.utils.Dev                      import pprint
 from osbot_utils.utils.Json                     import json_parse
 from osbot_utils.utils.Misc                     import list_set
-from osbot_utils.utils.Objects import default_value, value_type_matches_obj_annotation_for_attr, \
+from osbot_utils.utils.Objects                  import default_value, value_type_matches_obj_annotation_for_attr, \
     raise_exception_on_obj_type_annotation_mismatch, obj_is_attribute_annotation_of_type, enum_from_value, \
     obj_is_type_union_compatible, value_type_matches_obj_annotation_for_union_attr, \
     convert_dict_to_value_from_obj_annotation
 
 # Backport implementations of get_origin and get_args for Python 3.7
-if sys.version_info < (3, 8):
+if sys.version_info < (3, 8):                                           # pragma: no cover
     def get_origin(tp):
         if isinstance(tp, typing._GenericAlias):
             return tp.__origin__
@@ -39,7 +39,7 @@ else:
 
 if sys.version_info >= (3, 10):
     NoneType = types.NoneType
-else:
+else:                                                           # pragma: no cover
     NoneType = type(None)
 
 immutable_types = (bool, int, float, complex, str, tuple, frozenset, bytes, NoneType, EnumMeta)

{osbot_utils-1.44.0 → osbot_utils-1.45.0}/osbot_utils/context_managers/capture_duration.py

@@ -27,11 +27,4 @@ class capture_duration(Type_Safe):
         if self.action_name:
             print(f'action "{self.action_name}" took: {self.seconds} seconds')
         else:
-            print(f'action took: {self.seconds} seconds')
-
-class print_duration(capture_duration):
-
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        result = super().__exit__(exc_type, exc_val, exc_tb)
-        self.print()
-        return result
+            print(f'action took: {self.seconds} seconds')

{osbot_utils-1.44.0 → osbot_utils-1.45.0}/osbot_utils/context_managers/disable_root_loggers.py

@@ -1,9 +1,5 @@
 import logging
 
-from osbot_utils.utils.Dev import pprint
-from osbot_utils.utils.Misc import timestamp_utc_now
-
-
 class disable_root_loggers():
     def __init__(self):
         self.original_root_loggers  = []

osbot_utils-1.45.0/osbot_utils/context_managers/print_duration.py

@@ -0,0 +1,9 @@
+from osbot_utils.context_managers.capture_duration import capture_duration
+
+
+class print_duration(capture_duration):
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        result = super().__exit__(exc_type, exc_val, exc_tb)
+        self.print()
+        return result

{osbot_utils-1.44.0 → osbot_utils-1.45.0}/osbot_utils/decorators/lists/filter_list.py

@@ -3,9 +3,9 @@ from functools import wraps
 def filter_list(function):
     @wraps(function)
     def wrapper(*args, **kwargs):
-        only_show = kwargs.pop('only_show', None)                   # Directly extract and remove 'only_show' from kwargs if present
-        values    = function(*args, **kwargs)                       # Call the decorated function
-        if only_show:                                               # Filter the list of dictionaries to only include specified keys
+        only_show = kwargs.pop('only_show', None)                                               # Directly extract and remove 'only_show' from kwargs if present
+        values    = function(*args, **kwargs)                                                   # Call the decorated function
+        if only_show:                                                                           # Filter the list of dictionaries to only include specified keys
             return [{key: item[key] for key in only_show if key in item} for item in values]
         return values
 

{osbot_utils-1.44.0 → osbot_utils-1.45.0}/osbot_utils/decorators/methods/capture_exception.py

@@ -1,6 +1,6 @@
 import traceback
-from functools import wraps
-from osbot_utils.utils.Dev import pprint
+from functools              import wraps
+from osbot_utils.utils.Dev  import pprint
 
 def capture_exception(func):
     @wraps(func)

osbot_utils-1.45.0/osbot_utils/helpers/Dependency_Manager.py

@@ -0,0 +1,26 @@
+import inspect
+
+
+class Dependency_Manager:
+    def __init__(self):
+        self._dependencies = {}
+
+    def add_dependency(self, name: str, instance):                                          # Register a dependency by name.
+        self._dependencies[name] = instance
+
+    def get_dependency(self, name: str):                                                    # Retrieve a dependency by name.
+        return self._dependencies.get(name, None)
+
+    def resolve_dependencies(self, func, *args, **kwargs):                                  # Automatically inject dependencies based on function's parameters.
+        sig             = inspect.signature(func)                                           # Get the function's signature and parameters
+        bound_arguments = sig.bind_partial(*args, **kwargs)
+
+
+        for param_name, param in sig.parameters.items():                                    # Check parameters to see if we need to inject a dependency
+            if param_name not in bound_arguments.arguments:
+                if param_name in self._dependencies:                                        # Inject dependency if available
+                    bound_arguments.arguments[param_name] = self._dependencies[param_name]
+
+        return bound_arguments.args, bound_arguments.kwargs
+
+dependency_manager = Dependency_Manager()

{osbot_utils-1.44.0 → osbot_utils-1.45.0}/osbot_utils/helpers/flows/Flow.py

@@ -1,9 +1,9 @@
 import logging
 import typing
-from functools import wraps
 
 from osbot_utils.base_classes.Type_Safe import Type_Safe
-from osbot_utils.helpers.CFormat import CFormat, f_dark_grey, f_magenta
+from osbot_utils.helpers.CFormat import CFormat, f_dark_grey, f_magenta, f_bold
+from osbot_utils.helpers.flows.Flow__Config import Flow__Config
 from osbot_utils.testing.Stdout         import Stdout
 from osbot_utils.utils.Misc             import random_id, lower
 from osbot_utils.utils.Python_Logger    import Python_Logger
@@ -14,40 +14,32 @@ FLOW__RANDOM_NAME__PREFIX  = 'flow_name__'
 FLOW__LOGGING__LOG_FORMAT  = '%(asctime)s.%(msecs)03d | %(levelname)-8s | %(message)s'
 FLOW__LOGGING__DATE_FORMAT = '%H:%M:%S'
 
-def flow(**flow_kwargs):
-
-    def decorator(function):
-        @wraps(function)
-        def wrapper(*args, **kwargs):
-            with Flow(**flow_kwargs) as flow:
-                flow.set_flow_target(function)
-                flow.setup()
-                flow.create_flow()
-                flow.execute_flow(*args, **kwargs)
-                return flow.return_value
-
-        return wrapper
-    return decorator
 
 
 class Flow(Type_Safe):
     captured_exec_logs : list
+    data               : dict                   # dict available to the tasks to add and collect data
     flow_id            : str
     flow_name          : str
+    flow_config        : Flow__Config
     flow_target        : callable
+    flow_args          : tuple
+    flow_kwargs        : dict
+    flow_return_value  : typing.Any
     logger             : Python_Logger
     cformat            : CFormat
-    log_to_console     : bool    = False
-    log_to_memory      : bool    = True
-    print_logs         : bool    = False
-    return_value       : typing.Any
+    #log_to_console     : bool    = False
+    #log_to_memory      : bool    = True
+    #print_logs         : bool    = False
+    executed_tasks     : typing.List
+
 
 
     def config_logger(self):
         with self.logger as _:
             _.set_log_level(logging.DEBUG)
             _.set_log_format(log_format=FLOW__LOGGING__LOG_FORMAT, date_format=FLOW__LOGGING__DATE_FORMAT)
-            if self.log_to_console:
+            if self.flow_config.log_to_console:
                 _.add_console_logger()
 
 
@@ -58,23 +50,28 @@ class Flow(Type_Safe):
         self.set_flow_name()
         self.debug(f"Created flow run '{self.f__flow_id()}' for flow '{self.f__flow_name()}'")
 
-    def execute_flow(self, *args, **kwargs):
-        if self.log_to_memory:
+    def execute(self):
+        return self.execute_flow()
+
+    def execute_flow(self):
+        if self.flow_config.log_to_memory:
             self.logger.add_memory_logger()                                     # todo: move to method that does pre-execute tasks
 
         self.debug(f"Executing flow run '{self.f__flow_id()}''")
         try:
             with Stdout() as stdout:
-                self.return_value = self.flow_target(*args, **kwargs)           # todo, capture *args, **kwargs in logs
+                self.flow_return_value = self.flow_target(*self.flow_args, **self.flow_kwargs)           # todo, capture *args, **kwargs in logs
         except Exception as error:
             self.logger.error(self.cformat.red(f"Error executing flow: {error}"))
-        self.log_captured_stdout(stdout)
-        self.debug(f"{f_dark_grey('return value')}: {self.return_value}")
-        self.debug(f"Finished flow run '{self.f__flow_id()}''")
 
-        if self.log_to_memory:
+        self.log_captured_stdout        (stdout)
+        self.print_flow_return_value    ()
+        self.print_flow_finished_message()
+
+        if self.flow_config.log_to_memory:
             self.captured_exec_logs = self.log_messages_with_colors()
-            self.logger.remove_memory_logger()                                  # todo: move to method that does post-execute tasks
+            self.logger.remove_memory_logger()                                                          # todo: move to method that does post-execute tasks
+        return self
 
     def f__flow_id(self):
         return self.cformat.green(self.flow_id)
@@ -82,6 +79,9 @@ class Flow(Type_Safe):
     def f__flow_name(self):
         return self.cformat.blue(self.flow_name)
 
+    def captured_logs(self):
+        return ansis_to_texts(self.captured_exec_logs)
+
     def info(self, message):
         self.logger.info(message)
 
@@ -89,7 +89,7 @@ class Flow(Type_Safe):
         for line in stdout.value().splitlines():
             if line:
                 self.info(f_magenta(line))
-        if self.print_logs:
+        if self.flow_config.print_logs:
             print()
             print()
             self.print_log_messages()
@@ -103,12 +103,28 @@ class Flow(Type_Safe):
 
     def print_log_messages(self, use_colors=True):
         if use_colors:
-            for message in self.logger.memory_handler_messages():
-                print(message)
+            if self.captured_exec_logs:
+                for message in self.captured_exec_logs:
+                    print(message)
+            else:
+                for message in self.logger.memory_handler_messages():
+                    print(message)
         else:
             for message in self.log_messages():
                 print(message)
         return self
+
+    def print_flow_finished_message(self):
+        if self.flow_config.print_finished_message:
+            self.debug(f"Finished flow run '{self.f__flow_id()}''")
+
+    def print_flow_return_value(self):
+        if self.flow_config.print_none_return_value is False and self.flow_return_value is None:
+            return
+        self.debug(f"{f_dark_grey('Flow return value')}: {f_bold(self.flow_return_value)}")
+
+
+
     def random_flow_id(self):
         return lower(random_id(prefix=FLOW__RANDOM_ID__PREFIX))
 
@@ -116,8 +132,10 @@ class Flow(Type_Safe):
         return lower(random_id(prefix=FLOW__RANDOM_NAME__PREFIX))
 
 
-    def set_flow_target(self, target):
+    def set_flow_target(self, target, *args, **kwargs):
         self.flow_target = target
+        self.flow_args   = args
+        self.flow_kwargs = kwargs
         return self
 
     def set_flow_name(self, value=None):

osbot_utils-1.45.0/osbot_utils/helpers/flows/Flow__Config.py

@@ -0,0 +1,11 @@
+from osbot_utils.base_classes.Type_Safe import Type_Safe
+
+
+class Flow__Config(Type_Safe):
+    add_task_to_self       : bool = True
+    log_to_console         : bool = False
+    log_to_memory          : bool = True
+    print_logs             : bool = False
+    print_none_return_value: bool = False
+    print_finished_message : bool = False
+

osbot_utils-1.45.0/osbot_utils/helpers/flows/Task.py

@@ -0,0 +1,83 @@
+import inspect
+import typing
+
+from osbot_utils.helpers.Dependency_Manager import Dependency_Manager
+from osbot_utils.utils.Dev import pprint
+
+from osbot_utils.testing.Stdout             import Stdout
+from osbot_utils.helpers.CFormat            import CFormat, f_dark_grey, f_red, f_blue, f_bold
+from osbot_utils.base_classes.Type_Safe     import Type_Safe
+from osbot_utils.helpers.flows.Flow         import Flow
+
+
+
+class Task(Type_Safe):
+    data                : dict                          # dict available to the task to add and collect data
+    task_id             : str                           # todo add a random Id value to this
+    task_name           : str                           # make this the function mame
+    cformat             : CFormat
+    task_target         : callable                      # todo refactor this to to Task__Function class
+    task_args           : tuple
+    task_kwargs         : dict
+    task_flow           : Flow
+    task_return_value   : typing.Any
+    task_error          : Exception  = None
+    raise_on_error      : bool       = True
+
+    def execute(self):
+        self.task_flow = self.find_flow()
+        if self.task_flow is None:
+            raise Exception("No Flow found for Task")
+
+        if not self.task_name and self.task_target:
+            self.task_name = self.task_target.__name__
+
+        self.task_flow.executed_tasks.append(self)
+        self.task_flow.logger.debug(f"Executing task '{f_blue(self.task_name)}'")
+
+        try:
+            with Stdout() as stdout:
+                self.invoke_task_target()
+        except Exception as error:
+            self.task_error = error
+
+        self.task_flow.log_captured_stdout(stdout)
+        self.print_task_return_value()
+
+        if self.task_error:
+            self.task_flow.logger.error(f_red(f"Error executing '{self.task_name}' task: {self.task_error}"))
+            if self.raise_on_error:
+                raise Exception(f"'{self.task_name}' failed and task raise_on_error was set to True. Stopping flow execution")
+
+        self.print_task_finished_message()
+        return self.task_return_value
+
+    def invoke_task_target(self):
+        dependency_manager = Dependency_Manager()
+        dependency_manager.add_dependency('this_task', self               )
+        dependency_manager.add_dependency('this_flow', self.task_flow     )
+        dependency_manager.add_dependency('task_data', self.data          )
+        dependency_manager.add_dependency('flow_data', self.task_flow.data)
+        resolved_args, resolved_kwargs = dependency_manager.resolve_dependencies(self.task_target, *self.task_args, **self.task_kwargs)
+        self.task_return_value =  self.task_target(*resolved_args, **resolved_kwargs)
+
+    def find_flow(self):
+        stack = inspect.stack()
+        for frame_info in stack:
+            frame = frame_info.frame
+            if 'self' in frame.f_locals:
+                instance = frame.f_locals['self']
+                if type(instance) is Flow:
+                    return instance
+
+    def print_task_finished_message(self):
+        if self.task_flow.flow_config.print_finished_message:
+            self.task_flow.logger.debug(f"Finished task '{f_blue(self.task_name)}'")
+
+    def print_task_return_value(self):
+        flow_config = self.task_flow.flow_config
+        if flow_config.print_none_return_value is False and self.task_return_value is None:
+            return
+        self.task_flow.logger.debug(f"{f_dark_grey('Task return value')}: {f_bold(self.task_return_value)}")
+
+

osbot_utils-1.45.0/osbot_utils/helpers/flows/decorators/flow.py

@@ -0,0 +1,18 @@
+from functools                      import wraps
+from typing import TypeVar, Callable, Any
+
+from osbot_utils.helpers.flows.Flow import Flow
+
+# todo: find way to make the casting below work for the users of this decorator
+
+def flow(**flow_kwargs):
+    def decorator(function) -> Flow:
+        @wraps(function)
+        def wrapper(*args: Any, **kwargs: Any) -> Flow:
+            with Flow(**flow_kwargs) as _:
+                _.set_flow_target(function, *args, **kwargs)
+                _.setup()
+                _.create_flow()
+                return _
+        return wrapper
+    return decorator

osbot_utils-1.45.0/osbot_utils/helpers/flows/decorators/task.py

@@ -0,0 +1,11 @@
+from functools                      import wraps
+from osbot_utils.helpers.flows.Task import Task
+
+def task(**task_kwargs):
+    def decorator(function):
+        @wraps(function)
+        def wrapper(*args, **kwargs):
+            with Task(task_target=function, task_args=args, task_kwargs=kwargs, **task_kwargs) as _:
+                return _.execute()
+        return wrapper
+    return decorator

{osbot_utils-1.44.0 → osbot_utils-1.45.0}/osbot_utils/helpers/html/Dict_To_Tags.py

@@ -1,10 +1,9 @@
 from osbot_utils.helpers.html.Dict_To_Html import HTML_SELF_CLOSING_TAGS
-from osbot_utils.helpers.html.Tag__Base import Tag__Base
-from osbot_utils.helpers.html.Tag__Body import Tag__Body
-from osbot_utils.helpers.html.Tag__Head import Tag__Head
-from osbot_utils.helpers.html.Tag__Html import Tag__Html
-from osbot_utils.helpers.html.Tag__Link import Tag__Link
-from osbot_utils.utils.Dev import pprint
+from osbot_utils.helpers.html.Tag__Base     import Tag__Base
+from osbot_utils.helpers.html.Tag__Body     import Tag__Body
+from osbot_utils.helpers.html.Tag__Head     import Tag__Head
+from osbot_utils.helpers.html.Tag__Html     import Tag__Html
+from osbot_utils.helpers.html.Tag__Link     import Tag__Link
 
 
 class Dict_To_Tags:

{osbot_utils-1.44.0 → osbot_utils-1.45.0}/osbot_utils/utils/Call_Stack.py

@@ -185,3 +185,6 @@ def call_stack_frames_data(depth=None):
 def frames_in_threads():
     return sys._current_frames()
 
+
+def print_call_stack():
+    traceback.print_stack()

{osbot_utils-1.44.0 → osbot_utils-1.45.0}/osbot_utils/utils/Zip.py

@@ -6,6 +6,8 @@ import tarfile
 import zipfile
 from os.path import abspath
 
+from osbot_utils.utils.Misc import list_set
+
 from osbot_utils.utils.Files import temp_folder, folder_files, temp_file, is_file, file_copy, file_move, file_exists, \
     file_contents_as_bytes
 
@@ -99,6 +101,9 @@ def zip_bytes__files(zip_bytes):
 
     return files_dict                                       # Return the dictionary with file contents
 
+def zip_bytes__files_paths(zip_bytes):
+    return list_set(zip_bytes__files(zip_bytes))
+
 def zip_bytes__file_list(zip_bytes):
     zip_buffer_from_bytes = io.BytesIO(zip_bytes)
     with zipfile.ZipFile(zip_buffer_from_bytes, 'r') as zf:

osbot_utils-1.45.0/osbot_utils/version

@@ -0,0 +1 @@
+v1.45.0

{osbot_utils-1.44.0 → osbot_utils-1.45.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name        = "osbot_utils"
-version     = "v1.44.0"
+version     = "v1.45.0"
 description = "OWASP Security Bot - Utils"
 authors     = ["Dinis Cruz <dinis.cruz@owasp.org>"]
 license     = "MIT"

osbot_utils-1.44.0/osbot_utils/helpers/flows/Task.py

@@ -1,18 +0,0 @@
-import inspect
-
-from osbot_utils.base_classes.Type_Safe import Type_Safe
-from osbot_utils.helpers.flows.Flow import Flow
-
-
-class Task(Type_Safe):
-    task_id       : str
-    task_name     : str
-
-    def find_flow(self):
-        stack = inspect.stack()
-        for frame_info in stack:
-            frame = frame_info.frame
-            if 'self' in frame.f_locals:
-                instance = frame.f_locals['self']
-                if type(instance) is Flow:
-                    return instance

osbot_utils-1.44.0/osbot_utils/version

@@ -1 +0,0 @@
-v1.44.0