django-spire 0.23.4__py3-none-any.whl

django_spire/file/tools.py

@@ -0,0 +1,34 @@
+from typing import Any
+
+from django.contrib.contenttypes.models import ContentType
+
+from django_spire.file.models import File
+
+
+def copy_files_from_source_to_target_model_object(source: Any, target: Any) -> list[File]:
+    target_class = target.__class__
+    target_content_type = ContentType.objects.get_for_model(target_class)
+
+    file_list = source.files.active()
+
+    if not file_list.exists():
+        return []
+
+    files_to_create = []
+    for file in file_list:
+        new_file = File(
+            content_type=target_content_type,
+            object_id=target.pk,
+            file=file.file,
+            name=file.name,
+            size=file.size,
+            type=file.type,
+            related_field=file.related_field,
+            is_active=file.is_active,
+            is_deleted=file.is_deleted
+        )
+        files_to_create.append(new_file)
+
+    File.objects.bulk_create(files_to_create)
+
+    return files_to_create

django_spire/file/urls.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from django.urls import path
+
+from django_spire.file import views
+
+
+app_name = 'file'
+
+urlpatterns = [
+    path('upload/multiple/ajax',
+         views.file_multiple_upload_ajax,
+         name='upload_multiple_ajax'),
+
+    path('upload/single/ajax',
+         views.file_single_upload_ajax,
+         name='upload_single_ajax'),
+]

django_spire/file/utils.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import binascii
+import os
+
+
+def random_64_char_token() -> str:
+    return str(binascii.hexlify(os.urandom(32)).decode())

django_spire/file/views.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.contrib.auth.decorators import login_required
+from django.http import JsonResponse
+
+from django_spire.file.interfaces import MultiFileUploader, SingleFileUploader
+
+if TYPE_CHECKING:
+    from django.core.handlers.wsgi import WSGIRequest
+
+
+@login_required()
+def file_multiple_upload_ajax(request: WSGIRequest) -> JsonResponse:
+    if request.method == 'POST':
+        file_uploader = MultiFileUploader(request.POST.get('related_field', ''))
+        files = file_uploader.upload(list(request.FILES.values()))
+
+        return JsonResponse({
+            'files': [file.to_dict() for file in files]
+        })
+
+
+@login_required()
+def file_single_upload_ajax(request: WSGIRequest) -> JsonResponse:
+    if request.method == 'POST':
+        file_uploader = SingleFileUploader(request.POST.get('related_field', ''))
+        file = file_uploader.upload(list(request.FILES.values())[0])
+
+        return JsonResponse({
+            'file': file.to_dict()
+        })

django_spire/file/widgets.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json
+
+from django.template import loader
+from django.utils.safestring import mark_safe
+from django.forms import Widget
+
+
+class MultipleWidget(Widget):
+    needs_multipart_form = True
+    template_name = 'django_spire/file/widget/multiple_file_widget.html'
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def value_from_datadict(self, data, files, name):
+        return json.loads(data.get(f'{name}_data'))
+
+    def render(self, name, value, attrs=None, renderer=None):
+        context = self.get_context(name, value, attrs)
+        template = loader.get_template(self.template_name).render(context)
+        return mark_safe(template)
+
+
+class SingleFileWidget(Widget):
+    needs_multipart_form = True
+    template_name = 'django_spire/file/widget/single_file_widget.html'
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def value_from_datadict(self, data, files, name) -> dict:
+        return json.loads(data.get(f'{name}_data'))
+
+    def render(self, name, value, attrs=None, renderer=None):
+        context = self.get_context(name, value, attrs)
+        template = loader.get_template(self.template_name).render(context)
+        return mark_safe(template)

django_spire/help_desk/apps.py

@@ -0,0 +1,24 @@
+from django.apps import AppConfig
+
+from django_spire.utils import check_required_apps
+
+
+class HelpDeskConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    label = 'django_spire_help_desk'
+    name = 'django_spire.help_desk'
+    MODEL_PERMISSIONS = (
+        {
+            'name': 'help_desk',
+            'verbose_name': 'Help Desk',
+            'model_class_path': 'django_spire.help_desk.models.HelpDeskTicket',
+            'is_proxy_model': False,
+        },
+    )
+
+    REQUIRED_APPS = ('django_spire_core',)
+    URLPATTERNS_INCLUDE = 'django_spire.help_desk.urls'
+    URLPATTERNS_NAMESPACE = 'help_desk'
+
+    def ready(self) -> None:
+        check_required_apps(self.label)

django_spire/help_desk/auth/controller.py

@@ -0,0 +1,15 @@
+from django_spire.auth.controller.controller import BaseAuthController
+
+
+class BaseHelpDeskAuthController(BaseAuthController):
+    def can_add(self):
+        return self.request.user.has_perm('django_spire_help_desk.add_helpdeskticket')
+
+    def can_change(self):
+        return self.request.user.has_perm('django_spire_help_desk.change_helpdeskticket')
+
+    def can_delete(self):
+        return self.request.user.has_perm('django_spire_help_desk.delete_helpdeskticket')
+
+    def can_view(self):
+        return self.request.user.has_perm('django_spire_help_desk.view_helpdeskticket')

django_spire/help_desk/choices.py

@@ -0,0 +1,19 @@
+from django.db import models
+
+
+class HelpDeskTicketPurposeChoices(models.TextChoices):
+    APP = ('app', 'App')
+    COMPANY = ('comp', 'Company')
+
+
+class HelpDeskTicketStatusChoices(models.TextChoices):
+    READY = ('read', 'Ready')
+    INPROGRESS = ('prog', 'In Progress')
+    DONE = ('done', 'Done')
+
+
+class HelpDeskTicketPriorityChoices(models.TextChoices):
+    LOW = ('low', 'Low')
+    MEDIUM = ('med', 'Medium')
+    HIGH = ('high', 'High')
+    URGENT = ('urge', 'Urgent')

django_spire/help_desk/enums.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class TicketEventType(Enum):
+    NEW = 'new'
+    UPDATE = 'update'
+    COMMENT = 'comment'

django_spire/help_desk/exceptions.py

@@ -0,0 +1,5 @@
+class TicketEventNotificationTypeNotSupportedError(TypeError):
+    pass
+
+class HelpDeskNotificationRecipientMissingEmailError(ValueError):
+    pass

django_spire/help_desk/forms.py

@@ -0,0 +1,17 @@
+from typing import ClassVar
+
+from django import forms
+
+from django_spire.help_desk.models import HelpDeskTicket
+
+
+class HelpDeskTicketCreateForm(forms.ModelForm):
+    class Meta:
+        model = HelpDeskTicket
+        exclude: ClassVar[list] = ['created_by', 'status']
+
+
+class HelpDeskTicketUpdateForm(forms.ModelForm):
+    class Meta:
+        model = HelpDeskTicket
+        exclude: ClassVar[list] = ['created_by']

django_spire/help_desk/migrations/0001_initial.py

@@ -0,0 +1,37 @@
+# Generated by Django 5.2.1 on 2025-05-23 16:00
+
+import django.db.models.deletion
+import django.utils.timezone
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='HelpDeskTicket',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('is_active', models.BooleanField(default=True, editable=False)),
+                ('is_deleted', models.BooleanField(default=False, editable=False)),
+                ('created_datetime', models.DateTimeField(default=django.utils.timezone.localtime, editable=False)),
+                ('purpose', models.CharField(choices=[('app', 'App'), ('comp', 'Company')], max_length=4, verbose_name='Purpose')),
+                ('priority', models.CharField(choices=[('low', 'Low'), ('med', 'Medium'), ('high', 'High'), ('urge', 'Urgent')], max_length=4, verbose_name='Priority')),
+                ('status', models.CharField(choices=[('read', 'Ready'), ('prog', 'In Progress'), ('done', 'Done')], default='read', max_length=4, verbose_name='Status')),
+                ('description', models.TextField()),
+                ('created_by', models.ForeignKey(editable=False, on_delete=django.db.models.deletion.PROTECT, related_name='created_help_desk_tickets', related_query_name='created_help_desk_ticket', to=settings.AUTH_USER_MODEL, verbose_name='Created By')),
+            ],
+            options={
+                'verbose_name': 'Help Desk Ticket',
+                'verbose_name_plural': 'Help Desk Tickets',
+                'db_table': 'django_spire_help_desk_ticket',
+            },
+        ),
+    ]

django_spire/help_desk/models.py

@@ -0,0 +1,47 @@
+from django.db import models
+from django.contrib.auth.models import User
+
+from django_spire.help_desk.querysets import HelpDeskTicketQuerySet
+from django_spire.help_desk.services.service import HelpDeskTicketService
+from django_spire.history.mixins import HistoryModelMixin
+
+from django_spire.help_desk import choices
+
+
+class HelpDeskTicket(HistoryModelMixin):
+    created_by = models.ForeignKey(
+        User,
+        on_delete=models.PROTECT,
+        related_name='created_help_desk_tickets',
+        related_query_name='created_help_desk_ticket',
+        editable=False,
+        verbose_name='Created By'
+    )
+    purpose = models.CharField(
+        max_length=4,
+        choices=choices.HelpDeskTicketPurposeChoices.choices,
+        verbose_name='Purpose'
+    )
+    priority = models.CharField(
+        max_length=4,
+        choices=choices.HelpDeskTicketPriorityChoices.choices,
+        verbose_name='Priority'
+    )
+    status = models.CharField(
+        max_length=4,
+        choices=choices.HelpDeskTicketStatusChoices.choices,
+        default=choices.HelpDeskTicketStatusChoices.READY,
+        verbose_name='Status'
+    )
+    description = models.TextField()
+
+    objects = HelpDeskTicketQuerySet.as_manager()
+    services = HelpDeskTicketService()
+
+    def __str__(self):
+        return f'Ticket #{self.pk}'
+
+    class Meta:
+        db_table = 'django_spire_help_desk_ticket'
+        verbose_name = 'Help Desk Ticket'
+        verbose_name_plural = 'Help Desk Tickets'

django_spire/help_desk/querysets.py

@@ -0,0 +1,4 @@
+from django_spire.history.querysets import HistoryQuerySet
+
+class HelpDeskTicketQuerySet(HistoryQuerySet):
+    pass

django_spire/help_desk/services/notification_service.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from django.conf import settings
+from django.contrib.auth.models import User
+from django.contrib.contenttypes.models import ContentType
+from django.contrib.sites.models import Site
+from django.db.models import Q
+from typing import TYPE_CHECKING
+
+from django.urls import reverse
+
+from django_spire.contrib.service import BaseDjangoModelService
+from django_spire.help_desk.exceptions import (
+    TicketEventNotificationTypeNotSupportedError,
+)
+from django_spire.help_desk.enums import TicketEventType
+from django_spire.notification.app.models import AppNotification
+from django_spire.notification.choices import NotificationTypeChoices
+from django_spire.notification.email.models import EmailNotification
+from django_spire.notification.maps import NOTIFICATION_TYPE_CHOICE_TO_MODEL_MAP
+from django_spire.notification.models import Notification
+
+if TYPE_CHECKING:
+    from django_spire.help_desk.models import HelpDeskTicket
+
+
+class HelpDeskTicketNotificationService(BaseDjangoModelService['HelpDeskTicket']):
+    obj: HelpDeskTicket
+
+    def create_new_ticket_notifications(self):
+        event_type = TicketEventType.NEW
+
+        developers = User.objects.filter(
+            email__in=[
+                admin[1]
+                for admin in settings.ADMINS
+            ]
+        )
+
+        for notif_type in [NotificationTypeChoices.APP, NotificationTypeChoices.EMAIL]:
+            self._create_ticket_event_notifications(
+                users=developers,
+                notification_type=notif_type,
+                event_type=event_type,
+            )
+
+        managers = User.objects.filter(
+            Q(groups__permissions__codename='delete_helpdeskticket')
+        )
+
+        self._create_ticket_event_notifications(
+            users=managers,
+            notification_type=NotificationTypeChoices.APP,
+            event_type=event_type,
+        )
+
+    @staticmethod
+    def _get_ticket_event_notification_title(event_type: TicketEventType) -> str:
+        content_map = {
+            TicketEventType.NEW: 'A new help desk ticket has been created',
+        }
+
+        return content_map[event_type]
+
+    def _get_ticket_event_notification_body(
+            self,
+            event_type: TicketEventType,
+            notification_type: NotificationTypeChoices,
+    ) -> str:
+        content_map = {
+            TicketEventType.NEW: {
+                NotificationTypeChoices.EMAIL: f"""
+                    <h2>A new help desk ticket (#{self.obj.pk}) has been created.</h2>
+                    <p>Priority: {self.obj.get_priority_display()}</p>
+                    <p>Purpose: {self.obj.get_purpose_display()}</p>
+                    <p>Description:</p>
+                    <p>{self.obj.description}</p>
+                """,
+                NotificationTypeChoices.APP: (
+                    f'Priority: {self.obj.get_priority_display()} - '
+                    f'Purpose: {self.obj.get_purpose_display()}'
+                ),
+            }
+        }
+
+        try:
+            return content_map[event_type][notification_type]
+        except KeyError:
+            raise TicketEventNotificationTypeNotSupportedError(
+                f'Combination of event type and notification type not supported: '
+                f'Event type {event_type} - Notification type {notification_type}'
+            )
+
+    def _get_ticket_notification_url(
+            self,
+            notification_type: NotificationTypeChoices
+    ) -> str:
+        path = reverse('django_spire:help_desk:page:detail', kwargs={'pk': self.obj.pk})
+
+        if notification_type == NotificationTypeChoices.EMAIL:
+            site_host = Site.objects.get_current()
+            return f'{site_host}{path}'
+
+        return path
+
+    def _create_ticket_event_notification_for_user(
+            self,
+            notification_type: NotificationTypeChoices,
+            body: str,
+            title: str,
+            url: str,
+            user: User,
+    ) -> EmailNotification | AppNotification:
+        base_notification = Notification(
+            content_type=ContentType.objects.get_for_model(self.obj),
+            object_id=self.obj.pk,
+            url=url,
+            title=title,
+            body=body,
+            type=notification_type,
+            user=user,
+        )
+
+        if notification_type == NotificationTypeChoices.EMAIL:
+            return EmailNotification(
+                notification=base_notification,
+                to_email_address=(
+                    settings.DEVELOPMENT_EMAIL if settings.DEBUG else user.email
+                )
+            )
+        elif notification_type == NotificationTypeChoices.APP:
+            return AppNotification(notification=base_notification)
+        else:
+            raise TicketEventNotificationTypeNotSupportedError(notification_type)
+
+    def _create_ticket_event_notifications(
+            self,
+            users: list[User],
+            notification_type: NotificationTypeChoices,
+            event_type: TicketEventType,
+    ):
+        title = self._get_ticket_event_notification_title(event_type)
+        body = self._get_ticket_event_notification_body(
+            event_type=event_type,
+            notification_type=notification_type,
+        )
+        url = self._get_ticket_notification_url(notification_type)
+
+        notifications = [
+            self._create_ticket_event_notification_for_user(
+                notification_type=notification_type,
+                body=body,
+                title=title,
+                url=url,
+                user=user,
+            )
+            for user in users
+        ]
+
+        Notification.objects.bulk_create(
+            [
+                notification.notification
+                for notification in notifications
+                if notification
+            ]
+        )
+        NOTIFICATION_TYPE_CHOICE_TO_MODEL_MAP[notification_type].objects.bulk_create(
+            notifications
+        )

django_spire/help_desk/services/service.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+
+from django_spire.contrib.service import BaseDjangoModelService
+from django_spire.help_desk.services.notification_service import \
+    HelpDeskTicketNotificationService
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import User
+    from django_spire.help_desk.models import HelpDeskTicket
+
+
+class HelpDeskTicketService(BaseDjangoModelService['HelpDeskTicket']):
+    obj: HelpDeskTicket
+
+    notification: HelpDeskTicketNotificationService = HelpDeskTicketNotificationService()
+
+    def create(self, created_by: User, **kwargs) -> HelpDeskTicket:
+        self.obj.created_by = created_by
+        self.obj, _ = self.obj.services.save_model_obj(**kwargs)
+
+        self.obj.services.notification.create_new_ticket_notifications()
+
+        return self.obj

django_spire/help_desk/templates/django_spire/help_desk/card/ticket_detail_card.html

@@ -0,0 +1,34 @@
+{% extends 'django_spire/card/title_card.html' %}
+
+{% block card_title_content_style %}{% endblock %}
+
+{% block card_title %}
+    {{ ticket }}
+{% endblock %}
+
+{% block card_button %}
+    {% if AuthController.help_desk.can_change %}
+        {% url 'django_spire:help_desk:form:update' pk=ticket.pk as edit_url %}
+        {% include 'django_spire/button/primary_button.html' with button_text='Edit' button_href=edit_url button_icon='bi bi-pencil' %}
+    {% endif %}
+{% endblock %}
+
+{% block card_title_content %}
+    <div class="row mb-4">
+        <div class="col">
+            {% include 'django_spire/element/attribute_element.html' with attribute_title='Purpose' %}
+            {% include 'django_spire/help_desk/element/ticket_purpose_badge.html' %}
+        </div>
+        <div class="col">
+            {% include 'django_spire/element/attribute_element.html' with attribute_title='Priority' %}
+            {% include 'django_spire/help_desk/element/ticket_priority_badge.html' %}
+        </div>
+        <div class="col">
+            {% include 'django_spire/element/attribute_element.html' with attribute_title='Status' %}
+            {% include 'django_spire/help_desk/element/ticket_status_badge.html' %}
+        </div>
+    </div>
+    <div class="row">
+        {% include 'django_spire/element/attribute_element.html' with attribute_title='Ticket Description' attribute_value=ticket.description|linebreaks %}
+    </div>
+{% endblock %}

django_spire/help_desk/templates/django_spire/help_desk/card/ticket_form_card.html

@@ -0,0 +1,13 @@
+{% extends 'django_spire/card/title_card.html' %}
+
+{% block card_padding %}
+    px-3 py-2
+{% endblock %}
+
+{% block card_title %}
+    {% if ticket.pk is None %}Create Ticket{% else %}Update Ticket #{{ ticket.pk }}{% endif %}
+{% endblock %}
+
+{% block card_title_content %}
+    {% include 'django_spire/help_desk/form/ticket_form.html' %}
+{% endblock %}

django_spire/help_desk/templates/django_spire/help_desk/card/ticket_list_card.html

@@ -0,0 +1,24 @@
+{% extends 'django_spire/card/title_card.html' %}
+
+{% block card_title_content_style %}{% endblock %}
+
+{% block card_title %}
+    Tickets
+{% endblock %}
+
+{% block card_button %}
+    {% if AuthController.help_desk.can_add %}
+        <div class="col text-end mb-1">
+            {% url 'django_spire:help_desk:form:create' as create_url %}
+            {% include 'django_spire/button/primary_button.html' with button_text='Add' button_href=create_url button_icon="bi bi-plus" %}
+        </div>
+    {% endif %}
+{% endblock %}
+
+{% block card_title_content %}
+    {% for ticket in tickets %}
+        {% include 'django_spire/help_desk/item/ticket_item.html' %}
+    {% empty %}
+        {% include 'django_spire/item/no_data_item.html' %}
+    {% endfor %}
+{% endblock %}

django_spire/help_desk/templates/django_spire/help_desk/element/icon.html

@@ -0,0 +1,3 @@
+<a href="{% url 'django_spire:help_desk:page:list' %}">
+    <i class="bi bi-headset fs-2 mx-2 text-app-default-text-color"></i>
+</a>

django_spire/help_desk/templates/django_spire/help_desk/element/ticket_priority_badge.html

@@ -0,0 +1,9 @@
+{% if ticket.priority == 'low'  %}
+    {% include 'django_spire/badge/secondary_badge.html' with badge_text=ticket.get_priority_display %}
+{% elif ticket.priority == 'med' %}
+    {% include 'django_spire/badge/primary_badge.html' with badge_text=ticket.get_priority_display %}
+{% elif ticket.priority == 'high' %}
+    {% include 'django_spire/badge/warning_badge.html' with badge_text=ticket.get_priority_display %}
+{% elif ticket.priority == 'urge' %}
+    {% include 'django_spire/badge/danger_badge.html' with badge_text=ticket.get_priority_display %}
+{% endif %}

django_spire/help_desk/templates/django_spire/help_desk/element/ticket_purpose_badge.html

@@ -0,0 +1,5 @@
+{% if ticket.purpose == 'app'  %}
+    {% include 'django_spire/badge/accent_badge.html' with badge_text=ticket.get_purpose_display %}
+{% elif ticket.purpose == 'comp' %}
+    {% include 'django_spire/badge/primary_badge.html' with badge_text=ticket.get_purpose_display %}
+{% endif %}

django_spire/help_desk/templates/django_spire/help_desk/element/ticket_status_badge.html

@@ -0,0 +1,7 @@
+{% if ticket.status == 'read'  %}
+    {% include 'django_spire/badge/secondary_badge.html' with badge_text=ticket.get_status_display %}
+{% elif ticket.status == 'prog' %}
+    {% include 'django_spire/badge/primary_badge.html' with badge_text=ticket.get_status_display %}
+{% elif ticket.status == 'done' %}
+    {% include 'django_spire/badge/success_badge.html' with badge_text=ticket.get_status_display %}
+{% endif %}

django_spire/help_desk/templates/django_spire/help_desk/form/ticket_form.html

@@ -0,0 +1,31 @@
+<form
+    class="row align-items-center"
+    x-data="{
+        ticket: new ModelObjectGlue('ticket'),
+        async init () {
+            await this.ticket.get()
+        }
+    }"
+    method="post"
+    action="{{ form_action_url }}"
+>
+    {% csrf_token %}
+
+    <div class="col-12 col-sm mb-3 mb-sm-0">
+        {% include 'django_glue/form/field/select_field.html' with glue_model_field='ticket.purpose' %}
+    </div>
+    <div class="col-12 col-sm mb-3 mb-sm-0">
+        {% include 'django_glue/form/field/select_field.html' with glue_model_field='ticket.priority' %}
+    </div>
+    {% if ticket.pk is not None %}
+        <div class="col-12 col-sm mb-3 mb-sm-0">
+            {% include 'django_glue/form/field/select_field.html' with glue_model_field='ticket.status' %}
+        </div>
+    {% endif %}
+    <div class="col-12 mb-1 mt-3">
+        {% include 'django_glue/form/field/text_field.html' with glue_model_field='ticket.description' %}
+    </div>
+    <div class="my-2">
+        {% include 'django_spire/contrib/form/button/form_submit_button.html' %}
+    </div>
+</form>