global-api-tools 0.1.1

Reusable API response and exception handling utilities with FastAPI integration.

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

pip install global-api-tools

For local development:

pip install .

Optional extras:

pip install ".[fastapi]"
pip install ".[pydantic]"
pip install ".[database]"
pip install ".[full]"

Quick usage

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:

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:

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:

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:

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:

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:

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:

from fastapi import FastAPI
from global_api_tools import register_exception_handlers

app = FastAPI()
register_exception_handlers(app)

ExceptionHandler

Params:

• exc: Exception

Usage:

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:

from global_api_tools import handle_exception

payload_or_response = handle_exception(ValueError("invalid input"))

explain_error

Params:

• exc: Exception

Usage:

from global_api_tools import explain_error

message = explain_error(ValueError("invalid input"))

get_status_code

Params:

• exc: Exception

Usage:

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:

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:

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:

{
  "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

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:

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:

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