danielutils 1.1.28__py3-none-any.whl

danielutils/__init__.py

@@ -0,0 +1,50 @@
+__version__ = "1.1.28"
+"""danielutils is a convenience library of functions decorators
+    data-structures and more that make my development workflow faster
+"""
+# =================================================================
+# ============================= LEAFS =============================
+# =================================================================
+from .path import *
+from .date_time import *
+from .aliases import *
+from .exceptions import PrintCatchOne
+from .snippets import *
+from .abstractions import *
+from .protocols import *
+# =================================================================
+# ========================= ORDER MATTERS =========================
+# =================================================================
+
+from .reflection import *
+from .decorators import *
+# ========== NEEDS REFLECTION ==========
+# ========== NEEDS DECORATORS ==========
+from .colors import *
+# ========== NEEDS BOTH ==========
+
+from .progress_bar import *
+from .functions import *
+from .io_ import *
+from .system import *
+from .text import *
+from .conversions import *
+from .better_builtins import *
+from .time import *
+from .date import *
+from .data_structures import *
+from .math_ import *
+from .system import *
+from .print_ import *
+from .metaclasses import *
+from .generators import *
+from .university import *
+from .mock_ import *
+from .context_managers import *
+from .testing import *
+from .retry_executor import *
+from .java import *
+from .random_ import *
+from .lombok import *
+from .logging_ import *
+from .async_ import *

danielutils/abstractions/__init__.py

@@ -0,0 +1,3 @@
+from .db import *
+from .multiprogramming import *
+from .repl import *

danielutils/abstractions/db/__init__.py

@@ -0,0 +1,10 @@
+"""
+Database package for Stick With Me
+"""
+from .implementations import *
+from .database import *
+from .database_definitions import *
+from .database_exceptions import *
+from .database_factory import *
+from .dependencies import *
+from .database_initializer import *

danielutils/abstractions/db/database.py

@@ -0,0 +1,206 @@
+import functools
+import logging
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Callable, TypeVar, cast, Optional, Set
+from .database_exceptions import DBException
+from .database_definitions import TableSchema, SelectQuery, UpdateQuery, DeleteQuery
+from ...logging_.utils import get_logger
+logger = get_logger(__name__)
+
+# Type variable for the decorator
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+class Database(ABC):
+    """Abstract base class for database operations"""
+
+    @classmethod
+    def _wrap_db_exceptions(cls, db_method: F) -> F:
+        """
+        Private decorator to wrap database implementation methods and convert implementation-specific
+        exceptions to our standard database exceptions.
+        """
+
+        @functools.wraps(db_method)
+        async def wrapper(self: 'Database', *args: Any, **kwargs: Any) -> Any:
+            method_name = db_method.__name__
+            logger.debug("Executing database method: %s", method_name)
+            try:
+                result = await db_method(self, *args, **kwargs)
+                logger.debug("Database method '%s' completed successfully", method_name)
+                return result
+            except DBException as e:
+                logger.error("Database method '%s' failed with DBException: %s", method_name, e)
+                raise
+            except Exception as e:
+                logger.error("Database method '%s' failed with %s: %s", method_name, type(e).__name__, e)
+                raise cls._default_class_exception_conversion(e)
+
+        return cast(F, wrapper)
+
+    @classmethod
+    def _get_functions_with_auto_converted_exceptions(cls) -> Set[str]:
+        return {
+            "connect",
+            "disconnect",
+            "get_schemas",
+            "create_table",
+            "insert",
+            "get",
+            "update",
+            "delete"
+        }
+
+    @classmethod
+    def __init_subclass__(cls) -> None:
+        """Initialize subclass by wrapping all public methods with exception handling"""
+        logger.debug("Initializing Database subclass: %s", cls.__name__)
+        wrapped_methods = []
+        for name, method in cls.__dict__.items():
+            if (
+                    callable(method) and
+                    not name.startswith('_') and
+                    not isinstance(method, (classmethod, staticmethod))
+                    and name in cls._get_functions_with_auto_converted_exceptions()
+            ):
+                setattr(cls, name, cls._wrap_db_exceptions(method))
+                wrapped_methods.append(name)
+        logger.debug("Database subclass '%s' initialized with %s wrapped methods: %s", cls.__name__, len(wrapped_methods), wrapped_methods)
+
+    @classmethod
+    def _default_class_exception_conversion(cls, e: Exception) -> Exception:
+        """
+        Handle implementation-specific exceptions. Override this method in implementations
+        to provide custom exception handling.
+
+        Args:
+            e (Exception): The original exception
+
+        Returns:
+            Exception: The converted exception
+        """
+        logger.warning("Converting exception %s to DBException: %s", type(e).__name__, e)
+        return DBException(f"Database error: {str(e)}")
+
+    async def __aenter__(self) -> 'Database':
+        """
+        Context manager entry point. Connects to the database.
+
+        Returns:
+            Database: The database instance for use in the context
+        """
+        logger.debug("Entering database context for %s", self.__class__.__name__)
+        await self.connect()
+        logger.debug("Database context entered successfully for %s", self.__class__.__name__)
+        return self
+
+    async def __aexit__(self, exc_type: Optional[type], exc_val: Optional[Exception], exc_tb: Optional[Any]) -> None:
+        """
+        Context manager exit point. Disconnects from the database.
+
+        Args:
+            exc_type: The type of exception that was raised, if any
+            exc_val: The exception instance that was raised, if any
+            exc_tb: The traceback for the exception, if any
+        """
+        logger.debug("Exiting database context for %s", self.__class__.__name__)
+        if exc_type is not None:
+            logger.warning("Database context exited with exception: %s: %s", exc_type.__name__, exc_val)
+        await self.disconnect()
+        logger.debug("Database context exited successfully for %s", self.__class__.__name__)
+
+    @abstractmethod
+    async def connect(self) -> None:
+        """Establish connection to the database
+        Note: Implementations should log connection attempts and results
+        """
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Close the database connection
+        Note: Implementations should log disconnection attempts and results
+        """
+
+    @abstractmethod
+    def is_connected(self) -> bool:
+        """Check if the database connection is open
+        Note: Implementations should log connection status checks
+        """
+
+    @abstractmethod
+    async def get_schemas(self) -> Dict[str, TableSchema]:
+        """
+        Get the complete database schema
+        Note: Implementations should log schema retrieval operations
+
+        Returns:
+            Dict[str, TableSchema]: Dictionary mapping table names to their schemas
+        """
+
+    @abstractmethod
+    async def create_table(self, schema: TableSchema) -> None:
+        """
+        Create a new table in the database
+        Note: Implementations should log table creation operations
+
+        Args:
+            schema (TableSchema): Schema definition for the table
+        """
+
+    @abstractmethod
+    async def insert(self, table: str, data: Dict[str, Any]) -> Any:
+        """
+        Insert a record into the specified table
+        Note: Implementations should log insert operations with table name and data size
+
+        Args:
+            table (str): Name of the table to insert into
+            data (Dict[str, Any]): Dictionary containing column names and values
+
+        Returns:
+            Any: ID of the inserted record
+        """
+
+    @abstractmethod
+    async def get(self, query: SelectQuery) -> List[Dict[str, Any]]:
+        """
+        Get records from the database
+        Note: Implementations should log query operations with table name and result count
+
+        Args:
+            query (SelectQuery): Query definition containing table name, conditions, ordering, etc.
+
+        Returns:
+            List[Dict[str, Any]]: List of dictionaries containing the selected records
+        """
+
+    @abstractmethod
+    async def update(self, query: UpdateQuery) -> int:
+        """
+        Update records in the database
+        Note: Implementations should log update operations with table name and affected row count
+
+        Args:
+            query (UpdateQuery): Query definition containing table name, conditions, and data to update
+
+        Returns:
+            int: Number of affected rows
+        """
+
+    @abstractmethod
+    async def delete(self, query: DeleteQuery) -> int:
+        """
+        Delete records from the database
+        Note: Implementations should log delete operations with table name and affected row count
+
+        Args:
+            query (DeleteQuery): Query definition containing table name and conditions
+
+        Returns:
+            int: Number of affected rows
+        """
+
+
+__all__ = [
+    "Database"
+]

danielutils/abstractions/db/database_definitions.py

@@ -0,0 +1,219 @@
+import json
+from typing import Dict, Any, List, Optional, Literal, Union, Type
+from enum import Enum
+
+try:
+    from pydantic import BaseModel, Field, ConfigDict
+except ImportError:
+    BaseModel = type("BaseModel", (object,), {})  # type:ignore
+    Field = lambda **kwargs: kwargs  # type:ignore
+    ConfigDict = lambda **kwargs: kwargs  # type:ignore
+
+
+class ColumnType(str, Enum):
+    """SQL column types"""
+    INTEGER = "INTEGER"
+    AUTOINCREMENT = "AUTOINCREMENT"
+    SMALLINT = "SMALLINT"
+    MEDIUMINT = "MEDIUMINT"
+    TINYINT = "TINYINT"
+    BIGINT = "BIGINT"
+    FLOAT = "FLOAT"
+    DOUBLE = "DOUBLE"
+    DECIMAL = "DECIMAL"
+    BOOLEAN = "BOOLEAN"
+    TEXT = "TEXT"
+    VARCHAR = "VARCHAR"
+    CHAR = "CHAR"
+    DATE = "DATE"
+    TIME = "TIME"
+    DATETIME = "DATETIME"
+    TIMESTAMP = "TIMESTAMP"
+    BLOB = "BLOB"
+    JSON = "JSON"
+    UUID = "UUID"
+
+
+class BaseDBModel(BaseModel):
+    """Base model with JSON serialization support"""
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True
+    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert model to dictionary"""
+        return self.model_dump(mode="json")
+
+    def to_json(self) -> str:
+        """Convert model to JSON string"""
+        return self.model_dump_json()
+
+    @classmethod
+    def from_json(cls, json_str: str) -> 'BaseDBModel':
+        """Create model instance from JSON string"""
+        data = json.loads(json_str)
+        return cls.model_validate(data)
+
+
+class TableColumn(BaseDBModel):
+    """Represents a database column definition"""
+    name: str
+    type: ColumnType
+    nullable: bool = True
+    primary_key: bool = False
+    unique: bool = False
+    default: Any = None
+    foreign_key: Optional[Dict[str, str]] = None
+
+
+class TableIndex(BaseDBModel):
+    """Represents a database index definition"""
+    name: str
+    columns: List[str]
+    unique: bool = False
+
+
+class TableForeignKey(BaseDBModel):
+    """Represents a foreign key constraint"""
+    name: str
+    columns: List[str]
+    reference_table: str
+    reference_columns: List[str]
+    on_delete: Optional[str] = None
+    on_update: Optional[str] = None
+
+
+class TableSchema(BaseDBModel):
+    """Represents a complete table schema"""
+    name: str
+    columns: List[TableColumn]
+    indexes: List[TableIndex] = Field(default_factory=list)
+    foreign_keys: List[TableForeignKey] = Field(default_factory=list)
+
+
+class Operator(str, Enum):
+    """SQL comparison operators"""
+    EQ = "="
+    NEQ = "!="
+    GT = ">"
+    GTE = ">="
+    LT = "<"
+    LTE = "<="
+    LIKE = "LIKE"  # Not supported in InMemoryDatabase
+    ILIKE = "ILIKE"  # Not supported in InMemoryDatabase
+    CONTAINS = "CONTAINS"  # Case-insensitive contains
+    CONTAINS_CS = "CONTAINS_CS"  # Case-sensitive contains
+    IN = "IN"
+    NOT_IN = "NOT IN"
+    IS_NULL = "IS NULL"
+    IS_NOT_NULL = "IS NOT NULL"
+    AND = "AND"
+    OR = "OR"
+
+
+class JoinType(str, Enum):
+    """SQL join types"""
+    INNER = "INNER JOIN"
+    LEFT = "LEFT JOIN"
+    RIGHT = "RIGHT JOIN"
+    FULL = "FULL JOIN"
+
+
+class OrderDirection(str, Enum):
+    """SQL order directions"""
+    ASC = "ASC"
+    DESC = "DESC"
+
+
+class Condition(BaseDBModel):
+    """A single SQL condition"""
+    column: str
+    operator: Operator
+    value: Optional[Any] = None
+    values: Optional[List[Any]] = None  # For IN/NOT IN operators
+
+
+class Join(BaseDBModel):
+    """SQL join definition"""
+    type: JoinType
+    table: str
+    conditions: List[Condition]
+
+
+class OrderBy(BaseDBModel):
+    """SQL ORDER BY clause"""
+    column: str
+    direction: OrderDirection = OrderDirection.ASC
+
+
+class WhereClause(BaseDBModel):
+    """SQL WHERE clause with conditions"""
+    conditions: List[Condition]
+    operator: Literal["AND", "OR"] = "AND"
+
+
+class SelectQuery(BaseDBModel):
+    """Complete SELECT query definition"""
+    table: str
+    columns: Optional[List[str]] = None
+    where: Optional[WhereClause] = None
+    joins: Optional[List[Join]] = None
+    order_by: Optional[List[OrderBy]] = None
+    group_by: Optional[List[str]] = None
+    having: Optional[WhereClause] = None
+    limit: Optional[int] = None
+    offset: Optional[int] = None
+
+
+class UpdateQuery(BaseDBModel):
+    """Complete UPDATE query definition"""
+    table: str
+    data: Dict[str, Any]
+    where: Optional[WhereClause] = None
+
+
+class DeleteQuery(BaseDBModel):
+    """Complete DELETE query definition"""
+    table: str
+    where: Optional[WhereClause] = None
+
+
+# Helper functions for JSON serialization
+def serialize_to_json(obj: Union[BaseDBModel, List[BaseDBModel], Dict[str, Any]]) -> str:
+    """Serialize any supported object to JSON string"""
+    if isinstance(obj, BaseDBModel):
+        return obj.to_json()
+    elif isinstance(obj, list):
+        return json.dumps([item.to_dict() if isinstance(item, BaseDBModel) else item for item in obj])
+    elif isinstance(obj, dict):
+        return json.dumps({k: v.to_dict() if isinstance(v, BaseDBModel) else v for k, v in obj.items()})
+    return json.dumps(obj)
+
+
+def deserialize_from_json(json_str: str, model_class: Type[BaseDBModel]) -> Union[BaseDBModel, List[BaseDBModel]]:
+    """Deserialize JSON string to model instance(s)"""
+    data = json.loads(json_str)
+    if isinstance(data, list):
+        return [model_class.model_validate(item) for item in data]
+    return model_class.model_validate(data)
+
+
+__all__ = [
+    "ColumnType",
+    "TableColumn",
+    "TableIndex",
+    "TableForeignKey",
+    "TableSchema",
+    "Operator",
+    "JoinType",
+    "OrderDirection",
+    "Condition",
+    "Join",
+    "OrderBy",
+    "WhereClause",
+    "SelectQuery",
+    "UpdateQuery",
+    "DeleteQuery",
+    "serialize_to_json",
+    "deserialize_from_json"
+]

danielutils/abstractions/db/database_exceptions.py

@@ -0,0 +1,34 @@
+from typing import Optional
+
+
+class DBException(Exception):
+    """Base class for all database exceptions"""
+
+    def __init__(self, message: Optional[str] = None, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class DBConnectionError(DBException):
+    """Raised when there is an error connecting to the database"""
+
+
+class DBQueryError(DBException):
+    """Raised when there is an error executing a query"""
+
+
+class DBSchemaError(DBException):
+    """Raised when there is an error with database schema operations"""
+
+
+class DBValidationError(DBException):
+    """Raised when there is a validation error"""
+
+
+__all__ = [
+    "DBException",
+    "DBConnectionError",
+    "DBQueryError",
+    "DBSchemaError",
+    "DBValidationError"
+]

danielutils/abstractions/db/database_factory.py

@@ -0,0 +1,70 @@
+from abc import ABC, abstractmethod
+import logging
+from typing import Literal, Dict, Any, Optional, Tuple
+from .database import Database
+from .implementations import InMemoryDatabase, SQLiteDatabase, PersistentInMemoryDatabase, RedisDatabase
+from ...logging_.utils import get_logger
+logger = get_logger(__name__)
+
+MAPPING = {
+    "sqlite": SQLiteDatabase,
+    "memory": InMemoryDatabase,
+    "persistent_memory": PersistentInMemoryDatabase,
+    "redis": RedisDatabase
+}
+
+
+class DatabaseFactory(ABC):
+    """Factory class for creating database instances"""
+
+    _instances: Dict[str, Database] = {}
+
+    @classmethod
+    def get_database(
+            cls,
+            db_type: Literal["sqlite", "memory", "persistent_memory", "redis"] = "persistent_memory",
+            db_args: Optional[Tuple[Any, ...]] = None,
+            db_kwargs: Optional[Dict[str, Any]] = None
+    ) -> Database:
+        """
+        Get a database instance based on the specified type. Returns existing instance if available.
+
+        Args:
+            db_args (Optional[Tuple[Any, ...]]): Positional arguments for database initialization
+            db_type (str): Type of database to create (default: "persistent_memory")
+                Supported types: "sqlite", "memory", "persistent_memory"
+            db_kwargs (Optional[Dict[str, Any]]): Keyword arguments for database initialization
+        Returns:
+            Database: Database instance
+        """
+        logger.debug("Requesting database instance: type=%s, args_count=%s, kwargs_count=%s", db_type, len(db_args) if db_args else 0, len(db_kwargs) if db_kwargs else 0)
+        
+        if db_type not in cls._instances:
+            logger.info("Creating new database instance: %s", db_type)
+            if db_type not in MAPPING:
+                logger.error("Unsupported database type requested: %s", db_type)
+                raise ValueError(f"Unsupported database type: '{db_type}'")
+
+            # Convert None to empty tuple/dict for database initialization
+            args = db_args or ()
+            kwargs = db_kwargs or {}
+            logger.debug("Initializing %s database with args=%s, kwargs=%s", db_type, args, kwargs)
+            cls._instances[db_type] = MAPPING[db_type](*args, **kwargs)
+            logger.info("Database instance created successfully: %s", db_type)
+        else:
+            logger.debug("Returning existing database instance: %s", db_type)
+        
+        return cls._instances[db_type]
+
+    @classmethod
+    @abstractmethod
+    def get_database_from_settings(cls) -> Database:
+        """
+        Get a database instance using the application settings.
+        This is the preferred method for getting a database instance in the application.
+        """
+
+
+__all__ = [
+    "DatabaseFactory"
+]