global-api-tools 0.1.1__py3-none-any.whl

global_api_tools/__init__.py

@@ -0,0 +1,27 @@
+from .exceptions import (
+    ApiError,
+    ErrorHandler,
+    ExceptionHandler,
+    explain_error,
+    get_status_code,
+    handle_exception,
+    register_exception_handlers,
+    unified_exception_handler,
+)
+from .logging import get_logger, logs
+from .responses import create_response, value_correction
+
+__all__ = [
+    "ApiError",
+    "ErrorHandler",
+    "ExceptionHandler",
+    "create_response",
+    "explain_error",
+    "get_logger",
+    "get_status_code",
+    "handle_exception",
+    "logs",
+    "register_exception_handlers",
+    "unified_exception_handler",
+    "value_correction",
+]

global_api_tools/_compat.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+
+def optional_import(module_name: str, attribute: str | None = None) -> Any:
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+    if attribute is None:
+        return module
+    return getattr(module, attribute, None)
+
+
+def compact_types(*maybe_types: Any) -> tuple[type[Any], ...]:
+    return tuple(item for item in maybe_types if isinstance(item, type))

global_api_tools/exceptions.py

@@ -0,0 +1,369 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from ._compat import compact_types, optional_import
+from .logging import get_logger
+
+FastAPIHTTPException = optional_import("fastapi", "HTTPException")
+RequestValidationError = optional_import("fastapi.exceptions", "RequestValidationError")
+JSONResponse = optional_import("fastapi.responses", "JSONResponse")
+StarletteHTTPException = optional_import("starlette.exceptions", "HTTPException")
+PydanticValidationError = optional_import("pydantic", "ValidationError")
+SQLAlchemyError = optional_import("sqlalchemy.exc", "SQLAlchemyError")
+IntegrityError = optional_import("sqlalchemy.exc", "IntegrityError")
+OperationalError = optional_import("sqlalchemy.exc", "OperationalError")
+ProgrammingError = optional_import("sqlalchemy.exc", "ProgrammingError")
+DataError = optional_import("sqlalchemy.exc", "DataError")
+DisconnectionError = optional_import("sqlalchemy.exc", "DisconnectionError")
+PsycopgErrors = optional_import("psycopg2", "errors")
+AsyncPGExceptions = optional_import("asyncpg", "exceptions")
+
+AsyncPGDataError = getattr(AsyncPGExceptions, "DataError", None) if AsyncPGExceptions else None
+NotNullViolation = getattr(PsycopgErrors, "NotNullViolation", None) if PsycopgErrors else None
+UniqueViolation = getattr(PsycopgErrors, "UniqueViolation", None) if PsycopgErrors else None
+ForeignKeyViolation = getattr(PsycopgErrors, "ForeignKeyViolation", None) if PsycopgErrors else None
+CheckViolation = getattr(PsycopgErrors, "CheckViolation", None) if PsycopgErrors else None
+UndefinedTable = getattr(PsycopgErrors, "UndefinedTable", None) if PsycopgErrors else None
+
+HTTP_EXCEPTION_TYPES = compact_types(FastAPIHTTPException, StarletteHTTPException)
+VALIDATION_EXCEPTION_TYPES = compact_types(RequestValidationError, PydanticValidationError)
+INTEGRITY_EXCEPTION_TYPES = compact_types(
+    IntegrityError,
+    UniqueViolation,
+    ForeignKeyViolation,
+    NotNullViolation,
+    CheckViolation,
+)
+DATA_EXCEPTION_TYPES = compact_types(DataError, AsyncPGDataError)
+DB_UNAVAILABLE_EXCEPTION_TYPES = compact_types(OperationalError, DisconnectionError, ConnectionError)
+PROGRAMMING_EXCEPTION_TYPES = compact_types(ProgrammingError, UndefinedTable)
+GENERIC_DATABASE_EXCEPTION_TYPES = compact_types(SQLAlchemyError)
+
+DEFAULT_STATUS_MESSAGES = {
+    400: "The request data is invalid.",
+    401: "Authentication is required to access this resource.",
+    403: "You do not have permission to perform this action.",
+    404: "The requested resource was not found.",
+    409: "The request conflicts with existing data.",
+    422: "One or more fields are invalid.",
+    429: "Too many requests were sent in a short time.",
+    500: "An unexpected error occurred.",
+    503: "A required service is temporarily unavailable.",
+    504: "A required service took too long to respond.",
+}
+
+
+@dataclass(frozen=True)
+class ErrorInfo:
+    status_code: int
+    code: str
+    message: str
+    details: list[dict[str, Any]] | None = None
+
+
+class ApiError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 400,
+        code: str = "api_error",
+        details: list[dict[str, Any]] | None = None,
+        log_message: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.details = details
+        self.log_message = log_message
+
+
+def _default_message(status_code: int) -> str:
+    return DEFAULT_STATUS_MESSAGES.get(status_code, "An unexpected error occurred.")
+
+
+def _clean_message(message: str) -> str:
+    clean = message.strip().strip('"').strip("'")
+    if not clean:
+        return ""
+    if "\n" in clean or len(clean) > 240:
+        return ""
+    return clean
+
+
+def _safe_client_message(exc: Exception, default: str) -> str:
+    return _clean_message(str(exc)) or default
+
+
+def _extract_request_value(request: Any, attribute: str) -> Any:
+    if request is None:
+        return None
+    return getattr(request, attribute, None)
+
+
+def _extract_request_id(request: Any) -> str | None:
+    headers = _extract_request_value(request, "headers")
+    if headers is None:
+        return None
+    return headers.get("x-request-id") or headers.get("x-correlation-id")
+
+
+def _normalize_validation_errors(exc: Exception) -> list[dict[str, str]]:
+    if not hasattr(exc, "errors"):
+        return [{"field": "data", "message": _safe_client_message(exc, "Validation failed.")}]
+
+    normalized: list[dict[str, str]] = []
+    for error in exc.errors():  # type: ignore[attr-defined]
+        location = [str(part) for part in error.get("loc", []) if part != "__root__"]
+        if location and location[0] in {"body", "query", "path"}:
+            location = location[1:]
+        normalized.append(
+            {
+                "field": ".".join(location) if location else "data",
+                "message": error.get("msg") or error.get("message") or "Invalid value.",
+            }
+        )
+    return normalized
+
+
+def _database_message(exc: Exception) -> str:
+    original = getattr(exc, "orig", None)
+    raw_message = str(original or exc).lower()
+
+    duplicate_match = re.search(r"key\s*\((?P<field>[^)]+)\)=", raw_message)
+    foreign_key_match = re.search(r"key\s*\((?P<field>[^)]+)\)=", raw_message)
+    null_match = re.search(r'column\s+"(?P<field>[^"]+)"', raw_message)
+
+    if "duplicate key" in raw_message or "unique" in raw_message:
+        if duplicate_match:
+            return f"A record with this {duplicate_match.group('field')} already exists."
+        return "A record with the same value already exists."
+    if "foreign key" in raw_message:
+        if foreign_key_match:
+            return f"The related value for {foreign_key_match.group('field')} does not exist."
+        return "A related record was not found."
+    if "not-null" in raw_message or "cannot be null" in raw_message:
+        if null_match:
+            return f"The field {null_match.group('field')} is required."
+        return "A required field is missing."
+    if "check constraint" in raw_message:
+        return "One or more fields failed a database validation rule."
+    if "out of range" in raw_message:
+        return "A numeric value is outside the allowed range."
+    if "invalid input syntax" in raw_message or "expected" in raw_message:
+        return "One or more fields have the wrong type or format."
+    return "A database error occurred while processing the request."
+
+
+def _database_status(exc: Exception) -> tuple[int, str]:
+    raw_message = str(getattr(exc, "orig", exc)).lower()
+
+    if "duplicate key" in raw_message or "unique" in raw_message:
+        return 409, "duplicate_resource"
+    if "foreign key" in raw_message:
+        return 422, "invalid_reference"
+    if "not-null" in raw_message or "cannot be null" in raw_message:
+        return 422, "missing_required_field"
+    if "check constraint" in raw_message:
+        return 422, "constraint_violation"
+    if isinstance(exc, DATA_EXCEPTION_TYPES):
+        return 422, "invalid_data"
+    if isinstance(exc, DB_UNAVAILABLE_EXCEPTION_TYPES):
+        return 503, "database_unavailable"
+    if isinstance(exc, PROGRAMMING_EXCEPTION_TYPES):
+        return 500, "database_programming_error"
+    return 500, "database_error"
+
+
+class ErrorHandler:
+    def __init__(self, *, logger_name: str = "global_api_tools.errors") -> None:
+        self.logger = get_logger(logger_name)
+
+    def describe(self, exc: Exception) -> ErrorInfo:
+        if isinstance(exc, ApiError):
+            return ErrorInfo(
+                status_code=exc.status_code,
+                code=exc.code,
+                message=exc.message,
+                details=exc.details,
+            )
+
+        if HTTP_EXCEPTION_TYPES and isinstance(exc, HTTP_EXCEPTION_TYPES):
+            status_code = getattr(exc, "status_code", 500)
+            detail = getattr(exc, "detail", None)
+            if status_code >= 500:
+                message = _default_message(status_code)
+            elif isinstance(detail, str):
+                message = _clean_message(detail) or _default_message(status_code)
+            else:
+                message = _default_message(status_code)
+            return ErrorInfo(status_code=status_code, code=f"http_{status_code}", message=message)
+
+        if VALIDATION_EXCEPTION_TYPES and isinstance(exc, VALIDATION_EXCEPTION_TYPES):
+            return ErrorInfo(
+                status_code=422,
+                code="validation_error",
+                message=_default_message(422),
+                details=_normalize_validation_errors(exc),
+            )
+
+        if INTEGRITY_EXCEPTION_TYPES and isinstance(exc, INTEGRITY_EXCEPTION_TYPES):
+            status_code, code = _database_status(exc)
+            return ErrorInfo(status_code=status_code, code=code, message=_database_message(exc))
+
+        if DATA_EXCEPTION_TYPES and isinstance(exc, DATA_EXCEPTION_TYPES):
+            return ErrorInfo(
+                status_code=422,
+                code="invalid_data",
+                message="One or more fields have the wrong type or format.",
+            )
+
+        if DB_UNAVAILABLE_EXCEPTION_TYPES and isinstance(exc, DB_UNAVAILABLE_EXCEPTION_TYPES):
+            if isinstance(exc, TimeoutError):
+                return ErrorInfo(status_code=504, code="upstream_timeout", message=_default_message(504))
+            return ErrorInfo(status_code=503, code="service_unavailable", message=_default_message(503))
+
+        if GENERIC_DATABASE_EXCEPTION_TYPES and isinstance(exc, GENERIC_DATABASE_EXCEPTION_TYPES):
+            status_code, code = _database_status(exc)
+            message = _database_message(exc)
+            if status_code >= 500:
+                message = _default_message(status_code)
+            return ErrorInfo(status_code=status_code, code=code, message=message)
+
+        if isinstance(exc, FileNotFoundError):
+            return ErrorInfo(status_code=404, code="resource_not_found", message=_default_message(404))
+
+        if isinstance(exc, PermissionError):
+            return ErrorInfo(status_code=403, code="forbidden", message=_default_message(403))
+
+        if isinstance(exc, TimeoutError):
+            return ErrorInfo(status_code=504, code="upstream_timeout", message=_default_message(504))
+
+        if isinstance(exc, ConnectionError):
+            return ErrorInfo(status_code=503, code="service_unavailable", message=_default_message(503))
+
+        if isinstance(exc, MemoryError):
+            return ErrorInfo(status_code=503, code="service_unavailable", message=_default_message(503))
+
+        if isinstance(exc, (ValueError, TypeError, KeyError, IndexError, AssertionError)):
+            return ErrorInfo(
+                status_code=400,
+                code="bad_request",
+                message=_safe_client_message(exc, _default_message(400)),
+            )
+
+        return ErrorInfo(status_code=500, code="internal_error", message=_default_message(500))
+
+    def log_exception(self, exc: Exception, request: Any = None) -> None:
+        method = _extract_request_value(request, "method")
+        url = _extract_request_value(request, "url")
+        path = getattr(url, "path", None) if url else None
+        request_id = _extract_request_id(request)
+
+        context_parts = ["Handled exception"]
+        if method and path:
+            context_parts.append(f"{method} {path}")
+        if request_id:
+            context_parts.append(f"request_id={request_id}")
+
+        if isinstance(exc, ApiError) and exc.log_message:
+            context_parts.append(exc.log_message)
+
+        self.logger.error(" | ".join(context_parts), exc_info=exc)
+
+    def build_payload(self, exc: Exception, request: Any = None) -> dict[str, Any]:
+        info = self.describe(exc)
+        payload: dict[str, Any] = {
+            "success": False,
+            "response_code": info.status_code,
+            "status_code": info.status_code,
+            "error_message": info.message,
+            "error_type": exc.__class__.__name__,
+            "error": {
+                "code": info.code,
+                "type": exc.__class__.__name__,
+                "message": info.message,
+            },
+        }
+
+        if info.details:
+            payload["error"]["details"] = info.details
+            payload["errors"] = info.details
+
+        request_id = _extract_request_id(request)
+        if request_id:
+            payload["request_id"] = request_id
+
+        url = _extract_request_value(request, "url")
+        if url and getattr(url, "path", None):
+            payload["path"] = url.path
+
+        return payload
+
+    def explain_error(self, exc: Exception) -> str:
+        return self.describe(exc).message
+
+    def get_status_code(self, exc: Exception) -> int:
+        return self.describe(exc).status_code
+
+    def handle_exception(self, exc: Exception, request: Any = None) -> Any:
+        payload = self.build_payload(exc, request=request)
+        if JSONResponse is None:
+            return payload
+        return JSONResponse(status_code=payload["status_code"], content=payload)
+
+    async def unified_exception_handler(self, request: Any, exc: Exception) -> Any:
+        self.log_exception(exc, request=request)
+        return self.handle_exception(exc, request=request)
+
+    def raise_http_exception(self, exc: Exception) -> None:
+        if FastAPIHTTPException is None:
+            raise RuntimeError("FastAPI must be installed to raise HTTPException objects.")
+
+        self.log_exception(exc)
+        info = self.describe(exc)
+        raise FastAPIHTTPException(status_code=info.status_code, detail=info.message)
+
+
+_default_handler = ErrorHandler()
+
+
+def explain_error(exc: Exception) -> str:
+    return _default_handler.explain_error(exc)
+
+
+def get_status_code(exc: Exception) -> int:
+    return _default_handler.get_status_code(exc)
+
+
+def handle_exception(exc: Exception, request: Any = None) -> Any:
+    return _default_handler.handle_exception(exc, request=request)
+
+
+async def unified_exception_handler(request: Any, exc: Exception) -> Any:
+    return await _default_handler.unified_exception_handler(request, exc)
+
+
+def ExceptionHandler(exc: Exception) -> None:
+    _default_handler.raise_http_exception(exc)
+
+
+def register_exception_handlers(app: Any, handler: ErrorHandler | None = None) -> Any:
+    active_handler = handler or _default_handler
+    registered_types: list[type[Any]] = [Exception]
+
+    if FastAPIHTTPException and FastAPIHTTPException not in registered_types:
+        registered_types.append(FastAPIHTTPException)
+    if StarletteHTTPException and StarletteHTTPException not in registered_types:
+        registered_types.append(StarletteHTTPException)
+    if RequestValidationError and RequestValidationError not in registered_types:
+        registered_types.append(RequestValidationError)
+
+    for exception_type in registered_types:
+        app.add_exception_handler(exception_type, active_handler.unified_exception_handler)
+
+    return app

global_api_tools/logging.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+DEFAULT_LOGGER_NAME = "global_api_tools"
+LOG_FORMAT = "%(asctime)s | %(name)s | %(levelname)s | %(message)s"
+_FILE_HANDLERS: dict[str, logging.FileHandler] = {}
+
+
+def _ensure_stream_handler(logger: logging.Logger) -> None:
+    for handler in logger.handlers:
+        if isinstance(handler, logging.StreamHandler) and not isinstance(handler, logging.FileHandler):
+            return
+
+    stream_handler = logging.StreamHandler()
+    stream_handler.setFormatter(logging.Formatter(LOG_FORMAT))
+    logger.addHandler(stream_handler)
+
+
+def _resolve_log_path(file_name: str | Path) -> Path:
+    path = Path(file_name)
+    if not path.suffix:
+        path = path.with_suffix(".log")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_logger(
+    name: str = DEFAULT_LOGGER_NAME,
+    *,
+    file_name: str | Path | None = None,
+) -> logging.Logger:
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.INFO)
+    _ensure_stream_handler(logger)
+
+    if file_name:
+        path = _resolve_log_path(file_name)
+        handler_key = str(path.resolve())
+        file_handler = _FILE_HANDLERS.get(handler_key)
+
+        if file_handler is None:
+            file_handler = logging.FileHandler(path)
+            file_handler.setFormatter(logging.Formatter(LOG_FORMAT))
+            _FILE_HANDLERS[handler_key] = file_handler
+
+        if file_handler not in logger.handlers:
+            logger.addHandler(file_handler)
+
+    return logger
+
+
+def logs(
+    msg: object = "",
+    type: str = "info",
+    file_name: str | Path | None = None,
+    logger: logging.Logger | None = None,
+) -> None:
+    target_logger = logger or get_logger(file_name=file_name)
+    level_name = str(type).upper()
+    level = getattr(logging, level_name, logging.INFO)
+    target_logger.log(level, msg)

global_api_tools/responses.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta
+from decimal import Decimal
+from http import HTTPStatus
+from typing import Any, Mapping, Sequence
+
+from ._compat import optional_import
+from .logging import logs
+
+JSONResponse = optional_import("fastapi.responses", "JSONResponse")
+Response = optional_import("fastapi", "Response")
+PydanticValidationError = optional_import("pydantic", "ValidationError")
+
+
+def value_correction(data: Any) -> Any:
+    if isinstance(data, str):
+        return data.strip()
+    if isinstance(data, Decimal):
+        return float(data)
+    if isinstance(data, datetime):
+        return data.isoformat(sep=" ", timespec="seconds")
+    if isinstance(data, date):
+        return data.isoformat()
+    if isinstance(data, timedelta):
+        return str(data)
+    if isinstance(data, float):
+        return round(data, 2)
+    if isinstance(data, dict):
+        return {key: value_correction(value) for key, value in data.items()}
+    if isinstance(data, list):
+        return [value_correction(item) for item in data]
+    if isinstance(data, tuple):
+        return tuple(value_correction(item) for item in data)
+    if isinstance(data, set):
+        return [value_correction(item) for item in sorted(data, key=repr)]
+    return data
+
+
+def _http_status_message(response_code: int) -> str:
+    try:
+        phrase = HTTPStatus(response_code).phrase
+    except ValueError:
+        return "Request failed."
+    return phrase.replace("_", " ")
+
+
+def _dump_model(model: Any) -> Any:
+    if hasattr(model, "model_dump"):
+        return model.model_dump()
+    if hasattr(model, "dict"):
+        return model.dict()
+    return model
+
+
+def _validate_with_schema(schema: Any, item: Any) -> Any:
+    if hasattr(schema, "validate_python"):
+        return _dump_model(schema.validate_python(item))
+    if hasattr(schema, "model_validate"):
+        return _dump_model(schema.model_validate(item))
+    if hasattr(schema, "parse_obj"):
+        return _dump_model(schema.parse_obj(item))
+    raise TypeError("schema must be a Pydantic model class or adapter")
+
+
+def _format_validation_errors(exc: Exception) -> list[dict[str, str]]:
+    if not hasattr(exc, "errors"):
+        return [{"field": "data", "message": str(exc) or "Validation failed."}]
+
+    formatted_errors: list[dict[str, str]] = []
+    for error in exc.errors():  # type: ignore[attr-defined]
+        location = [str(part) for part in error.get("loc", []) if part != "__root__"]
+        if location and location[0] in {"body", "query", "path"}:
+            location = location[1:]
+        field_name = ".".join(location) if location else "data"
+        formatted_errors.append(
+            {
+                "field": field_name,
+                "message": error.get("msg") or error.get("message") or "Invalid value.",
+            }
+        )
+    return formatted_errors
+
+
+def _serialize_data(data: Any, schema: Any | None) -> Any:
+    if schema is None:
+        return value_correction(data)
+    if isinstance(data, list):
+        return [value_correction(_validate_with_schema(schema, item)) for item in data]
+    return value_correction(_validate_with_schema(schema, data))
+
+
+def _set_status_aliases(payload: dict[str, Any], response_code: int) -> None:
+    payload["response_code"] = response_code
+    payload["status_code"] = response_code
+
+
+def _set_error_aliases(
+    payload: dict[str, Any],
+    *,
+    message: str,
+    details: Sequence[Mapping[str, Any]] | None = None,
+) -> None:
+    payload["error_message"] = message
+    if details:
+        payload["errors"] = [dict(item) for item in details]
+
+
+def create_response(
+    response_code: int,
+    data: Any = None,
+    schema: Any | None = None,
+    pagination: Mapping[str, Any] | None = None,
+    error_message: str | None = None,
+    error_code: str | None = None,
+    details: Sequence[Mapping[str, Any]] | None = None,
+    *,
+    as_json_response: bool = True,
+) -> Any:
+    if response_code == 204 and as_json_response:
+        if Response is None:
+            raise RuntimeError("FastAPI must be installed to return a Response object.")
+        return Response(status_code=204)
+
+    payload: dict[str, Any] = {
+        "success": 200 <= response_code < 300,
+    }
+    _set_status_aliases(payload, response_code)
+
+    if data is not None:
+        try:
+            payload["data"] = _serialize_data(data, schema)
+        except Exception as exc:  # noqa: BLE001
+            if PydanticValidationError and isinstance(exc, PydanticValidationError):
+                validation_errors = _format_validation_errors(exc)
+            else:
+                validation_errors = [{"field": "data", "message": str(exc) or "Validation failed."}]
+
+            logs(validation_errors, type="error")
+            response_code = 422
+            payload["success"] = False
+            _set_status_aliases(payload, response_code)
+            payload["error"] = {
+                "code": "validation_error",
+                "message": "Response data did not match the expected schema.",
+                "details": validation_errors,
+            }
+            _set_error_aliases(
+                payload,
+                message="Response data did not match the expected schema.",
+                details=validation_errors,
+            )
+
+    if pagination is not None:
+        payload["pagination"] = value_correction(dict(pagination))
+
+    if "error" not in payload and (error_message or response_code >= 400):
+        payload["success"] = False
+        _set_status_aliases(payload, response_code)
+        error_obj: dict[str, Any] = {
+            "code": error_code or "api_error",
+            "message": error_message or _http_status_message(response_code),
+        }
+        if details:
+            error_obj["details"] = [dict(item) for item in details]
+        payload["error"] = error_obj
+        _set_error_aliases(
+            payload,
+            message=error_obj["message"],
+            details=error_obj.get("details"),
+        )
+
+    if not as_json_response:
+        return payload
+
+    if JSONResponse is None:
+        raise RuntimeError("FastAPI must be installed to return a JSONResponse object.")
+    return JSONResponse(content=payload, status_code=response_code)

global_api_tools-0.1.1.dist-info/METADATA

@@ -0,0 +1,405 @@
+Metadata-Version: 2.4
+Name: global-api-tools
+Version: 0.1.1
+Summary: Reusable API response and exception handling utilities with FastAPI integration.
+Author: Aniket Modi
+License: MIT
+Project-URL: Homepage, https://github.com/aniketmodi123/reusable_code_lib
+Project-URL: Repository, https://github.com/aniketmodi123/reusable_code_lib
+Keywords: api,fastapi,error-handling,responses,utilities
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == "fastapi"
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=1.10; extra == "pydantic"
+Provides-Extra: database
+Requires-Dist: sqlalchemy>=1.4; extra == "database"
+Requires-Dist: asyncpg>=0.29; extra == "database"
+Requires-Dist: psycopg2-binary>=2.9; extra == "database"
+Provides-Extra: full
+Requires-Dist: fastapi>=0.110; extra == "full"
+Requires-Dist: pydantic>=1.10; extra == "full"
+Requires-Dist: sqlalchemy>=1.4; extra == "full"
+Requires-Dist: asyncpg>=0.29; extra == "full"
+Requires-Dist: psycopg2-binary>=2.9; extra == "full"
+Dynamic: license-file
+
+# global-api-tools
+
+`global-api-tools` is a reusable Python library for centralized API responses, logging, and exception handling.
+
+It gives you one place to manage:
+
+- `create_response`
+- `value_correction`
+- `logs`
+- `ExceptionHandler`
+- `unified_exception_handler`
+
+## Install
+
+```bash
+pip install global-api-tools
+```
+
+For local development:
+
+```bash
+pip install .
+```
+
+Optional extras:
+
+```bash
+pip install ".[fastapi]"
+pip install ".[pydantic]"
+pip install ".[database]"
+pip install ".[full]"
+```
+
+## Quick usage
+
+```python
+from fastapi import FastAPI
+from global_api_tools import create_response, register_exception_handlers
+
+app = FastAPI()
+register_exception_handlers(app)
+
+
+@app.get("/health")
+async def health():
+    return create_response(200, data={"status": "ok"})
+```
+
+## Public API
+
+Import from the published package like this:
+
+Use only this import style in other projects:
+
+```python
+from global_api_tools import (
+    ApiError,
+    ErrorHandler,
+    ExceptionHandler,
+    create_response,
+    explain_error,
+    get_logger,
+    get_status_code,
+    handle_exception,
+    logs,
+    register_exception_handlers,
+    unified_exception_handler,
+    value_correction,
+)
+```
+
+### `create_response`
+
+Params:
+
+- `response_code: int`
+- `data: Any = None`
+- `schema: Any | None = None`
+- `pagination: Mapping[str, Any] | None = None`
+- `error_message: str | None = None`
+- `error_code: str | None = None`
+- `details: Sequence[Mapping[str, Any]] | None = None`
+- `as_json_response: bool = True`
+
+Usage:
+
+```python
+from global_api_tools import create_response
+
+return create_response(
+    200,
+    data={"name": "Aniket"},
+    pagination={"page": 1, "rows": 10, "total_rows": 100},
+)
+```
+
+### `value_correction`
+
+Params:
+
+- `data: Any`
+
+Usage:
+
+```python
+from decimal import Decimal
+from global_api_tools import value_correction
+
+cleaned = value_correction({"amount": Decimal("10.50"), "name": "  demo  "})
+```
+
+### `logs`
+
+Params:
+
+- `msg: object = ""`
+- `type: str = "info"`
+- `file_name: str | Path | None = None`
+- `logger: logging.Logger | None = None`
+
+Usage:
+
+```python
+from global_api_tools import logs
+
+logs("report created", type="info")
+logs("database failed", type="error", file_name="logs/app")
+```
+
+### `get_logger`
+
+Params:
+
+- `name: str = "global_api_tools"`
+- `file_name: str | Path | None = None`
+
+Usage:
+
+```python
+from global_api_tools import get_logger
+
+logger = get_logger("my_app", file_name="logs/app.log")
+logger.info("started")
+```
+
+### `unified_exception_handler`
+
+Params:
+
+- `request`
+- `exc: Exception`
+
+Usage:
+
+```python
+from fastapi import FastAPI, HTTPException
+from fastapi.exceptions import RequestValidationError
+from global_api_tools import unified_exception_handler
+
+app = FastAPI()
+
+app.add_exception_handler(HTTPException, unified_exception_handler)
+app.add_exception_handler(Exception, unified_exception_handler)
+app.add_exception_handler(RequestValidationError, unified_exception_handler)
+```
+
+### `register_exception_handlers`
+
+Params:
+
+- `app`
+- `handler: ErrorHandler | None = None`
+
+Usage:
+
+```python
+from fastapi import FastAPI
+from global_api_tools import register_exception_handlers
+
+app = FastAPI()
+register_exception_handlers(app)
+```
+
+### `ExceptionHandler`
+
+Params:
+
+- `exc: Exception`
+
+Usage:
+
+```python
+from global_api_tools import ExceptionHandler
+
+try:
+    raise ValueError("invalid meter id")
+except Exception as exc:
+    ExceptionHandler(exc)
+```
+
+### `handle_exception`
+
+Params:
+
+- `exc: Exception`
+- `request = None`
+
+Usage:
+
+```python
+from global_api_tools import handle_exception
+
+payload_or_response = handle_exception(ValueError("invalid input"))
+```
+
+### `explain_error`
+
+Params:
+
+- `exc: Exception`
+
+Usage:
+
+```python
+from global_api_tools import explain_error
+
+message = explain_error(ValueError("invalid input"))
+```
+
+### `get_status_code`
+
+Params:
+
+- `exc: Exception`
+
+Usage:
+
+```python
+from global_api_tools import get_status_code
+
+status_code = get_status_code(ValueError("invalid input"))
+```
+
+### `ErrorHandler`
+
+Params:
+
+- `logger_name: str = "global_api_tools.errors"`
+
+Usage:
+
+```python
+from global_api_tools import ErrorHandler
+
+handler = ErrorHandler()
+payload = handler.build_payload(ValueError("invalid input"))
+```
+
+### `ApiError`
+
+Params:
+
+- `message: str`
+- `status_code: int = 400`
+- `code: str = "api_error"`
+- `details: list[dict[str, Any]] | None = None`
+- `log_message: str | None = None`
+
+Usage:
+
+```python
+from global_api_tools import ApiError
+
+raise ApiError(
+    "Report is not ready.",
+    status_code=409,
+    code="report_pending",
+    details=[{"field": "report_id", "message": "still processing"}],
+)
+```
+
+## Error response format
+
+Every API failure uses one consistent structure:
+
+```json
+{
+  "success": false,
+  "status_code": 422,
+  "error": {
+    "code": "validation_error",
+    "type": "RequestValidationError",
+    "message": "One or more fields are invalid.",
+    "details": [
+      {
+        "field": "email",
+        "message": "field required"
+      }
+    ]
+  }
+}
+```
+
+## Package structure
+
+```text
+src/global_api_tools/
+  __init__.py
+  _compat.py
+  exceptions.py
+  logging.py
+  responses.py
+```
+
+## Extending it
+
+Add new shared functionality inside `src/global_api_tools/` and re-export it from `src/global_api_tools/__init__.py`. That keeps imports stable across every project that uses the package.
+
+## Import Rule
+
+For installed usage, import from `global_api_tools` only.
+
+Correct:
+
+```python
+from global_api_tools import create_response, unified_exception_handler
+```
+
+Do not rely on local-only paths like `utils` or `exception_handler` in other projects.
+
+## Auto Publish From `prod`
+
+This repo is configured so that a merged pull request into the `prod` branch publishes the package to PyPI through GitHub Actions.
+
+Required setup:
+
+1. Create the package on PyPI if needed.
+2. In PyPI, configure a Trusted Publisher with these values:
+   - Project name: `global-api-tools`
+   - Owner: `aniketmodi123`
+   - Repository: `reusable_code_lib`
+   - Workflow: `publish-pypi.yml`
+3. Before merging into `prod`, increase the version in `pyproject.toml`. PyPI will reject duplicate versions.
+
+Workflow file:
+
+- `.github/workflows/publish-pypi.yml`
+
+Release flow:
+
+```bash
+git checkout dev
+# make code changes
+# update version in pyproject.toml when this is a release
+git add .
+git commit -m "release: 0.1.1"
+git push origin dev
+```
+
+Then:
+
+1. Create a pull request from `dev` to `prod`
+2. Review and approve it
+3. Merge the pull request
+
+When the PR is merged into `prod`, GitHub Actions will use Trusted Publishing to:
+
+- build the wheel and source distribution
+- validate the package
+- upload it to PyPI

global_api_tools-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+global_api_tools/__init__.py,sha256=vEErhowuXm-Ibdnxv31mrO0Dl11YrJAH0YMWE8UC5aE,591
+global_api_tools/_compat.py,sha256=_9C9S_jG4g8aePVgUNLJjrjZGDV0LSEdZ8Mit1EYnuo,492
+global_api_tools/exceptions.py,sha256=LvFMfeTd7nH_h-IYitiHR1qJE0jQQGP1Gp_jKIMiyqA,15007
+global_api_tools/logging.py,sha256=_am3kocQ83dvHbsNYAWN-3uBu0i1RDZSjKv74b1eCtI,1871
+global_api_tools/responses.py,sha256=QaiWHdQm34GJclX1pJTTJXO4pZKnmKC48HLaR3VN68I,6232
+global_api_tools-0.1.1.dist-info/licenses/LICENSE,sha256=fHBOcmG4wnlk3QUq24bbuHainPKxT1niUGyelQyYaWA,1068
+global_api_tools-0.1.1.dist-info/METADATA,sha256=_POXpOdYZk6hwTLa0d49P0GzB82hsDJE3gBBVlACjws,8056
+global_api_tools-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+global_api_tools-0.1.1.dist-info/top_level.txt,sha256=cA_IgXwOZPUVkI5a4gaV54icshc_JCW1UJqdz7TaXLI,17
+global_api_tools-0.1.1.dist-info/RECORD,,

global_api_tools-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

global_api_tools-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aniket Modi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

global_api_tools-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+global_api_tools