django-dans-waitlist 0.0.1__tar.gz

django-dans-waitlist-0.0.1/AUTHORS

@@ -0,0 +1 @@
+Daniel Nazarian - dnaz@danielnazarian.com

django-dans-waitlist-0.0.1/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2024 Daniel Nazarian
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+* Neither the name of the Daniel Nazarian nor the names of its
+contributors may be used to endorse or promote products derived from this
+software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

django-dans-waitlist-0.0.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.rst
+recursive-include django_dans_waitlist/static *
+recursive-include django_dans_waitlist/templates *
+recursive-include docs *

django-dans-waitlist-0.0.1/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.1
+Name: django-dans-waitlist
+Version: 0.0.1
+Summary: A Django app to different basic waitlists.
+Home-page: https://www.github.com/dan1229/django_dans_waitlist
+Author: Daniel Nazarian
+Author-email: dnaz@danielnazarian.com
+License: BSD-3-Clause
+Platform: UNKNOWN
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.1
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: <3.12,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS
+
+# Django Dans Waitlist
+
+[![Lint](https://github.com/dan1229/django_dans_waitlist/actions/workflows/lint.yml/badge.svg)](https://github.com/dan1229/django_dans_waitlist/actions/workflows/lint.yml)
+[![Test Python](https://github.com/dan1229/django_dans_waitlist/actions/workflows/test-python.yml/badge.svg)](https://github.com/dan1229/django_dans_waitlist/actions/workflows/test-python.yml)
+[![codecov](https://codecov.io/gh/dan1229/django_dans_waitlist/branch/main/graph/badge.svg?token=TL09HDQWBJ)](https://codecov.io/gh/dan1229/django_dans_waitlist)
+
+## Description
+
+A Django app to handle waitlist and basic functionality.
+
+Support for `Waitlist` and `WaitlistEntry` models, as well as a `WaitlistManager` to handle common operations.
+
+## Quick start
+
+1. Install the package via pip:
+
+```bash
+pip install django-dans-waitlist
+```
+
+2. Add "django_dans_waitlist" to your INSTALLED_APPS setting like this:
+
+```python
+INSTALLED_APPS = [
+	...
+	'django_dans_waitlist',
+]
+```
+
+3. Include the URL configs in your project `urls.py` for the REST API endpoints like this:
+
+```python
+path("api/waitlist/", include("django_dans_waitlist.urls")),
+```
+
+4. Run `python manage.py migrate` to update your database schema.
+
+5. Use the API endpoints, in code or your Django admin portal.
+
+### Requirements
+
+- Python 3.10 - 3.11
+- Django 3.1 or higher
+- Django Rest Framework
+  - **NOTE:** not only must you have this installed, you must have set `DEFAULT_AUTHENTICATION_CLASSES` and `DEFAULT_PAGINATION_CLASS` in your `settings.py` to work with the APIs properly. An example config would be:
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
+    "PAGE_SIZE": 20,
+    "DEFAULT_AUTHENTICATION_CLASSES": (
+        "rest_framework.authentication.TokenAuthentication",
+    ),
+}
+```
+
+
+### Available Settings
+
+Currently all available settings are optional:
+
+- `TEAM_NAME` - Default team name to use for emails, can be added to message context manually as well still.
+
+
+Add these to your `settings.py` file to customize the app's behavior like so:
+
+```python
+TEAM_NAME = "My Team"
+```
+
+
+## Usage
+
+TODO
+
+## Docs
+
+TODO - which of these are still relevant?
+#### [Model docs](https://github.com/dan1229/django_dans_waitlist/tree/main/docs/models.md).
+
+#### [API docs](https://github.com/dan1229/django_dans_waitlist/tree/main/docs/apis.md).
+
+
+-------------------------------------------------------
+
+##### [https://danielnazarian.com](https://danielnazarian.com)
+
+##### Copyright 2024 © Daniel Nazarian.
+
+
+

django-dans-waitlist-0.0.1/README.md

@@ -0,0 +1,89 @@
+# Django Dans Waitlist
+
+[![Lint](https://github.com/dan1229/django_dans_waitlist/actions/workflows/lint.yml/badge.svg)](https://github.com/dan1229/django_dans_waitlist/actions/workflows/lint.yml)
+[![Test Python](https://github.com/dan1229/django_dans_waitlist/actions/workflows/test-python.yml/badge.svg)](https://github.com/dan1229/django_dans_waitlist/actions/workflows/test-python.yml)
+[![codecov](https://codecov.io/gh/dan1229/django_dans_waitlist/branch/main/graph/badge.svg?token=TL09HDQWBJ)](https://codecov.io/gh/dan1229/django_dans_waitlist)
+
+## Description
+
+A Django app to handle waitlist and basic functionality.
+
+Support for `Waitlist` and `WaitlistEntry` models, as well as a `WaitlistManager` to handle common operations.
+
+## Quick start
+
+1. Install the package via pip:
+
+```bash
+pip install django-dans-waitlist
+```
+
+2. Add "django_dans_waitlist" to your INSTALLED_APPS setting like this:
+
+```python
+INSTALLED_APPS = [
+	...
+	'django_dans_waitlist',
+]
+```
+
+3. Include the URL configs in your project `urls.py` for the REST API endpoints like this:
+
+```python
+path("api/waitlist/", include("django_dans_waitlist.urls")),
+```
+
+4. Run `python manage.py migrate` to update your database schema.
+
+5. Use the API endpoints, in code or your Django admin portal.
+
+### Requirements
+
+- Python 3.10 - 3.11
+- Django 3.1 or higher
+- Django Rest Framework
+  - **NOTE:** not only must you have this installed, you must have set `DEFAULT_AUTHENTICATION_CLASSES` and `DEFAULT_PAGINATION_CLASS` in your `settings.py` to work with the APIs properly. An example config would be:
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
+    "PAGE_SIZE": 20,
+    "DEFAULT_AUTHENTICATION_CLASSES": (
+        "rest_framework.authentication.TokenAuthentication",
+    ),
+}
+```
+
+
+### Available Settings
+
+Currently all available settings are optional:
+
+- `TEAM_NAME` - Default team name to use for emails, can be added to message context manually as well still.
+
+
+Add these to your `settings.py` file to customize the app's behavior like so:
+
+```python
+TEAM_NAME = "My Team"
+```
+
+
+## Usage
+
+TODO
+
+## Docs
+
+TODO - which of these are still relevant?
+#### [Model docs](https://github.com/dan1229/django_dans_waitlist/tree/main/docs/models.md).
+
+#### [API docs](https://github.com/dan1229/django_dans_waitlist/tree/main/docs/apis.md).
+
+
+-------------------------------------------------------
+
+##### [https://danielnazarian.com](https://danielnazarian.com)
+
+##### Copyright 2024 © Daniel Nazarian.
+

django-dans-waitlist-0.0.1/django_dans_waitlist/admin.py

@@ -0,0 +1,26 @@
+from django.contrib import admin
+from .models import WaitlistEntry
+
+
+#
+# WAITLIST ENTRY ========================= #
+#
+class WaitlistEntryAdmin(admin.ModelAdmin):
+    list_display = (
+        "email",
+        "datetime_created",
+    )
+
+    search_fields = (
+        "id",
+        "email",
+        "datetime_created",
+    )
+    readonly_fields = ("id",)
+    list_per_page = 100
+
+
+#
+# REGISTER ========================= #
+#
+admin.site.register(WaitlistEntry, WaitlistEntryAdmin)

django-dans-waitlist-0.0.1/django_dans_waitlist/api_response.py

@@ -0,0 +1,47 @@
+from typing import Any, Optional
+
+"""
+============================================================================================ #
+API RESPONSE =============================================================================== #
+============================================================================================ #
+"""
+
+
+class ApiResponse:
+    """
+    Response type to standardize response structure and conversions.
+
+    The point of this class is to standardize the response format for all API responses.
+    It does so by having properties that model the response structure you'd like.
+    """
+
+    def __init__(
+        self,
+        status: Optional[int] = None,
+        message: Optional[str] = None,
+        results: Optional[object | dict | list] = None,
+        error_fields: Optional[dict] = None,
+        **kwargs: Any
+    ) -> None:
+        self.status = status
+        self.message = message
+        self.results = results
+        self.error_fields = error_fields
+        self.extras = kwargs
+
+    def dict(self) -> dict:
+        """
+        Convert ApiResponse to dict. Primarily to use in actual Response object.
+
+        :returns: Dict containing ApiResponse object info
+        :rtype: dict
+        """
+        res = {
+            "status": self.status,
+            "message": self.message,
+            "results": self.results,
+            "error_fields": self.error_fields,
+        }
+        for key, value in self.extras.items():
+            res[key] = value
+        return res

django-dans-waitlist-0.0.1/django_dans_waitlist/api_response_handler.py

@@ -0,0 +1,171 @@
+import logging
+from typing import Optional
+from django.core.exceptions import ValidationError
+from django.db import IntegrityError
+from rest_framework.response import Response
+from rest_framework.status import HTTP_200_OK, HTTP_400_BAD_REQUEST
+from .api_response import ApiResponse
+
+LOGGER_DJANGO = logging.getLogger("django")
+
+"""
+============================================================================================ #
+API RESPONSE HANDLER ======================================================================= #
+============================================================================================ #
+"""
+
+
+class ApiResponseHandler:
+    """
+    Generic response handler to help manage API responses
+
+    This is used out of the box to provide standardized response formats,
+    as well as a centralized place to edit/mangle said responses.
+
+    Mainly just 'wrap' Responses/data you are already returning, this class
+    can help enforce structure or format such that you can have responses
+    look however you choose.
+
+    It works very closely with the ApiResponse class.
+    """
+
+    def __init__(
+        self,
+        message_error: str = "Error. Please try again later.",
+        message_success: str = "Successfully completed request.",
+        print_log: bool = True,
+    ):
+        self.message_error = message_error
+        self.message_success = message_success
+        self.print_log = print_log
+
+    @staticmethod
+    def _format_response(
+        response: Optional[Response] = None,
+        results: Optional[object | dict | list] = None,
+        message: Optional[str] = None,
+        status: Optional[int] = None,
+        error_fields: Optional[dict] = None,
+    ) -> Response:
+        """Internal function to format responses.
+
+        Args:
+            response (Response): Existing DRF response object to use for response.
+            results (list): List of results to include in response.
+            message (str): Message to include in response.
+            status (int): Status to use in response.
+            error_fields (dict, optional): Dictionary of field errors to include - typically provided by Django exceptions. Defaults to None.
+
+        Returns:
+            Response: DRF response object with desired format - can be used directly in views
+        """
+        api_response = ApiResponse(
+            message=message, status=status, results=results, error_fields=error_fields
+        )
+        if response:  # response passed -> simply edit
+            api_response.extras = response.data
+        return Response(api_response.dict(), status=status)
+
+    def _handle_logging(self, msg: str, print_log: Optional[bool] = None) -> None:
+        """Internal function to handle logging for responses handled by this class.
+
+        Args:
+            print_log (boolean): Whether or not to actually print the message.
+            msg (str): Message to print.
+        """
+        if print_log is None:  # print_log not passed, go by default
+            if self.print_log:
+                LOGGER_DJANGO.error(msg)
+        else:  # print_log passed, go by that
+            if print_log:
+                LOGGER_DJANGO.error(msg)
+
+    #
+    # RESPONSES
+    #
+    def response_success(
+        self,
+        message: Optional[str] = None,
+        results: Optional[object | dict | list] = None,
+        response: Optional[Response] = None,
+        status: Optional[int] = HTTP_200_OK,
+    ) -> Response:
+        """
+        :param str message: message to include in response
+        :param object results: results object/list to include in response
+        :param Response response: response object to simply edit
+        :param int status: HTTP status to use
+
+        :returns: response of the desired format
+        :rtype: Response
+        """
+        # no message = use default
+        if not message or message == "":
+            message = self.message_success
+        message = str(message)
+
+        return self._format_response(
+            response=response, results=results, message=message, status=status
+        )
+
+    def response_error(
+        self,
+        error: Optional[str | Exception] = None,
+        error_fields: Optional[dict] = None,
+        message: Optional[str] = None,
+        results: Optional[object | dict | list] = None,
+        response: Optional[Response] = None,
+        status: Optional[int] = HTTP_400_BAD_REQUEST,
+        print_log: Optional[bool] = True,
+    ) -> Response:
+        """
+        :param str|Exception error: error message to log
+        :param dict error_fields: list of fields to include in error response
+        :param str message: message to include in response
+        :param object results: results object/list to include in response
+        :param Response response: response object to simply edit
+        :param int status: HTTP status to use
+        :param bool print_log: override whether to print this error
+
+        :returns: response of the desired format
+        :rtype: Response
+        """
+        # django validation error
+        if (
+            isinstance(error, ValidationError)
+            and hasattr(error, "error_dict")
+            and error.error_dict.get("__all__")
+        ):
+            # try to parse ValidationError
+            messageDict = error.message_dict.get("__all__")
+            if isinstance(messageDict, list) and len(messageDict) > 0:
+                messageRes = str(messageDict[0])
+            else:
+                messageRes = self.message_error
+        # integrity error
+        elif isinstance(error, IntegrityError):
+            messageRes = str(error)
+        # no message passed and error isn't one we can parse
+        elif not message or message == "":  # use default message
+            messageRes = self.message_error
+        else:  # message passed, ensure it's a string
+            messageRes = str(message)
+
+        # error NOT passed, pass as this is probably not intended to be logged
+        if not error or error == "":
+            pass
+        else:  # error passed, log it somehow
+            if not message or message == "":  # message not passed, log error itself
+                self._handle_logging(str(error), print_log)
+            elif message != error:  # message and error different, log both
+                self._handle_logging(f"{message} - {error}", print_log)
+            else:  # error and message both exist and are the same
+                self._handle_logging(str(error), print_log)
+
+        return self._format_response(
+            response=response,
+            results=results,
+            message=messageRes,
+            status=status,
+            error_fields=error_fields,
+        )

django-dans-waitlist-0.0.1/django_dans_waitlist/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class DjangoDansWaitlistConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_dans_waitlist"

django-dans-waitlist-0.0.1/django_dans_waitlist/migrations/0001_initial.py

@@ -0,0 +1,33 @@
+from django.db import migrations, models
+import uuid
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="WaitlistEntry",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                ("datetime_created", models.DateTimeField(auto_now_add=True)),
+                ("datetime_modified", models.DateTimeField(auto_now=True)),
+                ("email", models.EmailField(max_length=254, unique=True)),
+            ],
+            options={
+                "verbose_name": "Waitlist Entry",
+                "verbose_name_plural": "Waitlist Entries",
+                "ordering": ["email"],
+            },
+        ),
+    ]

django-dans-waitlist-0.0.1/django_dans_waitlist/models.py

@@ -0,0 +1,42 @@
+import uuid
+
+from django.db import models
+
+"""
+# ==================================================================================== #
+# ABSTRACT BASE MODEL ================================================================ #
+# ==================================================================================== #
+"""
+
+
+class AbstractBaseModel(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    datetime_created = models.DateTimeField(auto_now_add=True, editable=False)
+    datetime_modified = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+        ordering = ["datetime_created"]
+
+    def __str__(self):
+        return "Abstract Base Model"
+
+
+"""
+# ==================================================================================== #
+# WAITLIST ENTRY ===================================================================== #
+# ==================================================================================== #
+"""
+
+
+class WaitlistEntry(AbstractBaseModel):
+    email = models.EmailField(unique=True)
+
+    def __str__(self) -> str:
+        return f"Waitlist Entry: {self.email}"
+
+    class Meta:
+        ordering = ["email"]
+        verbose_name = "Waitlist Entry"
+        verbose_name_plural = "Waitlist Entries"

django-dans-waitlist-0.0.1/django_dans_waitlist/permissions.py

@@ -0,0 +1,18 @@
+from typing import Any
+from rest_framework import permissions
+from rest_framework.request import Request
+
+"""
+============================================================================================ #
+BASE PERMISSIONS =========================================================================== #
+============================================================================================ #
+"""
+
+
+class AdminOnly(permissions.BasePermission):
+    """Allows access only to Admins."""
+
+    def has_permission(self, request: Request, view: Any) -> bool:
+        if request.user.is_authenticated and request.user.is_staff:
+            return True
+        return False

django-dans-waitlist-0.0.1/django_dans_waitlist/regex.py

@@ -0,0 +1,6 @@
+# REGEX.py
+# This file contains all the regular expression patterns used in the project
+#
+
+# Regular expression pattern for email validation
+REGEX_EMAIL = r"^[\w\.-]+@[\w\.-]+\.\w+$"

django-dans-waitlist-0.0.1/django_dans_waitlist/serializers/base.py

@@ -0,0 +1,60 @@
+from typing import Any, List
+from rest_framework import serializers
+
+"""
+# ===================================================================================
+# BASE SERIALIZER ===================================================================
+# ===================================================================================
+"""
+
+
+class BaseSerializer(serializers.ModelSerializer):
+    """
+    BaseSerializer to inherit from
+
+    :param bool masked:             If True, will mask the serializer.
+                                    Based on `masked_fields` property. Fields in `masked_fields` will only
+                                    show up if `masked` is False
+    :param bool ref_serializer:     If True, will return a reference serializer.
+                                    Based on `ref_fields` property, fields in `ref_fields` will only show
+                                    up if `ref_serializer` is False. If `ref_fields` is not provided,
+                                    all fields will be returned.
+    :param str[] fields:            Additional kwargs 'field' that controls which fields to include
+    """
+
+    ref_fields: List[str] = []
+    masked_fields: List[str] = []
+    masked = True
+    ref_serializer = False
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        # save kwargs for later
+        self.kwargs = kwargs
+
+        # handle 'fields' keyword argument
+        # Don't pass the 'fields' arg up to the superclass
+        fields = kwargs.pop("fields", None)
+
+        # if masked serializer, remove masked fields
+        self.masked = kwargs.pop("masked", self.masked)
+        masked_fields = getattr(self.Meta, "masked_fields", [])
+        if self.masked:
+            for field in masked_fields:
+                self.fields.pop(field)
+
+        # if ref serializer, remove ref fields
+        self.ref_serializer = kwargs.pop("ref_serializer", self.ref_serializer)
+        ref_fields = getattr(self.Meta, "ref_fields", [])
+        if self.ref_serializer:
+            for field in ref_fields:
+                self.fields.pop(field)
+
+        # Instantiate the superclass normally
+        super(BaseSerializer, self).__init__(*args, **kwargs)
+
+        # Drop any fields that are not specified in the `fields` argument.
+        if fields is not None:
+            allowed = set(fields)
+            existing = set(self.fields)
+            for field_name in existing - allowed:
+                self.fields.pop(field_name)