django-spire 0.23.4__py3-none-any.whl

django_spire/core/utils.py

@@ -0,0 +1,32 @@
+import inspect
+from inspect import Signature
+from typing import Callable, Any, Sequence
+
+
+def get_object_from_module_string(module_string: str) -> Any:
+    try:
+        module_string, object_name = module_string.rsplit('.', 1)
+        module = __import__(module_string, fromlist=[object_name])
+    except ImportError:
+        raise ImportError(f'Could not import module: {module_string}')
+
+    return getattr(module, object_name)
+
+def get_callable_from_module_string_and_validate_arguments(
+        module_string: str,
+        valid_args: Sequence[str],
+) -> Callable:
+    callable_ = get_object_from_module_string(module_string)
+
+    if not callable(callable_):
+        raise TypeError(f'Object {module_string} is not callable')
+
+    sig = inspect.signature(callable_)
+    params = sig.parameters
+
+    for name in valid_args:
+        if name not in params:
+            message = f'{callable_.__qualname__} is missing required argument: {name}'
+            raise TypeError(message)
+
+    return callable_

django_spire/exceptions.py

@@ -0,0 +1,2 @@
+class DjangoSpireException(Exception):
+    pass

django_spire/file/admin.py

@@ -0,0 +1,33 @@
+from django.contrib import admin
+from django.urls import reverse
+from django.utils.html import format_html
+
+from django_spire.file import models
+
+
+@admin.register(models.File)
+class FileAdmin(admin.ModelAdmin):
+    list_display = (
+        'id', 'name', 'type', 'size', 'content_object_link', 'file_link'
+    )
+    list_filter = ('type',)
+    search_fields = ('id', 'name', 'type')
+    ordering = ('-id',)
+
+    def content_object_link(self, file: models.File) -> str:
+        if file.content_object:
+            url = reverse(
+                f'admin:{file.content_type.app_label}_{file.content_type.model}_change',
+                args=[file.object_id]
+            )
+
+            return format_html(f'<a href="{url}">{file.content_object}</a>')
+
+        return 'No Related Object'
+
+    content_object_link.short_description = 'Content Object'
+
+    def file_link(self, file: models.File) -> str:
+        return format_html(f'<a href="{file.file.url}" download>{file.name}</a>')
+
+    file_link.short_description = 'File Download Link'

django_spire/file/apps.py

@@ -0,0 +1,29 @@
+from django.apps import AppConfig
+from django.conf import settings
+
+from django_spire.utils import check_required_apps
+
+
+class FileConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    label = 'django_spire_file'
+    name = 'django_spire.file'
+
+    REQUIRED_APPS = ('django_spire_core',)
+    URLPATTERNS_INCLUDE = 'django_spire.file.urls'
+    URLPATTERNS_NAMESPACE = 'file'
+
+    def ready(self) -> None:
+        if not hasattr(settings, 'BASE_FOLDER_NAME'):
+            raise ValueError(
+                f'"BASE_FOLDER_NAME" must be set in the django settings when '
+                f'using "{self.label}".'
+            )
+
+        elif not isinstance(getattr(settings, 'BASE_FOLDER_NAME'), str):
+            raise ValueError(
+                f'"BASE_FOLDER_NAME" must be a string in the django settings when '
+                f'using "{self.label}".'
+            )
+
+        check_required_apps(self.label)

django_spire/file/fields.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+
+from typing import TYPE_CHECKING
+
+from django import forms
+
+from django_spire.file import widgets
+from django_spire.file.queryset import FileQuerySet
+
+if TYPE_CHECKING:
+    from django_spire.file.models import File
+
+
+class MultipleFileField(forms.FileField):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.widget = widgets.MultipleWidget()
+
+    def prepare_value(self, value: list[File] | None):
+        if value is not None:
+            return json.dumps([file.to_dict() for file in value])
+
+        return json.dumps([])
+
+    def clean(self, data, initial = None) -> dict:
+        return data
+
+
+class SingleFileField(forms.FileField):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.widget = widgets.SingleFileWidget()
+
+    def prepare_value(self, value: File | FileQuerySet | None) -> str | None:
+        if isinstance(value, FileQuerySet):
+            value =  value.first()
+
+        if value is not None:
+            return value.to_json()
+
+        return json.dumps(None)
+
+    def clean(self, data, initial = None) -> dict:
+        return data

django_spire/file/forms.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from django import forms
+from django_spire.file.fields import MultipleFileField
+
+
+class FileForm(forms.Form):
+    files = MultipleFileField()
+
+    # def __init__(self, *args, **kwargs):
+    #     super().__init__(*args, **kwargs)
+    #
+    #     self.helper = FormHelper(self)
+    #     self.helper.include_media = False
+    #     self.helper.form_enctype = 'multipart/form-data'
+    #     self.helper.layout = Layout(
+    #         Row(
+    #             Column('files', css_class='form-group col-md-6'),
+    #         ),
+    #     )
+    #     self.helper.add_input(Submit('submit', 'Submit', css_class='btn-primary'))
+

django_spire/file/interfaces.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from django.conf import settings
+from django.core.files.base import ContentFile
+
+from django.contrib.contenttypes.models import ContentType
+from django.core.exceptions import ObjectDoesNotExist
+
+from django_spire.file.models import File
+from django_spire.file.utils import random_64_char_token
+
+if TYPE_CHECKING:
+    from django.core.files.uploadedfile import InMemoryUploadedFile
+    from django_spire.file.mixins import FileModelMixin
+
+
+@dataclass
+class FileFormatter:
+    file: InMemoryUploadedFile
+    related_field: str = None
+    name: str = ...
+    type: str = ...
+    app_name: str = 'Uncategorized'
+
+    def __post_init__(self):
+        self.name = self._format_name()
+        self.type = self._parse_type()
+
+    def _format_name(self) -> str:
+        return self.file.name.rsplit('.', 1)[0]
+
+    def _parse_type(self) -> str:
+        return self.file.name.rsplit('.', 1)[1]
+
+    @property
+    def location(self) -> str:
+        location = settings.BASE_FOLDER_NAME + '/'
+        location += str(self.app_name) + '/'
+
+        if self.related_field is not None:
+            location += str(self.related_field) + '/'
+
+        location += random_64_char_token() + '/'
+        location += self.name
+
+        return location
+
+    def null_file_obj(self) -> File:
+        file_obj = File(
+            name=self.name,
+            size=self.size_verbose(),
+            type=self.type,
+            related_field=self.related_field,
+        )
+        self.save_file(file_obj)
+
+        return file_obj
+
+    def size_verbose(self) -> str:
+        if self.file.size < 512000:
+            value = round(self.file.size / 1000, 2)
+            ext = ' kb'
+        elif self.file.size < 512000 * 1000:
+            value = round(self.file.size / 1000000, 2)
+            ext = ' Mb'
+        elif self.file.size < 512000 * 1000 * 1000:
+            value = round(self.file.size / 1000000000, 2)
+            ext = ' Gb'
+        else:
+            value = ''
+            ext = '>1.00 Tb'
+
+        return str(value) + ext
+
+    def save_file(self, file_obj: File):
+        file_path = self.location + '.' + self.type
+        file_obj.file.save(file_path, ContentFile(self.file.read()), save=False)
+
+
+@dataclass
+class FileContentObjectFormatter(FileFormatter):
+    content_object: FileModelMixin = ...
+
+    @property
+    def location(self) -> str:
+        location = settings.BASE_FOLDER_NAME + '/'
+        location += str(self.content_object._meta.app_label) + '/'
+
+        if self.related_field is not None:
+            location += str(self.related_field) + '/'
+
+        location += random_64_char_token() + '/'
+        location += self.name
+        return location
+
+    def null_file_obj(self) -> File:
+        file_obj = File(
+            content_type=ContentType.objects.get_for_model(self.content_object),
+            object_id=self.content_object.id,
+            name=self.name,
+            size=self.size_verbose(),
+            type=self.type,
+            related_field=self.related_field,
+        )
+        self.save_file(file_obj)
+
+        return file_obj
+
+
+@dataclass
+class FileUploader(ABC):
+    related_field: str | None
+    app_name: str = 'Uncategorized'
+
+    def null_file_obj(self, file):
+        formatted_file = FileFormatter(
+            file=file,
+            related_field=self.related_field,
+            app_name=self.app_name
+        )
+        return formatted_file.null_file_obj()
+
+    @abstractmethod
+    def upload(self, *args, **kwargs) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def upload_from_form_field(self, *args, **kwargs) -> None:
+        raise NotImplementedError
+
+
+@dataclass
+class SingleFileUploader(FileUploader):
+    def upload(self, file: InMemoryUploadedFile) -> File:
+        file = self.null_file_obj(file)
+        file.save()
+        return file
+
+    def delete_old_files(self, content_object: FileModelMixin):
+        old_files = content_object.files.active().related_field(self.related_field)
+
+        for file in old_files:
+            file.is_deleted = True
+            file.is_active = False
+
+        File.objects.bulk_update(old_files, ['is_active', 'is_deleted'])
+
+    def upload_from_form_field(
+        self,
+        form_data,
+        content_object: FileModelMixin
+    ) -> File:
+        try:
+            return content_object.files.get(id=form_data['id'])
+        except ObjectDoesNotExist:
+            self.delete_old_files(content_object)
+            file = File.objects.get(id=form_data['id'])
+            file.content_type = ContentType.objects.get_for_model(content_object.__class__)
+            file.object_id = content_object.id
+            file.related_field = self.related_field
+            return file.save()
+
+
+@dataclass
+class MultiFileUploader(FileUploader):
+    def upload(self, files: list[InMemoryUploadedFile]) -> list[File]:
+        files_to_upload = [self.null_file_obj(file) for file in files]
+        return File.objects.bulk_create(files_to_upload)
+
+    def upload_from_form_field(
+        self,
+        form_data: list[dict],
+        content_object: FileModelMixin
+    ) -> list[File]:
+        file_ids = [file['id'] for file in form_data]
+
+        # Delete files that are no longer in the form data
+        old_files = (
+            content_object
+            .files
+            .active()
+            .related_field(self.related_field)
+            .exclude(id__in=file_ids)
+        )
+
+        for old_file in old_files:
+            old_file.is_deleted = True
+            old_file.is_active = False
+
+        File.objects.bulk_update(old_files, ['is_active', 'is_deleted'])
+
+        link_files = File.objects.filter(id__in=file_ids, object_id__isnull=True)
+        content_type = ContentType.objects.get_for_model(content_object.__class__)
+
+        for link_file in link_files:
+            link_file.content_type = content_type
+            link_file.object_id = content_object.id
+            link_file.related_field = self.related_field
+
+        File.objects.bulk_update(
+            link_files,
+            fields=['content_type', 'object_id', 'related_field']
+        )
+
+        return content_object.files.active().related_field(self.related_field)

django_spire/file/migrations/0001_initial.py

@@ -0,0 +1,39 @@
+# Generated by Django 5.2 on 2025-04-23 17:23
+
+import django.db.models.deletion
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('contenttypes', '0002_remove_content_type_name'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='File',
+            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)),
+                ('object_id', models.PositiveIntegerField(blank=True, editable=False, null=True)),
+                ('file', models.FileField(max_length=500, upload_to='')),
+                ('name', models.CharField(default='', editable=False, max_length=255)),
+                ('type', models.CharField(default='', editable=False, max_length=255)),
+                ('size', models.CharField(default='', editable=False, max_length=64)),
+                ('related_field', models.CharField(blank=True, editable=False, max_length=3, null=True)),
+                ('content_type', models.ForeignKey(blank=True, editable=False, null=True, on_delete=django.db.models.deletion.CASCADE, to='contenttypes.contenttype')),
+            ],
+            options={
+                'verbose_name': 'File',
+                'verbose_name_plural': 'Files',
+                'db_table': 'django_spire_file',
+                'indexes': [models.Index(fields=['content_type', 'object_id'], name='django_spir_content_4f794c_idx')],
+            },
+        ),
+    ]

django_spire/file/mixins.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib.contenttypes.fields import GenericRelation
+
+from django.db import models
+
+from django_spire.file.models import File
+from django_spire.file.tools import copy_files_from_source_to_target_model_object
+
+
+class FileModelMixin(models.Model):
+    files = GenericRelation(File, editable=False)
+
+    def copy_files_to_target_model_object(self, target: Any[models.Model]) -> File:
+        # TODO: Move to File Service
+        return copy_files_from_source_to_target_model_object(source=self, target=target)
+
+    class Meta:
+        abstract = True

django_spire/file/models.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import json
+
+from django.contrib.contenttypes.models import ContentType
+
+from django.contrib.contenttypes.fields import GenericForeignKey
+from django.db import models
+
+from django_spire.file.queryset import FileQuerySet
+from django_spire.history.mixins import HistoryModelMixin
+
+
+class File(HistoryModelMixin):
+    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE, editable=False, blank=True, null=True)
+    object_id = models.PositiveIntegerField(editable=False, blank=True, null=True)
+    content_object = GenericForeignKey('content_type', 'object_id')
+
+    file = models.FileField(max_length=500)
+    name = models.CharField(max_length=255, default='', editable=False)
+    type = models.CharField(max_length=255, default='', editable=False)
+    size = models.CharField(max_length=64, default='', editable=False)
+
+    related_field = models.CharField(max_length=3, null=True, blank=True, editable=False)
+
+    objects = FileQuerySet.as_manager()
+
+    def __str__(self):
+        return self.name
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            'name': self.name,
+            'url': self.file.url,
+            'id': self.id
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())
+
+    class Meta:
+        db_table = 'django_spire_file'
+        verbose_name = 'File'
+        verbose_name_plural = 'Files'
+        indexes = [
+            models.Index(fields=['content_type', 'object_id']),
+        ]
+

django_spire/file/queryset.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from django.db.models import QuerySet
+
+
+class FileQuerySet(QuerySet):
+    def active(self):
+        return self.filter(is_deleted=False, is_active=True)
+
+    def related_field(self, field_name: str):
+        return self.filter(related_field=field_name)

django_spire/file/templates/django_spire/file/card/demo_detail_card.html

@@ -0,0 +1,9 @@
+{% extends 'django_spire/card/title_card.html' %}
+
+{% block card_title %}
+    {{ demo.name }}
+{% endblock %}
+
+{% block card_title_content %}
+    {% include 'django_spire/element/attribute_element.html' with attribute_type='Description' attribute_value=demo.description %}
+{% endblock %}

django_spire/file/templates/django_spire/file/card/demo_file_list_card.html

@@ -0,0 +1,20 @@
+{% extends 'django_spire/card/title_card.html' %}
+
+{% block card_title %}
+    Files
+{% endblock %}
+
+{% block card_button %}
+    {% url 'core_file:demo_file_form' demo_pk=demo.pk pk=0 as new_demo_file_url %}
+    {% include 'django_spire/button/secondary_outlined_button.html' with button_href=new_demo_file_url button_logo_only='bi bi-plus' %}
+{% endblock %}
+
+{% block card_title_content %}
+    {% if queryset %}
+        {% for file in file_list %}
+            {% include 'django_spire/file/item/file_item.html' with delete_url=delete_url %}
+        {% endfor %}
+    {% else %}
+        {% include 'django_spire/item/no_data_item.html' %}
+    {% endif %}
+{% endblock %}

django_spire/file/templates/django_spire/file/card/demo_filler_card.html

@@ -0,0 +1,9 @@
+{% extends 'django_spire/card/title_card.html'%}
+
+{% block card_title %}
+    Filler card
+{% endblock %}
+
+{% block card_title_content %}
+    This is a filler card!
+{% endblock %}

django_spire/file/templates/django_spire/file/card/demo_list_card.html

@@ -0,0 +1,20 @@
+{% extends 'django_spire/card/title_card.html' %}
+
+{% block card_title %}
+    Demo List
+{% endblock %}
+
+{% block card_button %}
+    {% url 'core_file:demo_form' pk=0 as new_demo_url %}
+    {% include 'django_spire/button/primary_button.html' with button_href=new_demo_url button_text='New' button_logo_left='bi bi-plus' %}
+{% endblock %}
+
+{% block card_title_content %}
+    {% if queryset %}
+        {% for demo in demo_list %}
+            {% include 'django_spire/file/item/demo_item.html' %}
+        {% endfor %}
+    {% else %}
+        {% include 'django_spire/item/no_data_item.html' %}
+    {% endif %}
+{% endblock %}

django_spire/file/templates/django_spire/file/item/demo_item.html

@@ -0,0 +1,16 @@
+{% extends 'django_spire/item/item.html' %}
+
+{% block item_title %}
+    {% url 'core_file:demo_detail' pk=demo.pk as demo_detail_url %}
+    {% include 'django_spire/element/attribute_element.html' with attribute_href=demo_detail_url attribute_type='Name' attribute_value=demo.name %}
+{% endblock %}
+
+{% block item_row_content %}
+    <div class="col">
+        {% include 'django_spire/element/attribute_element.html' with attribute_type='Description' attribute_value=demo.description %}
+    </div>
+{% endblock %}
+
+{% block item_button %}
+{#    {% include 'django_spire/inventory/element/inventory_item_ellpisis.html' %}#}
+{% endblock %}

django_spire/file/templates/django_spire/file/item/file_item.html

@@ -0,0 +1,22 @@
+{% extends 'django_spire/item/item.html' %}
+
+{% load spire_core_tags %}
+
+{% block item_title_col %} d-none{% endblock %}
+
+{% block item_title_padding %}{% endblock %}
+
+{% block item_row_content %}
+    <div class="col-8">
+        {% include 'django_spire/element/attribute_element.html' with attribute_type='Name' attribute_value=file.name attribute_href=file.file.url target='_blank' %}
+    </div>
+    <div class="col-2">
+        {% include 'django_spire/element/attribute_element.html' with attribute_type='Size' attribute_value=file.size %}
+    </div>
+    <div class="col-2">
+        {% include 'django_spire/element/attribute_element.html' with attribute_type='Type' attribute_value=file.type %}
+    </div>
+{% endblock %}
+
+{% block item_button %}
+{% endblock %}

django_spire/file/templates/django_spire/file/navigation/file_navigation.html

@@ -0,0 +1,2 @@
+{% url 'core_file:demo_list' view='all' as the_url %}
+{% include 'django_spire/navigation/link_navigation.html' with href=the_url name='Demo' icon='bi bi-easel2-fill' %}

django_spire/file/templates/django_spire/file/page/demo_detail_page.html

@@ -0,0 +1,19 @@
+{% extends 'django_spire/page/full_page.html' %}
+{% load comment_tags %}
+
+{% block page_content %}
+    <div class="row mb-3">
+        <div class="col">
+            {% include 'django_spire/file/card/demo_detail_card.html' %}
+        </div>
+    </div>
+
+    <div class="row g-lg-2">
+        <div class="col-8">
+            {% include 'django_spire/file/card/demo_filler_card.html' %}
+        </div>
+        <div class="col-4">
+            {% include 'django_spire/file/card/demo_file_list_card.html' with queryset=file_list %}
+        </div>
+    </div>
+{% endblock %}

django_spire/file/templates/django_spire/file/page/demo_list_page.html

@@ -0,0 +1,9 @@
+{% extends 'django_spire/page/full_page.html' %}
+
+{% block page_content %}
+    <div class="row">
+        <div class="col">
+            {% include 'django_spire/file/card/demo_list_card.html' with queryset=demo_list %}
+        </div>
+    </div>
+{% endblock %}

django_spire/file/templates/django_spire/file/page/version_list_page.html

@@ -0,0 +1,9 @@
+{% extends 'django_spire/page/full_page.html' %}
+
+{% block page_content %}
+    <div class="row">
+        <div class="col">
+            {% include 'demo/card/demo_file_version_list_container.html' with queryset=file_list %}
+        </div>
+    </div>
+{% endblock %}

django_spire/file/templates/django_spire/file/widget/multiple_file_widget.html

@@ -0,0 +1 @@
+{% include 'django_spire/contrib/form/multiple_file_field.html' with value=widget.value name=widget.name %}

django_spire/file/templates/django_spire/file/widget/single_file_widget.html

@@ -0,0 +1 @@
+{% include 'django_spire/contrib/form/single_file_field.html' with value=widget.value name=widget.name %}