bear-utils 0.0.1__py3-none-any.whl

bear_utils/constants/_exceptions.py

@@ -0,0 +1,8 @@
+"""Custom exceptions for the application."""
+
+
+class UserCancelledError(Exception):
+    """Exception raised when a user cancels an operation."""
+
+    def __init__(self, message: str = "User cancelled the operation"):
+        super().__init__(message)

bear_utils/constants/_exit_code.py

@@ -0,0 +1,60 @@
+from bear_utils.constants._meta import IntValue as Value, RichIntEnum
+
+
+class ExitCode(RichIntEnum):
+    """An enumeration of common exit codes used in shell commands."""
+
+    SUCCESS = Value(0, "Success")
+    FAILURE = Value(1, "General error")
+    MISUSE_OF_SHELL_COMMAND = Value(2, "Misuse of shell command")
+    COMMAND_CANNOT_EXECUTE = Value(126, "Command invoked cannot execute")
+    COMMAND_NOT_FOUND = Value(127, "Command not found")
+    INVALID_ARGUMENT_TO_EXIT = Value(128, "Invalid argument to exit")
+    SCRIPT_TERMINATED_BY_CONTROL_C = Value(130, "Script terminated by Control-C")
+    PROCESS_KILLED_BY_SIGKILL = Value(137, "Process killed by SIGKILL (9)")
+    SEGMENTATION_FAULT = Value(139, "Segmentation fault (core dumped)")
+    PROCESS_TERMINATED_BY_SIGTERM = Value(143, "Process terminated by SIGTERM (15)")
+    EXIT_STATUS_OUT_OF_RANGE = Value(255, "Exit status out of range")
+
+
+SUCCESS = ExitCode.SUCCESS
+"""An exit code indicating success."""
+FAIL = ExitCode.FAILURE
+"""Deprecated alias for ExitCode.FAILURE."""
+FAILURE = ExitCode.FAILURE
+"""An exit code indicating a general error."""
+MISUSE_OF_SHELL_COMMAND = ExitCode.MISUSE_OF_SHELL_COMMAND
+"""An exit code indicating misuse of a shell command."""
+COMMAND_CANNOT_EXECUTE = ExitCode.COMMAND_CANNOT_EXECUTE
+"""An exit code indicating that the command invoked cannot execute."""
+COMMAND_NOT_FOUND = ExitCode.COMMAND_NOT_FOUND
+"""An exit code indicating that the command was not found."""
+INVALID_ARGUMENT_TO_EXIT = ExitCode.INVALID_ARGUMENT_TO_EXIT
+"""An exit code indicating an invalid argument to exit."""
+SCRIPT_TERMINATED_BY_CONTROL_C = ExitCode.SCRIPT_TERMINATED_BY_CONTROL_C
+"""An exit code indicating that the script was terminated by Control-C."""
+PROCESS_KILLED_BY_SIGKILL = ExitCode.PROCESS_KILLED_BY_SIGKILL
+"""An exit code indicating that the process was killed by SIGKILL (9)."""
+SEGMENTATION_FAULT = ExitCode.SEGMENTATION_FAULT
+"""An exit code indicating a segmentation fault (core dumped)."""
+PROCESS_TERMINATED_BY_SIGTERM = ExitCode.PROCESS_TERMINATED_BY_SIGTERM
+"""An exit code indicating that the process was terminated by SIGTERM (15)."""
+EXIT_STATUS_OUT_OF_RANGE = ExitCode.EXIT_STATUS_OUT_OF_RANGE
+"""An exit code indicating that the exit status is out of range."""
+
+
+__all__ = [
+    "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",
+]

bear_utils/constants/_http_status_code.py

@@ -0,0 +1,37 @@
+"""HTTP status codes."""
+
+from bear_utils.constants._meta import IntValue as Value, RichIntEnum
+
+
+class HTTPStatusCode(RichIntEnum):
+    """An enumeration of common HTTP status codes."""
+
+    SERVER_ERROR = Value(500, "Internal Server Error")
+    SERVER_OK = Value(200, "OK")
+    PAGE_NOT_FOUND = Value(404, "Not Found")
+    BAD_REQUEST = Value(400, "Bad Request")
+    UNPROCESSABLE_CONTENT = Value(422, "Unprocessable Content")
+    UNAUTHORIZED = Value(401, "Unauthorized")
+    FORBIDDEN = Value(403, "Forbidden")
+    CONFLICT = Value(409, "Conflict")
+    METHOD_NOT_ALLOWED = Value(405, "Method Not Allowed")
+
+
+SERVER_ERROR = HTTPStatusCode.SERVER_ERROR
+"""Internal Server Error"""
+SERVER_OK = HTTPStatusCode.SERVER_OK
+"""OK"""
+PAGE_NOT_FOUND = HTTPStatusCode.PAGE_NOT_FOUND
+"""Not Found"""
+BAD_REQUEST = HTTPStatusCode.BAD_REQUEST
+"""Bad Request"""
+UNPROCESSABLE_CONTENT = HTTPStatusCode.UNPROCESSABLE_CONTENT
+"""Unprocessable Content"""
+UNAUTHORIZED = HTTPStatusCode.UNAUTHORIZED
+"""Unauthorized"""
+FORBIDDEN = HTTPStatusCode.FORBIDDEN
+"""Forbidden"""
+CONFLICT = HTTPStatusCode.CONFLICT
+"""Conflict"""
+METHOD_NOT_ALLOWED = HTTPStatusCode.METHOD_NOT_ALLOWED
+"""Method Not Allowed"""

bear_utils/constants/_lazy_typing.py

@@ -0,0 +1,15 @@
+from typing import Literal, TypeVar
+
+from sqlalchemy.ext.declarative import DeclarativeMeta
+
+LitInt = Literal["int"]
+LitFloat = Literal["float"]
+LitStr = Literal["str"]
+LitBool = Literal["bool"]
+
+OptInt = int | None
+OptFloat = float | None
+OptStr = str | None
+OptBool = bool | None
+
+TableType = TypeVar("TableType", bound=DeclarativeMeta)

bear_utils/constants/_meta.py

@@ -0,0 +1,196 @@
+from contextlib import suppress
+from dataclasses import dataclass
+from enum import IntEnum, StrEnum
+from typing import Any, Self, TextIO, overload
+
+
+@dataclass(frozen=True)
+class IntValue:
+    """A frozen dataclass for holding constant integer values."""
+
+    value: int
+    text: str
+    default: int = 0
+
+
+@dataclass(frozen=True)
+class StrValue:
+    """A frozen dataclass for holding constant string values."""
+
+    value: str
+    text: str
+    default: str = ""
+
+
+class RichStrEnum(StrEnum):
+    """Base class for StrEnums with rich metadata."""
+
+    text: str
+    default: str
+
+    def __new__(cls, value: StrValue) -> Self:
+        obj: Self = str.__new__(cls, value.value)
+        obj._value_ = value.value
+        obj.text = value.text
+        obj.default = value.default
+        return obj
+
+    @classmethod
+    def keys(cls) -> list[str]:
+        """Return a list of all enum member names."""
+        return [item.name for item in cls]
+
+    @overload
+    @classmethod
+    def get(cls, value: str | Self, default: Self) -> Self: ...
+
+    @overload
+    @classmethod
+    def get(cls, value: str | Self, default: None = None) -> None: ...
+
+    @classmethod
+    def get(cls, value: str | Self, default: Self | None = None) -> Self | None:
+        """Try to get an enum member by its value or name."""
+        if isinstance(value, cls):
+            return value
+        with suppress(ValueError):
+            if isinstance(value, str):
+                return cls.from_text(value)
+        return default
+
+    @classmethod
+    def from_text(cls, text: str) -> Self:
+        """Convert a string text to its corresponding enum member."""
+        for item in cls:
+            if item.text == text:
+                return item
+        raise ValueError(f"Text {text} not found in {cls.__name__}")
+
+    @classmethod
+    def from_name(cls, name: str) -> Self:
+        """Convert a string name to its corresponding enum member."""
+        try:
+            return cls[name.upper()]
+        except KeyError as e:
+            raise ValueError(f"Name {name} not found in {cls.__name__}") from e
+
+    def __str__(self) -> str:
+        """Return a string representation of the enum."""
+        return self.value
+
+    def str(self) -> str:
+        """Return the string value of the enum."""
+        return self.value
+
+
+class RichIntEnum(IntEnum):
+    """Base class for IntEnums with rich metadata."""
+
+    text: str
+    default: int
+
+    def __new__(cls, value: IntValue) -> Self:
+        obj: Self = int.__new__(cls, value.value)
+        obj._value_ = value.value
+        obj.text = value.text
+        obj.default = value.default
+        return obj
+
+    def __int__(self) -> int:
+        """Return the integer value of the enum."""
+        return self.value
+
+    def __str__(self) -> str:
+        """Return a string representation of the enum."""
+        return f"{self.name} ({self.value}): {self.text}"
+
+    @classmethod
+    def keys(cls) -> list[str]:
+        """Return a list of all enum member names."""
+        return [item.name for item in cls]
+
+    @overload
+    @classmethod
+    def get(cls, value: str | int | Self, default: Self) -> Self: ...
+
+    @overload
+    @classmethod
+    def get(cls, value: str | int | Self, default: None = None) -> None: ...
+
+    @classmethod
+    def get(cls, value: str | int | Self | Any, default: Self | None = None) -> Self | None:
+        """Try to get an enum member by its value, name, or text."""
+        if isinstance(value, cls):
+            return value
+        with suppress(ValueError):
+            if isinstance(value, int):
+                return cls.from_int(value)
+            if isinstance(value, str):
+                return cls.from_name(value)
+        return default
+
+    @classmethod
+    def from_name(cls, name: str) -> Self:
+        """Convert a string name to its corresponding enum member."""
+        try:
+            return cls[name.upper()]
+        except KeyError as e:
+            raise ValueError(f"Name {name} not found in {cls.__name__}") from e
+
+    @classmethod
+    def from_int(cls, code: int) -> Self:
+        """Convert an integer to its corresponding enum member."""
+        for item in cls:
+            if item.value == code:
+                return item
+        raise ValueError(f"Value {code} not found in {cls.__name__}")
+
+    @classmethod
+    def int_to_text(cls, code: int) -> str:
+        """Convert an integer to its text representation."""
+        try:
+            return cls.from_int(code).text
+        except ValueError:
+            return "Unknown value"
+
+
+class MockTextIO(TextIO):
+    """A mock TextIO class that captures written output for testing purposes."""
+
+    def __init__(self) -> None:
+        """Initialize the mock TextIO."""
+        self._buffer: list[str] = []
+
+    def write(self, _s: str, *_) -> None:  # type: ignore[override]
+        """Mock write method that appends to the buffer."""
+        if _s == "\n":
+            return
+        self._buffer.append(_s)
+
+    def output_buffer(self) -> list[str]:
+        """Get the output buffer."""
+        return self._buffer
+
+    def clear(self) -> None:
+        """Clear the output buffer."""
+        self._buffer.clear()
+
+    def flush(self) -> None:
+        """Mock flush method that does nothing."""
+
+
+class NullFile(TextIO):
+    """A class that acts as a null file, discarding all writes."""
+
+    def write(self, _s: str, *_: Any) -> None:  # type: ignore[override]
+        """Discard the string written to this null file."""
+
+    def flush(self) -> None:
+        """Flush the null file (no operation)."""
+
+    def __enter__(self) -> Self:
+        """Enter context manager and return self."""
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        """Exit context manager (no operation)."""

bear_utils/constants/date_related.py

@@ -0,0 +1,25 @@
+"""A module containing constants related to date and time formatting."""
+
+from bear_utils.time import (
+    DATE_FORMAT,
+    DATE_TIME_FORMAT,
+    DT_FORMAT_WITH_SECONDS,
+    DT_FORMAT_WITH_TZ,
+    DT_FORMAT_WITH_TZ_AND_SECONDS,
+    ET_TIME_ZONE,
+    PT_TIME_ZONE,
+    TIME_FORMAT_WITH_SECONDS,
+    UTC_TIME_ZONE,
+)
+
+__all__ = [
+    "DATE_FORMAT",
+    "DATE_TIME_FORMAT",
+    "DT_FORMAT_WITH_SECONDS",
+    "DT_FORMAT_WITH_TZ",
+    "DT_FORMAT_WITH_TZ_AND_SECONDS",
+    "ET_TIME_ZONE",
+    "PT_TIME_ZONE",
+    "TIME_FORMAT_WITH_SECONDS",
+    "UTC_TIME_ZONE",
+]

bear_utils/constants/time_related.py

@@ -0,0 +1,24 @@
+"""A module containing constants related to time calculations."""
+
+from typing import Literal
+
+MINUTES_IN_HOUR: Literal[60] = 60
+"""60 minutes in an hour"""
+
+HOURS_IN_DAY: Literal[24] = 24
+"""24 hours in a day"""
+
+DAYS_IN_MONTH: Literal[30] = 30
+"""30 days in a month, approximation for a month"""
+
+SECONDS_IN_MINUTE: Literal[60] = 60
+"""60 seconds in a minute"""
+
+SECONDS_IN_HOUR: Literal[3600] = SECONDS_IN_MINUTE * MINUTES_IN_HOUR
+"""60 * 60 = 3600 seconds in an hour"""
+
+SECONDS_IN_DAY: Literal[86400] = SECONDS_IN_HOUR * HOURS_IN_DAY
+"""24 * 60 * 60 = 86400 seconds in a day"""
+
+SECONDS_IN_MONTH: Literal[2592000] = SECONDS_IN_DAY * DAYS_IN_MONTH
+"""30 * 24 * 60 * 60 = 2592000 seconds in a month"""

bear_utils/database/__init__.py

@@ -0,0 +1,8 @@
+"""Database Manager Module for managing database connections and operations."""
+
+from ._db_manager import DatabaseManager, SingletonDB
+
+__all__ = [
+    "DatabaseManager",
+    "SingletonDB",
+]

bear_utils/database/_db_manager.py

@@ -0,0 +1,98 @@
+"""Database Manager Module for managing database connections and operations."""
+
+import atexit
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, ClassVar
+
+from singleton_base import SingletonBase
+from sqlalchemy import Engine, MetaData, create_engine
+from sqlalchemy.ext.declarative import DeclarativeMeta
+from sqlalchemy.orm import declarative_base, scoped_session, sessionmaker
+from sqlalchemy.orm.session import Session
+
+from bear_utils.constants._lazy_typing import TableType
+
+
+class DatabaseManager:
+    _base: ClassVar[DeclarativeMeta | None] = None
+
+    @classmethod
+    def set_base(cls, base: DeclarativeMeta) -> None:
+        """Set the base class for the database manager."""
+        cls._base = base
+
+    @classmethod
+    def get_base(cls) -> DeclarativeMeta:
+        """Get the base class for the database manager."""
+        if cls._base is None:
+            cls.set_base(declarative_base())
+        if cls._base is None:
+            raise ValueError("Base class is not set, failed to set base.")
+        return cls._base
+
+    def __init__(self, db_url: str | Path | None = None, default_schema: str = "sqlite:///"):
+        if db_url is None or db_url == "":
+            raise ValueError("Database URL cannot be None or empty.")
+        if isinstance(db_url, str) and not db_url.startswith(default_schema):
+            db_url = f"{default_schema}{db_url}"
+        self.db_url: str = str(db_url)
+        self.engine: Engine = create_engine(self.db_url, echo=False)
+        base: DeclarativeMeta = DatabaseManager.get_base()
+        self.metadata: MetaData = base.metadata
+        self.SessionFactory: sessionmaker[Session] = sessionmaker(bind=self.engine)
+        self.session: scoped_session[Session] = scoped_session(self.SessionFactory)
+        atexit.register(self.close_all)
+        self.create_tables()
+
+    def get_all_records(self, table_obj: type[TableType]) -> list[TableType]:
+        """Get all records from a table."""
+        return self.session().query(table_obj).all()
+
+    def count_records(self, table_obj: type[TableType]) -> int:
+        """Count the number of records in a table."""
+        return self.session().query(table_obj).count()
+
+    def get_records_by_var(self, table_obj: type[TableType], variable: str, value: str) -> list[TableType]:
+        """Get records from a table by a specific variable."""
+        return self.session().query(table_obj).filter(getattr(table_obj, variable) == value).all()
+
+    def count_records_by_var(self, table_obj: type[TableType], variable: str, value: str) -> int:
+        """Count the number of records in a table by a specific variable."""
+        return self.session().query(table_obj).filter(getattr(table_obj, variable) == value).count()
+
+    @contextmanager
+    def open_session(self) -> Generator[Session, Any]:
+        """Provide a transactional scope around a series of operations."""
+        session: Session = self.session()
+        try:
+            yield session
+            session.commit()
+        except Exception:
+            session.rollback()
+            raise
+
+    def get_session(self) -> Session:
+        """Get a new session."""
+        return self.session()
+
+    def close_session(self) -> None:
+        """Close the session."""
+        self.session.remove()
+
+    def create_tables(self) -> None:
+        """Create all tables defined by Base"""
+        self.metadata.create_all(self.engine)
+
+    def close_all(self) -> None:
+        """Close all sessions and connections."""
+        self.session.close()
+        self.engine.dispose()
+
+
+class SingletonDB(DatabaseManager, SingletonBase):
+    """Singleton class for DatabaseManager, uses SingletonBase to inject singleton pattern."""
+
+
+__all__ = ["DatabaseManager", "SingletonDB"]

bear_utils/events/__init__.py

@@ -0,0 +1,18 @@
+"""A module for event handling in Bear Utils."""
+
+from .events_class import Events
+from .events_module import clear_all, clear_handlers_for_event, dispatch_event, event_handler, set_handler
+
+subscribe = event_handler
+publish = dispatch_event
+
+__all__ = [
+    "Events",
+    "clear_all",
+    "clear_handlers_for_event",
+    "dispatch_event",
+    "event_handler",
+    "publish",
+    "set_handler",
+    "subscribe",
+]

bear_utils/events/events_class.py

@@ -0,0 +1,52 @@
+"""A module for event handling in Bear Utils."""
+
+from collections.abc import Callable
+from typing import Any
+
+from .events_module import (
+    clear_all as _clear_all,
+    clear_handlers_for_event as _clear_handlers_for_event,
+    dispatch_event as _dispatch_event,
+    event_handler as _event_handler,
+    set_handler as _set_handler,
+)
+
+Callback = Callable[..., Any]
+
+
+class Events:
+    """Simple wrapper exposing :mod:`events_module` functionality as methods."""
+
+    # Method names mirror functions from ``events_module`` for familiarity
+
+    def event_handler(self, event_name: str, func: Callback | None = None):
+        """Register ``func`` as a handler for ``event_name``.
+
+        Can be used as a decorator when ``func`` is omitted.
+        """
+        if func is None:
+            return _event_handler(event_name)
+        _set_handler(event_name, func)
+        return func
+
+    def dispatch_event(self, event_name: str, *args, **kwargs) -> Any | None:
+        """Dispatch ``event_name`` to all subscribed handlers."""
+        return _dispatch_event(event_name, *args, **kwargs)
+
+    def set_handler(self, event_name: str, func: Callback) -> None:
+        """Register ``func`` as a handler for ``event_name``."""
+        _set_handler(event_name, func)
+
+    def clear_handlers_for_event(self, event_name: str) -> None:
+        """Remove all handlers associated with ``event_name``."""
+        _clear_handlers_for_event(event_name)
+
+    def clear_all(self) -> None:
+        """Remove all registered event handlers."""
+        _clear_all()
+
+    subscribe = event_handler
+    publish = dispatch_event
+
+
+__all__ = ["Events"]

bear_utils/events/events_module.py

@@ -0,0 +1,74 @@
+"""Event handling module for Bear Utils."""
+
+import asyncio
+from collections import defaultdict
+from collections.abc import Callable
+from functools import wraps
+from types import MethodType
+from typing import Any
+import weakref
+from weakref import WeakMethod, ref
+
+from bear_utils.extras._async_helpers import is_async_function
+
+Callback = Callable[..., Any]
+
+_event_registry: dict[str, weakref.WeakSet[Callback]] = defaultdict(weakref.WeakSet)
+
+
+def clear_handlers_for_event(event_name: str) -> None:
+    """Remove all handlers associated with a specific event."""
+    _event_registry.pop(event_name, None)
+
+
+def clear_all() -> None:
+    """Remove all registered event handlers."""
+    _event_registry.clear()
+
+
+def _make_callback(name: str) -> Callable[[Any], None]:
+    """Create an internal callback to remove dead handlers."""
+
+    def callback(weak_method: Any) -> None:
+        _event_registry[name].remove(weak_method)
+        if not _event_registry[name]:
+            del _event_registry[name]
+
+    return callback
+
+
+def set_handler(name: str, func: Callback) -> None:
+    """Register a function as a handler for a specific event."""
+    if isinstance(func, MethodType):
+        _event_registry[name].add(WeakMethod(func, _make_callback(name)))
+    else:
+        _event_registry[name].add(ref(func, _make_callback(name)))
+
+
+def dispatch_event(name: str, *args, **kwargs) -> Any | None:
+    """Dispatch an event to all registered handlers."""
+    results: list[Any] = []
+    for func in _event_registry.get(name, []):
+        if is_async_function(func):
+            result: Any = asyncio.run(func(*args, **kwargs))  # FIXME: This will crash if called from an async context
+        else:
+            result: Any = func(*args, **kwargs)
+            results.append(result)
+    if not results:
+        return None
+    return results[0] if len(results) == 1 else results
+
+
+def event_handler(event_name: str) -> Callable[[Callback], Callback]:
+    """Decorator to register a callback as an event handler for a specific event."""
+
+    def decorator(callback: Callback) -> Callback:
+        @wraps(callback)
+        def wrapper(*args, **kwargs) -> Any:
+            """Wrapper to register the callback and call it."""
+            return callback(*args, **kwargs)
+
+        set_handler(event_name, wrapper)
+        return wrapper
+
+    return decorator

bear_utils/extras/__init__.py

@@ -0,0 +1,28 @@
+"""A module for various utilities in Bear Utils extras."""
+
+from singleton_base import SingletonBase
+
+from ._tools import ClipboardManager, ascii_header, clear_clipboard, copy_to_clipboard, paste_from_clipboard
+from ._zapper import zap, zap_as, zap_as_multi, zap_get, zap_multi
+from .platform_utils import OS, get_platform, is_linux, is_macos, is_windows
+from .wrappers.add_methods import add_comparison_methods
+
+__all__ = [
+    "OS",
+    "ClipboardManager",
+    "SingletonBase",
+    "add_comparison_methods",
+    "ascii_header",
+    "clear_clipboard",
+    "copy_to_clipboard",
+    "get_platform",
+    "is_linux",
+    "is_macos",
+    "is_windows",
+    "paste_from_clipboard",
+    "zap",
+    "zap_as",
+    "zap_as_multi",
+    "zap_get",
+    "zap_multi",
+]