osbot-utils 2.11.0__py3-none-any.whl → 2.13.0__py3-none-any.whl

osbot_utils/context_managers/capture_duration.py

@@ -1,26 +1,33 @@
+import time
+
 from osbot_utils.type_safe.Type_Safe import Type_Safe
-from osbot_utils.utils.Misc          import timestamp_utc_now
 
 
 class capture_duration(Type_Safe):
-    action_name     : str
-    duration        : float
-    start_timestamp : int
-    end_timestamp   : int
-    seconds         : float
+    action_name : str
+    duration    : float
+    start_time  : float
+    end_time    : float
+    seconds     : float
+    precision   : int = 3                                       # Default rounding to 3 decimal places
+
 
     def __enter__(self):
-        self.start_timestamp = timestamp_utc_now()
+        self.start_time = time.perf_counter()                   # Start the performance counter
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
-        self.end_timestamp  = timestamp_utc_now()
-        self.duration       = self.end_timestamp - self.start_timestamp
-        self.seconds        = round(self.duration / 1000, 3)                # Duration in seconds (rounded to the 3 digits)
-        return False                                                        # ensures that any exceptions that happened are rethrown
+        self.end_time = time.perf_counter()                     # End the performance counter
+        self.duration = self.end_time - self.start_time
+        self.seconds = round(self.duration, self.precision)     # Use configurable precision
+        return False                                            # Ensures that exceptions are rethrown
 
     def data(self):
-        return dict(start = self.start_timestamp, end = self.end_timestamp, seconds = self.seconds)
+        return {
+            "start": self.start_time,
+            "end": self.end_time,
+            "seconds": self.seconds,
+        }
 
     def print(self):
         print()

osbot_utils/helpers/CPrint.py

@@ -1,4 +1,3 @@
-from osbot_utils.base_classes.Kwargs_To_Self import Kwargs_To_Self
 from osbot_utils.helpers.CFormat import CFormat, CFormat_Colors
 
 

osbot_utils/helpers/Obj_Id.py

@@ -0,0 +1,29 @@
+import random
+
+_hex_table = [f"{i:02x}" for i in range(256)]
+
+def is_obj_id(value: str):
+    var_type = type(value)
+    if var_type is Obj_Id:
+        return True
+    if var_type is str:
+        if len(value) == 8:         # todo: add efficient check if we only have hex values
+            return True
+    return False
+
+def new_obj_id():
+    return hex(random.getrandbits(32))[2:].zfill(8)  # slice off '0x' and pad
+
+class Obj_Id(str):
+    def __new__(cls, value: str=None):
+        if value:
+            if is_obj_id(value):
+                obj_id = value
+            else:
+                raise ValueError(f'in Obj_Id: value provided was not a valid Obj_Id: {value}')
+        else:
+            obj_id = new_obj_id()
+        return super().__new__(cls, obj_id)                                          # Return a new instance of Guid initialized with the string version of the UUID
+
+    def __str__(self):
+        return self

osbot_utils/helpers/trace/Trace_Call.py

@@ -1,8 +1,7 @@
 import linecache
 import sys
 import threading
-from functools import wraps
-
+from functools                                              import wraps
 from osbot_utils.base_classes.Kwargs_To_Self                import Kwargs_To_Self
 from osbot_utils.helpers.trace.Trace_Call__Config           import Trace_Call__Config, PRINT_MAX_STRING_LENGTH
 from osbot_utils.helpers.trace.Trace_Call__Handler          import Trace_Call__Handler

osbot_utils/helpers/trace/Trace_Call__Handler.py

@@ -8,29 +8,29 @@ from osbot_utils.helpers.trace.Trace_Call__Stack_Node   import Trace_Call__Stack
 from osbot_utils.helpers.trace.Trace_Call__Stats        import Trace_Call__Stats
 
 DEFAULT_ROOT_NODE_NODE_TITLE = 'Trace Session'
-GLOBAL_FUNCTIONS_TO_IGNORE   = ['value_type_matches_obj_annotation_for_attr'                ,            # these are type safety functions which introduce quite a lot of noise in the traces (and unless one is debugging type safety, they will not be needed)
-                                'value_type_matches_obj_annotation_for_union_and_annotated' ,            # todo: map out and document why exactly these methods are ignore (and what is the side effect)
-                                'are_types_compatible_for_assigment'                        ,
-                                'obj_attribute_annotation'                                  ,
-                                'all_annotations'                                           ,
-                                'get_origin'                                                ,
-                                'getmro'                                                    ,
-                                'default_value'                                             ,
-                                'raise_exception_on_obj_type_annotation_mismatch'           ,
-                                '__cls_kwargs__'                                            ,
-                                '__default__value__'                                        ,
-                                '__setattr__'                                               ,
-                                '<module>']
+# GLOBAL_FUNCTIONS_TO_IGNORE   = ['value_type_matches_obj_annotation_for_attr'                ,            # these are type safety functions which introduce quite a lot of noise in the traces (and unless one is debugging type safety, they will not be needed)
+#                                 'value_type_matches_obj_annotation_for_union_and_annotated' ,            # todo: map out and document why exactly these methods are ignore (and what is the side effect)
+#                                 'are_types_compatible_for_assigment'                        ,
+#                                 'obj_attribute_annotation'                                  ,
+#                                 'all_annotations'                                           ,
+#                                 'get_origin'                                                ,
+#                                 'getmro'                                                    ,
+#                                 'default_value'                                             ,
+#                                 '__cls_kwargs__'                                            ,
+#                                 '__default__value__'                                        ,
+#                                 '__setattr__'                                               ,
+#                                 '<module>']
 GLOBAL_MODULES_TO_IGNORE     = ['osbot_utils.helpers.trace.Trace_Call'                      ,            # todo: map out and document why exactly these modules are ignore (and what is the side effect)
                                 'osbot_utils.helpers.trace.Trace_Call__Config'              ,
                                 'osbot_utils.helpers.trace.Trace_Call__View_Model'          ,
                                 'osbot_utils.helpers.trace.Trace_Call__Print_Traces'        ,
                                 'osbot_utils.helpers.trace.Trace_Call__Stack'               ,
-                                'osbot_utils.base_classes.Type_Safe'                        ,
+                               # 'osbot_utils.base_classes.Type_Safe'                        ,
                                 'osbot_utils.helpers.CPrint'                                ,            #       also see if this should be done here or at the print/view stage
                                 'osbot_utils.helpers.Print_Table'                           ,
                                 'osbot_utils.decorators.methods.cache_on_self'              ,
                                 'codecs'                                                    ]
+GLOBAL_FUNCTIONS_TO_IGNORE = []
 
 #GLOBAL_MODULES_TO_IGNORE = []
 #GLOBAL_FUNCTIONS_TO_IGNORE = []

osbot_utils/helpers/xml/Xml__File.py

@@ -1,5 +1,5 @@
 from typing                                 import Dict
-from osbot_utils.type_safe.Type_Safe     import Type_Safe
+from osbot_utils.type_safe.Type_Safe        import Type_Safe
 from osbot_utils.helpers.xml.Xml__Element   import XML__Element
 
 class Xml__File(Type_Safe):

osbot_utils/helpers/xml/Xml__File__To_Dict.py

@@ -1,5 +1,5 @@
 from typing                                 import Dict, Any
-from osbot_utils.type_safe.Type_Safe     import Type_Safe
+from osbot_utils.type_safe.Type_Safe        import Type_Safe
 from osbot_utils.helpers.xml.Xml__Element   import XML__Element
 from osbot_utils.helpers.xml.Xml__File      import Xml__File
 

osbot_utils/helpers/xml/Xml__File__To_Xml.py

@@ -1,7 +1,7 @@
 from typing                                 import Optional
 from xml.etree.ElementTree                  import Element, SubElement, tostring
 from xml.dom                                import minidom
-from osbot_utils.type_safe.Type_Safe     import Type_Safe
+from osbot_utils.type_safe.Type_Safe        import Type_Safe
 from osbot_utils.helpers.xml.Xml__Element   import XML__Element
 from osbot_utils.helpers.xml.Xml__File      import Xml__File
 

osbot_utils/testing/performance/Performance_Measure__Session.py

@@ -0,0 +1,128 @@
+import time
+from typing                                                                         import Callable, List
+from statistics                                                                     import mean, median, stdev
+from osbot_utils.utils.Env                                                          import in_github_action
+from osbot_utils.testing.performance.models.Model__Performance_Measure__Measurement import Model__Performance_Measure__Measurement
+from osbot_utils.testing.performance.models.Model__Performance_Measure__Result      import Model__Performance_Measure__Result
+from osbot_utils.type_safe.Type_Safe                                                import Type_Safe
+
+MEASURE__INVOCATION__LOOPS = [1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610]            # Fibonacci sequence for measurement loops
+
+class Performance_Measure__Session(Type_Safe):
+    result        : Model__Performance_Measure__Result = None                                          # Current measurement result
+    assert_enabled: bool = True
+    padding       : int  = 30
+
+    def calculate_raw_score(self, times: List[int]) -> int:                                     # Calculate raw performance score
+        if len(times) < 3:                                                                      # Need at least 3 values for stability
+            return mean(times)
+
+        sorted_times = sorted(times)                                                            # Sort times for analysis
+        trim_size    = max(1, len(times) // 10)                                                 # Remove ~10% from each end
+
+        trimmed      = sorted_times[trim_size:-trim_size]                                       # Remove outliers
+        med          = median(trimmed)                                                          # Get median of trimmed data
+        trimmed_mean = mean  (trimmed)                                                          # Get mean of trimmed data
+
+        raw_score = int(med * 0.6 + trimmed_mean * 0.4)                                         # Weighted combination favoring median
+        return raw_score
+
+    def calculate_stable_score(self, raw_score: float) -> int:                                  # Calculate stable performance score
+        if raw_score < 1_000:                                                                   # Dynamic normalization based on score magnitude
+            return int(round(raw_score / 100) * 100)                                            # Under 1µs: nearest 100ns
+        elif raw_score < 10_000:
+            return int(round(raw_score / 1000) * 1000)                                          # Under 10µs: nearest 500ns
+        elif raw_score < 100_000:
+            return int(round(raw_score / 10000) * 10000)                                        # Under 100µs: nearest 1000ns
+        else:
+            return int(round(raw_score / 100000) * 100000)                                        # Above 100µs: nearest 5000ns
+
+    def calculate_metrics(self, times: List[int]) -> Model__Performance_Measure__Measurement:   # Calculate statistical metrics
+        if not times:
+            raise ValueError("Cannot calculate metrics from empty time list")
+        raw_score = self.calculate_raw_score   (times)
+        score     = self.calculate_stable_score(raw_score)
+        return Model__Performance_Measure__Measurement(
+            avg_time    = int(mean(times))                                                  ,
+            min_time    = min(times)                                        ,
+            max_time    = max(times)                                        ,
+            median_time = int(median(times))                                ,
+            stddev_time = stdev(times) if len(times) > 1 else 0             ,
+            raw_times   = times                                             ,
+            sample_size = len(times)                                        ,
+            raw_score   = raw_score                                         ,
+            score       = score                                             )
+
+    def measure(self, target: Callable) -> 'Performance_Measure__Session':               # Perform measurements
+        name         = target.__name__
+        measurements = {}
+        all_times    = []                                                                    # Collect all times for final score
+
+        for loop_size in MEASURE__INVOCATION__LOOPS:                                        # Measure each loop size
+            loop_times = []
+            for i in range(loop_size):
+                start = time.perf_counter_ns()
+                target()
+                end   = time.perf_counter_ns()
+                time_taken = end - start
+                loop_times.append(time_taken)
+                all_times.append(time_taken)                                                 # Add to overall collection
+
+            measurements[loop_size] = self.calculate_metrics(loop_times)                     # Store metrics for this loop size
+
+        raw_score    = self.calculate_raw_score  (all_times)
+        final_score = self.calculate_stable_score(raw_score)                                # Calculate final stable score
+
+        self.result = Model__Performance_Measure__Result(
+            measurements = measurements                                                      ,
+            name        = name                                                              ,
+            raw_score   = raw_score                                                         ,
+            final_score = final_score                                                       )
+
+        return self
+
+    def print_measurement(self, measurement: Model__Performance_Measure__Measurement):       # Format measurement details
+        print(f"Samples : {measurement.sample_size}")
+        print(f"Score   : {measurement.score:,.0f}ns")
+        print(f"Avg     : {measurement.avg_time:,}ns")
+        print(f"Min     : {measurement.min_time:,}ns")
+        print(f"Max     : {measurement.max_time:,}ns")
+        print(f"Median  : {measurement.median_time:,}ns")
+        print(f"StdDev  : {measurement.stddev_time:,.2f}ns")
+
+    def print(self):                                                # Print measurement results
+        if not self.result:
+            print("No measurements taken yet")
+            return
+        print(f"{self.result.name:{self.padding}} | score: {self.result.final_score:7,d} ns  | raw: {self.result.raw_score:7,d} ns")          # Print name and normalized score
+
+        return self
+
+    def assert_time(self, *expected_time: int):                                              # Assert that the final score matches the expected normalized time"""
+        if self.assert_enabled is False:
+            return
+        if in_github_action():
+            last_expected_time = expected_time[-1] + 100                                    # +100 in case it is 0
+            new_expected_time   = last_expected_time * 5                                    # using last_expected_time * 5 as the upper limit (since these tests are significantly slowed in GitHUb Actions)
+            assert last_expected_time <=  self.result.final_score <= new_expected_time, f"Performance changed for {self.result.name}: expected {last_expected_time} < {self.result.final_score:,d}ns, expected {new_expected_time}"
+        else:
+            assert self.result.final_score in expected_time,  f"Performance changed for {self.result.name}: got {self.result.final_score:,d}ns, expected {expected_time}"
+
+    def assert_time(self, *expected_time: int):                                              # Assert that the final score matches the expected normalized time"""
+        if self.assert_enabled is False:
+            return
+        if in_github_action():
+            last_expected_time = expected_time[-1] + 100                                    # +100 in case it is 0
+            new_expected_time   = last_expected_time * 5                                    # using last_expected_time * 5 as the upper limit (since these tests are significantly slowed in GitHUb Actions)
+            assert last_expected_time <=  self.result.final_score <= new_expected_time, f"Performance changed for {self.result.name}: expected {last_expected_time} < {self.result.final_score:,d}ns, expected {new_expected_time}"
+        else:
+            assert self.result.final_score in expected_time,  f"Performance changed for {self.result.name}: got {self.result.final_score:,d}ns, expected {expected_time}"
+
+    def assert_time__less_than(self, max_time: int):                                              # Assert that the final score matches the expected normalized time"""
+        if self.assert_enabled is False:
+            return
+        if in_github_action():
+            max_time   = max_time * 5               # adjust for GitHub's slowness
+
+        assert self.result.final_score <= max_time,  f"Performance changed for {self.result.name}: got {self.result.final_score:,d}ns, expected less than {max_time}ns"
+

osbot_utils/testing/performance/models/Model__Performance_Measure__Measurement.py

@@ -0,0 +1,14 @@
+from typing                             import List
+from osbot_utils.type_safe.Type_Safe    import Type_Safe
+
+
+class Model__Performance_Measure__Measurement(Type_Safe):                                     # Pure data container for measurement metrics
+    avg_time     : int                                                                       # Average time in nanoseconds
+    min_time     : int                                                                       # Minimum time observed
+    max_time     : int                                                                       # Maximum time observed
+    median_time  : int                                                                       # Median time
+    stddev_time  : float                                                                     # Standard deviation
+    raw_times    : List[int]                                                                 # Raw measurements for analysis
+    sample_size  : int                                                                       # Number of measurements taken
+    score        : float
+    raw_score    : float

osbot_utils/testing/performance/models/Model__Performance_Measure__Result.py

@@ -0,0 +1,10 @@
+from typing                                                                         import Dict
+from osbot_utils.testing.performance.models.Model__Performance_Measure__Measurement import Model__Performance_Measure__Measurement
+from osbot_utils.type_safe.Type_Safe                                                import Type_Safe
+
+class Model__Performance_Measure__Result(Type_Safe):                                         # Pure data container for measurement results
+    measurements : Dict[int, Model__Performance_Measure__Measurement]                        # Results per loop size
+    name         : str                                                                       # Name of measured target
+    raw_score    : float
+    final_score  : float
+