bear-utils 0.7.11__tar.gz

bear_utils-0.7.11/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.3
+Name: bear-utils
+Version: 0.7.11
+Summary: Various utilities for Bear programmers, including a rich logging utility, a disk cache, and a SQLite database wrapper amongst other things.
+Author: chaz
+Author-email: bright.lid5647@fastmail.com
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: diskcache (>=5.6.3,<6.0.0)
+Requires-Dist: httpx (>=0.28.1)
+Requires-Dist: pathspec (>=0.12.1)
+Requires-Dist: pillow (>=11.2.1,<12.0.0)
+Requires-Dist: prompt-toolkit (>=3.0.51,<4.0.0)
+Requires-Dist: pydantic (>=2.11.5)
+Requires-Dist: pyglm (>=2.8.2,<3.0.0)
+Requires-Dist: pyqt6 (>=6.9.0)
+Requires-Dist: pytz (>=2025.2)
+Requires-Dist: pyyaml (>=6.0.2)
+Requires-Dist: rich (>=14.0.0,<15.0.0)
+Requires-Dist: singleton-base (>=1.0.5)
+Requires-Dist: sqlalchemy (>=2.0.40,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Bear Utils v# Bear Utils v0.7.11
+
+Personal set of tools and utilities for Python projects, focusing on modularity and ease of use. This library includes components for caching, database management, logging, time handling, file operations, CLI prompts, image processing, clipboard interaction, gradient utilities, event systems, and async helpers.
+
+## Overview
+
+Bear Utils is a collection of utility modules I've created for common tasks across my Python projects. The library is designed to be modular and easy to use, with each component focusing on a specific functionality.
+
+## Installation
+
+```bash
+# Using pip
+pip install bear-utils
+
+# Using poetry
+poetry add bear-utils
+```
+
+## Key Components
+
+### Cache Management
+
+The `cache` package provides disk cache functionality via `diskcache`:
+
+```python
+from bear_utils.cache import CacheWrapper, cache_factory
+
+# Create a cache instance
+cache = Cache(directory="~/.cache/my_app")
+
+# Use the cache factory to create a decorated function
+@cache_factory(directory="~/.cache/my_app")
+def expensive_function(arg1, arg2):
+    # Function will be cached based on arguments
+    pass
+```
+
+### Database Management
+
+The `database` package provides SQLAlchemy integration with helpful patterns:
+
+```python
+from bear_utils.database import DatabaseManager
+from sqlalchemy import Column, Integer, String
+
+# Get declarative base
+Base = DatabaseManager.get_base()
+
+# Define models
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+
+# Create and use database
+db = DatabaseManager("sqlite:///app.db")
+with db.session() as session:
+    session.add(User(name="test"))
+    session.commit()
+```
+
+### Logging
+
+The `logging` package provides an enhanced console logger using rich:
+
+```python
+from bear_utils.logging import ConsoleLogger
+
+logger = ConsoleLogger()
+logger.info("Information message")
+logger.error("Error message") 
+logger.warning("Warning message")
+```
+
+### Time Management
+
+The `time` package contains tools for time handling and measurement:
+
+```python
+from bear_utils.time import TimeTools, EpochTimestamp
+
+# Get current timestamp
+now = EpochTimestamp()
+
+# Time function execution
+from bear_utils.time.time_manager import timer
+
+with timer(name="my_operation"):
+    # Code to measure
+    pass
+```
+
+### File Handling
+
+The `files` package provides abstractions for working with different file types:
+
+```python
+from pathlib import Path
+from bear_utils.files.file_handlers import FileHandlerFactory
+
+factory = FileHandlerFactory()
+handler = factory.get_handler(Path("config.json"))
+data = handler.read_file()
+```
+
+### Prompt Helpers
+
+Utilities for creating interactive command-line prompts:
+
+```python
+from bear_utils.cli.prompt_helpers import restricted_prompt
+
+choice = restricted_prompt(
+    message="Select an option:", 
+    valid_options=["option1", "option2"]
+)
+```
+
+### Image Helpers
+
+Utilities for working with images are located in the `graphics` package:
+
+```python
+from pathlib import Path
+from bear_utils.graphics import encode_image_to_jpeg, encode_image_to_png
+
+# Encode image to base64 string
+jpeg_data = encode_image_to_jpeg(Path("image.jpg"), max_size=800)
+png_data = encode_image_to_png(Path("image.png"), max_size=800)
+```
+
+### Clipboard Helpers
+
+`bear_utils.extras._tools` includes simple helpers for interacting with the system clipboard:
+
+```python
+from bear_utils.extras._tools import copy_to_clipboard, paste_from_clipboard
+
+copy_to_clipboard("hello world")
+text = paste_from_clipboard()
+```
+
+Supported platforms include macOS (`pbcopy/pbpaste`), Windows (`clip`/`powershell Get-Clipboard`),
+and Linux with either Wayland (`wl-copy`/`wl-paste`) or X11 (`xclip`).
+
+### Gradient Utilities
+
+The `graphics.bear_gradient` module provides color gradient functionality for the purposes of visualizing data or creating color transitions:
+
+```python
+from bear_utils.graphics import ColorGradient, RichColor
+from rich.console import Console
+from rich.color_triplet import ColorTriplet
+
+console = Console()
+
+# Health meter goes from red (low health) to green (full health)
+health_gradient = ColorGradient()
+
+console.print("🏥 [bold]Health Meter Demonstration[/bold] 🏥\n")
+
+# Normal health: Red (low) -> Green (high)
+console.print("[bold green]Normal Health Levels (0% = Critical, 100% = Perfect):[/bold green]")
+for health in range(0, 101, 10):
+    color: ColorTriplet = health_gradient.map_to_color(0, 100, health)
+    health_bar = "█" * (health // 5)
+    console.print(f"HP: {health:3d}/100 {health_bar:<20}", style=color.rgb)
+
+console.print("\n" + "="*50 + "\n")
+
+# Reversed: Infection/Damage meter (Green = good, Red = bad)
+console.print("[bold red]Infection Level (0% = Healthy, 100% = Critical):[/bold red]")
+health_gradient.reverse = True
+for infection in range(0, 101, 10):
+    color: ColorTriplet = health_gradient.map_to_color(0, 100, infection)
+    infection_bar = "█" * (infection // 5)
+    status = "🦠" if infection > 70 else "⚠️" if infection > 30 else "✅"
+    console.print(f"Infection: {infection:3d}% {infection_bar:<20} {status}", style=color.rgb)
+
+health_scenarios = [
+    (5, "💀 Nearly Dead"),
+    (25, "🩸 Critical Condition"), 
+    (50, "⚠️  Wounded"),
+    (75, "😐 Recovering"),
+    (95, "💪 Almost Full Health"),
+    (100, "✨ Perfect Health")
+]
+
+console.print("[bold green]Health Status Examples:[/bold green]")
+for hp, status in health_scenarios:
+    color: ColorTriplet = health_gradient.map_to_color(0, 100, hp)
+    console.print(f"{status}: {hp}/100 HP", style=color.rgb)
+```
+
+### Event System
+
+The `events` module provides a pub/sub event system that supports both synchronous and asynchronous handlers:
+
+```python
+from bear_utils.events.events_module import subscribe, publish
+
+# Subscribe to events
+@subscribe("user_logged_in")
+def handle_login(user_id):
+    print(f"User {user_id} logged in")
+
+# Publish events
+publish("user_logged_in", 12345)
+
+# Async support
+@subscribe("data_processed")
+async def handle_process(data):
+    await process_async(data)
+
+# Clear handlers
+from bear_utils.events.events_module import clear_handlers_for_event
+clear_handlers_for_event("user_logged_in")
+```
+
+### Async Helpers
+
+The `extras/_async_helpers.py` module provides utility functions for working with async code:
+
+```python
+from bear_utils.extras._async_helpers import is_async_function
+
+def handle_function(func):
+    if is_async_function(func):
+        # Handle async function
+        pass
+    else:
+        # Handle sync function
+        pass
+```
+

bear_utils-0.7.11/README.md

@@ -0,0 +1,234 @@
+# Bear Utils v# Bear Utils v0.7.11
+
+Personal set of tools and utilities for Python projects, focusing on modularity and ease of use. This library includes components for caching, database management, logging, time handling, file operations, CLI prompts, image processing, clipboard interaction, gradient utilities, event systems, and async helpers.
+
+## Overview
+
+Bear Utils is a collection of utility modules I've created for common tasks across my Python projects. The library is designed to be modular and easy to use, with each component focusing on a specific functionality.
+
+## Installation
+
+```bash
+# Using pip
+pip install bear-utils
+
+# Using poetry
+poetry add bear-utils
+```
+
+## Key Components
+
+### Cache Management
+
+The `cache` package provides disk cache functionality via `diskcache`:
+
+```python
+from bear_utils.cache import CacheWrapper, cache_factory
+
+# Create a cache instance
+cache = Cache(directory="~/.cache/my_app")
+
+# Use the cache factory to create a decorated function
+@cache_factory(directory="~/.cache/my_app")
+def expensive_function(arg1, arg2):
+    # Function will be cached based on arguments
+    pass
+```
+
+### Database Management
+
+The `database` package provides SQLAlchemy integration with helpful patterns:
+
+```python
+from bear_utils.database import DatabaseManager
+from sqlalchemy import Column, Integer, String
+
+# Get declarative base
+Base = DatabaseManager.get_base()
+
+# Define models
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+
+# Create and use database
+db = DatabaseManager("sqlite:///app.db")
+with db.session() as session:
+    session.add(User(name="test"))
+    session.commit()
+```
+
+### Logging
+
+The `logging` package provides an enhanced console logger using rich:
+
+```python
+from bear_utils.logging import ConsoleLogger
+
+logger = ConsoleLogger()
+logger.info("Information message")
+logger.error("Error message") 
+logger.warning("Warning message")
+```
+
+### Time Management
+
+The `time` package contains tools for time handling and measurement:
+
+```python
+from bear_utils.time import TimeTools, EpochTimestamp
+
+# Get current timestamp
+now = EpochTimestamp()
+
+# Time function execution
+from bear_utils.time.time_manager import timer
+
+with timer(name="my_operation"):
+    # Code to measure
+    pass
+```
+
+### File Handling
+
+The `files` package provides abstractions for working with different file types:
+
+```python
+from pathlib import Path
+from bear_utils.files.file_handlers import FileHandlerFactory
+
+factory = FileHandlerFactory()
+handler = factory.get_handler(Path("config.json"))
+data = handler.read_file()
+```
+
+### Prompt Helpers
+
+Utilities for creating interactive command-line prompts:
+
+```python
+from bear_utils.cli.prompt_helpers import restricted_prompt
+
+choice = restricted_prompt(
+    message="Select an option:", 
+    valid_options=["option1", "option2"]
+)
+```
+
+### Image Helpers
+
+Utilities for working with images are located in the `graphics` package:
+
+```python
+from pathlib import Path
+from bear_utils.graphics import encode_image_to_jpeg, encode_image_to_png
+
+# Encode image to base64 string
+jpeg_data = encode_image_to_jpeg(Path("image.jpg"), max_size=800)
+png_data = encode_image_to_png(Path("image.png"), max_size=800)
+```
+
+### Clipboard Helpers
+
+`bear_utils.extras._tools` includes simple helpers for interacting with the system clipboard:
+
+```python
+from bear_utils.extras._tools import copy_to_clipboard, paste_from_clipboard
+
+copy_to_clipboard("hello world")
+text = paste_from_clipboard()
+```
+
+Supported platforms include macOS (`pbcopy/pbpaste`), Windows (`clip`/`powershell Get-Clipboard`),
+and Linux with either Wayland (`wl-copy`/`wl-paste`) or X11 (`xclip`).
+
+### Gradient Utilities
+
+The `graphics.bear_gradient` module provides color gradient functionality for the purposes of visualizing data or creating color transitions:
+
+```python
+from bear_utils.graphics import ColorGradient, RichColor
+from rich.console import Console
+from rich.color_triplet import ColorTriplet
+
+console = Console()
+
+# Health meter goes from red (low health) to green (full health)
+health_gradient = ColorGradient()
+
+console.print("🏥 [bold]Health Meter Demonstration[/bold] 🏥\n")
+
+# Normal health: Red (low) -> Green (high)
+console.print("[bold green]Normal Health Levels (0% = Critical, 100% = Perfect):[/bold green]")
+for health in range(0, 101, 10):
+    color: ColorTriplet = health_gradient.map_to_color(0, 100, health)
+    health_bar = "█" * (health // 5)
+    console.print(f"HP: {health:3d}/100 {health_bar:<20}", style=color.rgb)
+
+console.print("\n" + "="*50 + "\n")
+
+# Reversed: Infection/Damage meter (Green = good, Red = bad)
+console.print("[bold red]Infection Level (0% = Healthy, 100% = Critical):[/bold red]")
+health_gradient.reverse = True
+for infection in range(0, 101, 10):
+    color: ColorTriplet = health_gradient.map_to_color(0, 100, infection)
+    infection_bar = "█" * (infection // 5)
+    status = "🦠" if infection > 70 else "⚠️" if infection > 30 else "✅"
+    console.print(f"Infection: {infection:3d}% {infection_bar:<20} {status}", style=color.rgb)
+
+health_scenarios = [
+    (5, "💀 Nearly Dead"),
+    (25, "🩸 Critical Condition"), 
+    (50, "⚠️  Wounded"),
+    (75, "😐 Recovering"),
+    (95, "💪 Almost Full Health"),
+    (100, "✨ Perfect Health")
+]
+
+console.print("[bold green]Health Status Examples:[/bold green]")
+for hp, status in health_scenarios:
+    color: ColorTriplet = health_gradient.map_to_color(0, 100, hp)
+    console.print(f"{status}: {hp}/100 HP", style=color.rgb)
+```
+
+### Event System
+
+The `events` module provides a pub/sub event system that supports both synchronous and asynchronous handlers:
+
+```python
+from bear_utils.events.events_module import subscribe, publish
+
+# Subscribe to events
+@subscribe("user_logged_in")
+def handle_login(user_id):
+    print(f"User {user_id} logged in")
+
+# Publish events
+publish("user_logged_in", 12345)
+
+# Async support
+@subscribe("data_processed")
+async def handle_process(data):
+    await process_async(data)
+
+# Clear handlers
+from bear_utils.events.events_module import clear_handlers_for_event
+clear_handlers_for_event("user_logged_in")
+```
+
+### Async Helpers
+
+The `extras/_async_helpers.py` module provides utility functions for working with async code:
+
+```python
+from bear_utils.extras._async_helpers import is_async_function
+
+def handle_function(func):
+    if is_async_function(func):
+        # Handle async function
+        pass
+    else:
+        # Handle sync function
+        pass
+```

bear_utils-0.7.11/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "bear-utils"
+version = "0.7.11"
+description = "Various utilities for Bear programmers, including a rich logging utility, a disk cache, and a SQLite database wrapper amongst other things."
+authors = [
+    { name = "chaz", email = "bright.lid5647@fastmail.com" }
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "diskcache (>=5.6.3,<6.0.0)",
+    "pyglm (>=2.8.2,<3.0.0)",
+    "sqlalchemy (>=2.0.40,<3.0.0)",
+    "pillow (>=11.2.1,<12.0.0)",
+    "rich (>=14.0.0,<15.0.0)",
+    "prompt-toolkit (>=3.0.51,<4.0.0)",
+    "pyqt6>=6.9.0",
+    "pydantic>=2.11.5",
+    "pathspec>=0.12.1",
+    "pyyaml>=6.0.2",
+    "pytz>=2025.2",
+    "singleton-base>=1.0.5",
+    "httpx>=0.28.1",
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "bump2version>=1.0.1",
+    "isort>=6.0.1",
+    "pytest>=8.3.5",
+    "twine>=6.1.0",
+]
+
+
+[tool.pytest.ini_options]
+markers = [
+    "visual: marks tests as visual verification tests (deselect with '-m \"not visual\"')"
+]

bear_utils-0.7.11/src/bear_utils/__init__.py

@@ -0,0 +1,13 @@
+from .cache import CacheWrapper, cache, cache_factory
+from .config.settings_manager import SettingsManager, get_settings_manager
+from .constants.date_related import DATE_FORMAT, DATE_TIME_FORMAT
+from .database import DatabaseManager
+from .events import Events
+from .files.file_handlers.file_handler_factory import FileHandlerFactory
+from .logging.logger_manager._common import VERBOSE_CONSOLE_FORMAT
+from .logging.logger_manager._styles import VERBOSE
+from .logging.loggers import BaseLogger, BufferLogger, ConsoleLogger, FileLogger
+from .time._time_class import EpochTimestamp
+from .time.time_manager import TimeTools
+
+__version__ = "__version__ = "0.7.11""

bear_utils-0.7.11/src/bear_utils/ai/__init__.py

@@ -0,0 +1,30 @@
+from .ai_helpers._common import (
+    GPT_4_1,
+    GPT_4_1_MINI,
+    GPT_4_1_NANO,
+    PRODUCTION_MODE,
+    TESTING_MODE,
+    AIModel,
+    EnvironmentMode,
+)
+from .ai_helpers._config import AIEndpointConfig
+from .ai_helpers._parsers import CommandResponseParser, PassthroughResponseParser, ResponseParser, TypedResponseParser
+from .ai_helpers._types import ResponseParser as BaseResponseParser
+from .ai_helpers._types import T_Response
+
+__all__ = [
+    "GPT_4_1",
+    "GPT_4_1_MINI",
+    "GPT_4_1_NANO",
+    "PRODUCTION_MODE",
+    "TESTING_MODE",
+    "AIModel",
+    "EnvironmentMode",
+    "AIEndpointConfig",
+    "CommandResponseParser",
+    "PassthroughResponseParser",
+    "ResponseParser",
+    "TypedResponseParser",
+    "T_Response",
+    "BaseResponseParser",
+]

bear_utils-0.7.11/src/bear_utils/ai/ai_helpers/__init__.py

@@ -0,0 +1,130 @@
+from collections.abc import Callable
+from typing import Any
+
+from ...logging import BaseLogger
+from ._common import GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, PRODUCTION_MODE, TESTING_MODE, AIModel, EnvironmentMode
+from ._config import AIEndpointConfig
+from ._parsers import JSONResponseParser, ModularAIEndpoint, PassthroughResponseParser, TypedResponseParser
+
+
+def create_typed_endpoint[T_Response](
+    response_type: type[T_Response],
+    project_name: str,
+    prompt: str,
+    testing_url: str,
+    production_url: str,
+    logger: BaseLogger,
+    transformers: dict[str, Callable] | None = None,
+    environment: EnvironmentMode = PRODUCTION_MODE,
+    chat_model: AIModel = GPT_4_1_NANO,
+    **kwargs,
+) -> ModularAIEndpoint[T_Response]:
+    """Create an endpoint with strict TypedDict response typing."""
+    config = AIEndpointConfig(
+        project_name=project_name,
+        prompt=prompt,
+        testing_url=testing_url,
+        production_url=production_url,
+        environment=environment,
+        chat_model=chat_model,
+        **kwargs,
+    )
+    parser = TypedResponseParser(default_response=response_type, response_transformers=transformers)
+    return ModularAIEndpoint(config, logger, parser)  # type: ignore[return-value, arg-type]
+
+
+def create_command_endpoint[T_Response](
+    default_response: T_Response,
+    project_name: str,
+    prompt: str,
+    testing_url: str,
+    production_url: str,
+    logger: BaseLogger,
+    environment: EnvironmentMode = EnvironmentMode.PRODUCTION,
+    chat_model: AIModel = GPT_4_1_NANO,
+    **kwargs,
+) -> ModularAIEndpoint[T_Response]:
+    from rich.markdown import Markdown
+
+    config = AIEndpointConfig(
+        project_name=project_name,
+        prompt=prompt,
+        testing_url=testing_url,
+        production_url=production_url,
+        environment=environment,
+        chat_model=chat_model,
+        **kwargs,
+    )
+
+    parser = TypedResponseParser(
+        default_response=default_response,
+        response_transformers={"response": lambda x: Markdown(str(x))},
+    )
+
+    return ModularAIEndpoint(config, logger, parser)
+
+
+def create_flexible_endpoint(
+    project_name: str,
+    prompt: str,
+    testing_url: str,
+    production_url: str,
+    logger: BaseLogger,
+    required_fields: list | None = None,
+    transformers: dict[str, Callable] | None = None,
+    append_json: bool = True,
+    environment: EnvironmentMode = PRODUCTION_MODE,
+    chat_model: AIModel = GPT_4_1_NANO,
+    **kwargs,
+) -> ModularAIEndpoint[dict[str, Any]]:
+    """Create an endpoint with flexible JSON parsing."""
+    config = AIEndpointConfig(
+        project_name=project_name,
+        prompt=prompt,
+        testing_url=testing_url,
+        production_url=production_url,
+        append_json_suffix=append_json,
+        environment=environment,
+        chat_model=chat_model,
+        **kwargs,
+    )
+    parser = JSONResponseParser(required_fields, transformers)
+    return ModularAIEndpoint(config, logger, parser)
+
+
+def create_simple_endpoint(
+    project_name: str,
+    prompt: str,
+    testing_url: str,
+    production_url: str,
+    logger: BaseLogger,
+    environment: EnvironmentMode = PRODUCTION_MODE,
+    chat_model: AIModel = GPT_4_1_NANO,
+    **kwargs,
+) -> ModularAIEndpoint[dict[str, Any]]:
+    """Create an endpoint that returns raw output without JSON parsing."""
+    config = AIEndpointConfig(
+        project_name=project_name,
+        prompt=prompt,
+        testing_url=testing_url,
+        production_url=production_url,
+        append_json_suffix=False,
+        environment=environment,
+        chat_model=chat_model,
+        **kwargs,
+    )
+    parser = PassthroughResponseParser()
+    return ModularAIEndpoint(config, logger, parser)
+
+
+__all__: list[str] = [
+    "create_typed_endpoint",
+    "create_command_endpoint",
+    "create_flexible_endpoint",
+    "create_simple_endpoint",
+    "AIEndpointConfig",
+    "EnvironmentMode",
+    "PRODUCTION_MODE",
+    "TESTING_MODE",
+    "ModularAIEndpoint",
+]