osbot-utils 2.72.0__py3-none-any.whl → 2.74.0__py3-none-any.whl

osbot_utils/type_safe/{steps → type_safe_core/steps}/Type_Safe__Step__Class_Kwargs.py

@@ -1,10 +1,11 @@
-from typing                                                      import Dict, Any, Type
-from osbot_utils.helpers.Obj_Id                                  import Obj_Id
-from osbot_utils.helpers.Random_Guid                             import Random_Guid
-from osbot_utils.type_safe.shared.Type_Safe__Cache               import Type_Safe__Cache, type_safe_cache
-from osbot_utils.type_safe.shared.Type_Safe__Shared__Variables   import IMMUTABLE_TYPES
-from osbot_utils.type_safe.shared.Type_Safe__Validation          import type_safe_validation
-from osbot_utils.type_safe.steps.Type_Safe__Step__Default_Value  import type_safe_step_default_value
+from typing                                                                     import Dict, Any, Type
+from osbot_utils.helpers.Obj_Id                                                 import Obj_Id
+from osbot_utils.type_safe.primitives.safe_str.identifiers.Random_Guid          import Random_Guid
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Cache               import type_safe_cache, Type_Safe__Cache
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Shared__Variables   import IMMUTABLE_TYPES
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Validation          import type_safe_validation
+from osbot_utils.type_safe.type_safe_core.steps.Type_Safe__Step__Default_Value  import type_safe_step_default_value
+
 
 class Type_Safe__Step__Class_Kwargs:                                                     # Handles class-level keyword arguments processing
 

osbot_utils/type_safe/{steps → type_safe_core/steps}/Type_Safe__Step__Default_Value.py

@@ -1,12 +1,12 @@
 import sys
 import inspect
 import typing
-from osbot_utils.type_safe.Type_Safe__Set           import Type_Safe__Set
-from osbot_utils.type_safe.Type_Safe__Tuple         import Type_Safe__Tuple
-from osbot_utils.type_safe.shared.Type_Safe__Cache  import type_safe_cache
-from osbot_utils.utils.Objects                      import default_value
-from osbot_utils.type_safe.Type_Safe__List          import Type_Safe__List
-from osbot_utils.type_safe.Type_Safe__Dict          import Type_Safe__Dict
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__Dict   import Type_Safe__Dict
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__List   import Type_Safe__List
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__Set    import Type_Safe__Set
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__Tuple  import Type_Safe__Tuple
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Cache       import type_safe_cache
+from osbot_utils.utils.Objects                                          import default_value
 
 
 # Backport implementations of get_args for Python 3.7        # todo: refactor into separate class (focused on past python version compatibility)

osbot_utils/type_safe/{steps → type_safe_core/steps}/Type_Safe__Step__From_Json.py

@@ -1,20 +1,21 @@
 import sys
 import types
-from decimal                                             import Decimal
-from enum                                                import EnumMeta
-from osbot_utils.helpers.Obj_Id                          import Obj_Id
-from osbot_utils.helpers.safe_str.Safe_Str__Hash         import Safe_Str__Hash
-from osbot_utils.type_safe.Type_Safe                     import Type_Safe
-from osbot_utils.type_safe.Type_Safe__List               import Type_Safe__List
-from osbot_utils.helpers.Random_Guid                     import Random_Guid
-from osbot_utils.helpers.Random_Guid_Short               import Random_Guid_Short
-from osbot_utils.type_safe.Type_Safe__Set                import Type_Safe__Set
-from osbot_utils.type_safe.shared.Type_Safe__Annotations import type_safe_annotations
-from osbot_utils.type_safe.shared.Type_Safe__Cache       import type_safe_cache
-from osbot_utils.type_safe.shared.Type_Safe__Convert     import type_safe_convert
-from osbot_utils.utils.Objects                           import enum_from_value
-from osbot_utils.helpers.Safe_Id                         import Safe_Id
-from osbot_utils.helpers.Timestamp_Now                   import Timestamp_Now
+from decimal                                                                      import Decimal
+from enum                                                                         import EnumMeta
+from osbot_utils.helpers.Obj_Id                                                   import Obj_Id
+from osbot_utils.type_safe.Type_Safe                                              import Type_Safe
+from osbot_utils.type_safe.primitives.safe_str.identifiers.Random_Guid            import Random_Guid
+from osbot_utils.type_safe.primitives.safe_str.identifiers.Random_Guid_Short                                        import Random_Guid_Short
+from osbot_utils.type_safe.primitives.safe_str.cryptography.hashes.Safe_Str__Hash import Safe_Str__Hash
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__Dict             import Type_Safe__Dict
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__List             import Type_Safe__List
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__Set              import Type_Safe__Set
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Annotations           import type_safe_annotations
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Cache                 import type_safe_cache
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Convert               import type_safe_convert
+from osbot_utils.utils.Objects                                                    import enum_from_value
+from osbot_utils.type_safe.primitives.safe_str.identifiers.Safe_Id                import Safe_Id
+from osbot_utils.type_safe.primitives.safe_int.Timestamp_Now                       import Timestamp_Now
 
 # todo; refactor all this python compatibility into the python_3_8 class
 if sys.version_info < (3, 8):                                           # pragma: no cover
@@ -148,8 +149,6 @@ class Type_Safe__Step__From_Json:
         return value
 
     def deserialize_dict__using_key_value_annotations(self, _self, key, value):
-        from osbot_utils.type_safe.Type_Safe__Dict import Type_Safe__Dict
-
         annotations            = type_safe_cache.get_obj_annotations(_self)
         dict_annotations_tuple = get_args(annotations.get(key))
         if not dict_annotations_tuple:                                      # happens when the value is a dict/Dict with no annotations

osbot_utils/type_safe/{steps → type_safe_core/steps}/Type_Safe__Step__Init.py

@@ -1,7 +1,12 @@
 from enum                                                       import EnumMeta
 from typing                                                     import ForwardRef
-from osbot_utils.type_safe.shared.Type_Safe__Annotations        import type_safe_annotations
-from osbot_utils.type_safe.steps.Type_Safe__Step__Default_Value import type_safe_step_default_value, get_args
+
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__Dict import Type_Safe__Dict
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__List import Type_Safe__List
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__Set import Type_Safe__Set
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__Tuple import Type_Safe__Tuple
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Annotations import type_safe_annotations
+from osbot_utils.type_safe.type_safe_core.steps.Type_Safe__Step__Default_Value import type_safe_step_default_value, get_args
 
 
 class Type_Safe__Step__Init:
@@ -46,7 +51,6 @@ class Type_Safe__Step__Init:
                     value = type_safe_step_default_value.default_value(__self.__class__, annotation)        # Use default_value to create the proper type-safe container
                             # Handle non-empty list
                 elif origin is list and isinstance(value, list):
-                    from osbot_utils.type_safe.Type_Safe__List import Type_Safe__List
                     item_type = get_args(annotation)[0]
                     if isinstance(item_type, ForwardRef):
                         forward_name = item_type.__forward_arg__
@@ -59,7 +63,6 @@ class Type_Safe__Step__Init:
 
                 # Handle non-empty set
                 elif origin is set and isinstance(value, set):
-                    from osbot_utils.type_safe.Type_Safe__Set import Type_Safe__Set
                     item_type = get_args(annotation)[0]
                     type_safe_set = Type_Safe__Set(expected_type=item_type)
                     for item in value:
@@ -68,13 +71,11 @@ class Type_Safe__Step__Init:
 
                 # Handle non-empty tuple
                 elif origin is tuple and isinstance(value, tuple):
-                    from osbot_utils.type_safe.Type_Safe__Tuple import Type_Safe__Tuple
                     item_types = get_args(annotation)
                     return Type_Safe__Tuple(expected_types=item_types, items=value)
 
                 # Handle non-empty dict
                 elif origin is dict and isinstance(value, dict):
-                    from osbot_utils.type_safe.Type_Safe__Dict import Type_Safe__Dict
                     key_type, value_type = get_args(annotation)
                     type_safe_dict       = Type_Safe__Dict(expected_key_type=key_type, expected_value_type=value_type)
                     for k, v in value.items():

osbot_utils/type_safe/{steps → type_safe_core/steps}/Type_Safe__Step__Set_Attr.py

@@ -1,9 +1,9 @@
 from typing                                                  import get_origin, Annotated, get_args
-from osbot_utils.type_safe.Type_Safe__List                   import Type_Safe__List
 from osbot_utils.type_safe.Type_Safe__Primitive              import Type_Safe__Primitive
-from osbot_utils.type_safe.shared.Type_Safe__Cache           import type_safe_cache
-from osbot_utils.type_safe.shared.Type_Safe__Convert         import type_safe_convert
-from osbot_utils.type_safe.shared.Type_Safe__Validation      import type_safe_validation
+from osbot_utils.type_safe.type_safe_core.collections.Type_Safe__List import Type_Safe__List
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Cache import type_safe_cache
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Convert import type_safe_convert
+from osbot_utils.type_safe.type_safe_core.shared.Type_Safe__Validation import type_safe_validation
 from osbot_utils.type_safe.validators.Type_Safe__Validator   import Type_Safe__Validator
 
 class Type_Safe__Step__Set_Attr:
@@ -67,9 +67,9 @@ class Type_Safe__Step__Set_Attr:
                 attribute.validate(value=value, field_name=name, target_type=target_type)
 
     def handle_get_class__dict(self, _self, name, value):
-        if value:                                                                                                       # todo: see side effects of doing this here (since going into deserialize_dict__using_key_value_annotations has performance hit)
-            from osbot_utils.type_safe.steps.Type_Safe__Step__From_Json import Type_Safe__Step__From_Json               # here because of circular dependencies
-            value = Type_Safe__Step__From_Json().deserialize_dict__using_key_value_annotations(_self, name, value)      # todo: refactor how this actually works since it is not good to having to use the deserialize_dict__using_key_value_annotations from here
+        if value:                                                                                                           # todo: see side effects of doing this here (since going into deserialize_dict__using_key_value_annotations has performance hit)
+            from osbot_utils.type_safe.type_safe_core.steps.Type_Safe__Step__From_Json import Type_Safe__Step__From_Json    # here because of circular dependencies
+            value = Type_Safe__Step__From_Json().deserialize_dict__using_key_value_annotations(_self, name, value)          # todo: refactor how this actually works since it is not good to having to use the deserialize_dict__using_key_value_annotations from here
         return value
 
     def handle_get_class(self, _self, annotations, name, value):

osbot_utils/utils/Files.py

@@ -1,7 +1,6 @@
 import os
-from typing import Union, List
-
-from osbot_utils.helpers.safe_str.Safe_Str__File__Path import Safe_Str__File__Path
+from typing                                                                    import Union, List
+from osbot_utils.type_safe.primitives.safe_str.filesystem.Safe_Str__File__Path import Safe_Str__File__Path
 
 
 class Files:

osbot_utils/version

@@ -1 +1 @@
-v2.72.0
+v2.74.0

osbot_utils-2.74.0.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.3
+Name: osbot_utils
+Version: 2.74.0
+Summary: OWASP Security Bot - Utils
+License: MIT
+Author: Dinis Cruz
+Author-email: dinis.cruz@owasp.org
+Requires-Python: >=3.7,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Project-URL: Homepage, https://github.com/owasp-sbot/OSBot-Utils
+Project-URL: Repository, https://github.com/owasp-sbot/OSBot-Utils
+Description-Content-Type: text/markdown
+
+# OSBot-Utils
+
+![Current Release](https://img.shields.io/badge/release-v2.74.0-blue)
+![Python](https://img.shields.io/badge/python-3.8+-green)
+![Type-Safe](https://img.shields.io/badge/Type--Safe-✓-brightgreen)
+![Caching](https://img.shields.io/badge/Caching-Built--In-orange)
+[![codecov](https://codecov.io/gh/owasp-sbot/OSBot-Utils/graph/badge.svg?token=GNVW0COX1N)](https://codecov.io/gh/owasp-sbot/OSBot-Utils)
+
+A comprehensive Python utility toolkit providing **Type-Safe primitives**, decorators, caching layers, HTML/AST helpers, SQLite tooling, SSH execution, LLM request pipelines, tracing, and more — all designed to accelerate building robust, maintainable automation and integration code.
+
+---
+
+## ✨ Key Features
+
+* **🛡️ Type-Safe First**: Strongly typed primitives (`Safe_Str`, `Safe_Int`, `Safe_Float`, etc.) with validation and sanitization
+* **⚡ Multi-layer Caching**: In-memory, per-instance, pickle-on-disk, temp-file, and request/response caches
+* **🗂️ Rich Utilities**: Helpers for HTML parsing/rendering, AST inspection, SSH/SCP execution, SQLite schema management, and more
+* **🧠 LLM Support**: Structured request builders, OpenAI API integration, schema enforcement, and persistent cache
+* **🔍 Tracing & Debugging**: Full function call tracing with configurable depth, locals capture, and pretty output
+* **🧪 Testing Utilities**: Temp SQLite DBs, mockable caches, and easy test helpers
+
+---
+
+## 📦 Installation
+
+```bash
+pip install osbot-utils
+```
+
+From source:
+
+```bash
+pip install git+https://github.com/owasp-sbot/OSBot-Utils.git@dev
+```
+
+---
+
+## 🚀 Quick Start
+
+### Using Type-Safe Primitives
+
+```python
+from osbot_utils.type_safe.primitives.safe_str.Safe_Str import Safe_Str
+
+class Username(Safe_Str):
+    max_length = 20
+
+print(Username("alice"))  # 'alice'
+print(Username("invalid username!"))  # 'invalid_username_'
+```
+
+---
+
+### Simple In-Memory Caching
+
+```python
+from osbot_utils.decorators.methods.cache_on_self import cache_on_self
+
+class DataFetcher:
+    @cache_on_self
+    def fetch(self, x):
+        print("Fetching…")
+        return x * 2
+
+fetcher = DataFetcher()
+fetcher.fetch(10)  # Calls method
+fetcher.fetch(10)  # Returns cached result
+```
+
+---
+
+### HTML Parsing
+
+```python
+from osbot_utils.helpers.html.Html__To__Html_Dict import html_to_dict
+
+html_code = "<html><body><h1>Hello</h1></body></html>"
+print(html_to_dict(html_code))
+```
+
+---
+
+### SQLite Dynamic Table
+
+```python
+from osbot_utils.helpers.sqlite.Temp_Sqlite__Table import Temp_Sqlite__Table
+
+with Temp_Sqlite__Table() as table:
+    table.row_schema = type("Row", (), {"name": str, "age": int})
+    table.create()
+    table.add_row_and_commit(name="Alice", age=30)
+    print(table.rows())
+```
+
+---
+
+### LLM Request Execution
+
+```python
+from osbot_utils.helpers.llms.builders.LLM_Request__Builder__Open_AI import LLM_Request__Builder__Open_AI
+from osbot_utils.helpers.llms.actions.LLM_Request__Execute import LLM_Request__Execute
+
+builder = LLM_Request__Builder__Open_AI()
+builder.set__model__gpt_4o().add_message__user("Say hi in JSON")
+
+executor = LLM_Request__Execute(request_builder=builder)
+response = executor.execute(builder.llm_request())
+print(response.response_data)
+```
+
+---
+
+## 🏗️ Architecture
+
+OSBot-Utils is organized into core **Type-Safe foundations** with layered utilities for different domains:
+
+```
+┌──────────────────────────────────────────────┐
+│                 Your Code                     │
+│  ┌───────────┐  ┌─────────────┐  ┌──────────┐ │
+│  │ Type-Safe │  │  Decorators │  │  Helpers │ │
+│  │ Primitives│  │  & Caching  │  │ (HTML,   │ │
+│  │           │  │             │  │  AST,   │ │
+│  │           │  │             │  │  SQLite)│ │
+│  └───────────┘  └─────────────┘  └──────────┘ │
+└──────────────────────────┬───────────────────┘
+                           │
+┌──────────────────────────▼───────────────────┐
+│                OSBot-Utils                    │
+│  ┌────────────────────────────────────────┐  │
+│  │       Type-Safe Core Classes           │  │
+│  │  Validation / Sanitization / Defaults  │  │
+│  └────────────────────────────────────────┘  │
+│  ┌────────────────────────────────────────┐  │
+│  │    Caching Layers & Decorators         │  │
+│  │  @cache, @cache_on_self, pickle, tmp   │  │
+│  └────────────────────────────────────────┘  │
+│  ┌────────────────────────────────────────┐  │
+│  │ Domain Helpers                          │ │
+│  │ HTML, AST, SSH, LLMs, SQLite, Tracing   │ │
+│  └────────────────────────────────────────┘  │
+└──────────────────────────────────────────────┘
+```
+
+---
+
+## 📚 Key Modules
+
+* **`helpers/safe_*`** — Type-Safe primitives for validated strings, ints, floats
+* **`decorators/methods`** — Caching, exception capture, timing, validation
+* **`helpers/html`** — HTML ↔ dict ↔ tag classes
+* **`helpers/ast`** — Python AST parsing, visiting, merging
+* **`helpers/sqlite`** — High-level SQLite APIs, schema generation, temp DBs
+* **`helpers/ssh`** — SSH/SCP execution with caching
+* **`helpers/llms`** — LLM request/response handling with caching
+* **`helpers/trace`** — Function call tracing with configurable output
+
+---
+
+## 🎯 Benefits
+
+### For Developers
+
+* Strong runtime type validation with Type-Safe classes
+* Consistent patterns for caching and decorators
+* Rich helper library to avoid reinventing the wheel
+
+### For Production
+
+* Deterministic caching with persistence options
+* Safe, validated data structures at integration boundaries
+* Lightweight, dependency-minimal utilities
+
+### For Teams
+
+* Standardized approach to cross-cutting concerns (logging, tracing, caching)
+* Modular helpers to fit many contexts (CLI, web apps, serverless)
+
+---
+
+## 🤝 Contributing
+
+Pull requests are welcome!
+Check existing patterns in `/helpers` and `/decorators` for style guidance.
+
+---
+
+## 📄 License
+
+Licensed under the Apache 2.0 License.
+