osbot-utils 1.89.0__tar.gz → 1.91.0__tar.gz

{osbot_utils-1.89.0 → osbot_utils-1.91.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: osbot_utils
-Version: 1.89.0
+Version: 1.91.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.89.0-blue)
+![Current Release](https://img.shields.io/badge/release-v1.91.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.89.0 → osbot_utils-1.91.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.89.0-blue)
+![Current Release](https://img.shields.io/badge/release-v1.91.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.89.0 → osbot_utils-1.91.0}/osbot_utils/base_classes/Type_Safe.py

@@ -3,7 +3,7 @@
 
 import sys
 import types
-from osbot_utils.utils.Objects                  import default_value         # todo: remove test mocking requirement for this to be here (instead of on the respective method)
+from osbot_utils.utils.Objects                          import default_value         # todo: remove test mocking requirement for this to be here (instead of on the respective method)
 
 # Backport implementations of get_origin and get_args for Python 3.7
 if sys.version_info < (3, 8):                                           # pragma: no cover
@@ -24,6 +24,7 @@ if sys.version_info < (3, 8):                                           # pragma
             return ()
 else:
     from typing import get_origin, get_args, ForwardRef
+    from osbot_utils.helpers.python_compatibility.python_3_8 import Annotated
 
 if sys.version_info >= (3, 10):
     NoneType = types.NoneType
@@ -44,7 +45,6 @@ class Type_Safe:
 
         for (key, value) in self.__cls_kwargs__().items():                  # assign all default values to self
             if value is not None:                                           # when the value is explicitly set to None on the class static vars, we can't check for type safety
-
                 raise_exception_on_obj_type_annotation_mismatch(self, key, value)
             if hasattr(self, key):
                 existing_value = getattr(self, key)
@@ -65,10 +65,11 @@ class Type_Safe:
     def __exit__(self, exc_type, exc_val, exc_tb): pass
 
     def __setattr__(self, name, value):
-        from osbot_utils.utils.Objects import convert_dict_to_value_from_obj_annotation
-        from osbot_utils.utils.Objects import convert_to_value_from_obj_annotation
-        from osbot_utils.utils.Objects import value_type_matches_obj_annotation_for_attr
-        from osbot_utils.utils.Objects import value_type_matches_obj_annotation_for_union_attr
+        from osbot_utils.utils.Objects                          import convert_dict_to_value_from_obj_annotation
+        from osbot_utils.utils.Objects                          import convert_to_value_from_obj_annotation
+        from osbot_utils.utils.Objects                          import value_type_matches_obj_annotation_for_attr
+        from osbot_utils.utils.Objects                          import value_type_matches_obj_annotation_for_union_and_annotated
+        from osbot_utils.helpers.type_safe.Type_Safe__Validator import Type_Safe__Validator
 
         if not hasattr(self, '__annotations__'):                    # can't do type safety checks if the class does not have annotations
             return super().__setattr__(name, value)
@@ -79,7 +80,7 @@ class Type_Safe:
             if type(value) in [int, str]:                                                   # for now only a small number of str and int classes are supported (until we understand the full implications of this)
                 value = convert_to_value_from_obj_annotation (self, name, value)
             check_1 = value_type_matches_obj_annotation_for_attr      (self, name, value)
-            check_2 = value_type_matches_obj_annotation_for_union_attr(self, name, value)
+            check_2 = value_type_matches_obj_annotation_for_union_and_annotated(self, name, value)
             if (check_1 is False and check_2 is None  or
                 check_1 is None  and check_2 is False or
                 check_1 is False and check_2 is False   ):          # fix for type safety assigment on Union vars
@@ -89,6 +90,16 @@ class Type_Safe:
                 if getattr(self, name) is not None:                         # unless it is already set to None
                     raise ValueError(f"Can't set None, to a variable that is already set. Invalid type for attribute '{name}'. Expected '{self.__annotations__.get(name)}' but got '{type(value)}'")
 
+        # todo: refactor this to separate method
+        if hasattr(self.__annotations__, 'get'):
+            annotation = self.__annotations__.get(name)
+            if annotation and get_origin(annotation) is Annotated:
+                annotation_args = get_args(annotation)
+                target_type = annotation_args[0]
+                for attribute in annotation_args[1:]:
+                    if isinstance(attribute, Type_Safe__Validator):
+                        attribute.validate(value=value, field_name=name, target_type=target_type)
+
         super().__setattr__(name, value)
 
     def __attr_names__(self):
@@ -131,6 +142,8 @@ class Type_Safe:
                     else:
                         var_value = getattr(base_cls, var_name)
                         if var_value is not None:                                                                   # allow None assignments on ctor since that is a valid use case
+                            if get_origin(var_type) is Annotated:
+                                continue
                             if var_type and not isinstance(var_value, var_type):                                    # check type
                                 exception_message = f"variable '{var_name}' is defined as type '{var_type}' but has value '{var_value}' of type '{type(var_value)}'"
                                 raise ValueError(exception_message)

{osbot_utils-1.89.0 → osbot_utils-1.91.0}/osbot_utils/graphs/mermaid/Mermaid.py

@@ -1,10 +1,10 @@
-from osbot_utils.graphs.mermaid.Mermaid__Renderer   import Mermaid__Renderer
-from osbot_utils.graphs.mermaid.Mermaid__Edge       import Mermaid__Edge
-from osbot_utils.graphs.mermaid.Mermaid__Graph      import Mermaid__Graph
-from osbot_utils.graphs.mermaid.models.Mermaid__Diagram_Direction import Diagram__Direction
-from osbot_utils.graphs.mermaid.models.Mermaid__Diagram__Type import Diagram__Type
-from osbot_utils.utils.Python_Logger            import Python_Logger
-from osbot_utils.base_classes.Kwargs_To_Self    import Kwargs_To_Self
+from osbot_utils.graphs.mermaid.Mermaid__Renderer                   import Mermaid__Renderer
+from osbot_utils.graphs.mermaid.Mermaid__Edge                       import Mermaid__Edge
+from osbot_utils.graphs.mermaid.Mermaid__Graph                      import Mermaid__Graph
+from osbot_utils.graphs.mermaid.models.Mermaid__Diagram_Direction   import Diagram__Direction
+from osbot_utils.graphs.mermaid.models.Mermaid__Diagram__Type       import Diagram__Type
+from osbot_utils.utils.Python_Logger                                import Python_Logger
+from osbot_utils.base_classes.Kwargs_To_Self                        import Kwargs_To_Self
 
 class Mermaid(Kwargs_To_Self):
     graph             : Mermaid__Graph

{osbot_utils-1.89.0 → osbot_utils-1.91.0}/osbot_utils/helpers/Zip_Bytes.py

@@ -2,10 +2,10 @@ from osbot_utils.base_classes.Type_Safe     import Type_Safe
 from osbot_utils.utils.Dev                  import pprint
 from osbot_utils.utils.Files                import files_list, file_create_from_bytes, temp_file, parent_folder, parent_folder_create
 from osbot_utils.utils.Misc                 import random_text
-from osbot_utils.utils.Regex                import list__match_regex, list__match_regexes
+from osbot_utils.utils.Regex                import list__match_regexes
 from osbot_utils.utils.Zip                  import zip_bytes_empty, zip_bytes__files, zip_bytes__add_file, zip_bytes__add_files, \
     zip_bytes__replace_files, zip_bytes__replace_file, zip_bytes__file_list, zip_bytes__file, \
-    zip_bytes__add_file__from_disk, zip_bytes__add_files__from_disk, zip_files, zip_file__files, zip_bytes__remove_files
+    zip_bytes__add_file__from_disk, zip_bytes__add_files__from_disk, zip_file__files, zip_bytes__remove_files
 
 
 class Zip_Bytes(Type_Safe):

osbot_utils-1.91.0/osbot_utils/helpers/python_compatibility/python_3_8.py

@@ -0,0 +1,8 @@
+import sys
+
+if sys.version_info < (3, 9):
+    class Annotated:
+        def __init__(self, *args) -> None:
+            pass
+else:
+    from typing import Annotated

{osbot_utils-1.89.0 → osbot_utils-1.91.0}/osbot_utils/helpers/trace/Trace_Call__Handler.py

@@ -8,28 +8,28 @@ 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_attr' ,            # 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'                         ,
-                                'get_origin'                                       ,
-                                'getmro'                                           ,
-                                'default_value'                                    ,
-                                'raise_exception_on_obj_type_annotation_mismatch'  ,
-                                '__cls_kwargs__'        ,
-                                '__default__value__'    ,
-                                '__setattr__'           ,
+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'                                  ,
+                                'get_origin'                                                ,
+                                'getmro'                                                    ,
+                                'default_value'                                             ,
+                                'raise_exception_on_obj_type_annotation_mismatch'           ,
+                                '__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.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_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.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_MODULES_TO_IGNORE = []
 #GLOBAL_FUNCTIONS_TO_IGNORE = []

osbot_utils-1.91.0/osbot_utils/helpers/type_safe/Type_Safe__Validator.py

@@ -0,0 +1,14 @@
+from osbot_utils.helpers.python_compatibility.python_3_8 import Annotated
+from typing                                              import Any
+
+class Type_Safe__Validator:                                                                 # Base class for all Type_Safe validators.
+
+    def validate(self, value: Any, field_name: str, target_type: type) -> None:                                # Validate a value against this validator's rules.
+        if value and type(value) != target_type:
+            raise ValueError(f"{field_name} must be of type {target_type}, got {type(value)}")
+
+    def describe(self) -> str:                                                              # Return a human-readable description of this validator's rules.
+        pass
+
+
+Validate = Annotated

osbot_utils-1.91.0/osbot_utils/helpers/type_safe/validators/Validator__Max.py

@@ -0,0 +1,28 @@
+from typing                                             import Any
+from osbot_utils.helpers.type_safe.Type_Safe__Validator import Type_Safe__Validator
+
+
+class Validator__Max(Type_Safe__Validator):                             #    Validates that a numeric value is at most the specified maximum."""
+    max_value: float
+
+    def __init__(self, max_value):
+        self.max_value = max_value
+
+    def validate(self, value: Any, field_name: str, target_type: type) -> None:
+        super().validate(value=value, field_name=field_name, target_type=target_type)
+        if value is None:
+            return
+        compare_value = value if isinstance(value, (int, float)) else len(value)
+        if compare_value > self.max_value:
+            if not isinstance(value, (int, float)):
+                msg = f"{field_name} must be at most {self.max_value}, got {compare_value}"
+            elif isinstance(value, (list, tuple)):
+                msg = f"{field_name} must be at most {self.max_value}, got length {compare_value}"
+            else:
+                msg = f"{field_name} must be at most {self.max_value}, got size {compare_value}"
+            raise ValueError(msg)
+
+    def describe(self) -> str:
+        return f"maximum value: {self.max_value}"
+
+Max = Validator__Max

osbot_utils-1.91.0/osbot_utils/helpers/type_safe/validators/Validator__Min.py

@@ -0,0 +1,38 @@
+from typing                                             import Any
+from osbot_utils.helpers.type_safe.Type_Safe__Validator import Type_Safe__Validator
+
+class Validator__Min(Type_Safe__Validator):                     # Validates that a value is at least the specified minimum. Works with any type that supports the < operator (numbers, strings, lists, etc.)
+    min_value: Any
+
+    def __init__(self, min_value):
+        super().__init__()
+        self.min_value = min_value
+
+    def validate(self, value: Any, field_name: str, target_type: type) -> None:
+        super().validate(value=value, field_name=field_name, target_type=target_type)
+        if value is None:                                                               # can't compare if value has been set to None
+            return
+
+        try:
+            compare_value = value if isinstance(value, (int, float)) else len(value)
+
+            if compare_value < self.min_value:
+                if isinstance(value, (int, float)):
+                    msg = f"{field_name} must be at least {self.min_value}, got {compare_value}"
+                elif isinstance(value, str):
+                    msg = f"{field_name} must have length at least {self.min_value}, got length {compare_value}"
+                elif isinstance(value, (list, tuple)):
+                    msg = f"{field_name} must have length at least {self.min_value}, got length {compare_value}"
+                else:
+                    msg = f"{field_name} must have size at least {self.min_value}, got size {compare_value}"
+                raise ValueError(msg)
+        except TypeError:
+            raise ValueError(f"Cannot compare {field_name} of type {type(value)} with minimum value of type {type(self.min_value)}")
+
+    def describe(self) -> str:
+        if isinstance(self.min_value, (int, float)):
+            return f"minimum value: {self.min_value}"
+        else:
+            return f"minimum length: {len(self.min_value)}"
+
+Min = Validator__Min

osbot_utils-1.91.0/osbot_utils/helpers/type_safe/validators/Validator__One_Of.py

@@ -0,0 +1,18 @@
+from typing                                             import Any
+from osbot_utils.helpers.type_safe.Type_Safe__Validator import Type_Safe__Validator
+
+
+class Validator__One_Of(Type_Safe__Validator):                  # Validates that a value is one of a set of allowed values."""
+    allowed: list
+
+    def __init__(self, allowed):
+        self.allowed = allowed
+
+    def validate(self, value: Any, field_name: str, target_type:type) -> None:
+        if value not in self.allowed:
+            raise ValueError(f"{field_name} must be one of {self.allowed}, got {value}")
+
+    def describe(self) -> str:
+        return f"must be one of: {self.allowed}"
+
+One_Of = Validator__One_Of

osbot_utils-1.91.0/osbot_utils/helpers/type_safe/validators/Validator__Regex.py

@@ -0,0 +1,26 @@
+from typing                                             import Any
+from osbot_utils.helpers.type_safe.Type_Safe__Validator import Type_Safe__Validator
+
+class Validator__Regex(Type_Safe__Validator):            # Validates that a string matches the specified regex pattern.
+    pattern    : str
+    description: str
+
+    def __init__(self, pattern, description=None):
+        self.pattern     = pattern
+        self.description = description
+
+    def validate(self, value: Any, field_name: str, target_type:type) -> None:
+        import re
+        if value is None:
+            return
+        if not isinstance(value, str):
+            raise ValueError(f"{field_name} must be a string, got {type(value)}")
+        if not re.match(self.pattern, value):
+            raise ValueError(f"{field_name} must match pattern {self.pattern}")
+
+    def describe(self) -> str:
+        if self.description:
+            return self.description
+        return f"must match pattern: {self.pattern}"
+
+Regex = Validator__Regex

osbot_utils-1.91.0/osbot_utils/helpers/xml/Xml__Attribute.py

@@ -0,0 +1,7 @@
+from osbot_utils.base_classes.Type_Safe import Type_Safe
+
+
+class Xml__Attribute(Type_Safe):
+    name     : str
+    value    : str
+    namespace: str

osbot_utils-1.91.0/osbot_utils/helpers/xml/Xml__Element.py

@@ -0,0 +1,15 @@
+from typing                                 import Dict, List, Union
+from osbot_utils.base_classes.Type_Safe     import Type_Safe
+from osbot_utils.helpers.xml.Xml__Attribute import Xml__Attribute
+
+class XML__Element(Type_Safe):
+    tag             : str                                   # Element's local name
+    namespace       : str                                   # Element's namespace URI
+    namespace_prefix: str                                   # Element's namespace prefix
+    attributes      : Dict[str, Xml__Attribute]             # Element attributes
+    children        : List[Union[str, 'XML__Element']]      # Child elements/text
+
+    # def qualified_name(self) -> str:                        # Get fully qualified name with prefix
+    #     if self.namespace_prefix:
+    #         return f"{self.namespace_prefix}:{self.tag}"
+    #     return self.tag

osbot_utils-1.91.0/osbot_utils/helpers/xml/Xml__File.py

@@ -0,0 +1,9 @@
+from typing                                 import Dict
+from osbot_utils.base_classes.Type_Safe     import Type_Safe
+from osbot_utils.helpers.xml.Xml__Element   import XML__Element
+
+class Xml__File(Type_Safe):
+    xml_data    : str                           # Raw XML content
+    root_element: XML__Element                  # Parsed root element
+    namespaces  : Dict[str, str]                # XML namespace mappings
+

osbot_utils-1.91.0/osbot_utils/helpers/xml/Xml__File__Load.py

@@ -0,0 +1,88 @@
+from io                                     import StringIO
+from typing                                 import List, Union, Dict
+from xml.etree.ElementTree                  import iterparse, Element, fromstring, ParseError
+from osbot_utils.base_classes.Type_Safe     import Type_Safe
+from osbot_utils.helpers.xml.Xml__Attribute import Xml__Attribute
+from osbot_utils.helpers.xml.Xml__Element   import XML__Element
+from osbot_utils.helpers.xml.Xml__File      import Xml__File
+
+
+class Xml__File__Load(Type_Safe):
+
+    def load_from_string(self, xml_data: str) -> Xml__File:    # Create Xml__File from string
+        xml_file = Xml__File(xml_data=xml_data)
+        self.load_namespaces(xml_file)
+        self.parse_xml      (xml_file)
+        return xml_file
+
+    def load_namespaces(self, xml_file: Xml__File):           # Extract namespaces from XML
+        if not xml_file.xml_data:
+            raise ValueError("XML data cannot be empty")
+
+        for event, elem in iterparse(StringIO(xml_file.xml_data), events=("start-ns",)):
+            prefix, uri = elem
+            xml_file.namespaces[prefix] = uri
+
+    def parse_xml(self, xml_file: Xml__File):                 # Parse XML into type-safe structure
+        if not xml_file.xml_data:
+            raise ValueError("XML data cannot be empty")
+
+        try:
+            root       = fromstring(xml_file.xml_data)
+            namespaces = xml_file.namespaces
+            xml_file.root_element = self.convert_element(namespaces,root)
+        except ParseError as error:
+            raise ValueError(f"Invalid XML: {str(error)}")
+
+    def convert_element(self, namespaces: Dict[str,str], element: Element) -> XML__Element:
+        attributes = self.convert_attributes(element)
+        children: List[Union[str, XML__Element]] = []
+
+        tag             = element.tag
+        namespace        = ''
+        namespace_prefix = ''
+
+        if '}' in tag:
+            namespace, tag = tag.split('}', 1)          # Split namespace and tag
+            namespace = namespace[1:]                   # Remove the '{' prefix
+
+            for prefix, uri in namespaces.items(): # Find prefix for this namespace
+                if uri == namespace:
+                    namespace_prefix = prefix
+                    break
+
+        # Handle text content
+        if element.text and element.text.strip():
+            children.append(element.text.strip())
+
+        # Process child elements
+        for child in element:
+            child_element = self.convert_element(namespaces, child)
+            children.append(child_element)
+
+            if child.tail and child.tail.strip():
+                children.append(child.tail.strip())
+
+        return XML__Element(tag=tag,
+                          namespace=namespace,
+                          namespace_prefix=namespace_prefix,
+                          attributes=attributes,
+                          children=children)
+
+    def convert_attributes(self, element: Element) -> Dict[str, Xml__Attribute]:    # Convert element attributes
+        attributes = {}
+        for key, value in element.attrib.items():
+            if '}' in key:                                        # Handle namespaced attributes
+                namespace, name = key.split('}', 1)
+                namespace = namespace[1:]                         # Remove the '{' prefix
+            else:
+                namespace = ''
+                name = key
+
+            attribute = Xml__Attribute(
+                name=name,
+                value=value,
+                namespace=namespace
+            )
+            attributes[key] = attribute
+        return attributes

osbot_utils-1.91.0/osbot_utils/helpers/xml/Xml__File__To_Dict.py

@@ -0,0 +1,41 @@
+from typing                                 import Dict, Any
+from osbot_utils.base_classes.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
+
+
+class Xml__File__To_Dict(Type_Safe):
+    def to_dict(self, xml_file: Xml__File) -> Dict[str, Any]:   # Convert Xml__File to dictionary
+        if not xml_file.root_element:
+            return {}
+        return self.element_to_dict(xml_file.root_element)
+
+    def element_to_dict(self, element: XML__Element) -> Dict[str, Any]:         # Convert XML__Element to dictionary
+        result = {}
+
+        for key, attr in element.attributes.items():                            # Convert attributes first
+            result[key] = attr.value
+
+
+        child_nodes: Dict[str, Any] = {}                                        # Process children and collect text content
+        text_content = []
+        for child in element.children:
+            if isinstance(child, str):
+                text_content.append(child)
+            else:
+                if child.tag in child_nodes:                     # Handle child elements
+                    if not isinstance(child_nodes[child.tag], list):
+                        child_nodes[child.tag] = [child_nodes[child.tag]]
+                    child_nodes[child.tag].append(self.element_to_dict(child))
+                else:
+                    child_nodes[child.tag] = self.element_to_dict(child)
+
+        if text_content:                                        # Handle text content
+            text_value = ' '.join(text_content)
+            if child_nodes or result:                           # If we have attributes or child nodes
+                result['#text'] = text_value                    # Add text as a special key
+            else:
+                return text_value                               # Return just the text if no attributes/children
+
+        result.update(child_nodes)                             # Merge child nodes into result
+        return result

osbot_utils-1.91.0/osbot_utils/helpers/xml/Xml__File__To_Xml.py

@@ -0,0 +1,72 @@
+from typing                                 import Optional
+from xml.etree.ElementTree                  import Element, SubElement, tostring
+from xml.dom                                import minidom
+from osbot_utils.base_classes.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
+
+class Xml__File__To_Xml(Type_Safe):
+
+    def convert_to_xml(self, xml_file: Xml__File, pretty_print: bool = True) -> str:
+        if not xml_file.root_element:
+            raise ValueError("XML file must have a root element")
+
+        # Create XML element tree
+        root = self.create_element(xml_file.root_element, xml_file.namespaces)
+
+        # Add all namespace declarations to root element
+        for prefix, uri in xml_file.namespaces.items():
+            if prefix == '':
+                root.set('xmlns', uri)
+            else:
+                root.set(f'xmlns:{prefix}', uri)
+
+        # Convert to string
+        xml_string = tostring(root, encoding='unicode', method='xml')
+
+        # Pretty print if requested
+        if pretty_print:
+            return self.pretty_print(xml_string)
+        return xml_string
+
+    def create_element(self, xml_element: XML__Element, namespaces: Optional[dict] = None, parent: Optional[Element] = None) -> Element:
+        # Create tag with namespace if applicable
+        tag = xml_element.tag
+        if xml_element.namespace_prefix:
+            tag = f"{xml_element.namespace_prefix}:{tag}"
+        # Don't add namespace URI for default namespace - let it be inherited
+
+        # Create new element or sub-element
+        if parent is not None:
+            element = SubElement(parent, tag)
+        else:
+            element = Element(tag)
+
+        # Add attributes including namespace declarations
+        for attr_key, attr in xml_element.attributes.items():
+            if attr.namespace:
+                attr_name = f"{{{attr.namespace}}}{attr.name}"
+            else:
+                attr_name = attr.name
+            element.set(attr_name, attr.value)
+
+        # Process children
+        text_parts = []
+        for child in xml_element.children:
+            if isinstance(child, str):
+                text_parts.append(child)
+            elif isinstance(child, XML__Element):
+                self.create_element(child, namespaces, element)
+
+        # Set text content if any
+        if text_parts:
+            element.text = ''.join(text_parts)
+
+        return element
+
+    def pretty_print(self, xml_string: str) -> str:
+        """Format XML string with proper indentation."""
+        parsed = minidom.parseString(xml_string)
+        pretty_xml = parsed.toprettyxml(indent='  ').rstrip() + '\n'
+        # Remove empty lines (common issue with toprettyxml)
+        return '\n'.join(line for line in pretty_xml.split('\n') if line.strip())

osbot_utils-1.91.0/osbot_utils/helpers/xml/rss/RSS__Channel.py

@@ -0,0 +1,17 @@
+from typing                                     import Any, Dict, List
+from osbot_utils.base_classes.Type_Safe         import Type_Safe
+from osbot_utils.helpers.xml.rss.RSS__Image     import RSS__Image
+from osbot_utils.helpers.xml.rss.RSS__Item      import RSS__Item
+
+
+class RSS__Channel(Type_Safe):
+    description     : str
+    extensions      : Dict[str, Any]
+    image           : RSS__Image         = None
+    items           : List[RSS__Item]
+    language        : str
+    last_build_date : str
+    link            : str
+    title           : str
+    update_frequency: str
+    update_period   : str

osbot_utils-1.91.0/osbot_utils/helpers/xml/rss/RSS__Enclosure.py

@@ -0,0 +1,7 @@
+from osbot_utils.base_classes.Type_Safe import Type_Safe
+
+
+class RSS__Enclosure(Type_Safe):
+    url    : str
+    type   : str
+    length : int

osbot_utils-1.91.0/osbot_utils/helpers/xml/rss/RSS__Feed.py

@@ -0,0 +1,11 @@
+from typing                                     import Dict, Any
+from osbot_utils.base_classes.Type_Safe         import Type_Safe
+from osbot_utils.helpers.xml.rss.RSS__Channel   import RSS__Channel
+
+DEFAULT__RSS_FEED__VERSION = "2.0"
+
+class RSS__Feed(Type_Safe):
+    version    : str           = DEFAULT__RSS_FEED__VERSION
+    channel    : RSS__Channel  = None
+    namespaces : Dict[str, str]
+    extensions : Dict[str, Any]