| Name | osbot-utils JSON |
| Version |
3.3.0
JSON |
| download |
| home_page | None |
| Summary | OWASP Security Bot - Utils |
| upload_time | 2025-09-13 22:38:19 |
| maintainer | None |
| docs_url | None |
| author | Dinis Cruz |
| requires_python | <4.0,>=3.7 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# OSBot-Utils
[](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.transformers.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.
Raw data
{
"_id": null,
"home_page": null,
"name": "osbot-utils",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Dinis Cruz",
"author_email": "dinis.cruz@owasp.org",
"download_url": "https://files.pythonhosted.org/packages/45/d1/6c1184fbbc27cec6169c73b3c0b1185e29c93f2f145c0437e5f5b6d25aa9/osbot_utils-3.3.0.tar.gz",
"platform": null,
"description": "# OSBot-Utils\n\n\n\n\n\n[](https://codecov.io/gh/owasp-sbot/OSBot-Utils)\n\nA comprehensive Python utility toolkit providing **Type-Safe primitives**, decorators, caching layers, HTML/AST helpers, SQLite tooling, SSH execution, LLM request pipelines, tracing, and more \u2014 all designed to accelerate building robust, maintainable automation and integration code.\n\n---\n\n## \u2728 Key Features\n\n* **\ud83d\udee1\ufe0f Type-Safe First**: Strongly typed primitives (`Safe_Str`, `Safe_Int`, `Safe_Float`, etc.) with validation and sanitization\n* **\u26a1 Multi-layer Caching**: In-memory, per-instance, pickle-on-disk, temp-file, and request/response caches\n* **\ud83d\uddc2\ufe0f Rich Utilities**: Helpers for HTML parsing/rendering, AST inspection, SSH/SCP execution, SQLite schema management, and more\n* **\ud83e\udde0 LLM Support**: Structured request builders, OpenAI API integration, schema enforcement, and persistent cache\n* **\ud83d\udd0d Tracing & Debugging**: Full function call tracing with configurable depth, locals capture, and pretty output\n* **\ud83e\uddea Testing Utilities**: Temp SQLite DBs, mockable caches, and easy test helpers\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npip install osbot-utils\n```\n\nFrom source:\n\n```bash\npip install git+https://github.com/owasp-sbot/OSBot-Utils.git@dev\n```\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Using Type-Safe Primitives\n\n```python\nfrom osbot_utils.type_safe.primitives.safe_str.Safe_Str import Safe_Str\n\nclass Username(Safe_Str):\n max_length = 20\n\nprint(Username(\"alice\")) # 'alice'\nprint(Username(\"invalid username!\")) # 'invalid_username_'\n```\n\n---\n\n### Simple In-Memory Caching\n\n```python\nfrom osbot_utils.decorators.methods.cache_on_self import cache_on_self\n\nclass DataFetcher:\n @cache_on_self\n def fetch(self, x):\n print(\"Fetching\u2026\")\n return x * 2\n\nfetcher = DataFetcher()\nfetcher.fetch(10) # Calls method\nfetcher.fetch(10) # Returns cached result\n```\n\n---\n\n### HTML Parsing\n\n```python\nfrom osbot_utils.helpers.html.transformers.Html__To__Html_Dict import html_to_dict\n\nhtml_code = \"<html><body><h1>Hello</h1></body></html>\"\nprint(html_to_dict(html_code))\n```\n\n---\n\n### SQLite Dynamic Table\n\n```python\nfrom osbot_utils.helpers.sqlite.Temp_Sqlite__Table import Temp_Sqlite__Table\n\nwith Temp_Sqlite__Table() as table:\n table.row_schema = type(\"Row\", (), {\"name\": str, \"age\": int})\n table.create()\n table.add_row_and_commit(name=\"Alice\", age=30)\n print(table.rows())\n```\n\n---\n\n### LLM Request Execution\n\n```python\nfrom osbot_utils.helpers.llms.builders.LLM_Request__Builder__Open_AI import LLM_Request__Builder__Open_AI\nfrom osbot_utils.helpers.llms.actions.LLM_Request__Execute import LLM_Request__Execute\n\nbuilder = LLM_Request__Builder__Open_AI()\nbuilder.set__model__gpt_4o().add_message__user(\"Say hi in JSON\")\n\nexecutor = LLM_Request__Execute(request_builder=builder)\nresponse = executor.execute(builder.llm_request())\nprint(response.response_data)\n```\n\n---\n\n## \ud83c\udfd7\ufe0f Architecture\n\nOSBot-Utils is organized into core **Type-Safe foundations** with layered utilities for different domains:\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Your Code \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Type-Safe \u2502 \u2502 Decorators \u2502 \u2502 Helpers \u2502 \u2502\n\u2502 \u2502 Primitives\u2502 \u2502 & Caching \u2502 \u2502 (HTML, \u2502 \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502 \u2502 AST, \u2502 \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502 \u2502 SQLite)\u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 OSBot-Utils \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Type-Safe Core Classes \u2502 \u2502\n\u2502 \u2502 Validation / Sanitization / Defaults \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Caching Layers & Decorators \u2502 \u2502\n\u2502 \u2502 @cache, @cache_on_self, pickle, tmp \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Domain Helpers \u2502 \u2502\n\u2502 \u2502 HTML, AST, SSH, LLMs, SQLite, Tracing \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n---\n\n## \ud83d\udcda Key Modules\n\n* **`helpers/safe_*`** \u2014 Type-Safe primitives for validated strings, ints, floats\n* **`decorators/methods`** \u2014 Caching, exception capture, timing, validation\n* **`helpers/html`** \u2014 HTML \u2194 dict \u2194 tag classes\n* **`helpers/ast`** \u2014 Python AST parsing, visiting, merging\n* **`helpers/sqlite`** \u2014 High-level SQLite APIs, schema generation, temp DBs\n* **`helpers/ssh`** \u2014 SSH/SCP execution with caching\n* **`helpers/llms`** \u2014 LLM request/response handling with caching\n* **`helpers/trace`** \u2014 Function call tracing with configurable output\n\n---\n\n## \ud83c\udfaf Benefits\n\n### For Developers\n\n* Strong runtime type validation with Type-Safe classes\n* Consistent patterns for caching and decorators\n* Rich helper library to avoid reinventing the wheel\n\n### For Production\n\n* Deterministic caching with persistence options\n* Safe, validated data structures at integration boundaries\n* Lightweight, dependency-minimal utilities\n\n### For Teams\n\n* Standardized approach to cross-cutting concerns (logging, tracing, caching)\n* Modular helpers to fit many contexts (CLI, web apps, serverless)\n\n---\n\n## \ud83e\udd1d Contributing\n\nPull requests are welcome!\nCheck existing patterns in `/helpers` and `/decorators` for style guidance.\n\n---\n\n## \ud83d\udcc4 License\n\nLicensed under the Apache 2.0 License.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "OWASP Security Bot - Utils",
"version": "3.3.0",
"project_urls": {
"Homepage": "https://github.com/owasp-sbot/OSBot-Utils",
"Repository": "https://github.com/owasp-sbot/OSBot-Utils"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d1f523e000a710ac1ed35930cadd8ede3cd2424888b9fbbae651389941296852",
"md5": "4fa477dbfc1a69457b8793210b215e07",
"sha256": "19589de40a4741051b9854dcbec427e844f3b4d7411cf5a32a04b0f3caf954fa"
},
"downloads": -1,
"filename": "osbot_utils-3.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4fa477dbfc1a69457b8793210b215e07",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 392196,
"upload_time": "2025-09-13T22:38:17",
"upload_time_iso_8601": "2025-09-13T22:38:17.962223Z",
"url": "https://files.pythonhosted.org/packages/d1/f5/23e000a710ac1ed35930cadd8ede3cd2424888b9fbbae651389941296852/osbot_utils-3.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "45d16c1184fbbc27cec6169c73b3c0b1185e29c93f2f145c0437e5f5b6d25aa9",
"md5": "cdd8160c06949d9a29bfe6105f9a4946",
"sha256": "d7033ba32d0908d0ca519de5f7fdc3926e4700425681db80fa0b37e359a5c646"
},
"downloads": -1,
"filename": "osbot_utils-3.3.0.tar.gz",
"has_sig": false,
"md5_digest": "cdd8160c06949d9a29bfe6105f9a4946",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 216166,
"upload_time": "2025-09-13T22:38:19",
"upload_time_iso_8601": "2025-09-13T22:38:19.953388Z",
"url": "https://files.pythonhosted.org/packages/45/d1/6c1184fbbc27cec6169c73b3c0b1185e29c93f2f145c0437e5f5b6d25aa9/osbot_utils-3.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 22:38:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "owasp-sbot",
"github_project": "OSBot-Utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "osbot-utils"
}
