django-small-view-set 0.1.0__py3-none-any.whl

django_small_view_set-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nateonguitar
+
+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_small_view_set-0.1.0.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.1
+Name: django-small-view-set
+Version: 0.1.0
+Summary: A lightweight Django ViewSet alternative with minimal abstraction.
+Home-page: https://github.com/yourusername/django-small-view-set
+License: MIT
+Keywords: django,viewset
+Author: Nate Brooks
+Requires-Python: >=3.8
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: django (>=3.2)
+Project-URL: Repository, https://github.com/yourusername/django-small-view-set
+Description-Content-Type: text/markdown
+
+# Django Small View Set
+
+A lightweight Django ViewSet alternative with minimal abstraction. This library provides a simple and transparent way to define API endpoints without relying on complex abstractions.
+
+## Documentation
+
+- [Getting Started](./README_SIMPLE.md): A bare-bones example to get the fundamentals.
+- [Register URLs](./README_REGISTER_URLS): How to register viewset urls.
+- [Custom Endpoints](./README_CUSTOM_ENDPOINT.md): Learn how to define custom endpoints alongside the default router.
+- [Handling Endpoint Exceptions](./README_HANDLE_ENDPOINT_EXCEPTIONS.md): Understand how to write your own decorators for exception handling.
+- [Custom Protections](./README_CUSTOM_PROTECTIONS.md): Learn how to subclass `SmallViewSet` to add custom protections like logged-in checks.
+- [DRF Compatibility](./README_DRF_COMPATIBILITY.md): Learn how to use some of Django Rest Framework's tools, like Serializers.
+
+## Reasoning behind this library:
+
+A note from the library creator:
+
+I feel like a justification to not "just use DRF" is in order.
+
+After working in Django Rest Framework for years, I liked how nice it was for getting an API up and running really quickly, but I hated how often I would get stuck debugging some abstracted thing in a serializer, or a viewset, then spend too much time implementing some niche (and usually hacky feeling) fix.
+
+Sadly, there are a lot of these pain points in DRF, and a lack of separation-of-concerns. For instance, I always disliked how serializers don't just serialize, they do operations like saving and updating, often resulting in business logic in serializers. That is not serialization. When using mixins on DRF viewsets, often customization methods are required, like which permissions to use for each endpoint, which serializer to use, add a custom "perform_create" method to help serializers save, etc. and it makes it difficult to do reverse lookups to endpoints. It also meant POSTing to reverse('foo-list') would happen, which really should be posting to the "foo-collection" or something else. It's nitpicky yes, but these nitpicks are all over.
+
+So I wrote this. No black box anything. Surprisingly (because it was not the goal), I reduced the number of lines of code in every single one of my viewsets because I didn't need to register so many mixins, set up complex decorators, or define so many helper methods.
+
+I still like some tools DRF provides, like throttles and serializers (when only used as validators or model => json conversions), those are still completely compatible and honestly amazing. I'm glad DRF exists, I've gotten a TON of use out of it over the years.
+
+I also really liked my Spring Boot experience (and other frameworks, but Spring Boot was recent) where the pattern is to throw exceptions and a global exception handler will convert the errors to json responses, allowing a developer to bail on an endpoint at any time, no matter how deep in business logic they may be.
+
+With this ViewSet and pattern, your call stack will never be far away from the real issue, letting you debug in peace.

django_small_view_set-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+small_view_set/README.md,sha256=ltlV_52FkT8L1V_JfczYmSMRKaqOWWFKpcaWmzBnec4,1121
+small_view_set/__init__.py,sha256=FoYcTj03W41-w0jC1EOv1_VD4iBxO_03fIr_plSKnp8,441
+small_view_set/decorators.py,sha256=OSwGz5SfTw7hUjOcPNmCmUl8mLqaHOMXaLcqg9JBHXo,6750
+small_view_set/exceptions.py,sha256=8CAnzvNZFlqjez8z66jLo-4P3Tlj5Y5MioDPmrb9wQg,948
+small_view_set/small_view_set.py,sha256=THDeJp1PmodaWzFUUnowpDmhH8w1El4p97jvQnjyU4k,5192
+django_small_view_set-0.1.0.dist-info/LICENSE,sha256=M4ZuHeiGHHuewaZyqz7tol4E6E2GMz7fF1ywNoXD1tA,1069
+django_small_view_set-0.1.0.dist-info/METADATA,sha256=xAvDG-F2RRm2ByiAe8No_qcuuBeYwJ0PRIceH2fPB4o,3819
+django_small_view_set-0.1.0.dist-info/WHEEL,sha256=d2fvjOD7sXsVzChCqf0Ty0JbHKBaLYwDbGQDwQTnJ50,88
+django_small_view_set-0.1.0.dist-info/RECORD,,

django_small_view_set-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.7.0
+Root-Is-Purelib: true
+Tag: py3-none-any

small_view_set/README.md

@@ -0,0 +1,40 @@
+# Steps for Releasing to PyPI
+
+1. **Build the Docker Image**:
+   ```bash
+   docker compose build --no-cache
+   docker compose up -d
+   ```
+
+2. **Configure PyPI Credentials**:
+   - Set up your PyPI token inside the Docker container:
+     ```bash
+     docker compose run django-small-view-set-builder sh -c 'poetry config pypi-token.pypi $POETRY_PUBLISH_TOKEN'
+     ```
+
+3. **Install Dependencies**:
+   - Install dependencies inside the container after mounting the directory:
+     ```bash
+     docker compose run django-small-view-set-builder poetry install
+     ```
+
+4. **Run Tests**:
+   - Run tests before releasing:
+     ```bash
+     docker compose run django-small-view-set-builder python /app/tests/manage.py test
+     ```
+
+5. **Build the Package**:
+   Inside the Docker container, build the package:
+   ```bash
+   docker compose run django-small-view-set-builder poetry build
+     ```
+
+6. **Publish to PyPI**:
+   Upload the package to PyPI:
+   ```bash
+   docker compose run django-small-view-set-builder poetry publish
+     ```
+
+7. **Verify the Release**:
+   - Visit your package page on PyPI to confirm the release.

small_view_set/__init__.py

@@ -0,0 +1,21 @@
+from .small_view_set import SmallViewSet
+from .decorators import (
+    default_handle_endpoint_exceptions,
+    disable_endpoint,
+)
+from .exceptions import (
+    BadRequest,
+    EndpointDisabledException,
+    MethodNotAllowed,
+    Unauthorized,
+)
+
+__all__ = [
+    "SmallViewSet",
+    "default_handle_endpoint_exceptions",
+    "disable_endpoint",
+    "BadRequest",
+    "EndpointDisabledException",
+    "MethodNotAllowed",
+    "Unauthorized",
+]

small_view_set/decorators.py

@@ -0,0 +1,185 @@
+import logging
+from django.conf import settings
+from functools import wraps
+
+import json
+import functools
+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):
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        logger = _get_logger('django-small-view-set.default_handle_endpoint_exceptions')
+
+        try:
+            return func(*args, **kwargs)
+
+        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 (EndpointDisabledException, Http404, ObjectDoesNotExist):
+            return JsonResponse(data=None, safe=False, status=404)
+
+        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
+                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')
+
+    return wrapper
+
+
+def disable_endpoint(view_func):
+    """
+    Temporarily disables an API endpoint based on the SMALL_VIEWSET_RESPECT_DISABLED_ENDPOINTS setting.
+
+    When `SMALL_VIEWSET_RESPECT_DISABLED_ENDPOINTS` in Django settings is set to `True`, this decorator
+    will raise an `EndpointDisabledException`, resulting in a 404 response. When set to `False`,
+    the endpoint will remain active, which is useful for testing environments.
+
+    Usage:
+        - Apply this decorator directly to a view method or action.
+        - Example:
+        
+        ```python
+        class ExampleViewSet(SmallViewSet):
+
+            @disable_endpoint
+            @default_handle_endpoint_exceptions
+            def retrieve(self, request: Request) -> JsonResponse:
+                self.protect_retrieve(request)
+                . . .
+        ```
+    """
+    @wraps(view_func)
+    def wrapper(*args, **kwargs):
+        if settings.SMALL_VIEWSET_RESPECT_DISABLED_ENDPOINTS:
+            raise EndpointDisabledException()
+        return view_func(*args, **kwargs)
+    return wrapper
+

small_view_set/exceptions.py

@@ -0,0 +1,30 @@
+class EndpointDisabledException(Exception):
+    status_code = 404
+    message = "Not Found"
+    error_code = "not_found"
+
+class Unauthorized(Exception):
+    status_code = 401
+    message = "Unauthorized"
+    error_code = "unauthorized"
+
+class BadRequest(Exception):
+    status_code = 400
+    error_code = "bad_request"
+    def __init__(self, message: str | list | dict):
+        """
+        Args:
+            message (str | list | dict): 
+                A JSON-serializable error description to send to the client. 
+                Typically a string, list of errors, or dictionary of field errors.
+        """
+        self.message = message or "Bad Request"
+        super().__init__(message)
+
+class MethodNotAllowed(Exception):
+    status_code = 405
+    error_code = "method_not_allowed"
+    def __init__(self, method: str):
+        self.method = method
+        self.message = f'Method {method} not allowed'
+        super().__init__(self.message)

small_view_set/small_view_set.py

@@ -0,0 +1,138 @@
+import json
+import logging
+from django.http import JsonResponse
+from urllib.request import Request
+
+from .exceptions import BadRequest, MethodNotAllowed
+
+logger = logging.getLogger('app')
+
+class SmallViewSet:
+    def create(self, request: Request, *args, **kwargs):
+        raise MethodNotAllowed('POST')
+
+    def list(self, request: Request, *args, **kwarg):
+        raise MethodNotAllowed('GET')
+
+    def retrieve(self, request: Request, pk, *args, **kwargs):
+        raise MethodNotAllowed('GET')
+
+    def put(self, request: Request, pk, *args, **kwargs):
+        raise MethodNotAllowed('PUT')
+
+    def patch(self, request: Request, pk, *args, **kwargs):
+        raise MethodNotAllowed('PATCH')
+
+    def delete(self, request: Request, pk, *args, **kwargs):
+        raise MethodNotAllowed('DELETE')
+
+    def parse_json_body(self, request: Request):
+        if request.content_type != 'application/json':
+            raise BadRequest('Invalid content type')
+        return json.loads(request.body)
+
+    def protect_create(self, request: Request):
+        """
+        Ensures that the request method is POST.
+        Raises:
+            MethodNotAllowed: If the request method is not GET.
+        """
+        if request.method != 'POST':
+            raise MethodNotAllowed('POST')
+
+    def protect_list(self, request: Request):
+        """
+        Ensures that the request method is GET.
+        Raises:
+            MethodNotAllowed: If the request method is not GET.
+        """
+        if request.method != 'GET':
+            raise MethodNotAllowed(request.method)
+
+    def protect_retrieve(self, request: Request):
+        """
+        Ensures that the request method is GET.
+        Raises:
+            MethodNotAllowed: If the request method is not GET.
+        """
+        if request.method != 'GET':
+            raise MethodNotAllowed(request.method)
+
+    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.
+        """
+        if request.method not in ['PUT', 'PATCH']:
+            raise MethodNotAllowed(request.method)
+
+    def protect_delete(self, request: Request):
+        """
+        Ensures that the request method is DELETE.
+        Raises:
+            MethodNotAllowed: If the request method is not DELETE.
+        """
+        if request.method != 'DELETE':
+            raise MethodNotAllowed(request.method)
+
+    def default_router(self, request: Request, pk=None, *args, **kwargs):
+        """
+        This method routes requests to the appropriate method based on the HTTP method and presence of a primary key (pk).
+        
+        It also handles errors and returns appropriate JSON responses by using the decorator @default_handle_endpoint_exceptions.
+        
+        GET/POST for collection endpoints and GET/PUT/PATCH/DELETE for detail endpoints.
+
+        Example:
+        ```
+        # Note: AppViewSet is a subclass of SmallViewSet with overridden protect methods with more specific logic.
+
+        class CommentViewSet(AppViewSet):
+            def urlpatterns(self):
+                return [
+                    path('api/comments/',                     self.default_router, name='comments_collection'),
+                    path('api/comments/<int:pk>/',            self.default_router, name='comments_detail'),
+                    path('api/comments/<int:pk>/custom_put/', self.custom_put,     name='comments_custom_put_detail'),
+                ]
+
+            @default_handle_endpoint_exceptions
+            def create(self, request: Request):
+                self.protect_create(request)
+                . . .
+
+            @default_handle_endpoint_exceptions
+            def update(self, request: Request, pk: int):
+                self.protect_update(request)
+                . . .
+
+            @default_handle_endpoint_exceptions
+            def custom_put(self, request: Request, pk: int):
+                self.protect_update(request)
+                . . .
+
+            @disable_endpoint
+            @default_handle_endpoint_exceptions
+            def some_disabled_endpoint(self, request: Request):
+                self.protect_retrieve(request)
+                . . .
+                
+        ```
+        """
+        if pk is None:
+            if request.method == 'GET':
+                return self.list(request, *args, **kwargs)
+            elif request.method == 'POST':
+                return self.create(request, *args, **kwargs)
+        else:
+            if request.method == 'GET':
+                return self.retrieve(request, pk, *args, **kwargs)
+            elif request.method == 'PUT':
+                return self.put(request, pk, *args, **kwargs)
+            elif request.method == 'PATCH':
+                return self.patch(request, pk, *args, **kwargs)
+            elif request.method == 'DELETE':
+                return self.delete(request, pk, *args, **kwargs)
+        endpoint_type = "detail" if pk else "collection"
+        logger.error(f'Got a none response from request_router for {endpoint_type} method {request.method}')
+        return JsonResponse(data=None, safe=False, status=500)