dtpyfw 0.0.1__tar.gz

dtpyfw-0.0.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.3
+Name: dtpyfw
+Version: 0.0.1
+Summary: DealerTower Python Framework: reusable building‑blocks for DealerTower services
+Author: Reza Shirazi
+Author-email: reza@dealertower.com
+Requires-Python: >=3.11.9,<3.12.0
+Classifier: Programming Language :: Python :: 3
+Provides-Extra: all
+Provides-Extra: api
+Provides-Extra: bucket
+Provides-Extra: db
+Provides-Extra: ftp
+Provides-Extra: normal
+Provides-Extra: redis
+Provides-Extra: security
+Provides-Extra: streamer
+Provides-Extra: worker
+Requires-Dist: SQLAlchemy (>=2.0.39,<2.1.0) ; extra == "all" or extra == "normal" or extra == "db"
+Requires-Dist: asyncpg (>=0.30.0,<0.31.0) ; extra == "all" or extra == "normal" or extra == "db"
+Requires-Dist: boto3 (>=1.37.19,<1.38.0) ; extra == "all" or extra == "bucket"
+Requires-Dist: botocore (>=1.37.19,<1.38.0) ; extra == "all" or extra == "bucket"
+Requires-Dist: celery (>=5.4.0,<5.5.0) ; extra == "all" or extra == "normal" or extra == "worker"
+Requires-Dist: celery-redbeat (>=2.3.2,<2.4.0) ; extra == "all" or extra == "normal" or extra == "worker"
+Requires-Dist: fastapi (>=0.115.12,<0.116.0) ; extra == "all" or extra == "normal" or extra == "api"
+Requires-Dist: gunicorn (>=23.0.0,<23.1.0) ; extra == "all" or extra == "normal" or extra == "api"
+Requires-Dist: paramiko (>=3.5.1,<3.6.0) ; extra == "all" or extra == "ftp"
+Requires-Dist: passlib[bcrypt] (>=1.7.4,<1.8.0) ; extra == "all" or extra == "security"
+Requires-Dist: psycopg2 (>=2.9.10,<2.10.0) ; extra == "all" or extra == "normal" or extra == "db"
+Requires-Dist: python-dateutil (>=2.9.0,<2.10.0) ; extra == "all" or extra == "ftp"
+Requires-Dist: python-jose (>=3.4.0,<3.5.0) ; extra == "all" or extra == "security"
+Requires-Dist: python-multipart (>=0.0.18,<0.1.0) ; extra == "all" or extra == "normal" or extra == "api"
+Requires-Dist: redis (>=5.2.1,<5.3.0) ; extra == "all" or extra == "normal" or extra == "redis" or extra == "streamer" or extra == "worker"
+Requires-Dist: requests (>=2.32.3,<2.33.0)
+Requires-Dist: uvicorn (>=0.34.0,<0.35.0) ; extra == "all" or extra == "normal" or extra == "api"
+Description-Content-Type: text/markdown
+
+# Dealer Tower Python Framework
+
+DealerTower Framework: reusable building‑blocks for DealerTower services
+
+## Installation
+
+You can install the package via pip:
+
+```bash
+pip install dtpyfw
+```
+

dtpyfw-0.0.1/README.md

@@ -0,0 +1,11 @@
+# Dealer Tower Python Framework
+
+DealerTower Framework: reusable building‑blocks for DealerTower services
+
+## Installation
+
+You can install the package via pip:
+
+```bash
+pip install dtpyfw
+```

dtpyfw-0.0.1/dtpyfw/api/__init__.py

@@ -0,0 +1,3 @@
+from ..core.require_extra import require_extra
+
+require_extra("api", "fastapi", "starlette", "pydantic")

dtpyfw-0.0.1/dtpyfw/api/applications/main.py

@@ -0,0 +1,105 @@
+from fastapi import FastAPI
+from fastapi.responses import RedirectResponse
+from fastapi.middleware.cors import CORSMiddleware
+
+from .sub import SubApp
+
+
+class MainApp:
+    def __init__(
+        self,
+        application_title: str,
+        applications: list[tuple[str, SubApp]],
+        startups: list[callable] = None,
+        shutdowns: list[callable] = None,
+        version: str = "*",
+        redirection_path: str = None,
+        redoc_url: str | None = None,
+        docs_url: str | None = None,
+        allow_credentials: bool = False,
+        allow_methods: list[str] | None = None,
+        allow_headers: list[str] | None = None,
+        allow_origins: list[str] | None = None,
+        allow_origin_regex: str | None = None,
+        expose_headers: list[str] | None = None,
+        access_control_max_age: int = 600,
+    ):
+        """
+        Initialize a MainApp instance and create the FastAPI application.
+        """
+        self.application_title = application_title
+        self.applications = applications
+        self.version = version
+        self.redirection_path = redirection_path
+        self.redoc_url = redoc_url
+        self.docs_url = docs_url
+        self.allow_credentials = allow_credentials
+        self.startups = startups or []
+        self.shutdowns = shutdowns or []
+        self.allow_methods = allow_methods or ["*"]
+        self.allow_headers = allow_headers or ["*"]
+        self.allow_origins = allow_origins or ["*"]
+        self.allow_origin_regex = allow_origin_regex
+        self.expose_headers = expose_headers or []
+        self.access_control_max_age = access_control_max_age
+        self.app = self._create_app()
+
+    def _create_app(self) -> FastAPI:
+        """
+        Create and configure the FastAPI application.
+        """
+
+        # Default redirection path
+        if self.redirection_path is None and self.applications:
+            self.redirection_path = self.applications[0][0]
+
+        # Initialize FastAPI app
+        app = FastAPI(
+            title=self.application_title,
+            version=self.version,
+            redoc_url=self.redoc_url,
+            docs_url=self.docs_url,
+            swagger_ui_parameters={"defaultModelsExpandDepth": -1},
+        )
+
+        # Startup event handlers
+        @app.on_event("startup")
+        async def startup():
+            for startup_application in self.startups:
+                startup_application()
+
+        # Shutdown event handlers
+        @app.on_event("shutdown")
+        async def shutdown_event():
+            for shutdown_application in self.shutdowns:
+                shutdown_application()
+
+        # Add CORS middleware
+        app.add_middleware(
+            CORSMiddleware,
+            allow_credentials=self.allow_credentials,
+            allow_methods=self.allow_methods,
+            allow_headers=self.allow_headers,
+            allow_origins=self.allow_origins,
+            allow_origin_regex=self.allow_origin_regex,
+            expose_headers=self.expose_headers,
+            max_age=self.access_control_max_age,
+        )
+
+        # Mount sub-applications
+        for path, application in self.applications:
+            app.mount(path, application.get_app())
+
+        # Redirect root to the specified path
+        if self.redirection_path:
+            @app.get("/", status_code=302)
+            async def redirect():
+                return RedirectResponse(self.redirection_path)
+
+        return app
+
+    def get_app(self) -> FastAPI:
+        """
+        Get the created FastAPI application instance.
+        """
+        return self.app

dtpyfw-0.0.1/dtpyfw/api/applications/sub.py

@@ -0,0 +1,87 @@
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from ..middlewares import runtime, http_exception, validation_exception
+from ..routes.router import Router
+
+
+class SubApp:
+    def __init__(
+        self,
+        application_title: str,
+        version: str = "*",
+        redoc_url: str = "/",
+        docs_url: str = "/swagger",
+        middlewares: list = None,
+        routers: list[Router] = None,
+        gzip_compression: int = None,
+        session_middleware_settings: dict = None,
+    ):
+        """
+        Initialize a SubApp instance and create the FastAPI application.
+        """
+        self.application_title = application_title
+        self.version = version
+        self.redoc_url = redoc_url
+        self.docs_url = docs_url
+        self.middlewares = middlewares or []
+        self.routers = routers or []
+        self.gzip_compression = gzip_compression
+        self.session_middleware_settings = session_middleware_settings or {}
+        self.app = self._create_app()
+
+    def _create_app(self) -> FastAPI:
+        """
+        Create and configure a FastAPI application.
+        """
+        app = FastAPI(
+            title=self.application_title,
+            version=self.version,
+            redoc_url=self.redoc_url,
+            docs_url=self.docs_url,
+            swagger_ui_parameters={"defaultModelsExpandDepth": -1},
+        )
+
+        # Add GZip middleware
+        if self.gzip_compression is not None:
+            from fastapi.middleware.gzip import GZipMiddleware
+            app.add_middleware(GZipMiddleware, minimum_size=self.gzip_compression)
+
+        # Add custom middlewares
+        applicable_middlewares = [runtime.Runtime()] + self.middlewares
+        for middleware in applicable_middlewares:
+            app.add_middleware(BaseHTTPMiddleware, dispatch=middleware)
+
+        # Add session middleware if settings provided
+        if self.session_middleware_settings:
+            from starlette.middleware.sessions import SessionMiddleware
+            app.add_middleware(
+                SessionMiddleware,
+                secret_key=self.session_middleware_settings.get("secret_key"),
+                session_cookie=self.session_middleware_settings.get("session_cookie"),
+                https_only=self.session_middleware_settings.get("https_only"),
+                same_site=self.session_middleware_settings.get("same_site"),
+            )
+
+        # Exception handlers
+        @app.exception_handler(StarletteHTTPException)
+        async def http_exception_handler(request, exc):
+            return await http_exception.http_exception_handler(request, exc)
+
+        @app.exception_handler(RequestValidationError)
+        async def validation_exception_handler(request, exc):
+            return await validation_exception.validation_exception_handler(request, exc)
+
+        # Add routers
+        for router in self.routers:
+            app.include_router(router=router.get_router())
+
+        return app
+
+    def get_app(self) -> FastAPI:
+        """
+        Get the created FastAPI application instance.
+        """
+        return self.app

dtpyfw-0.0.1/dtpyfw/api/middlewares/http_exception.py

@@ -0,0 +1,13 @@
+from fastapi.responses import JSONResponse
+
+from ..routes.response import return_response
+
+
+async def http_exception_handler(request, exc):
+    status_code = exc.status_code
+    detail = request.url.path if status_code == 404 else exc.detail
+    return return_response(
+        data=str(detail),
+        status_code=status_code,
+        response_class=JSONResponse,
+    )

dtpyfw-0.0.1/dtpyfw/api/middlewares/runtime.py

@@ -0,0 +1,91 @@
+import time
+from fastapi import Request
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse
+
+from ...core.exception import exception_to_dict, RequestException
+
+from ..routes.response import return_response
+from ...log import footprint
+
+
+class Runtime:
+
+    def __init__(self):
+        pass
+
+    @staticmethod
+    async def get_request_body(request: Request) -> dict:
+        content_length = request.headers.get('content-length')
+        content_type = request.headers.get('content-type')
+        try:
+            if content_length and int(content_length) > (1 * 1024 * 1024):
+                return {}
+            body = await request.body()
+            return {
+                'content_length': content_length,
+                'content_type': content_type,
+                'json': jsonable_encoder(body.decode('utf-8')),
+            }
+        except Exception:
+            return {
+                'content_length': content_length,
+                'content_type': content_type,
+            }
+
+    @staticmethod
+    async def create_payload(request: Request, exception: Exception) -> dict:
+        body = await Runtime.get_request_body(request)
+        return jsonable_encoder({
+            'path': request.url.path,
+            'method': request.method,
+            'query_parameters': request.query_params,
+            'path_parameters': request.path_params,
+            'headers': request.headers,
+            'body': body,
+            **exception_to_dict(exception),
+        })
+
+    async def __call__(self, request: Request, call_next):
+        start_time = time.time()
+        try:
+            response = await call_next(request)
+        except RequestException as e:
+            payload = await self.create_payload(request, e)
+            if not e.skip_footprint:
+                footprint.leave(
+                    log_type='warning',
+                    message=e.message,
+                    controller=e.controller,
+                    subject='Request Error',
+                    payload=payload,
+                )
+
+            return return_response(
+                data=str(e.message),
+                status_code=e.status_code,
+                response_class=JSONResponse,
+            )
+        except Exception as e:
+            payload = await self.create_payload(request, e)
+            try:
+                message = payload.get('args', ['Unrecognized Error'])[0]
+            except:
+                message = 'Unrecognized Error has happened.'
+
+            footprint.leave(
+                log_type='error',
+                message=message,
+                controller='runtime',
+                subject='Unrecognized Error',
+                payload=payload,
+            )
+
+            return return_response(
+                data='An unexpected issue has occurred; our team has been notified and is working diligently to resolve it promptly.',
+                status_code=500,
+                response_class=JSONResponse,
+            )
+        else:
+            response.headers["X-Process-Time"] = str(round((time.time() - start_time) * 1000))
+            return response

dtpyfw-0.0.1/dtpyfw/api/middlewares/validation_exception.py

@@ -0,0 +1,23 @@
+import json
+from fastapi.responses import JSONResponse
+
+from ..routes.response import return_response
+
+
+async def validation_exception_handler(_, exc):
+    error = ''
+    for error in exc.errors():
+        location = " -> ".join([str(l) for l in error["loc"]])
+        try:
+            input_data = ', input: ' + json.dumps(error['input'], default=str)
+        except:
+            input_data = ''
+
+        error = f"Error [location: '{location}'; message: '{error['msg']}'{input_data}'."
+        break
+
+    return return_response(
+        data=error,
+        status_code=422,
+        response_class=JSONResponse,
+    )

dtpyfw-0.0.1/dtpyfw/api/routes/authentication.py

@@ -0,0 +1,65 @@
+from dataclasses import dataclass
+from enum import Enum
+from fastapi import Depends, Request
+from fastapi.security import APIKeyHeader, APIKeyQuery
+
+from ...core.exception import RequestException
+
+
+class AuthType(Enum):
+    HEADER = "header"
+    QUERY = "query"
+
+
+@dataclass
+class Auth:
+    auth_type: AuthType
+    header_key: str | None = None
+    real_value: str | None = None
+
+
+class HeaderAuthChecker:
+    def __init__(self, key: str, real_value: str):
+        self.key = key
+        self.real_value = real_value
+
+    def __call__(self, request: Request):
+        auth_token = request.headers.get(self.key)
+        if auth_token is None or auth_token != self.real_value:
+            raise RequestException(
+                controller='dtpyfw.middlewares.authentication.header',
+                message='Wrong credential.',
+                status_code=403,
+            )
+
+
+class QueryAuthChecker:
+    def __init__(self, key: str, real_value: str):
+        self.key = key
+        self.real_value = real_value
+
+    def __call__(self, request: Request):
+        auth_token = request.query_params.get(self.key)
+        if auth_token is None or auth_token != self.real_value:
+            raise RequestException(
+                controller='dtpyfw.middlewares.authentication.query',
+                message='Wrong credential.',
+                status_code=403,
+            )
+
+
+def auth_data_class_to_dependency(authentication: Auth) -> list[Depends]:
+    if authentication.auth_type == AuthType.HEADER:
+        checker = HeaderAuthChecker(key=authentication.header_key, real_value=authentication.real_value)
+        return [
+            Depends(checker),
+            Depends(APIKeyHeader(name=authentication.header_key)),
+        ]
+    elif authentication.auth_type == AuthType.QUERY:
+        checker = QueryAuthChecker(key=authentication.header_key, real_value=authentication.real_value)
+        return [
+            Depends(checker),
+            Depends(APIKeyQuery(name=authentication.header_key)),
+        ]
+    else:
+        return []

dtpyfw-0.0.1/dtpyfw/api/routes/response.py

@@ -0,0 +1,58 @@
+from typing import Any
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse, Response
+
+
+def return_response(
+        data: Any,
+        status_code: int,
+        response_class: Response,
+        return_json_directly: bool = False,
+        headers: dict[int, dict] = None,
+        no_cache: bool = True,
+) -> Response:
+    if headers is None:
+        headers = {}
+
+    final_headers = headers.get(status_code) or {}
+
+    if no_cache:
+        final_headers.update({
+            'Cache-Control': 'private, no-cache, no-store, must-revalidate, max-age=0, s-maxage=0',
+            'Pragma': 'no-cache',
+            'Expires': '0',
+        })
+
+    if response_class != JSONResponse:
+        return_json_directly = True
+
+    if return_json_directly:
+        content = data
+    else:
+        if status_code < 300:
+            content = {'success': True, 'data': jsonable_encoder(data)}
+        else:
+            content = {'success': False, 'message': data}
+
+    return response_class(
+        status_code=status_code,
+        content=content,
+        headers=final_headers
+    )
+
+
+def return_json_response(
+        data: Any,
+        status_code: int,
+        return_json_directly: bool = False,
+        headers: dict[int, dict] = None,
+        no_cache: bool = True,
+) -> JSONResponse:
+    return return_response(
+        data=data,
+        status_code=status_code,
+        return_json_directly=return_json_directly,
+        headers=headers,
+        no_cache=no_cache,
+        response_class=JSONResponse,
+    )

dtpyfw-0.0.1/dtpyfw/api/routes/route.py

@@ -0,0 +1,127 @@
+import inspect
+from enum import Enum
+from functools import wraps
+from typing import Callable, List, Optional, Type, Any, Dict
+from pydantic import BaseModel
+from fastapi.responses import Response, JSONResponse
+
+from .authentication import Auth, auth_data_class_to_dependency
+from .response import return_response
+
+
+class RouteMethod(Enum):
+    GET = "GET"
+    PUT = "PUT"
+    POST = "POST"
+    DELETE = "DELETE"
+    PATCH = "PATCH"
+    HEAD = "HEAD"
+    OPTIONS = "OPTIONS"
+    TRACE = "TRACE"
+    CONNECT = "CONNECT"
+
+
+class Route:
+    def __init__(
+            self,
+            path: str,
+            method: RouteMethod,
+            handler: Callable,
+            wrapping_handler: bool = True,
+            authentications: list[Auth] = None,
+            response_model: Optional[Type[BaseModel]] = None,
+            status_code: int = 200,
+            dependencies: List[Any] = None,
+            wrapper_kwargs: Dict[str, Any] = None,
+            name: Optional[str] = None,
+            summary: Optional[str] = None,
+            description: Optional[str] = None,
+            tags: Optional[List[str]] = None,
+            response_description: str = "Successful Response",
+            responses: Optional[Dict[int, Dict[str, Any]]] = None,
+            deprecated: bool = False,
+            operation_id: Optional[str] = None,
+            include_in_schema: bool = True,
+            response_class: Optional[Response] = JSONResponse,
+            response_model_exclude_unset: bool = False,
+            response_model_exclude_defaults: bool = False,
+            response_model_exclude_none: bool = False,
+            response_model_by_alias: bool = True,
+            response_return_json_directly: bool = False,
+            response_headers: dict[int, dict] = None,
+            response_no_cache_headers: bool = True,
+    ):
+        """
+        Initialize a Route instance and create a wrapped handler.
+        """
+        dependencies = dependencies or []
+        for authentication in (authentications or []):
+            dependencies.extend(auth_data_class_to_dependency(authentication))
+
+        self.dependencies = dependencies
+
+        self.path = path
+        self.method = method
+        self.handler = handler
+        self.wrapping_handler = wrapping_handler
+        self.response_model = response_model
+        self.status_code = status_code
+        self.wrapper_kwargs = wrapper_kwargs or {}
+        self.name = name
+        self.summary = summary
+        self.description = description
+        self.tags = tags
+        self.response_description = response_description
+        self.responses = responses
+        self.deprecated = deprecated
+        self.operation_id = operation_id
+        self.include_in_schema = include_in_schema
+        self.response_class = response_class
+        self.response_model_exclude_unset = response_model_exclude_unset
+        self.response_model_exclude_defaults = response_model_exclude_defaults
+        self.response_model_exclude_none = response_model_exclude_none
+        self.response_model_by_alias = response_model_by_alias
+        self.response_return_json_directly = response_return_json_directly
+        self.response_headers = response_headers
+        self.response_no_cache_headers = response_no_cache_headers
+
+    def wrapped_handler(self) -> Callable:
+        """
+        Create and return a wrapped handler based on the response type.
+        """
+        is_async = inspect.iscoroutinefunction(self.handler)
+
+        def wrap_function(wrapped_func: Callable) -> Callable:
+            @wraps(wrapped_func)
+            async def async_wrapper(*args, **kwargs):
+                result = await wrapped_func(*args, **kwargs)
+                if self.wrapping_handler:
+                    return return_response(
+                        data=result,
+                        status_code=self.status_code,
+                        response_class=self.response_class,
+                        return_json_directly=self.response_return_json_directly,
+                        headers=self.response_headers,
+                        no_cache=self.response_no_cache_headers,
+                    )
+                else:
+                    return result
+
+            @wraps(wrapped_func)
+            def sync_wrapper(*args, **kwargs):
+                result = wrapped_func(*args, **kwargs)
+                if self.wrapping_handler:
+                    return return_response(
+                        data=result,
+                        status_code=self.status_code,
+                        response_class=self.response_class,
+                        return_json_directly=self.response_return_json_directly,
+                        headers=self.response_headers,
+                        no_cache=self.response_no_cache_headers,
+                    )
+                else:
+                    return result
+
+            return async_wrapper if is_async else sync_wrapper
+
+        return wrap_function(self.handler)