bear-utils 0.0.1__py3-none-any.whl

bear_utils/cli/shell/_common.py

@@ -0,0 +1,19 @@
+"""Shared shell utilities.
+
+``DEFAULT_SHELL`` attempts to locate ``zsh`` on the host using :func:`shutil.which`.
+If that fails, ``/bin/sh`` is used instead.
+"""
+
+from shutil import which
+
+DEFAULT_SHELL: str = which("zsh") or which("bash") or "/bin/sh"
+"""Dynamically detected shell path, falling back to ``/bin/sh``."""
+
+BASH: str | None = which("bash")
+"""Path to the Bash shell, falling back to ``/bin/bash`` if not found."""
+
+ZSH: str | None = which("zsh") or which("/bin/zsh")
+"""Path to the Zsh shell, falling back to ``/bin/zsh`` if not found."""
+
+SH: str | None = which("sh") or "bin/sh"
+"""Path to the Bourne shell, falling back to ``/bin/sh`` if not found."""

bear_utils/cli/typer_bridge.py

@@ -0,0 +1,90 @@
+"""A simple bridge for augmenting Typer with alias support and command execution for interactive use."""
+
+from collections.abc import Callable
+import shlex
+from typing import Any, TypedDict
+
+from rich.console import Console
+from singleton_base import SingletonBase
+from typer import Exit, Typer
+from typer.models import CommandInfo
+
+from bear_utils.logger_manager import AsyncLoggerProtocol, LoggerProtocol
+
+
+class CommandMeta(TypedDict):
+    """Metadata for a Typer command."""
+
+    name: str
+    help: str
+    hidden: bool
+
+
+def get_command_meta(command: CommandInfo) -> CommandMeta:
+    """Extract metadata from a Typer command."""
+    return {
+        "name": command.name or (command.callback.__name__ if command.callback else "unknown"),
+        "help": (command.callback.__doc__ if command.callback else None) or "No description available",
+        "hidden": command.hidden,
+    }
+
+
+# TODO: Add support for usage statements for a more robust help system
+
+
+class TyperBridge(SingletonBase):
+    """Simple bridge for Typer command execution."""
+
+    def __init__(self, typer_app: Typer, console: AsyncLoggerProtocol | LoggerProtocol | Console) -> None:
+        """Initialize the TyperBridge with a Typer app instance."""
+        self.app: Typer = typer_app
+        self.console: AsyncLoggerProtocol | LoggerProtocol | Console = console or Console()
+        self.command_meta: dict[str, CommandMeta] = {}
+
+    def alias(self, *alias_names: str) -> Callable[..., Callable[..., Any]]:
+        """Register aliases as hidden Typer commands."""
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            for alias in alias_names:
+                self.app.command(name=alias, hidden=True)(func)
+            return func
+
+        return decorator
+
+    def execute_command(self, command_string: str) -> bool:
+        """Execute command via Typer. Return True if successful."""
+        try:
+            parts: list[str] = shlex.split(command_string.strip())
+            if not parts:
+                return False
+            self.app(parts, standalone_mode=False)
+            return True
+        except Exit:
+            return True
+        except Exception as e:
+            if isinstance(self.console, Console):
+                self.console.print(f"[red]Error executing command: {e}[/red]")
+            else:
+                self.console.error(f"Error executing command: {e}", exc_info=True)
+            return False
+
+    def bootstrap_command_meta(self) -> None:
+        """Bootstrap command metadata from the Typer app."""
+        if not self.command_meta:
+            for cmd in self.app.registered_commands:
+                cmd_meta: CommandMeta = get_command_meta(command=cmd)
+                self.command_meta[cmd_meta["name"]] = cmd_meta
+
+    def get_all_command_info(self, show_hidden: bool = False) -> dict[str, CommandMeta]:
+        """Get all command information from the Typer app."""
+        if not self.command_meta:
+            self.bootstrap_command_meta()
+        if not show_hidden:
+            return {name: meta for name, meta in self.command_meta.items() if not meta["hidden"]}
+        return self.command_meta
+
+    def get_command_info(self, command_name: str) -> CommandMeta | None:
+        """Get metadata for a specific command."""
+        if not self.command_meta:
+            self.bootstrap_command_meta()
+        return self.command_meta.get(command_name)

bear_utils/config/__init__.py

@@ -0,0 +1,13 @@
+"""Config and settings management utilities for Bear Utils."""
+
+from .config_manager import ConfigManager
+from .dir_manager import DirectoryManager
+from .settings_manager import SettingsManager, get_settings_manager, settings
+
+__all__ = [
+    "ConfigManager",
+    "DirectoryManager",
+    "SettingsManager",
+    "get_settings_manager",
+    "settings",
+]

bear_utils/config/config_manager.py

@@ -0,0 +1,229 @@
+"""Config Manager Module for Bear Utils."""
+
+from collections.abc import Callable
+from functools import cached_property
+import os
+from pathlib import Path
+import tomllib
+from typing import Any
+
+from pydantic import BaseModel, ValidationError, field_validator
+
+
+def nullable_string_validator(field_name: str) -> Callable[..., str | None]:
+    """Create a validator that converts 'null' strings to None."""
+
+    @field_validator(field_name)
+    @classmethod
+    def _validate(cls: object, v: str | None) -> str | None:  # noqa: ARG001
+        if isinstance(v, str) and v.lower() in ("null", "none", ""):
+            return None
+        return v
+
+    return _validate
+
+
+class ConfigManager[ConfigType: BaseModel]:
+    """A generic configuration manager with environment-based overrides."""
+
+    def __init__(self, config_model: type[ConfigType], config_path: Path | None = None, env: str = "dev") -> None:
+        """Initialize the ConfigManager with a Pydantic model and configuration path."""
+        self._model: type[ConfigType] = config_model
+        self._config_path: Path = config_path or Path("config")
+        self._env: str = env
+        self._config: ConfigType | None = None
+        self._config_path.mkdir(parents=True, exist_ok=True)
+
+    def _get_env_overrides(self) -> dict[str, Any]:
+        """Convert environment variables to nested dictionary structure."""
+        env_config: dict[str, Any] = {}
+
+        for key, value in os.environ.items():
+            if not key.startswith("APP_"):
+                continue
+
+            # Convert APP_DATABASE_HOST to ['database', 'host']
+            parts: list[str] = key.lower().replace("app_", "").split("_")
+
+            current: dict[str, Any] = env_config
+            for part in parts[:-1]:
+                current = current.setdefault(part, {})
+
+            final_value: Any = self._convert_env_value(value)
+            current[parts[-1]] = final_value
+        return env_config
+
+    def _convert_env_value(self, value: str) -> Any:
+        """Convert string environment variables to appropriate types."""
+        if value.lower() in ("true", "false"):
+            return value.lower() == "true"
+
+        if value.isdigit():
+            return int(value)
+
+        try:
+            if "." in value:
+                return float(value)
+        except ValueError:
+            pass
+
+        if "," in value:
+            return [item.strip() for item in value.split(",")]
+
+        return value
+
+    def _load_toml_file(self, file_path: Path) -> dict[str, Any]:
+        """Load a TOML file and return its contents."""
+        try:
+            with open(file_path, "rb") as f:
+                return tomllib.load(f)
+        except (FileNotFoundError, tomllib.TOMLDecodeError):
+            return {}
+
+    @cached_property
+    def load(self) -> ConfigType:
+        """Load configuration from files and environment variables."""
+        # Load order (later overrides earlier):
+        # 1. default.toml
+        # 2. {env}.toml
+        # 3. local.toml (gitignored)
+        # 4. environment variables
+        config_data: dict[str, Any] = {}
+
+        # TODO: Update this so it looks for it in more than one place
+        config_files: list[Path] = [
+            self._config_path / "default.toml",
+            self._config_path / f"{self._env}.toml",
+            self._config_path / "local.toml",
+        ]
+
+        for config_file in config_files:
+            if config_file.exists():
+                file_data = self._load_toml_file(config_file)
+                config_data = self._deep_merge(config_data, file_data)
+
+        env_overrides: dict[str, Any] = self._get_env_overrides()
+        config_data = self._deep_merge(config_data, env_overrides)
+
+        try:
+            return self._model.model_validate(config_data)
+        except ValidationError as e:
+            raise ValueError(f"Configuration validation failed: {e}") from e
+
+    def _deep_merge(self, base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+        """Deep merge two dictionaries."""
+        result: dict[str, Any] = base.copy()
+        for key, value in override.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = self._deep_merge(result[key], value)
+            else:
+                result[key] = value
+        return result
+
+    @property
+    def config(self) -> ConfigType:
+        """Get the loaded configuration."""
+        if self._config is None:
+            self._config = self.load
+        return self._config
+
+    def reload(self) -> ConfigType:
+        """Force reload the configuration."""
+        if "config" in self.__dict__:
+            del self.__dict__["config"]
+        return self.config
+
+    def create_default_config(self) -> None:
+        """Create a default.toml file with example values."""
+        default_path = self._config_path / "default.toml"
+        if default_path.exists():
+            return
+
+        try:
+            default_instance: ConfigType = self._model()
+            toml_content: str = self._model_to_toml(default_instance)
+            default_path.write_text(toml_content)
+        except Exception as e:
+            print(f"Could not create default config: {e}")
+
+    def _model_to_toml(self, instance: ConfigType) -> str:
+        """Convert a Pydantic model to TOML format."""
+        lines: list[str] = ["# Default configuration"]
+
+        def _dict_to_toml(data: dict[str, Any], prefix: str = "") -> None:
+            for key, value in data.items():
+                full_key: str = f"{prefix}.{key}" if prefix else key
+
+                if isinstance(value, dict):
+                    lines.append(f"\n[{full_key}]")
+                    for sub_key, sub_value in value.items():
+                        lines.append(f"{sub_key} = {self._format_toml_value(sub_value)}")
+                elif not prefix:
+                    lines.append(f"{key} = {self._format_toml_value(value)}")
+
+        _dict_to_toml(instance.model_dump())
+        return "\n".join(lines)
+
+    def _format_toml_value(self, value: Any) -> str:
+        """Format a value for TOML output."""
+        if isinstance(value, str):
+            return f'"{value}"'
+        if isinstance(value, bool):
+            return str(value).lower()
+        if isinstance(value, list):
+            formatted_items = [self._format_toml_value(item) for item in value]
+            return f"[{', '.join(formatted_items)}]"
+        if value is None:
+            return '"null"'
+        return str(value)
+
+
+if __name__ == "__main__":
+    # Example usage and models
+    class DatabaseConfig(BaseModel):
+        """Configuration for an example database connection."""
+
+        host: str = "localhost"
+        port: int = 5432
+        username: str = "app"
+        password: str = "secret"  # noqa: S105 This is just an example
+        database: str = "myapp"
+
+    class LoggingConfig(BaseModel):
+        """Configuration for an example logging setup."""
+
+        level: str = "INFO"
+        format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        file: str | None = None
+
+        _validate_file = nullable_string_validator("file")
+
+    class AppConfig(BaseModel):
+        """Example application configuration model."""
+
+        database: DatabaseConfig = DatabaseConfig()
+        logging: LoggingConfig = LoggingConfig()
+        environment: str = "development"
+        debug: bool = False
+        api_key: str = "your-api-key-here"
+        allowed_hosts: list[str] = ["localhost", "127.0.0.1"]
+
+    def get_config_manager(env: str = "dev") -> ConfigManager[AppConfig]:
+        """Get a configured ConfigManager instance."""
+        return ConfigManager[AppConfig](
+            config_model=AppConfig,
+            config_path=Path("config"),
+            env=env,
+        )
+
+    config_manager: ConfigManager[AppConfig] = get_config_manager("development")
+    config_manager.create_default_config()
+    config: AppConfig = config_manager.config
+
+    print(f"Database host: {config.database.host}")
+    print(f"Debug mode: {config.debug}")
+    print(f"Environment: {config.environment}")
+
+    # Test environment variable override
+    # Set: APP_DATABASE_HOST=production-db.example.com
+    # Set: APP_DEBUG=true

bear_utils/config/dir_manager.py

@@ -0,0 +1,69 @@
+"""Directory Manager Module for Bear Utils."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar
+
+
+@dataclass
+class DirectoryManager:
+    """A class to manage directories for bear_utils."""
+
+    _base_path: ClassVar[Path] = Path.home() / ".config" / "bear_utils"
+    _settings_path: ClassVar[Path] = _base_path / "settings"
+    _temp_path: ClassVar[Path] = _base_path / "temp"
+
+    def setup(self) -> None:
+        """Ensure the base, settings, and temp directories exist."""
+        self._base_path.mkdir(parents=True, exist_ok=True)
+        self._settings_path.mkdir(parents=True, exist_ok=True)
+        self._temp_path.mkdir(parents=True, exist_ok=True)
+
+    def clear_temp(self) -> None:
+        """Clear the temporary directory."""
+        if self.temp_path.exists():
+            for item in self.temp_path.iterdir():
+                if item.is_file() or item.is_symlink():
+                    item.unlink()
+                elif item.is_dir():
+                    item.rmdir()
+
+    @property
+    def base_path(self) -> Path:
+        """Get the base path for bear_utils."""
+        return self._base_path
+
+    @property
+    def settings_path(self) -> Path:
+        """Get the path to the settings directory."""
+        return self._settings_path
+
+    @property
+    def temp_path(self) -> Path:
+        """Get the path to the temporary directory."""
+        return self._temp_path
+
+
+def get_base_path() -> Path:
+    """Get the base path for bear_utils."""
+    return DirectoryManager().base_path
+
+
+def get_settings_path() -> Path:
+    """Get the path to the settings directory."""
+    return DirectoryManager().settings_path
+
+
+def get_temp_path() -> Path:
+    """Get the path to the temporary directory."""
+    return DirectoryManager().temp_path
+
+
+def setup_directories() -> None:
+    """Set up the necessary directories for bear_utils."""
+    DirectoryManager().setup()
+
+
+def clear_temp_directory() -> None:
+    """Clear the temporary directory."""
+    DirectoryManager().clear_temp()

bear_utils/config/settings_manager.py

@@ -0,0 +1,179 @@
+"""Settings Manager Module for Bear Utils."""
+
+import atexit
+from collections.abc import Generator
+from contextlib import contextmanager
+import hashlib
+from pathlib import Path
+from typing import Any, Self
+
+from tinydb import Query, TinyDB
+
+DEFAULT_PATH: Path = Path.home() / ".config" / "bear_utils"
+
+
+def get_config_folder(path: str | Path | None = None) -> Path:
+    """Get the path to the bear configuration directory."""
+    config_path: Path = Path(path) if isinstance(path, str) else path or DEFAULT_PATH
+    config_path.mkdir(parents=True, exist_ok=True)
+    return config_path
+
+
+def get_file_hash(file_path: Path) -> str:
+    """Return the blake2 hash of the file at the given path."""
+    hasher = hashlib.blake2b()
+    with file_path.open("rb") as file:
+        while chunk := file.read(8192):
+            hasher.update(chunk)
+    return hasher.hexdigest()
+
+
+class SettingsManager:
+    """A class to manage settings using TinyDB and an in-memory cache."""
+
+    __slots__ = ("cache", "db", "file_hash", "file_path", "settings_name")
+
+    def __init__(self, settings_name: str, folder_path: str | Path | None = None) -> None:
+        """Initialize the SettingsManager with a specific settings name."""
+        self.settings_name: str = settings_name
+        self.cache: dict[str, Any] = {}
+        file_name: str = f"{settings_name}.json"
+        self.file_path: Path = get_config_folder(folder_path) / file_name
+        self.db: TinyDB = TinyDB(self.file_path, indent=4, ensure_ascii=False)
+        self.file_hash: str = get_file_hash(self.file_path) if self.file_path.exists() else ""
+        atexit.register(self.close)
+        self._load_cache()
+
+    def __getattr__(self, key: str) -> Any:
+        """Handle dot notation access for settings."""
+        if key in self.__slots__:
+            raise AttributeError(f"'{key}' not initialized")
+        if key.startswith("_"):
+            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{key}'")
+        return self.get(key)
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        """Handle dot notation assignment for settings."""
+        if key in self.__slots__:
+            object.__setattr__(self, key, value)
+            return
+        self.set(key=key, value=value)
+
+    def invalidate_cache(self) -> None:
+        """Invalidate the in-memory cache."""
+        self.cache.clear()
+        self._load_cache()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a setting value."""
+        file_hash = get_file_hash(self.file_path)
+
+        if file_hash != self.file_hash:
+            self.invalidate_cache()
+            self.file_hash = file_hash
+
+        if key in self.cache:
+            return self.cache[key]
+        if result := self.db.search(Query().key == key):
+            value = result[0]["value"]
+            self.cache[key] = value
+            return value
+        return default
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a setting value."""
+        self.db.upsert({"key": key, "value": value}, Query().key == key)
+        self.cache[key] = value
+
+    def has(self, key: str) -> bool:
+        """Check if a setting exists."""
+        return key in self.cache or self.db.contains(Query().key == key)
+
+    def _load_cache(self) -> None:
+        """Load all settings into cache."""
+        for record in self.db.all():
+            self.cache[record["key"]] = record["value"]
+
+    def open(self) -> None:
+        """Reopen the settings file after it's been closed/destroyed."""
+        self.db = TinyDB(self.file_path, indent=4, ensure_ascii=False)
+        self.cache = {}
+        self._load_cache()
+
+    def close(self) -> None:
+        """Close the database."""
+        if hasattr(self, "db"):
+            self.db.close()
+        if hasattr(self, "cache"):
+            self.cache.clear()
+
+    def destroy_settings(self) -> bool:
+        """Delete the settings file."""
+        if self.file_path.exists():
+            self.close()
+            self.file_path.unlink()
+            self.cache.clear()
+            return True
+        return False
+
+    def __contains__(self, key: str) -> bool:
+        return self.has(key)
+
+    def keys(self) -> list[str]:
+        """Get all setting keys."""
+        return list(self.cache.keys())
+
+    def items(self) -> list[tuple[str, Any]]:
+        """Get all setting key-value pairs."""
+        return list(self.cache.items())
+
+    def values(self) -> list[Any]:
+        """Get all setting values."""
+        return list(self.cache.values())
+
+    def __len__(self):
+        return len(self.cache)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"<SettingsManager settings_name='{self.settings_name}'>"
+
+    def __str__(self) -> str:
+        return f"SettingsManager for '{self.settings_name}' with {len(self.keys())} settings."
+
+
+_settings_managers: dict[str, SettingsManager] = {}
+
+
+def get_settings_manager(settings_name: str) -> SettingsManager:
+    """Get or create a SettingsManager instance."""
+    if settings_name not in _settings_managers:
+        _settings_managers[settings_name] = SettingsManager(settings_name=settings_name)
+    return _settings_managers[settings_name]
+
+
+@contextmanager
+def settings(settings_name: str) -> Generator[SettingsManager]:
+    """Context manager for SettingsManager."""
+    sm: SettingsManager = get_settings_manager(settings_name)
+    try:
+        yield sm
+    finally:
+        sm.close()
+
+
+if __name__ == "__main__":
+    # Example usage of the SettingsManager
+    with settings(settings_name="example_settings") as sm:
+        sm.sample_setting = "This is a sample setting"
+        print(sm.sample_setting)
+        print(sm.keys())
+        for key, value in sm.items():
+            print("This is items()")
+            print(f"Key: {key}, Value: {value}")
+        print(sm.file_path)

bear_utils/constants/__init__.py

@@ -0,0 +1,90 @@
+"""Constants Module for Bear Utils."""
+
+from pathlib import Path
+import sys
+from typing import TextIO
+
+from bear_utils.constants._exit_code import (
+    COMMAND_CANNOT_EXECUTE,
+    COMMAND_NOT_FOUND,
+    EXIT_STATUS_OUT_OF_RANGE,
+    FAIL,
+    FAILURE,
+    INVALID_ARGUMENT_TO_EXIT,
+    MISUSE_OF_SHELL_COMMAND,
+    PROCESS_KILLED_BY_SIGKILL,
+    PROCESS_TERMINATED_BY_SIGTERM,
+    SCRIPT_TERMINATED_BY_CONTROL_C,
+    SEGMENTATION_FAULT,
+    SUCCESS,
+    ExitCode,
+)
+from bear_utils.constants._http_status_code import (
+    BAD_REQUEST,
+    CONFLICT,
+    FORBIDDEN,
+    PAGE_NOT_FOUND,
+    SERVER_ERROR,
+    SERVER_OK,
+    UNAUTHORIZED,
+    HTTPStatusCode,
+)
+from bear_utils.constants._meta import IntValue, NullFile, RichIntEnum, RichStrEnum, StrValue
+
+VIDEO_EXTS = [".mp4", ".mov", ".avi", ".mkv"]
+"""Extensions for video files."""
+IMAGE_EXTS = [".jpg", ".jpeg", ".png", ".gif"]
+"""Extensions for image files."""
+FILE_EXTS = IMAGE_EXTS + VIDEO_EXTS
+"""Extensions for both image and video files."""
+
+PATH_TO_DOWNLOADS = Path.home() / "Downloads"
+"""Path to the Downloads folder."""
+PATH_TO_PICTURES = Path.home() / "Pictures"
+"""Path to the Pictures folder."""
+GLOBAL_VENV = Path.home() / ".global_venv"
+"""Path to the global virtual environment."""
+
+STDOUT: TextIO = sys.stdout
+"""Standard output stream."""
+STDERR: TextIO = sys.stderr
+"""Standard error stream."""
+DEVNULL: TextIO = NullFile()
+"""A null file that discards all writes."""
+
+__all__ = [
+    "BAD_REQUEST",
+    "COMMAND_CANNOT_EXECUTE",
+    "COMMAND_NOT_FOUND",
+    "CONFLICT",
+    "EXIT_STATUS_OUT_OF_RANGE",
+    "FAIL",
+    "FAILURE",
+    "FILE_EXTS",
+    "FORBIDDEN",
+    "GLOBAL_VENV",
+    "IMAGE_EXTS",
+    "INVALID_ARGUMENT_TO_EXIT",
+    "MISUSE_OF_SHELL_COMMAND",
+    "PAGE_NOT_FOUND",
+    "PATH_TO_DOWNLOADS",
+    "PATH_TO_PICTURES",
+    "PROCESS_KILLED_BY_SIGKILL",
+    "PROCESS_TERMINATED_BY_SIGTERM",
+    "SCRIPT_TERMINATED_BY_CONTROL_C",
+    "SEGMENTATION_FAULT",
+    "SERVER_ERROR",
+    "SERVER_OK",
+    "STDERR",
+    "STDOUT",
+    "SUCCESS",
+    "UNAUTHORIZED",
+    "VIDEO_EXTS",
+    "ExitCode",
+    "HTTPStatusCode",
+    "IntValue",
+    "NullFile",
+    "RichIntEnum",
+    "RichStrEnum",
+    "StrValue",
+]