django-small-view-set 0.1.4__py3-none-any.whl → 0.2.1__py3-none-any.whl

{django_small_view_set-0.1.4.dist-info → django_small_view_set-0.2.1.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.1
 Name: django-small-view-set
-Version: 0.1.4
+Version: 0.2.1
 Summary: A lightweight Django ViewSet alternative with minimal abstraction.
 Home-page: https://github.com/nateonguitar/django-small-view-set
 License: MIT
-Keywords: django,viewset
+Keywords: django,small,viewset,view set
 Author: Nate Brooks
 Requires-Python: >=3.8
 Classifier: License :: OSI Approved :: MIT License
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Requires-Dist: django (>=3.2)
+Requires-Dist: pytest-django (>=4.11.1,<5.0.0)
 Project-URL: Repository, https://github.com/nateonguitar/django-small-view-set
 Description-Content-Type: text/markdown
 
@@ -27,41 +28,50 @@ This guide provides a simple example to get started with the library.
 
 ### Example Usage
 
-Here’s how you can define a basic API endpoint with one collection route and one detail route:
+Here’s how to define a basic view set:
+
+In settings.py
+```python
+# Register SmallViewSetConfig in settings
+from small_view_set SmallViewSetConfig
+
+SMALL_VIEW_SET_CONFIG = SmallViewSetConfig()
+```
+
 
 ```python
 import asyncio
 from django.http import JsonResponse
 from django.urls import path
-from small_view_set.small_view_set import SmallViewSet, default_handle_endpoint_exceptions, disable_endpoint
+from small_view_set import SmallViewSet, endpoint, endpoint_disabled
 
 class BarViewSet(SmallViewSet):
 
     def urlpatterns(self):
         return [
             path('api/bars/',          self.default_router, name='bars_collection'),
-            path('api/bars/items/',    self.items, name='bars_items'),
+            path('api/bars/items/',    self.items,          name='bars_items'),
             path('api/bars/<int:pk>/', self.default_router, name='bars_detail'),
         ]
 
-    @default_handle_endpoint_exceptions
+    @endpoint(allowed_methods=['GET'])
     def list(self, request):
         self.protect_list(request)
         return JsonResponse({"message": "Hello, world!"}, status=200)
 
-    @default_handle_endpoint_exceptions
-    @disable_endpoint
+    @endpoint(allowed_methods=['GET'])
+    @endpoint_disabled
     async def items(self, request):
         self.protect_list(request)
         await asyncio.sleep(1)
         return JsonResponse({"message": "List of items"}, status=200)
 
-    @default_handle_endpoint_exceptions
+    @endpoint(allowed_methods=['PATCH'])
     def patch(self, request, pk):
         self.protect_update(request)
         return JsonResponse({"message": f"Updated {pk}"}, status=200)
 
-    @default_handle_endpoint_exceptions
+    @endpoint(allowed_methods=['GET'])
     async def retrieve(self, request, pk):
         self.protect_retrieve(request)
         return JsonResponse({"message": f"Detail for ID {pk}"}, status=200)

django_small_view_set-0.2.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+small_view_set/README.md,sha256=oovLoOhBsg5wK8AwGe9iyuWXStHUo9x4fsrlb-oxHt4,1061
+small_view_set/__init__.py,sha256=lJ09qERCFrf4WAY6mRFyFsEG1R3ErpWqblIKi4TVggI,625
+small_view_set/config.py,sha256=nGu840qa6zYyXoQa1EO7xIlWh3dFPd0oYwN-2Qmj7Ws,1446
+small_view_set/decorators.py,sha256=0XSnTdmhvxnkLaRanoZhZq3BNiuP8JCe4vfVFWrRQkw,3200
+small_view_set/exceptions.py,sha256=5VaPS9m9syhag7p-gveG7Dep4DV3YQ7WjI1Sv5C_1N0,966
+small_view_set/helpers.py,sha256=EKx71YLS-5cN-JrMJXYR39O15qf4O6TDiaQsal7BVwY,5117
+small_view_set/small_view_set.py,sha256=wvNY1s3DRe2pLLLxz_91MCruEDl3iScOtDa8Y8L4siQ,5566
+django_small_view_set-0.2.1.dist-info/LICENSE,sha256=M4ZuHeiGHHuewaZyqz7tol4E6E2GMz7fF1ywNoXD1tA,1069
+django_small_view_set-0.2.1.dist-info/METADATA,sha256=UHgGDqDGiv6zTLzedn_jUtnCmCQigAgDViAhZ-hRIzQ,3607
+django_small_view_set-0.2.1.dist-info/WHEEL,sha256=d2fvjOD7sXsVzChCqf0Ty0JbHKBaLYwDbGQDwQTnJ50,88
+django_small_view_set-0.2.1.dist-info/RECORD,,

small_view_set/__init__.py

@@ -1,7 +1,12 @@
 from .small_view_set import SmallViewSet
+from .config import SmallViewSetConfig
 from .decorators import (
-    default_handle_endpoint_exceptions,
-    disable_endpoint,
+    endpoint,
+    endpoint_disabled,
+)
+from.helpers import (
+    default_exception_handler,
+    default_options_and_head_handler,
 )
 from .exceptions import (
     BadRequest,
@@ -12,8 +17,14 @@ from .exceptions import (
 
 __all__ = [
     "SmallViewSet",
-    "default_handle_endpoint_exceptions",
-    "disable_endpoint",
+    "SmallViewSetConfig",
+
+    "endpoint",
+    "endpoint_disabled",
+
+    "default_exception_handler",
+    "default_options_and_head_handler",
+
     "BadRequest",
     "EndpointDisabledException",
     "MethodNotAllowed",

small_view_set/config.py

@@ -0,0 +1,30 @@
+from typing import Callable
+from urllib.request import Request
+from .helpers import default_exception_handler, default_options_and_head_handler
+
+
+class SmallViewSetConfig:
+    """
+    Configuration class for SmallViewSet.
+
+    This class allows customization of exception handling and handling of
+    OPTIONS and HEAD requests for endpoints.
+
+    Args:
+        exception_handler (Callable[[str, Exception], None]): A callback function
+            for handling exceptions. The function takes two parameters:
+            1. The name of the endpoint function (e.g., 'list', 'retrieve', or a custom endpoint name).
+            2. The exception that was thrown.
+        options_and_head_handler (Callable[[Request, list[str]], None]): A callback function
+            for handling OPTIONS and HEAD requests. The function takes two parameters:
+            1. The Django Request object.
+            2. A list of allowed HTTP methods for the endpoint (e.g., ['PUT', 'PATCH']).
+    """
+    def __init__(
+            self,
+            exception_handler: Callable[[str, Exception], None] = default_exception_handler,
+            options_and_head_handler: Callable[[Request, list[str]], None] = default_options_and_head_handler,
+            respect_disabled_endpoints=True):
+        self.exception_handler = exception_handler
+        self.options_and_head_handler = options_and_head_handler
+        self.respect_disabled_endpoints = respect_disabled_endpoints

small_view_set/decorators.py

@@ -1,176 +1,52 @@
 import inspect
-import logging
 from django.conf import settings
 
-import json
-from django.conf import settings
-from django.core.exceptions import ObjectDoesNotExist, SuspiciousOperation, PermissionDenied
-from django.http import (
-    Http404,
-    JsonResponse,
-)
-
-from .exceptions import EndpointDisabledException, MethodNotAllowed, Unauthorized
-
-
-def _get_logger(name):
-    """
-    Retrieves a logger by name. If no logger is configured in settings.LOGGING,
-    it provides a fallback logger with a StreamHandler.
-
-    To control this logger in `settings.py`, add a logger configuration
-    under the `LOGGING` dictionary. For example:
-
-    LOGGING = {
-        'version': 1,
-        'disable_existing_loggers': False,
-        'handlers': {
-            'console': {
-                'class': 'logging.StreamHandler',
-            },
-        },
-        'loggers': {
-            'django-small-view-set.default_handle_endpoint_exceptions': {
-                'handlers': ['console'],
-                'level': 'INFO',
-                'propagate': True,
-            },
-        },
-    }
-
-    This configuration ensures that the logger named
-    'django-small-view-set.default_handle_endpoint_exceptions' uses the specified
-    handlers and logging level.
-    """
-    logger = logging.getLogger(name)
-
-    # Check if Django's logging is configured
-    if not logger.hasHandlers():
-        # Fallback logger setup
-        handler = logging.StreamHandler()
-        formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
-        handler.setFormatter(formatter)
-        logger.addHandler(handler)
-        logger.setLevel(logging.INFO)
-
-    return logger
-
-
-def default_handle_endpoint_exceptions(func):
-    logger = _get_logger('django-small-view-set.default_handle_endpoint_exceptions')
-
-    def _exception_handler(e):
-        try:
-            raise e
-
-        except json.JSONDecodeError:
-            return JsonResponse(data={"errors": "Invalid JSON"}, status=400)
-
-        except (TypeError, ValueError) as e:
-            if hasattr(e, 'detail'):
-                return JsonResponse(data={'errors': e.detail}, status=400)
-            if hasattr(e, 'message'):
-                return JsonResponse(data={'errors': e.message}, status=400)
-            return JsonResponse(data=None, safe=False, status=400)
-
-        except Unauthorized:
-            return JsonResponse(data=None, safe=False, status=401)
-
-        except (PermissionDenied, SuspiciousOperation):
-            return JsonResponse(data=None, safe=False, status=403)
-
-        except (Http404, ObjectDoesNotExist):
-            return JsonResponse(data=None, safe=False, status=404)
-        
-        except EndpointDisabledException:
-            return JsonResponse(data=None, safe=False, status=405)
-
-        except MethodNotAllowed as e:
-            return JsonResponse(
-                data={'errors': f"Method {e.method} is not allowed"},
-                status=405)
-
-        except Exception as e:
-            # Catch-all exception handler for API endpoints.
-            # 
-            # - Always defaults to HTTP 500 with "Internal server error" unless the exception provides a more specific status code and error details.
-            # - Duck types to extract error information from `detail` or `message` attributes, if available.
-            # - Never exposes internal exception contents to end users for 5xx server errors unless settings.DEBUG is True.
-            # - Allows structured error payloads (string, list, or dict) without assumptions about the error format.
-            # - Logs exceptions fully for server-side diagnostics, distinguishing handled vs unhandled cases.
-            # 
-            # This design prioritizes API security, developer debugging, and future portability across projects.
-
-            status_code = getattr(e, 'status_code', 500)
-            error_contents = None
-
-            if hasattr(e, 'detail'):
-                error_contents = e.detail
-            elif hasattr(e, 'message') and isinstance(e.message, str):
-                error_contents = e.message
-
-            if 400 <= status_code <= 499:
-                if status_code == 400:
-                    message = 'Bad request'
-                elif status_code == 401:
-                    message = 'Unauthorized'
-                elif status_code == 403:
-                    message = 'Forbidden'
-                elif status_code == 404:
-                    message = 'Not found'
-                elif status_code == 405:
-                    message = 'Method not allowed'
-                elif status_code == 429:
-                    message = 'Too many requests'
-                elif error_contents:
-                    message = error_contents
+from .config import SmallViewSetConfig
+from .exceptions import EndpointDisabledException
+
+def endpoint(
+        allowed_methods: list[str]):
+    def decorator(func):
+        func_name = func.__name__
+        def sync_wrapper(viewset, *args, **kwargs):
+            request = args[0]
+            try:
+                config: SmallViewSetConfig = getattr(settings, 'SMALL_VIEW_SET_CONFIG', SmallViewSetConfig())
+                pre_response = config.options_and_head_handler(request, allowed_methods)
+                if pre_response:
+                    return pre_response
+                pk = kwargs.pop('pk', None)
+                if pk is None:
+                    return func(viewset, request=request)
                 else:
-                    message = 'An error occurred'
-
-                if settings.DEBUG and error_contents:
-                    message = error_contents
-            else:
-                status_code = 500
-                message = 'Internal server error'
-                if settings.DEBUG:
-                    message = error_contents if error_contents else str(e)
-
-            func_name = func.__name__
-            e_name = type(e).__name__
-            if error_contents:
-                msg = f"Handled API exception in {func_name}: {e_name}: {error_contents}"
-                logger.error(msg)
-                    
-            else:
-                msg = f"Unhandled exception in {func_name}: {e_name}: {e}"
-                logger.error(msg)
-                    
-
-            return JsonResponse(
-                data={'errors': message},
-                safe=False,
-                status=status_code,
-                content_type='application/json')
-
-    def sync_wrapper(*args, **kwargs):
-        try:
-            return func(*args, **kwargs)
-        except Exception as e:
-            return _exception_handler(e)
+                    return func(viewset, request=request, pk=pk)
+            except Exception as e:
+                return config.exception_handler(request, func_name, e)
+
+        async def async_wrapper(viewset, *args, **kwargs):
+            request = args[0]
+            try:
+                config: SmallViewSetConfig = getattr(settings, 'SMALL_VIEW_SET_CONFIG', SmallViewSetConfig())
+                pre_response = config.options_and_head_handler(request, allowed_methods)
+                if pre_response:
+                    return pre_response
+                pk = kwargs.pop('pk', None)
+                if pk is None:
+                    return await func(viewset, request=request)
+                else:
+                    return await func(viewset, request=request, pk=pk)
+            except Exception as e:
+                return config.exception_handler(request, func_name, e)
 
-    async def async_wrapper(*args, **kwargs):
-        try:
-            return await func(*args, **kwargs)
-        except Exception as e:
-            return _exception_handler(e)
+        if inspect.iscoroutinefunction(func):
+            return async_wrapper
+        else:
+            return sync_wrapper
 
-    if inspect.iscoroutinefunction(func):
-        return async_wrapper
-    else:
-        return sync_wrapper
+    return decorator
 
 
-def disable_endpoint(func):
+def endpoint_disabled(func):
     """
     Temporarily disables an API endpoint based on the SMALL_VIEWSET_RESPECT_DISABLED_ENDPOINTS setting.
 
@@ -186,20 +62,20 @@ def disable_endpoint(func):
         class ExampleViewSet(SmallViewSet):
 
             @default_handle_endpoint_exceptions
-            @disable_endpoint
+            @endpoint_disabled
             def retrieve(self, request: Request) -> JsonResponse:
                 self.protect_retrieve(request)
                 . . .
         ```
     """
-    respect_disabled_endpoints = getattr(settings, 'SMALL_VIEWSET_RESPECT_DISABLED_ENDPOINTS', True)
+    config: SmallViewSetConfig = getattr(settings, 'SMALL_VIEW_SET_CONFIG', SmallViewSetConfig())
     def sync_wrapper(*args, **kwargs):
-        if respect_disabled_endpoints:
+        if config.respect_disabled_endpoints:
             raise EndpointDisabledException()
         return func(*args, **kwargs)
 
     async def async_wrapper(*args, **kwargs):
-        if respect_disabled_endpoints:
+        if config.respect_disabled_endpoints:
             raise EndpointDisabledException()
         return await func(*args, **kwargs)
 

small_view_set/helpers.py

@@ -0,0 +1,133 @@
+import json
+import logging
+
+from django.conf import settings
+from django.core.exceptions import ObjectDoesNotExist, SuspiciousOperation, PermissionDenied
+from django.http import Http404, JsonResponse
+from urllib.request import Request
+
+from .exceptions import EndpointDisabledException, MethodNotAllowed, Unauthorized
+
+
+_logger = logging.getLogger('django-small-view-set.default_handle_endpoint_exceptions')
+if not _logger.hasHandlers():
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
+    handler.setFormatter(formatter)
+    _logger.addHandler(handler)
+    _logger.setLevel(logging.INFO)
+
+
+def default_options_and_head_handler(request, allowed_methods: list[str]):
+    if request.method == 'OPTIONS':
+            response = JsonResponse(
+                data=None,
+                safe=False,
+                status=200,
+                content_type='application/json')
+            response['Allow'] = ', '.join(allowed_methods)
+            return response
+
+    if request.method == 'HEAD':
+        response = JsonResponse(
+            data=None,
+            safe=False,
+            status=200,
+            content_type='application/json')
+        response['Allow'] = ', '.join(allowed_methods)
+        return response
+
+    if request.method not in allowed_methods:
+        raise MethodNotAllowed(method=request.method)
+
+
+def default_exception_handler(request: Request, endpoint_name: str, exception):
+    try:
+        raise exception
+
+    except json.JSONDecodeError:
+        return JsonResponse(data={"errors": "Invalid JSON"}, status=400)
+
+    except (TypeError, ValueError) as exception:
+        if hasattr(exception, 'detail'):
+            return JsonResponse(data={'errors': exception.detail}, status=400)
+        if hasattr(exception, 'message'):
+            return JsonResponse(data={'errors': exception.message}, status=400)
+        return JsonResponse(data=None, safe=False, status=400)
+
+    except Unauthorized:
+        return JsonResponse(data=None, safe=False, status=401)
+
+    except (PermissionDenied, SuspiciousOperation):
+        return JsonResponse(data=None, safe=False, status=403)
+
+    except (Http404, ObjectDoesNotExist):
+        return JsonResponse(data=None, safe=False, status=404)
+    
+    except EndpointDisabledException:
+        return JsonResponse(data=None, safe=False, status=405)
+
+    except MethodNotAllowed as exception:
+        return JsonResponse(
+            data={'errors': f"Method {exception.method} is not allowed"},
+            status=405)
+
+    except Exception as exception:
+        # Catch-all exception handler for API endpoints.
+        # 
+        # - Always defaults to HTTP 500 with "Internal server error" unless the exception provides a more specific status code and error details.
+        # - Duck types to extract error information from `detail` or `message` attributes, if available.
+        # - Never exposes internal exception contents to end users for 5xx server errors unless settings.DEBUG is True.
+        # - Allows structured error payloads (string, list, or dict) without assumptions about the error format.
+        # - Logs exceptions fully for server-side diagnostics, distinguishing handled vs unhandled cases.
+        # 
+        # This design prioritizes API security, developer debugging, and future portability across projects.
+
+        status_code = getattr(exception, 'status_code', 500)
+        error_contents = None
+
+        if hasattr(exception, 'detail'):
+            error_contents = exception.detail
+        elif hasattr(exception, 'message') and isinstance(exception.message, str):
+            error_contents = exception.message
+
+        if 400 <= status_code <= 499:
+            if status_code == 400:
+                message = 'Bad request'
+            elif status_code == 401:
+                message = 'Unauthorized'
+            elif status_code == 403:
+                message = 'Forbidden'
+            elif status_code == 404:
+                message = 'Not found'
+            elif status_code == 405:
+                message = 'Method not allowed'
+            elif status_code == 429:
+                message = 'Too many requests'
+            elif error_contents:
+                message = error_contents
+            else:
+                message = 'An error occurred'
+
+            if settings.DEBUG and error_contents:
+                message = error_contents
+        else:
+            status_code = 500
+            message = 'Internal server error'
+            if settings.DEBUG:
+                message = error_contents if error_contents else str(exception)
+
+        e_name = type(exception).__name__
+        if error_contents:
+            msg = f"Handled API exception in {endpoint_name}: {e_name}: {error_contents}"
+            _logger.error(msg)
+                
+        else:
+            msg = f"Unhandled exception in {endpoint_name}: {e_name}: {exception}"
+            _logger.error(msg)
+
+        return JsonResponse(
+            data={'errors': message},
+            safe=False,
+            status=status_code,
+            content_type='application/json')

small_view_set/small_view_set.py

@@ -1,6 +1,7 @@
 import inspect
 import json
 import logging
+from django.http import JsonResponse
 from urllib.request import Request
 
 from .exceptions import BadRequest, MethodNotAllowed
@@ -15,48 +16,68 @@ class SmallViewSet:
 
     def protect_create(self, request: Request):
         """
-        Ensures that the request method is POST.
-        Raises:
-            MethodNotAllowed: If the request method is not GET.
+        Stub for adding any custom business logic to protect the create method.
+        For example:
+        - Check if the user is authenticated
+        - Check if the user has validated their email
+        - Throttle requests
+
+        Recommended to call super().protect_create(request) in the subclass in case
+        this library adds logic in the future.
         """
-        if request.method != 'POST':
-            raise MethodNotAllowed('POST')
+        pass
 
     def protect_list(self, request: Request):
         """
-        Ensures that the request method is GET.
-        Raises:
-            MethodNotAllowed: If the request method is not GET.
+        Stub for adding any custom business logic to protect the list method.
+        For example:
+        - Check if the user is authenticated
+        - Check if the user has validated their email
+        - Throttle requests
+
+        Recommended to call super().protect_create(request) in the subclass in case
+        this library adds logic in the future.
         """
-        if request.method != 'GET':
-            raise MethodNotAllowed(request.method)
+        pass
 
     def protect_retrieve(self, request: Request):
         """
-        Ensures that the request method is GET.
-        Raises:
-            MethodNotAllowed: If the request method is not GET.
+        Stub for adding any custom business logic to protect the retrieve method.
+        For example:
+        - Check if the user is authenticated
+        - Check if the user has validated their email
+        - Throttle requests
+
+        Recommended to call super().protect_create(request) in the subclass in case
+        this library adds logic in the future.
         """
-        if request.method != 'GET':
-            raise MethodNotAllowed(request.method)
+        pass
 
     def protect_update(self, request: Request):
         """
-        Ensures that the request method is PUT or PATCH.
-        Raises:
-            MethodNotAllowed: If the request method is not PUT or PATCH.
+        Stub for adding any custom business logic to protect the update method.
+        For example:
+        - Check if the user is authenticated
+        - Check if the user has validated their email
+        - Throttle requests
+
+        Recommended to call super().protect_create(request) in the subclass in case
+        this library adds logic in the future.
         """
-        if request.method not in ['PUT', 'PATCH']:
-            raise MethodNotAllowed(request.method)
+        pass
 
     def protect_delete(self, request: Request):
         """
-        Ensures that the request method is DELETE.
-        Raises:
-            MethodNotAllowed: If the request method is not DELETE.
+        Stub for adding any custom business logic to protect the delete method.
+        For example:
+        - Check if the user is authenticated
+        - Check if the user has validated their email
+        - Throttle requests
+
+        Recommended to call super().protect_create(request) in the subclass in case
+        this library adds logic in the future.
         """
-        if request.method != 'DELETE':
-            raise MethodNotAllowed(request.method)
+        pass
 
     async def default_router(self, request: Request, pk=None, *args, **kwargs):
         """

django_small_view_set-0.1.4.dist-info/RECORD

@@ -1,9 +0,0 @@
-small_view_set/README.md,sha256=oovLoOhBsg5wK8AwGe9iyuWXStHUo9x4fsrlb-oxHt4,1061
-small_view_set/__init__.py,sha256=FoYcTj03W41-w0jC1EOv1_VD4iBxO_03fIr_plSKnp8,441
-small_view_set/decorators.py,sha256=f_1K7YVvWe409UdwnX3rTTypzkV0IsKqS9oBaBICqRQ,7509
-small_view_set/exceptions.py,sha256=5VaPS9m9syhag7p-gveG7Dep4DV3YQ7WjI1Sv5C_1N0,966
-small_view_set/small_view_set.py,sha256=t_oRePTjjHhMjc1g3vrJtY9C5oW_dtfrhdKNA3PzU7Q,4775
-django_small_view_set-0.1.4.dist-info/LICENSE,sha256=M4ZuHeiGHHuewaZyqz7tol4E6E2GMz7fF1ywNoXD1tA,1069
-django_small_view_set-0.1.4.dist-info/METADATA,sha256=yxIVHh9dcAYCrw9157Q6SwGscdCNdhP3W5lLGyewmtc,3475
-django_small_view_set-0.1.4.dist-info/WHEEL,sha256=d2fvjOD7sXsVzChCqf0Ty0JbHKBaLYwDbGQDwQTnJ50,88
-django_small_view_set-0.1.4.dist-info/RECORD,,