feat: ✨ simplifies the structure, update docs

Author: gwainor

arcstack_api/__init__.py

@@ -1,11 +1,19 @@
 from .api import arcstack_api
 from .decorators import api_endpoint
 from .endpoint import Endpoint
-from .errors import APIError
+from .errors import APIError, InternalServerError, UnauthorizedError, ValidationError
 
 
 # isort: off
 
 __version__ = '0.0.0'
 
-__all__ = ['arcstack_api', 'Endpoint', 'APIError', 'api_endpoint']
+__all__ = [
+    'arcstack_api',
+    'Endpoint',
+    'APIError',
+    'ValidationError',
+    'UnauthorizedError',
+    'InternalServerError',
+    'api_endpoint',
+]

arcstack_api/api.py

@@ -8,30 +8,21 @@
 from typing_extensions import Doc
 
 from .conf import settings
-from .errors import ValidationError
 from .logger import logger
+from .meta import ArcStackRequestMeta
 from .responses import InternalServerErrorResponse
-from .serializers import JsonSerializer
-from .signature import EndpointSignature
 
 
 class ArcStackAPI:
-    _param_middleware: Annotated[
+    _endpoint_middleware: Annotated[
         list[Callable],
         Doc(
             """
             Middleware that will be called to build the endpoint kwargs.
             Should accept the following arguments:
             - request: The request object.
-            - signature: The signature of the endpoint.
-            - callback_args: The arguments of the callback.
-            - callback_kwargs: The keyword arguments of the callback.
-            Should return a tuple of (kwargs, response).
-            - kwargs: The keyword arguments to pass to the endpoint. Must be a
-              dictionary. `None` can be returned if there is nothing to add.
-            - response: The response to return. If the response is not None,
-              the execution will be terminated because there is probably a
-              validation error.
+            - meta: The ArcStackRequestMeta object.
+            Should either return a new ArcStackRequestMeta object or None.
             """
         ),
     ] = []
@@ -62,7 +53,7 @@ def __init__(self):
         self.load_middleware()
 
     def load_middleware(self):
-        self._param_middleware = []
+        self._endpoint_middleware = []
         self._exception_middleware = []
         handler = self._get_response
         for middleware_path in reversed(settings.API_MIDDLEWARE):
@@ -85,73 +76,53 @@ def load_middleware(self):
                     f'Middleware factory {middleware_path} returned None.'
                 )
 
-            if hasattr(mw_instance, 'process_params'):
-                self._param_middleware.insert(0, mw_instance.process_params)
+            if hasattr(mw_instance, 'process_endpoint'):
+                self._endpoint_middleware.insert(0, mw_instance.process_endpoint)
             if hasattr(mw_instance, 'process_exception'):
                 self._exception_middleware.append(mw_instance.process_exception)
-
         self._middleware_chain = handler
 
     def __call__(self, endpoint: Callable):
-        wrapper = self._create_wrapper(endpoint)
-        return wrapper
+        return self._create_wrapper(endpoint)
 
     def _create_wrapper(self, endpoint: Callable):
         @wraps(endpoint)
         def wrapper(request, *args, **kwargs):
-            request.endpoint = endpoint
-            request.signature = EndpointSignature(endpoint)
+            request._arcstack_meta = ArcStackRequestMeta(endpoint, args, kwargs)
 
             try:
-                response = self._middleware_chain(request, *args, **kwargs)
+                response = self._middleware_chain(request)
             except Exception as e:
                 response = self._process_exception(e, request)
 
             return response
 
         return wrapper
 
-    def _get_response(self, request, *args, **kwargs):
-        if not hasattr(request, 'endpoint'):
+    def _get_response(self, request):
+        if not hasattr(request, '_arcstack_meta'):
             raise ImproperlyConfigured(
-                'The request object must have an `endpoint` attribute. '
-                'To endpointize a view, use the `api` decorator or '
+                'The request object must have an `_arcstack_meta` attribute. '
+                'To endpointify a view, use the `api_endpoint` decorator or '
                 'subclass `Endpoint`.'
             )
 
-        response, endpoint_args, endpoint_kwargs = self._process_params(
-            request, *args, **kwargs
-        )
-
-        if response is None:
-            response = request.endpoint(request, *endpoint_args, **endpoint_kwargs)
-
-        return response
+        endpoint = request._arcstack_meta.endpoint
+        args = request._arcstack_meta.args
+        kwargs = request._arcstack_meta.kwargs
+        del request._arcstack_meta
 
-    def _process_params(self, request, *args, **kwargs):
-        """Process the parameters of the request through the middleware."""
         response = None
 
-        validation_errors = []
-        for middleware in self._param_middleware:
-            try:
-                args, kwargs = middleware(args, kwargs)
-            except ValidationError as e:
-                validation_errors.append(e)
-            except Exception as e:
-                response = self._process_exception(e, request)
+        for middleware in self._endpoint_middleware:
+            response = middleware(request, endpoint, *args, **kwargs)
+            if response is not None:
+                break
 
-        if validation_errors:
-            response = HttpResponse(
-                content=JsonSerializer.serialize(
-                    {
-                        'errors': [str(e) for e in validation_errors],
-                    }
-                ),
-                status=400,
-            )
+        if response is None:
+            response = endpoint(request, *args, **kwargs)
 
-        return response, args, kwargs
+        return response
 
     def _process_exception(
         self, exception: Exception, request: HttpRequest

arcstack_api/conf.py

@@ -4,7 +4,7 @@
 
 
 class ArcStackAPIConf(AppConf):
-    MIDDLEWARE = ['arcstack_api.middleware.common.CommonMiddleware']
+    MIDDLEWARE = ['arcstack_api.middleware.CommonMiddleware']
 
     JSON_ENCODER = 'django.core.serializers.json.DjangoJSONEncoder'
 

arcstack_api/constants.py

@@ -1,80 +1,10 @@
-from asgiref.sync import markcoroutinefunction
 from django.utils.decorators import classonlymethod
 from django.views import View
 
 from .api import arcstack_api
-from .conf import settings
-from .responses import MethodNotAllowedResponse, NotFoundResponse
 
 
 class Endpoint(View):
     @classonlymethod
     def as_endpoint(cls, **initkwargs):
-        """Serve the view as an endpoint.
-
-        The `View` class is a base class for all Django class-based views.
-        """
-        for key in initkwargs:
-            if key in cls.http_method_names:
-                raise TypeError(
-                    f'The method name {key} is not accepted as a keyword argument '
-                    f'to {cls.__name__}().'
-                )
-            if not hasattr(cls, key):
-                raise TypeError(
-                    f'{cls.__name__}() received an invalid keyword {key}. '
-                    'as_endpoint only accepts arguments that are already '
-                    'attributes of the class.'
-                )
-
-        def endpoint(request, *args, **kwargs):
-            self = cls(**initkwargs)
-            self.http_method = request.method.lower()
-
-            if 'setup_kwargs' in kwargs:
-                self.setup(request, **kwargs['setup_kwargs'])
-                del kwargs['setup_kwargs']
-            else:
-                self.setup(request, *args, **kwargs)
-
-            if self.http_method not in self.http_method_names:
-                return MethodNotAllowedResponse()
-
-            return self.dispatch(request, *args, **kwargs)
-
-        endpoint.view_class = cls
-        endpoint.view_initkwargs = initkwargs
-
-        # __name__ and __qualname__ are intentionally left unchanged as
-        # view_class should be used to robustly determine the name of the view
-        # instead.
-        endpoint.__doc__ = cls.__doc__
-        endpoint.__module__ = cls.__module__
-        endpoint.__annotations__ = cls.dispatch.__annotations__
-        # Copy possible attributes set by decorators, e.g. @csrf_exempt, from
-        # the dispatch method.
-        endpoint.__dict__.update(cls.dispatch.__dict__)
-
-        # Mark the callback if the view class is async.
-        if cls.view_is_async:
-            markcoroutinefunction(endpoint)
-
-        endpoint.LOGIN_REQUIRED = getattr(
-            cls, 'LOGIN_REQUIRED', settings.API_DEFAULT_LOGIN_REQUIRED
-        )
-
-        return arcstack_api(endpoint)
-
-    def setup(self, request, *args, **kwargs):
-        pass
-
-    def dispatch(self, request, *args, **kwargs):
-        handler = getattr(self, self.http_method, None)
-
-        if handler is None:
-            return NotFoundResponse()
-
-        if 'method_args' in kwargs:
-            return handler(**kwargs['method_args'])
-        else:
-            return handler(request, *args, **kwargs)
+        return arcstack_api(cls.as_view(**initkwargs))

arcstack_api/endpoint.py

@@ -1,11 +1,16 @@
+# pragma: exclude file
+
+from typing import Any
+
+
 class APIError(Exception):
     """Represents errors that should be returned as a response.
 
     Classes that inherit from this class should modify the `status_code`
     and `message` attributes.
     """
 
-    def __init__(self, message: str, status_code: int = 400):
+    def __init__(self, message: Any, status_code: int = 400):
         self.message = message
         self.status_code = status_code
 

arcstack_api/errors.py

@@ -0,0 +1,22 @@
+from collections.abc import Callable
+
+from .signature import EndpointSignature
+
+
+class ArcStackRequestMeta:
+    endpoint: Callable
+    args: tuple
+    kwargs: dict
+    _signature: EndpointSignature = None
+
+    def __init__(self, endpoint: Callable, args: tuple, kwargs: dict):
+        self.endpoint = endpoint
+        self.args = args
+        self.kwargs = kwargs
+
+    @property
+    def signature(self) -> EndpointSignature:
+        """Lazy signature creation."""
+        if self._signature is None:
+            self._signature = EndpointSignature(self.endpoint)
+        return self._signature

arcstack_api/meta.py

@@ -1,25 +1,25 @@
 from django.http import HttpRequest, HttpResponse
 
-from ..conf import settings
-from ..errors import APIError, UnauthorizedError
-from ..responses import JsonResponse, UnauthorizedResponse
-from ..serializers import JsonSerializer
-from .mixin import MiddlewareMixin
+from .conf import settings
+from .errors import APIError, InternalServerError, UnauthorizedError
+from .mixins import MiddlewareMixin
+from .responses import InternalServerErrorResponse, UnauthorizedResponse
+from .serializers import JsonSerializer
 
 
 class CommonMiddleware(MiddlewareMixin):
-    def process_request(self, request, *args, **kwargs):
-        endpoint = getattr(request, 'endpoint', None)
+    def process_request(self, request):
+        meta = getattr(request, '_arcstack_meta', None)
 
-        if endpoint is None:
+        if meta is None:
             # Not a valid request as an API endpoint
             return
 
-        self._check_login_required(request, endpoint)
+        self._check_login_required(request, meta.endpoint)
 
         return None
 
-    def process_response(self, request, response, *args, **kwargs):
+    def process_response(self, request, response):
         if isinstance(response, HttpResponse):
             # noop: The response is already an HttpResponse
             pass
@@ -30,10 +30,16 @@ def process_response(self, request, response, *args, **kwargs):
             or isinstance(response, bool)
         ):
             # Convert the response to a string and return it as an HttpResponse
-            response = HttpResponse(content=f'{response}')
+            response = HttpResponse(
+                content=f'{response}',
+                content_type='text/plain',
+            )
         elif JsonSerializer.is_json_serializable(response):
             data = JsonSerializer.serialize(response)
-            response = HttpResponse(content=data, content_type='application/json')
+            response = HttpResponse(
+                content=data,
+                content_type='application/json',
+            )
         else:
             raise ValueError(f'Unsupported response type: {type(response)}')
 
@@ -45,15 +51,12 @@ def process_exception(
         response = None
 
         if isinstance(exception, APIError):
-            response = JsonResponse(
-                {
-                    'error': exception.message,
-                    'status': exception.status_code,
-                },
-                status=exception.status_code,
-            )
+            response = self.process_response(request, exception.message)
+            response.status_code = exception.status_code
         elif isinstance(exception, UnauthorizedError):
             response = UnauthorizedResponse()
+        elif isinstance(exception, InternalServerError):
+            response = InternalServerErrorResponse()
 
         # Not an exception defined in the ArcStack API.
         # Let the other middleware handle it.

arcstack_api/middleware/common.py renamed to arcstack_api/middleware.py

@@ -13,15 +13,15 @@ def __repr__(self):
         )
         return f'<{qualname} get_response={get_response_qualname}>'
 
-    def __call__(self, request, *args, **kwargs):
+    def __call__(self, request):
         response = None
 
         if hasattr(self, 'process_request'):
-            response = self.process_request(request, *args, **kwargs)
+            response = self.process_request(request)
 
-        response = response or self.get_response(request, *args, **kwargs)
+        response = response or self.get_response(request)
 
         if hasattr(self, 'process_response'):
-            response = self.process_response(request, response, *args, **kwargs)
+            response = self.process_response(request, response)
 
         return response