maleo-foundation 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

maleo_foundation/clients/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+from .general import BaseGeneralClients
+from .google import GoogleClients
+
+class BaseClients:
+    General = BaseGeneralClients
+    Google = GoogleClients

maleo_foundation/clients/general/__init__.py

@@ -0,0 +1,4 @@
+from .http import HTTPClientManager
+
+class BaseGeneralClients:
+    HTTP = HTTPClientManager

maleo_foundation/clients/general/http.py

@@ -0,0 +1,41 @@
+import httpx
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator, Optional
+
+class HTTPClientManager:
+    _client:Optional[httpx.AsyncClient] = None
+
+    @classmethod
+    def initialize(cls) -> None:
+        """Initialize the HTTP client if not already initialized."""
+        if cls._client is None:
+            cls._client = httpx.AsyncClient()
+
+    @classmethod
+    async def _client_handler(cls) -> AsyncGenerator[httpx.AsyncClient, None]:
+        """Reusable generator for client handling."""
+        if cls._client is None:
+            raise RuntimeError("Client has not been initialized. Call initialize first.")
+
+        yield cls._client
+
+    @classmethod
+    async def inject(cls) -> AsyncGenerator[httpx.AsyncClient, None]:
+        return cls._client_handler()
+
+    @classmethod
+    @asynccontextmanager
+    async def get(cls) -> AsyncGenerator[httpx.AsyncClient, None]:
+        """
+        Async context manager for manual HTTP client handling.
+        Supports `async with HTTPClientManager.get() as client:`
+        """
+        async for client in cls._client_handler():
+            yield client
+
+    @classmethod
+    async def dispose(cls) -> None:
+        """Dispose of the HTTP client and release any resources."""
+        if cls._client is not None:
+            await cls._client.aclose()
+            cls._client = None

maleo_foundation/clients/google/__init__.py

@@ -0,0 +1,4 @@
+from .cloud import GoogleCloudClients
+
+class GoogleClients:
+    Cloud = GoogleCloudClients

maleo_foundation/clients/google/cloud/__init__.py

@@ -0,0 +1,8 @@
+from .logging import GoogleCloudLogging
+from .secret import GoogleSecretManager
+from .storage import GoogleCloudStorage
+
+class GoogleCloudClients:
+    Logging = GoogleCloudLogging
+    Secret = GoogleSecretManager
+    Storage = GoogleCloudStorage

maleo_foundation/clients/google/cloud/logging.py

@@ -0,0 +1,45 @@
+import os
+from google.auth import default
+from google.cloud.logging import Client
+from google.cloud.logging.handlers import CloudLoggingHandler
+from google.oauth2 import service_account
+from typing import Optional
+
+class GoogleCloudLogging:
+    _client:Optional[Client] = None
+
+    @classmethod
+    def initialize(cls) -> Client:
+        """Initialize the cloud logging if not already initialized."""
+        if cls._client is None:
+            #* Setup credentials with fallback chain
+            credentials = None
+            credentials_file = os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
+            try:
+                if credentials_file:
+                    credentials = service_account.Credentials.from_service_account_file(credentials_file)
+                else:
+                    credentials, _ = default()
+            except Exception as e:
+                raise ValueError(f"Failed to initialize credentials: {str(e)}")
+
+            cls._client = Client(credentials=credentials)
+            cls._client.setup_logging()
+
+    @classmethod
+    def dispose(cls) -> None:
+        """Dispose of the cloud logging and release any resources."""
+        if cls._client is not None:
+            cls._client.close()
+            cls._client = None
+
+    @classmethod
+    def _get_client(cls) -> Client:
+        """Retrieve the cloud logging client, initializing it if necessary."""
+        cls.initialize()
+        return cls._client
+
+    @classmethod
+    def create_handler(cls, name:str):
+        cls.initialize()
+        return CloudLoggingHandler(client=cls._client, name=name)

maleo_foundation/clients/google/cloud/secret.py

@@ -0,0 +1,92 @@
+import os
+from google.api_core import retry
+from google.api_core.exceptions import NotFound
+from google.auth import default
+from google.cloud import secretmanager
+from google.oauth2 import service_account
+from typing import Optional
+
+class GoogleSecretManager:
+    _project:Optional[str] = None
+    _client:Optional[secretmanager.SecretManagerServiceClient] = None
+
+    @classmethod
+    def initialize(cls, project_id:Optional[str] = None) -> None:
+        """Initialize the cloud storage if not already initialized."""
+        cls._project = project_id or os.getenv("GCP_PROJECT_ID")
+        if cls._project is None:
+            raise ValueError("GCP_PROJECT_ID environment variable must be set if no project_id is provided")
+        if cls._client is None:
+            #* Setup credentials with fallback chain
+            credentials = None
+            credentials_file = os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
+            try:
+                if credentials_file:
+                    credentials = service_account.Credentials.from_service_account_file(credentials_file)
+                else:
+                    credentials, _ = default()
+            except Exception as e:
+                raise ValueError(f"Failed to initialize credentials: {str(e)}")
+
+            cls._client = secretmanager.SecretManagerServiceClient(credentials=credentials)
+
+    @classmethod
+    def dispose(cls):
+        """Disposes of the Google Secret Manager client"""
+        if cls._client is not None:
+            cls._client = None
+        if cls._project is not None:
+            cls._project = None
+
+    @classmethod
+    @retry.Retry(
+        predicate=retry.if_exception_type(Exception),
+        timeout=5
+    )
+    def get(
+        cls,
+        name:str,
+        version:str = "latest",
+    ) -> Optional[str]:
+        try:
+            secret_path = f"projects/{cls._project}/secrets/{name}/versions/{version}"
+            request = secretmanager.AccessSecretVersionRequest(name=secret_path)
+            response = cls._client.access_secret_version(request=request)
+            return response.payload.data.decode()
+        except Exception as e:
+            return None
+
+    @classmethod
+    @retry.Retry(
+        predicate=retry.if_exception_type(Exception),
+        timeout=5
+    )
+    def create(
+        cls,
+        name:str,
+        data:str
+    ) -> Optional[str]:
+        parent = f"projects/{cls._project}"
+        secret_path = f"{parent}/secrets/{name}"
+        try:
+            #* Check if the secret already exists
+            request = secretmanager.GetSecretRequest(name=secret_path)
+            cls._client.get_secret(request=request)
+
+        except NotFound:
+            #* Secret does not exist, create it first
+            try:
+                secret = secretmanager.Secret(name=name, replication={"automatic": {}})
+                request = secretmanager.CreateSecretRequest(parent=parent, secret_id=name, secret=secret)
+                cls._client.create_secret(request=request)
+            except Exception as e:
+                return None
+
+        #* Add a new secret version
+        try:
+            payload = secretmanager.SecretPayload(data=data.encode())  # ✅ Fixed attribute name
+            request = secretmanager.AddSecretVersionRequest(parent=secret_path, payload=payload)
+            response = cls._client.add_secret_version(request=request)
+            return data
+        except Exception as e:
+            return None

maleo_foundation/clients/google/cloud/storage.py

@@ -0,0 +1,77 @@
+import os
+from datetime import timedelta
+from google.auth import default
+from google.cloud.storage import Bucket, Client
+from google.oauth2 import service_account
+from typing import Optional
+
+class GoogleCloudStorage:
+    _client:Optional[Client] = None
+    _bucket:Optional[Bucket] = None
+
+    @classmethod
+    def initialize(cls) -> None:
+        """Initialize the cloud storage if not already initialized."""
+        if cls._client is None:
+            #* Setup credentials with fallback chain
+            credentials = None
+            credentials_file = os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
+            try:
+                if credentials_file:
+                    credentials = service_account.Credentials.from_service_account_file(credentials_file)
+                else:
+                    credentials, _ = default()
+            except Exception as e:
+                raise ValueError(f"Failed to initialize credentials: {str(e)}")
+
+            cls._client = Client(credentials=credentials)
+
+            #* Preload bucket
+            bucket_name = os.getenv("GCS_BUCKET_NAME")
+            if not bucket_name:
+                cls._client.close()
+                raise ValueError("GCS_BUCKET_NAME environment variable must be set")
+
+            #* Validate bucket existence
+            bucket = cls._client.lookup_bucket(bucket_name)
+            if bucket is None:
+                raise ValueError(f"Bucket '{bucket_name}' does not exist.")
+
+            cls._bucket = bucket
+
+    @classmethod
+    def dispose(cls) -> None:
+        """Dispose of the cloud storage and release any resources."""
+        if cls._client is not None:
+            cls._client.close()
+            cls._client = None
+            cls._bucket = None
+
+    @classmethod
+    def _get_client(cls) -> Client:
+        """Retrieve the cloud storage client, initializing it if necessary."""
+        cls.initialize()
+        return cls._client
+
+    @classmethod
+    def generate_signed_url(cls, location:str) -> str:
+        """
+        generate signed URL of a file in the bucket based on its location.
+
+        Args:
+            location: str
+                Location of the file inside the bucket
+
+        Returns:
+            str: File's pre-signed download url
+
+        Raises:
+            ValueError: If the file does not exist
+        """
+        cls.initialize()
+        blob = cls._bucket.blob(blob_name=location)
+        if not blob.exists():
+            raise ValueError(f"File '{location}' did not exists.")
+
+        url = blob.generate_signed_url(version="v4", expiration=timedelta(minutes=15), method="GET")
+        return url

maleo_foundation/constants.py

@@ -0,0 +1,8 @@
+import re
+
+EMAIL_REGEX:str = r"^[^\s@]+@[^\s@]+\.[^\s@]+$"
+TOKEN_COOKIE_KEY_NAME="token"
+REFRESH_TOKEN_DURATION_DAYS:int = 7
+ACCESS_TOKEN_DURATION_MINUTES:int = 5
+SORT_COLUMN_PATTERN = re.compile(r'^[a-z_]+\.(asc|desc)$')
+DATE_FILTER_PATTERN = re.compile(r'^[a-z_]+(?:\|from::\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))?(?:\|to::\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))?$')

maleo_foundation/controller.py

@@ -0,0 +1,50 @@
+from fastapi import status
+from typing import Type, Any
+from maleo_foundation.models.enums import BaseEnums
+from maleo_foundation.models.responses import BaseResponses
+from maleo_foundation.models.transfers.results.service.controllers.rest import BaseServiceRESTControllerResults
+from maleo_foundation.models.transfers.parameters.service import BaseServiceParametersTransfers
+from maleo_foundation.models.types.service import BaseServiceTypes
+
+class BaseController:
+    @staticmethod
+    def check_unique_existence(
+        check:BaseServiceParametersTransfers.UniqueFieldCheck,
+        get_single_parameters_class:Type[BaseServiceTypes.GetSingleParameter],
+        get_single_service_function:BaseServiceTypes.SyncGetSingleFunction,
+        create_failed_response_class:Type[BaseResponses.Fail],
+        update_failed_response_class:Type[BaseResponses.Fail],
+        **additional_get_parameters:Any
+    ) -> BaseServiceRESTControllerResults:
+        """Generic helper function to check if a unique value exists in the database."""
+
+        #* Return early if nullable and no new value
+        if check.nullable and check.new_value is None:
+            return BaseServiceRESTControllerResults(success=True, content=None)
+
+        #* Return early if values are unchanged on update
+        if check.operation == BaseEnums.OperationType.UPDATE and check.old_value == check.new_value:
+            return BaseServiceRESTControllerResults(success=True, content=None)
+
+        #* Prepare parameters to query for existing data
+        get_single_parameters = get_single_parameters_class(identifier=check.field, value=check.new_value)
+
+        #* Query the existing data using provided function
+        service_result:BaseServiceTypes.GetSingleResult = get_single_service_function(parameters=get_single_parameters, **additional_get_parameters)
+        if not service_result.success:
+            content = BaseResponses.ServerError.model_validate(service_result.model_dump(exclude_unset=True)).model_dump()
+            return BaseServiceRESTControllerResults(success=False, content=content, status_code=status.HTTP_500_INTERNAL_SERVER_ERROR)
+
+        #* Handle case if duplicate is found
+        if service_result.data:
+            description = f"External error: {check.field} of '{check.new_value}' already exists in the database"
+            other = check.suggestion or f"Select another {check.field} value"
+            if check.operation == BaseEnums.OperationType.CREATE:
+                content = create_failed_response_class(description=description, other=other).model_dump()
+            elif check.operation == BaseEnums.OperationType.UPDATE:
+                content = update_failed_response_class(description=description, other=other).model_dump()
+
+            return BaseServiceRESTControllerResults(success=False, content=content, status_code=status.HTTP_400_BAD_REQUEST)
+
+        #* No duplicates found
+        return BaseServiceRESTControllerResults(success=True, content=None)

maleo_foundation/db/__init__.py

@@ -0,0 +1,3 @@
+from .database import DatabaseManager
+from .engine import EngineManager
+from .session import SessionManager

maleo_foundation/db/database.py

@@ -0,0 +1,41 @@
+from sqlalchemy import Engine, MetaData, Column, Integer, UUID, TIMESTAMP, Enum, func
+from sqlalchemy.orm import declarative_base, declared_attr
+from uuid import uuid4
+from maleo_foundation.models.enums import BaseEnums
+from maleo_foundation.utils.formatter.case import CaseFormatter
+
+Base = declarative_base()  #* Correct way to define a declarative base
+
+class DatabaseManager:
+    class Base(Base):  #* Inheriting from declarative_base
+        __abstract__ = True  #* Ensures this class is not treated as a table itself
+
+        @declared_attr
+        def __tablename__(cls) -> str:
+            """Automatically generates table name (in snake_case) based on class name."""
+            return CaseFormatter.to_snake_case(cls.__name__)
+
+        #* ----- ----- Common columns definition ----- ----- *#
+
+        #* Identifiers
+        id = Column(name="id", type_=Integer, primary_key=True)
+        uuid = Column(name="uuid", type_=UUID, default=uuid4, unique=True, nullable=False)
+
+        #* Timestamps
+        created_at = Column(name="created_at", type_=TIMESTAMP(timezone=True), server_default=func.now(), nullable=False)
+        updated_at = Column(name="updated_at", type_=TIMESTAMP(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+        deleted_at = Column(name="deleted_at", type_=TIMESTAMP(timezone=True))
+        restored_at = Column(name="restored_at", type_=TIMESTAMP(timezone=True))
+        deactivated_at = Column(name="deactivated_at", type_=TIMESTAMP(timezone=True))
+        activated_at = Column(name="activated_at", type_=TIMESTAMP(timezone=True), server_default=func.now(), nullable=False)
+
+        #* Statuses
+        status = Column(name="status", type_=Enum(BaseEnums.StatusType, name="statustype"), default=BaseEnums.StatusType.ACTIVE, nullable=False)
+
+    #* Explicitly define the type of metadata
+    metadata:MetaData = Base.metadata
+
+    @staticmethod
+    def initialize(engine: Engine):
+        """Creates the database tables if they do not exist."""
+        DatabaseManager.metadata.create_all(engine)

maleo_foundation/db/engine.py

@@ -0,0 +1,40 @@
+import os
+from sqlalchemy import create_engine, Engine
+from typing import Optional
+from maleo_foundation.utils.logger import BaseLogger
+
+class EngineManager:
+    _logger:Optional[BaseLogger] = None
+    _engine:Optional[Engine] = None
+
+    @classmethod
+    def initialize(cls, logger:BaseLogger, url:Optional[str] = None) -> Engine:
+        """Initialize the engine if not already initialized."""
+        if cls._engine is None:
+            cls._logger = logger
+            url = url or os.getenv("DB_CONNECTION_STRING")
+            if url is None:
+                raise ValueError("DB_CONNECTION_STRING environment variable must be set if url is not provided")
+            cls._engine = create_engine(url=url, echo=False, pool_pre_ping=True, pool_recycle=3600)
+            cls._logger.info("EngineManager initialized successfully.")
+        return cls._engine
+
+    @classmethod
+    def get(cls) -> Engine:
+        """Retrieve the engine, initializing it if necessary."""
+        if cls._logger is None:
+            raise RuntimeError("Logger has not been initialized. Call initialize(db_connection_string, logger) first.")
+        if cls._engine is None:
+            raise RuntimeError("Engine has not been initialized. Call initialize(db_connection_string, logger) first.")
+
+        return cls._engine
+
+    @classmethod
+    def dispose(cls) -> None:
+        """Dispose of the engine and release any resources."""
+        if cls._engine is not None:
+            cls._engine.dispose()
+            cls._engine = None
+
+        cls._logger.info("Engine disposed successfully.")
+        cls._logger = None

maleo_foundation/db/session.py

@@ -0,0 +1,64 @@
+from contextlib import contextmanager
+from sqlalchemy import Engine
+from sqlalchemy.orm import sessionmaker, Session
+from sqlalchemy.exc import SQLAlchemyError
+from typing import Generator, Optional
+from maleo_foundation.utils.logger import BaseLogger
+
+class SessionManager:
+    _logger:Optional[BaseLogger] = None
+    _sessionmaker:Optional[sessionmaker[Session]] = None
+
+    @classmethod
+    def initialize(cls, logger:BaseLogger, engine:Engine) -> None:
+        """Initialize the sessionmaker if not already initialized."""
+        if cls._sessionmaker is None:
+            cls._logger = logger
+            cls._sessionmaker = sessionmaker(bind=engine, expire_on_commit=False)
+            cls._logger.info("SessionManager initialized successfully.")
+
+    @classmethod
+    def _session_handler(cls) -> Generator[Session, None, None]:
+        """Reusable function for managing database sessions."""
+        if cls._logger is None:
+            raise RuntimeError("Logger has not been initialized. Call initialize() first.")
+        if cls._sessionmaker is None:
+            raise RuntimeError("SessionLocal has not been initialized. Call initialize() first.")
+
+        session = cls._sessionmaker()
+        cls._logger.debug("New database session created.")
+        try:
+            yield session  #* Provide session
+            session.commit()  #* Auto-commit on success
+        except SQLAlchemyError as e:
+            session.rollback()  #* Rollback on error
+            cls._logger.error(f"[SQLAlchemyError] Database transaction failed: {e}", exc_info=True)
+            raise
+        except Exception as e:
+            session.rollback()  #* Rollback on error
+            cls._logger.error(f"[Exception] Database transaction failed: {e}", exc_info=True)
+            raise
+        finally:
+            session.close()  #* Ensure session closes
+            cls._logger.debug("Database session closed.")
+
+    @classmethod
+    def inject(cls) -> Generator[Session, None, None]:
+        """Returns a generator that yields a SQLAlchemy session for dependency injection."""
+        return cls._session_handler()
+
+    @classmethod
+    @contextmanager
+    def get(cls) -> Generator[Session, None, None]:
+        """Context manager for manual session handling. Supports `with SessionManager.get() as session:`"""
+        yield from cls._session_handler()
+
+    @classmethod
+    def dispose(cls) -> None:
+        """Dispose of the sessionmaker and release any resources."""
+        if cls._sessionmaker is not None:
+            cls._sessionmaker.close_all()
+            cls._sessionmaker = None
+
+        cls._logger.info("SessionManager disposed successfully.")
+        cls._logger = None

maleo_foundation/models/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+from .enums import BaseEnums
+from .schemas import BaseSchemas
+from .transfers import BaseTransfers
+from .responses import BaseResponses
+from .types import BaseTypes
+
+class BaseModels:
+    Enums = BaseEnums
+    Schemas = BaseSchemas
+    Transfers = BaseTransfers
+    Responses = BaseResponses
+    Types = BaseTypes

maleo_foundation/models/enums.py

@@ -0,0 +1,66 @@
+import logging
+from enum import IntEnum, StrEnum
+from fastapi import responses
+
+class BaseEnums:
+    class StatusType(StrEnum):
+        DELETED = "deleted"
+        INACTIVE = "inactive"
+        ACTIVE = "active"
+
+    class UserType(StrEnum):
+        REGULAR = "regular"
+        PROXY = "proxy"
+
+    class SortOrder(StrEnum):
+        ASC = "asc"
+        DESC = "desc"
+
+    class StatusUpdateAction(StrEnum):
+        ACTIVATE = "activate"
+        DEACTIVATE = "deactivate"
+        RESTORE = "restore"
+        DELETE = "delete"
+
+    class TokenType(StrEnum):
+        REFRESH = "refresh"
+        ACCESS = "access"
+
+    class OperationType(StrEnum):
+        CREATE = "create"
+        UPDATE = "update"
+
+    class UniqueIdentifiers(StrEnum):
+        ID = "id"
+        UUID = "uuid"
+
+    class RESTControllerResponseType(StrEnum):
+        NONE = "none"
+        HTML = "html"
+        TEXT = "text"
+        JSON = "json"
+        REDIRECT = "redirect"
+        STREAMING = "streaming"
+        FILE = "file"
+
+        def get_response_type(self) -> type[responses.Response]:
+            """Returns the corresponding FastAPI Response type."""
+            return {
+                BaseEnums.RESTControllerResponseType.NONE: responses.Response,
+                BaseEnums.RESTControllerResponseType.HTML: responses.HTMLResponse,
+                BaseEnums.RESTControllerResponseType.TEXT: responses.PlainTextResponse,
+                BaseEnums.RESTControllerResponseType.JSON: responses.JSONResponse,
+                BaseEnums.RESTControllerResponseType.REDIRECT: responses.RedirectResponse,
+                BaseEnums.RESTControllerResponseType.STREAMING: responses.StreamingResponse,
+                BaseEnums.RESTControllerResponseType.FILE: responses.FileResponse,
+            }.get(self, responses.Response)
+
+    class LoggerLevel(IntEnum):
+        CRITICAL = logging.CRITICAL
+        FATAL = logging.FATAL
+        ERROR = logging.ERROR
+        WARNING = logging.WARNING
+        WARN = logging.WARN
+        INFO = logging.INFO
+        DEBUG = logging.DEBUG
+        NOTSET = logging.NOTSET