django-api-utility 0.1.0__tar.gz

django_api_utility-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Django MQTT Publisher
+
+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.

django_api_utility-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include MANIFEST.in
+include pyproject.toml
+include setup.py
+include requirements.txt
+recursive-include django_api_utility *.py
+recursive-include config *.json
+global-exclude __pycache__
+global-exclude *.py[co]

django_api_utility-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: django-api-utility
+Version: 0.1.0
+Summary: Reusable API integration utility for Django services
+Author: Nexgensis
+License: MIT
+Project-URL: Repository, https://example.com/django-api-utility
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=3.2
+Requires-Dist: requests>=2.28
+Requires-Dist: cryptography>=41.0
+Requires-Dist: jsonschema>=4.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-django>=4.5; extra == "test"
+Dynamic: license-file
+
+# django-api-utility
+
+Reusable API integration utility for Django services.
+
+## Features
+- Service + endpoint registry models
+- Definition-key based endpoint resolution
+- OAuth token fetch/refresh flow with encrypted token storage
+- Consistent utility exceptions for config, token, and request errors
+- Thin request wrapper with retry support
+
+## Install
+```bash
+pip install -e .
+```
+
+## Django setup
+Add app:
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_api_utility",
+]
+```
+
+## Definition key mapping
+Provide a JSON mapping file via `EXTERNAL_DEFINITION_KEYS_FILE`, or use the packaged default at `config/external_definition_keys.json`.
+
+Example:
+```json
+{
+  "users_get": "service_users_get"
+}
+```
+
+## Usage
+```python
+from django_api_utility import get_by_key, post_by_key
+
+response = get_by_key("users_get", params={"page": 1})
+create_response = post_by_key("users_create", payload={"name": "Alice"})
+```
+
+## Internal layout
+- `django_api_utility/transport/`: HTTP transport and outbound execution primitives
+- `django_api_utility/domain/`: definition keys, endpoint resolution, token lifecycle
+- `django_api_utility/orchestration/`: request orchestration with retries and token refresh fallback
+
+## Tests
+```bash
+pip install -e ".[test]"
+pytest -q
+```

django_api_utility-0.1.0/README.md

@@ -0,0 +1,53 @@
+# django-api-utility
+
+Reusable API integration utility for Django services.
+
+## Features
+- Service + endpoint registry models
+- Definition-key based endpoint resolution
+- OAuth token fetch/refresh flow with encrypted token storage
+- Consistent utility exceptions for config, token, and request errors
+- Thin request wrapper with retry support
+
+## Install
+```bash
+pip install -e .
+```
+
+## Django setup
+Add app:
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_api_utility",
+]
+```
+
+## Definition key mapping
+Provide a JSON mapping file via `EXTERNAL_DEFINITION_KEYS_FILE`, or use the packaged default at `config/external_definition_keys.json`.
+
+Example:
+```json
+{
+  "users_get": "service_users_get"
+}
+```
+
+## Usage
+```python
+from django_api_utility import get_by_key, post_by_key
+
+response = get_by_key("users_get", params={"page": 1})
+create_response = post_by_key("users_create", payload={"name": "Alice"})
+```
+
+## Internal layout
+- `django_api_utility/transport/`: HTTP transport and outbound execution primitives
+- `django_api_utility/domain/`: definition keys, endpoint resolution, token lifecycle
+- `django_api_utility/orchestration/`: request orchestration with retries and token refresh fallback
+
+## Tests
+```bash
+pip install -e ".[test]"
+pytest -q
+```

django_api_utility-0.1.0/config/external_definition_keys.json

@@ -0,0 +1 @@
+{}

django_api_utility-0.1.0/django_api_utility/__init__.py

@@ -0,0 +1,68 @@
+"""Reusable API integration utility for Django services."""
+
+from .exceptions import (
+    ApiUtilityError,
+    ConfigurationError,
+    DefinitionKeyError,
+    EndpointConfigError,
+    EndpointRequestError,
+    HttpClientError,
+    TokenConfigError,
+    TokenRequestError,
+    SchemaValidationError,
+)
+
+
+def request_by_key(*args, **kwargs):
+    from .orchestration.api_service import request_by_key as _request_by_key
+
+    return _request_by_key(*args, **kwargs)
+
+
+def get_by_key(*args, **kwargs):
+    from .orchestration.api_service import get_by_key as _get_by_key
+
+    return _get_by_key(*args, **kwargs)
+
+
+def post_by_key(*args, **kwargs):
+    from .orchestration.api_service import post_by_key as _post_by_key
+
+    return _post_by_key(*args, **kwargs)
+
+
+def put_by_key(*args, **kwargs):
+    from .orchestration.api_service import put_by_key as _put_by_key
+
+    return _put_by_key(*args, **kwargs)
+
+
+def patch_by_key(*args, **kwargs):
+    from .orchestration.api_service import patch_by_key as _patch_by_key
+
+    return _patch_by_key(*args, **kwargs)
+
+
+def delete_by_key(*args, **kwargs):
+    from .orchestration.api_service import delete_by_key as _delete_by_key
+
+    return _delete_by_key(*args, **kwargs)
+
+
+__all__ = [
+    "ApiUtilityError",
+    "ConfigurationError",
+    "DefinitionKeyError",
+    "EndpointConfigError",
+    "EndpointRequestError",
+    "HttpClientError",
+    "TokenConfigError",
+    "TokenRequestError",
+    "SchemaValidationError",
+    "request_by_key",
+    "get_by_key",
+    "post_by_key",
+    "put_by_key",
+    "patch_by_key",
+    "delete_by_key",
+]

django_api_utility-0.1.0/django_api_utility/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class DjangoApiUtilityConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_api_utility"
+    verbose_name = "Django API Utility"

django_api_utility-0.1.0/django_api_utility/domain/__init__.py

@@ -0,0 +1,15 @@
+"""Domain layer: config lookup, endpoint resolution, and token flow."""
+
+from .definition_keys import clear_definition_key_cache, get_definition_key
+from .endpoint_service import build_url, resolve_endpoint
+from .token_service import get_or_refresh_service_token
+from .types import ResolvedEndpoint
+
+__all__ = [
+    "get_definition_key",
+    "clear_definition_key_cache",
+    "build_url",
+    "resolve_endpoint",
+    "get_or_refresh_service_token",
+    "ResolvedEndpoint",
+]

django_api_utility-0.1.0/django_api_utility/domain/definition_keys.py

@@ -0,0 +1,53 @@
+import json
+import os
+from functools import lru_cache
+from pathlib import Path
+
+from django.conf import settings
+
+from django_api_utility.exceptions import DefinitionKeyError
+
+
+_DEFAULT_KEYS_FILE = Path(__file__).resolve().parents[2] / "config" / "external_definition_keys.json"
+
+
+def _keys_file_path() -> Path:
+    configured = (
+        getattr(settings, "EXTERNAL_DEFINITION_KEYS_FILE", "")
+        or os.getenv("EXTERNAL_DEFINITION_KEYS_FILE", "")
+        or str(_DEFAULT_KEYS_FILE)
+    )
+    return Path(configured)
+
+
+@lru_cache(maxsize=1)
+def _load_keys() -> dict:
+    keys_file = _keys_file_path()
+    if not keys_file.exists():
+        raise DefinitionKeyError(
+            f"Definition key config file not found at {keys_file}. "
+            "Set EXTERNAL_DEFINITION_KEYS_FILE to a valid JSON file."
+        )
+
+    try:
+        with keys_file.open("r", encoding="utf-8") as file_obj:
+            data = json.load(file_obj) or {}
+    except json.JSONDecodeError as exc:
+        raise DefinitionKeyError(f"Definition key file is invalid JSON at {keys_file}: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise DefinitionKeyError("external_definition_keys.json must contain a JSON object")
+    return data
+
+
+def get_definition_key(name: str) -> str:
+    """Resolve runtime key alias to configured endpoint definition key."""
+    keys = _load_keys()
+    value = keys.get(name)
+    if not value:
+        raise DefinitionKeyError(f"Definition key '{name}' not found in {_keys_file_path()}")
+    return str(value)
+
+
+def clear_definition_key_cache() -> None:
+    _load_keys.cache_clear()

django_api_utility-0.1.0/django_api_utility/domain/endpoint_service.py

@@ -0,0 +1,34 @@
+from django_api_utility.exceptions import EndpointConfigError
+from django_api_utility.models import ExternalServiceEndpoint
+
+from .token_service import get_or_refresh_service_token
+from .types import ResolvedEndpoint
+
+
+def build_url(base_url: str, path: str) -> str:
+    """Join base URL and endpoint path with normalized slashes."""
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+
+
+def resolve_endpoint(definition_key: str, force_token_refresh: bool = False) -> ResolvedEndpoint:
+    """Resolve active endpoint config and authorization headers for execution."""
+    endpoint = (
+        ExternalServiceEndpoint.objects.select_related("service")
+        .filter(definition_key=definition_key, is_active=True, service__is_active=True)
+        .first()
+    )
+    if not endpoint:
+        raise EndpointConfigError(f"Active endpoint definition_key '{definition_key}' is not configured")
+
+    headers: dict[str, str] = {}
+    if endpoint.service.auth_required:
+        token = get_or_refresh_service_token(endpoint.service, force_refresh=force_token_refresh)
+        headers["Authorization"] = f"Bearer {token}"
+
+    timeout = endpoint.timeout_seconds or endpoint.service.default_timeout_seconds or 10
+    return ResolvedEndpoint(
+        endpoint=endpoint,
+        url=build_url(endpoint.service.base_url, endpoint.path),
+        timeout=timeout,
+        headers=headers,
+    )

django_api_utility-0.1.0/django_api_utility/domain/schema_service.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from django.conf import settings
+
+from django_api_utility.exceptions import SchemaValidationError
+from django_api_utility.models import ExternalEndpointSchema
+
+try:
+    from jsonschema import ValidationError as JsonSchemaValidationError
+    from jsonschema import validate as jsonschema_validate
+except Exception:  # pragma: no cover - import failure path
+    JsonSchemaValidationError = Exception
+    jsonschema_validate = None
+
+
+def schema_validation_enabled() -> bool:
+    return bool(getattr(settings, "API_UTILITY_VALIDATE_SCHEMAS", True))
+
+
+def _get_active_schema(endpoint, schema_kind: str) -> Optional[ExternalEndpointSchema]:
+    # Supports tests that pass mocked/non-model endpoints.
+    endpoint_pk = getattr(endpoint, "pk", None)
+    if not endpoint_pk:
+        return None
+
+    return (
+        ExternalEndpointSchema.objects.filter(
+            endpoint=endpoint,
+            schema_kind=schema_kind,
+            is_active=True,
+        )
+        .order_by("-updated_at")
+        .first()
+    )
+
+
+def validate_payload_schema(*, definition_key: str, endpoint, schema_kind: str, payload: Any) -> None:
+    if not schema_validation_enabled():
+        return
+
+    schema_row = _get_active_schema(endpoint, schema_kind)
+    if not schema_row:
+        return
+
+    if jsonschema_validate is None:
+        raise SchemaValidationError(
+            f"Schema validation requested for '{definition_key}' but jsonschema dependency is unavailable"
+        )
+
+    schema_json = schema_row.schema_json or {}
+    try:
+        jsonschema_validate(instance=payload, schema=schema_json)
+    except JsonSchemaValidationError as exc:
+        raise SchemaValidationError(
+            f"{schema_kind.title()} schema validation failed for '{definition_key}': {exc.message}"
+        ) from exc

django_api_utility-0.1.0/django_api_utility/domain/token_service.py

@@ -0,0 +1,125 @@
+from datetime import timedelta
+
+from django.conf import settings
+from django.utils import timezone
+
+from django_api_utility.exceptions import HttpClientError, TokenConfigError, TokenRequestError
+from django_api_utility.models import ExternalServiceEndpoint, IntegrationServiceTokenConfig
+from django_api_utility.transport.outbound_service import execute_outbound_request
+
+
+def _get_token_config_for_service(service):
+    return (
+        IntegrationServiceTokenConfig.objects.filter(service=service, is_active=True)
+        .order_by("-updated_at")
+        .first()
+    )
+
+
+def _resolve_token_url(service) -> str:
+    configured_key = str(getattr(settings, "API_UTILITY_TOKEN_DEFINITION_KEY", "request_service_token") or "").strip()
+    if not configured_key:
+        configured_key = "request_service_token"
+
+    service_key = str(service.name or "").strip().lower().replace(" ", "_")
+    candidate_keys = [
+        configured_key,
+        "request_service_token",
+        "request_token",
+        f"{service_key}_{configured_key}",
+        f"{service_key}_request_service_token",
+        f"{service_key}_request_token",
+    ]
+
+    token_endpoint = None
+    for key in candidate_keys:
+        token_endpoint = (
+            ExternalServiceEndpoint.objects.filter(
+                service=service,
+                is_active=True,
+                method__iexact="POST",
+                definition_key__iexact=key,
+            )
+            .order_by("id")
+            .first()
+        )
+        if token_endpoint:
+            break
+
+    if not token_endpoint:
+        raise TokenConfigError(
+            f"Token endpoint not configured in ExternalServiceEndpoint for service '{service.name}'. "
+            f"Expected definition_key one of: {candidate_keys}"
+        )
+
+    return f"{service.base_url.rstrip('/')}/{token_endpoint.path.lstrip('/')}"
+
+
+def _request_new_service_token(config, service) -> str:
+    token_service = config.service or service
+    if config.service_id and config.service_id != service.id:
+        raise TokenConfigError(
+            f"Token config service mismatch. Config is for '{config.service.name}', "
+            f"requested service is '{service.name}'."
+        )
+
+    token_url = _resolve_token_url(token_service)
+    grant_type = str(getattr(settings, "API_UTILITY_TOKEN_GRANT_TYPE", "client_credentials") or "client_credentials")
+    scope = str(getattr(settings, "API_UTILITY_TOKEN_SCOPE", "") or "").strip()
+
+    payload = {
+        "grant_type": grant_type,
+        "client_id": config.client_id,
+        "client_secret": config.get_client_secret(),
+    }
+    if scope:
+        payload["scope"] = scope
+
+    timeout = int(getattr(settings, "API_UTILITY_TOKEN_TIMEOUT_SECONDS", 10) or 10)
+    try:
+        response = execute_outbound_request(
+            method="POST",
+            url=token_url,
+            form_data=payload,
+            timeout=timeout,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+    except HttpClientError as exc:
+        raise TokenRequestError(f"Token request failed for service '{token_service.name}': {exc}") from exc
+
+    if response.status_code >= 400:
+        raise TokenRequestError(
+            f"Token request failed for service '{token_service.name}' "
+            f"with status {response.status_code}: {response.text[:500]}"
+        )
+
+    try:
+        body = response.json() or {}
+    except ValueError as exc:
+        raise TokenRequestError(f"Token response for service '{token_service.name}' is not valid JSON") from exc
+
+    access_token = str(body.get("access_token") or "").strip()
+    if not access_token:
+        raise TokenRequestError(f"Token response for service '{token_service.name}' missing access_token")
+
+    expires_in = int(body.get("expires_in") or getattr(settings, "API_UTILITY_DEFAULT_TOKEN_EXPIRES_IN", 3600))
+    config.set_service_token(access_token)
+    config.token_expiry = timezone.now() + timedelta(seconds=max(expires_in, 1))
+    config.save(update_fields=["service_token", "token_expiry", "updated_at"])
+    return access_token
+
+
+def get_or_refresh_service_token(service, force_refresh: bool = False) -> str:
+    """Return valid token for service and refresh it when required."""
+    config = _get_token_config_for_service(service)
+    if not config:
+        raise TokenConfigError(
+            f"No active IntegrationServiceTokenConfig found for service '{service.name}'. "
+            "Save token config with matching service first."
+        )
+
+    buffer_seconds = int(getattr(settings, "API_UTILITY_TOKEN_EXPIRY_BUFFER_SECONDS", 60) or 60)
+    if not force_refresh and config.has_valid_service_token(buffer_seconds=buffer_seconds):
+        return config.get_service_token()
+
+    return _request_new_service_token(config=config, service=service)

django_api_utility-0.1.0/django_api_utility/domain/types.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass, field
+from typing import Dict
+
+from django_api_utility.models import ExternalServiceEndpoint
+
+
+@dataclass(frozen=True)
+class ResolvedEndpoint:
+    """Resolved endpoint metadata required to execute a request."""
+
+    endpoint: ExternalServiceEndpoint
+    url: str
+    timeout: int
+    headers: Dict[str, str] = field(default_factory=dict)

django_api_utility-0.1.0/django_api_utility/exceptions.py

@@ -0,0 +1,34 @@
+class ApiUtilityError(Exception):
+    """Base exception for the utility."""
+
+
+class ConfigurationError(ApiUtilityError):
+    """Raised when static utility configuration is invalid."""
+
+
+class DefinitionKeyError(ConfigurationError):
+    """Raised when a definition key cannot be loaded/resolved."""
+
+
+class EndpointConfigError(ConfigurationError):
+    """Raised when endpoint config is missing or invalid."""
+
+
+class TokenConfigError(ConfigurationError):
+    """Raised when token config is missing or invalid."""
+
+
+class HttpClientError(ApiUtilityError):
+    """Raised when an outbound HTTP call fails at transport layer."""
+
+
+class TokenRequestError(ApiUtilityError):
+    """Raised when token endpoint request/response is invalid."""
+
+
+class EndpointRequestError(ApiUtilityError):
+    """Raised when endpoint request execution fails."""
+
+
+class SchemaValidationError(EndpointRequestError):
+    """Raised when request/response schema validation fails."""