Initial version

Author: Dmitry Berezovsky

.gitignore

@@ -1,3 +1,4 @@
+.idea
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -8,7 +9,7 @@ __pycache__/
 
 # Distribution / packaging
 .Python
-env/
+/env/
 build/
 develop-eggs/
 dist/
@@ -85,7 +86,6 @@ celerybeat-schedule
 # virtualenv
 .venv
 venv/
-ENV/
 
 # Spyder project settings
 .spyderproject

api_commons/__init__.py

@@ -0,0 +1,206 @@
+import logging
+import sys
+from json import JSONEncoder
+from uuid import UUID
+
+import collections
+from django.core.exceptions import ObjectDoesNotExist
+from django.http import HttpRequest
+from django.http import HttpResponse
+from rest_framework import status as HttpStatus
+from rest_framework.authentication import SessionAuthentication, BasicAuthentication
+from rest_framework.exceptions import NotAuthenticated, AuthenticationFailed
+from rest_framework.renderers import JSONRenderer
+from rest_framework.response import Response
+from rest_framework.settings import api_settings
+from rest_framework.views import APIView
+from typing import Union
+
+from .dto import BaseDto, ApiResponseDto
+from .error import InvalidPaginationOptionsError, InvalidInputDataError, ErrorCode
+
+DtoOrMessageOrErrorCode = Union[BaseDto, str, ErrorCode]
+Payload = Union[collections.Iterable, BaseDto, None]
+
+logger = logging.getLogger(__name__)
+
+
+class ApiResponse(Response):
+    __SECRET = object()
+
+    def __init__(self, payload: Payload = None, status=None, template_name=None, headers=None, exception=False,
+                 content_type='application/json',
+                 secret=None) -> None:
+        if secret != self.__SECRET:
+            raise ValueError(
+                "Using constructor of the ApiResponse is not allowed, please "
+                "use static methods instead. See .success()")
+
+        assert payload is None \
+               or isinstance(payload, collections.Iterable) \
+               or isinstance(payload, BaseDto), "payload should be subclass of ApiResponse"
+        super().__init__(None, status, template_name, headers, exception, content_type)
+        api_response_dto = ApiResponseDto(payload)
+        self.data = api_response_dto
+
+    @classmethod
+    def __update_response_for_error(cls, response, dto_or_error_message: DtoOrMessageOrErrorCode, error_code,
+                                    default_message):
+        if isinstance(dto_or_error_message, ErrorCode):
+            error_code = dto_or_error_message.error_code
+            dto_or_error_message = dto_or_error_message.dto_or_error_message
+        if isinstance(dto_or_error_message, BaseDto):
+            response.data.service.validation_errors = dto_or_error_message.errors
+        response.data.service.error_code = error_code if error_code is not None else response.status_code
+        response.data.service.error_message = default_message \
+            if isinstance(dto_or_error_message, BaseDto) else str(dto_or_error_message)
+
+    @classmethod
+    def not_found(cls, dto_or_error_message: DtoOrMessageOrErrorCode, error_code=None):
+        response = ApiResponse(None, status=HttpStatus.HTTP_404_NOT_FOUND, secret=cls.__SECRET)
+        cls.__update_response_for_error(response, dto_or_error_message, error_code, "Entity not found")
+        return response
+
+    @classmethod
+    def success(cls, payload: [BaseDto, None] = None, status: int = HttpStatus.HTTP_200_OK):
+        return ApiResponse(payload, status=status, secret=cls.__SECRET)
+
+    @classmethod
+    def not_authenticated(cls, *args):
+        response = ApiResponse(None, status=HttpStatus.HTTP_401_UNAUTHORIZED, secret=cls.__SECRET)
+        if len(args) > 0:
+            message = args[0]
+        else:
+            message = "Unauthorized"
+        response.data.service.error_message = message
+        return response
+
+    @classmethod
+    def bad_request(cls, dto_or_error_message: Union[BaseDto, str], error_code: int = None):
+        response = ApiResponse(None, status=HttpStatus.HTTP_400_BAD_REQUEST, secret=cls.__SECRET)
+        cls.__update_response_for_error(response, dto_or_error_message, error_code,
+                                        "Bad request. Check service.validation_errors for details")
+        return response
+
+    @classmethod
+    def internal_server_error(cls, exception: Exception = None):
+        response = ApiResponse(None, status=HttpStatus.HTTP_500_INTERNAL_SERVER_ERROR, secret=cls.__SECRET)
+        response.data.service.error_code = HttpStatus.HTTP_500_INTERNAL_SERVER_ERROR
+        return response
+
+
+class JsonEncoder(JSONEncoder):
+    def default(self, o):
+        if isinstance(o, BaseDto):
+            return o.to_dict()
+        if isinstance(o, UUID):
+            return str(o)
+        return super().default(o)
+
+
+class CsrfExemptSessionAuthentication(SessionAuthentication):
+    def enforce_csrf(self, request: HttpRequest):
+        pass
+
+
+class JsonRenderer(JSONRenderer):
+    encoder_class = JsonEncoder
+    media_type = 'application/json'
+    format = 'json'
+    ensure_ascii = not api_settings.UNICODE_JSON
+    compact = api_settings.COMPACT_JSON
+
+    def get_indent(self, accepted_media_type, renderer_context: dict):
+        return None if self.compact else 4
+
+    def render(self, api_response: ApiResponseDto, accepted_media_type=None, renderer_context=None):
+        assert isinstance(api_response, ApiResponseDto), "api_response should be an instance of ApiResponseDto"
+        return super().render(api_response, accepted_media_type, renderer_context)
+
+
+class BaseController(APIView):
+    renderer_classes = [JsonRenderer]
+    authentication_classes = (CsrfExemptSessionAuthentication,)
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+    def parse_int(self, str_value, field_name=None) -> int:
+        try:
+            return int(str_value)
+        except ValueError:
+            raise InvalidInputDataError('Invalid {} value. Should be integer.'.format(field_name), str_value)
+
+    def parse_int_pk(self, str_value, field_name=None) -> int:
+        pk = self.parse_int(str_value)
+        if pk <= 0:
+            raise InvalidInputDataError('Invalid {} value. Should be positive integer'.format(field_name), str_value)
+        return pk
+
+    def parse_bool_value(self, str_value, field_name=None) -> bool:
+        try:
+            return str_value.lower() not in ['false', 'no', '1', 'False']
+        except ValueError:
+            raise InvalidInputDataError('Invalid {} value. Should be boolean'.format(field_name), str_value)
+
+    def get_bool_param_from_url(self, request, param):
+        create_node = True
+        if request.query_params.get(param) is not None:
+            create_node = self.parse_bool_value(request.query_params[param], param)
+        return create_node
+
+    def get_string_param_from_url(self, request, param):
+        if request.query_params.get(param) is not None:
+            return request.query_params[param]
+
+
+class BasicAuthController(BaseController):
+    authentication_classes = (CsrfExemptSessionAuthentication, BasicAuthentication,)
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+
+def exception_handler(exc: Exception, context):
+    logger.warning("Incoming request processing was terminated due to handled exception:", exc_info=exc)
+    if isinstance(exc, InvalidPaginationOptionsError):
+        return ApiResponse.bad_request('Bad limit and/or offset')
+    if isinstance(exc, (NotAuthenticated, AuthenticationFailed)):
+        return ApiResponse.not_authenticated()
+    if isinstance(exc, ObjectDoesNotExist):
+        return ApiResponse.not_found(exc)
+    if isinstance(exc, InvalidInputDataError):
+        return ApiResponse.bad_request(str(exc))
+    else:
+        logger.exception(str(exc))
+        return ApiResponse.internal_server_error(exc)
+    raise exc
+
+
+def __set_response_attributes(response: HttpResponse):
+    response.accepted_renderer = JsonRenderer()
+    response.accepted_media_type = JsonRenderer.media_type
+    response.renderer_context = {"data": None}
+    return response.render()
+
+
+def error_500_handler(request: HttpRequest):
+    exec_info = sys.exc_info()
+    logger.error('Internal Server Error: %s.', str(exec_info[1]),
+                 exc_info=exec_info,
+                 extra={
+                     'status_code': 500,
+                     'rs.path': request.path,
+                     'request': request
+                 })
+    return __set_response_attributes(ApiResponse.internal_server_error(exec_info[1]))
+
+
+def error_404_handler(request: HttpRequest, exception: Exception):
+    logger.warning('Not Found: %s. %s', request.path, str(exception),
+                   extra={
+                       'status_code': 404,
+                       'path': request.path,
+                       'request': request
+                   })
+    return __set_response_attributes(ApiResponse.not_found(""))

api_commons/common.py

@@ -0,0 +1,109 @@
+from django.conf import settings
+from rest_framework.fields import empty, Field
+from rest_framework.serializers import Serializer
+
+
+class BaseDto(Serializer):
+    def to_dict(self):
+        if not hasattr(self, '_data'):
+            return self.initial_data
+        else:
+            return self.data
+
+    def __init__(self, data=empty, **kwargs):
+        self.initial_data = {}
+        super(BaseDto, self).__init__(None, data, **kwargs)
+
+    def __setattr__(self, key, value):
+        if key in self.get_declared_fields():
+            self.initial_data[key] = value
+        else:
+            super().__setattr__(key, value)
+
+    def __getattr__(self, key):
+        if key in self.get_declared_fields():
+            return self.initial_data.get(key)
+        else:
+            if key in dir(super(BaseDto, self)):
+                return getattr(super(), key)
+            else:
+                raise AttributeError("Object {} doesn't have attribute {}".format(self.__class__.__name__, key))
+
+    @classmethod
+    def from_dict(cls, dictionary=empty):
+        instance = cls(dictionary)
+        return instance
+
+    @classmethod
+    def get_declared_fields(cls):
+        if hasattr(cls, '_declared_fields'):
+            return getattr(cls, '_declared_fields')
+        else:
+            return []
+
+
+class ApiResponseServiceSection(BaseDto):
+    def __init__(self):
+        self.error_code = 0
+        self.error_message = None
+        self.validation_errors = []
+        self.api_version = settings.API_VERSION
+
+    def is_successful(self):
+        return self.error_code == 0
+
+    def to_dict(self):
+        return {
+            "error_code": self.error_code,
+            "node_id": settings.HOSTNAME,
+            "error_message": self.error_message,
+            "validation_errors": self.validation_errors,
+            "successful": self.is_successful(),
+            "api_version": self.api_version
+        }
+
+
+class ApiResponseDto(BaseDto):
+    def __init__(self, payload=None):
+        self.payload = payload
+        self.service = ApiResponseServiceSection()
+
+    def to_dict(self):
+        serialized_payload = self.payload
+        if isinstance(self.payload, BaseDto):
+            serialized_payload = self.payload.to_representation(self.payload)
+        return {
+            "payload": serialized_payload,
+            "service": self.service.to_dict()
+        }
+
+
+class RelatedDtoField(Field):
+    def __init__(self, dto_class, required: bool = None, default=empty, initial=empty) -> None:
+        super().__init__(read_only=False, write_only=False, source=None, required=required, default=default,
+                         initial=initial,
+                         label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)
+        self.dto_class = dto_class
+
+    def to_representation(self, instance: BaseDto):
+        return instance.to_dict()
+
+    def to_internal_value(self, data: dict):
+        dto = self.dto_class.from_dict(data)
+        dto.is_valid()
+        return dto
+
+
+class PaginationOptions(object):
+    """ Pagination options class, has offset and limit parameters."""
+
+    def __init__(self, offset: int = 0, limit: int = 50) -> None:
+        """ Return pagination options object with limit and offset.
+        :param offset: Pagination offset
+        :type offset: int
+        :param limit: Pagination limit
+        :type limit: int
+        :rtype: PaginationOptions
+        """
+        self.offset = offset
+        self.limit = limit

api_commons/dto.py

@@ -0,0 +1,20 @@
+class InvalidInputDataError(Exception):
+    def __init__(self, msg, input_value, *args, **kwargs):
+        super().__init__(msg, *args, **kwargs)
+        self.input_value = input_value
+
+
+class InvalidPaginationOptionsError(Exception):
+    pass
+
+
+class NotFoundException(Exception):
+    def __init__(self, msg, input_value, *args, **kwargs):
+        super().__init__(msg, *args, **kwargs)
+        self.input_value = input_value
+
+
+class ErrorCode:
+    def __init__(self, error_code, dto_or_error_message=''):
+        self.error_code = error_code
+        self.dto_or_error_message = dto_or_error_message

api_commons/error.py

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+cd $(dirname "$(realpath "$0")")
+copyright -c ./copyright.json ../api_commons

development/copyright-update

@@ -0,0 +1,11 @@
+{
+    "author": "Dmitry Berezovsky",
+    "back": false,
+    "exclude": "",
+    "include": "*.py",
+    "license": "mit",
+    "program": "Django API Commons",
+    "short": "Boilerplate commons for django based web api application.",
+    "single": true,
+    "year": "2017"
+}