django-spire 0.23.4__py3-none-any.whl

django_spire/contrib/progress/mixins.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django_spire.contrib.progress.tracker import ProgressTracker
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+class ProgressTrackingMixin:
+    _tracker: ProgressTracker | None = None
+
+    def get_tracker_key(self) -> str:
+        raise NotImplementedError
+
+    @property
+    def tracker(self) -> ProgressTracker:
+        if self._tracker is None:
+            key = self.get_tracker_key()
+            self._tracker = ProgressTracker(key)
+
+        return self._tracker
+
+    def update_progress(
+        self,
+        step: str,
+        message: str,
+        progress: int,
+        **kwargs: Any
+    ) -> None:
+        self.tracker.update(step, message, progress, **kwargs)
+
+    def progress_error(self, message: str) -> None:
+        self.tracker.error(message)

django_spire/contrib/progress/static/django_spire/js/contrib/progress/progress.js

@@ -0,0 +1,62 @@
+class ProgressStream {
+    constructor(url, config = {}) {
+        this.url = url;
+        this.event_source = null;
+        this.config = {
+            on_update: config.on_update || (() => {}),
+            on_complete: config.on_complete || (() => {}),
+            on_error: config.on_error || (() => {}),
+            redirect_on_complete: config.redirect_on_complete || null,
+            redirect_delay: config.redirect_delay || 1000
+        };
+    }
+
+    start() {
+        this.event_source = new EventSource(this.url);
+
+        this.event_source.onmessage = (event) => {
+            const data = JSON.parse(event.data);
+
+            this.config.on_update(data);
+
+            if (data.step === 'error') {
+                this.config.on_error(data);
+                this.stop();
+
+                return;
+            }
+
+            if (data.progress >= 100) {
+                this.config.on_complete(data);
+                this.stop();
+
+                if (this.config.redirect_on_complete) {
+                    setTimeout(() => {
+                        window.location.href = this.config.redirect_on_complete;
+                    }, this.config.redirect_delay);
+                }
+            }
+        };
+
+        this.event_source.onerror = (error) => {
+            console.error('ProgressStream error:', error);
+
+            this.config.on_error({
+                step: 'error',
+                message: 'Connection error',
+                progress: 0
+            });
+
+            this.stop();
+        };
+    }
+
+    stop() {
+        if (this.event_source) {
+            this.event_source.close();
+            this.event_source = null;
+        }
+    }
+}
+
+window.ProgressStream = ProgressStream;

django_spire/contrib/progress/templates/django_spire/contrib/progress/card/card.html

@@ -0,0 +1,81 @@
+{% extends 'django_spire/card/title_card.html' %}
+
+{% block card_title %}
+    <i class="bi bi-magic"></i>
+    {% block progress_card_title %}Processing{% endblock %}
+{% endblock %}
+
+{% block card_title_content %}
+    <div
+        data-stream-url="{% block progress_stream_url %}{% endblock %}"
+        data-redirect-url="{% block progress_redirect_url %}{% endblock %}"
+        data-redirect-delay="{% block progress_redirect_delay %}1000{% endblock %}"
+        x-data="{
+            step: 'starting',
+            message: 'Initializing...',
+            progress: 0,
+            has_error: false,
+            stream: null,
+            init() {
+                const stream_url = this.$el.dataset.streamUrl;
+                const redirect_url = this.$el.dataset.redirectUrl;
+                const redirect_delay = parseInt(this.$el.dataset.redirectDelay);
+
+                this.stream = new ProgressStream(stream_url, {
+                    on_update: (data) => {
+                        this.step = data.step;
+                        this.message = data.message;
+                        this.progress = data.progress;
+                    },
+                    on_complete: (data) => {},
+                    on_error: (data) => {
+                        this.has_error = true;
+                        this.message = data.message;
+                    },
+                    redirect_on_complete: redirect_url,
+                    redirect_delay: redirect_delay
+                });
+                this.stream.start();
+            }
+        }"
+    >
+        <div class="row g-3">
+            <div class="col-12" x-show="!has_error">
+                <div class="d-flex justify-content-between align-items-center mb-2">
+                    <span class="fs-6" x-text="message"></span>
+                    {% include 'django_spire/badge/accent_badge.html' with x_badge_text="progress + '%'" %}
+                </div>
+                <div class="progress" style="height: 8px;">
+                    <div
+                        class="progress-bar bg-app-accent"
+                        role="progressbar"
+                        :style="'width: ' + progress + '%'"
+                        :aria-valuenow="progress"
+                        aria-valuemin="0"
+                        aria-valuemax="100"
+                    ></div>
+                </div>
+            </div>
+
+            <div class="col-12" x-show="!has_error">
+                <p class="text-app-secondary mb-0 fs-7">
+                    {% block progress_wait_message %}Processing your request. This may take a moment.{% endblock %}
+                </p>
+            </div>
+
+            <div class="col-12" x-show="has_error" x-cloak>
+                <div class="row g-2">
+                    <div class="col-12">
+                        {% include 'django_spire/element/attribute_element.html' with attribute_title='Error' %}
+                        <span class="fs-6 text-app-danger" x-text="message"></span>
+                    </div>
+                    <div class="col-12">
+                        {% block progress_error_button %}
+                            {% include 'django_spire/button/primary_button.html' with button_text='Go Back' %}
+                        {% endblock %}
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+{% endblock %}

django_spire/contrib/progress/templates/django_spire/contrib/progress/modal/content.html

@@ -0,0 +1,90 @@
+{% extends 'django_spire/modal/content/modal_title_content.html' %}
+
+{% block modal_content_title %}
+    <i class="bi bi-magic"></i>
+    {% block progress_modal_title %}Processing{% endblock %}
+{% endblock %}
+
+{% block modal_content_close_button %}
+{% endblock %}
+
+{% block modal_content_content %}
+    <div
+        data-stream-url="{% block progress_stream_url %}{% endblock %}"
+        data-redirect-url="{% block progress_redirect_url %}{% endblock %}"
+        data-redirect-delay="{% block progress_redirect_delay %}1000{% endblock %}"
+        x-data="{
+            step: 'starting',
+            message: 'Initializing...',
+            progress: 0,
+            has_error: false,
+            stream: null,
+            init() {
+                const stream_url = this.$el.dataset.streamUrl;
+                const redirect_url = this.$el.dataset.redirectUrl;
+                const redirect_delay = parseInt(this.$el.dataset.redirectDelay);
+
+                this.stream = new ProgressStream(stream_url, {
+                    on_update: (data) => {
+                        this.step = data.step;
+                        this.message = data.message;
+                        this.progress = data.progress;
+                    },
+                    on_complete: (data) => {
+                        setTimeout(() => {
+                            close_modal();
+                        }, 500);
+                    },
+                    on_error: (data) => {
+                        this.has_error = true;
+                        this.message = data.message;
+                    },
+                    redirect_on_complete: redirect_url,
+                    redirect_delay: redirect_delay
+                });
+                this.stream.start();
+            }
+        }"
+    >
+        <div class="row g-3">
+            <div class="col-12" x-show="!has_error">
+                <div class="d-flex justify-content-between align-items-center mb-2">
+                    <span class="fs-6" x-text="message"></span>
+                    {% include 'django_spire/badge/accent_badge.html' with x_badge_text="progress + '%'" %}
+                </div>
+                <div class="progress" style="height: 8px;">
+                    <div
+                        class="progress-bar bg-app-accent"
+                        role="progressbar"
+                        :style="'width: ' + progress + '%'"
+                        :aria-valuenow="progress"
+                        aria-valuemin="0"
+                        aria-valuemax="100"
+                    ></div>
+                </div>
+            </div>
+
+            <div class="col-12" x-show="!has_error">
+                <p class="text-app-secondary mb-0 fs-7">
+                    {% block progress_wait_message %}We are processing your request. This may take a moment.{% endblock %}
+                </p>
+            </div>
+
+            <div class="col-12" x-show="has_error" x-cloak>
+                <div class="row g-2">
+                    <div class="col-12">
+                        {% include 'django_spire/element/attribute_element.html' with attribute_title='Error' %}
+                        <span class="fs-6 text-app-danger" x-text="message"></span>
+                    </div>
+                    <div class="col-12">
+                        <span @click="close_modal()">
+                            {% block progress_error_button %}
+                                {% include 'django_spire/button/primary_button.html' with button_text='Close' %}
+                            {% endblock %}
+                        </span>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+{% endblock %}

django_spire/contrib/progress/tracker.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.core.cache import cache
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+class ProgressTracker:
+    def __init__(self, key: str, timeout: int = 300) -> None:
+        self.key = f'progress_tracker_{key}'
+        self.timeout = timeout
+
+    def update(
+        self,
+        step: str,
+        message: str,
+        progress: int,
+        **kwargs: Any
+    ) -> None:
+        data = {
+            'step': step,
+            'message': message,
+            'progress': progress,
+            **kwargs
+        }
+
+        cache.set(self.key, data, timeout=self.timeout)
+
+    def get(self) -> dict[str, Any] | None:
+        return cache.get(self.key)
+
+    def clear(self) -> None:
+        cache.delete(self.key)
+
+    def error(self, message: str) -> None:
+        self.update('error', message, 0)

django_spire/contrib/progress/views.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+import time
+
+from typing import TYPE_CHECKING
+
+from django.http import StreamingHttpResponse
+
+from django_spire.contrib.progress.tracker import ProgressTracker
+
+if TYPE_CHECKING:
+    from typing import Callable
+
+
+def sse_stream_view(
+    key: str,
+    interval: float = 0.5,
+    should_continue: Callable[[dict], bool] | None = None
+) -> StreamingHttpResponse:
+    def event_stream() -> None:
+        tracker = ProgressTracker(key)
+        previous_progress = -1
+
+        while True:
+            time.sleep(interval)
+            data = tracker.get()
+
+            if data:
+                current_progress = data.get('progress', 0)
+
+                if current_progress != previous_progress:
+                    yield f'data: {json.dumps(data)}\n\n'
+                    previous_progress = current_progress
+
+                if should_continue and not should_continue(data):
+                        break
+
+                if current_progress >= 100 or data.get('step') == 'error':
+                    break
+
+    response = StreamingHttpResponse(
+        event_stream(),
+        content_type='text/event-stream'
+    )
+
+    response['Cache-Control'] = 'no-cache'
+    response['X-Accel-Buffering'] = 'no'
+
+    return response

django_spire/contrib/queryset/enums.py

@@ -0,0 +1,6 @@
+from enum import StrEnum
+
+
+class SessionFilterActionEnum(StrEnum):
+    CLEAR = 'Clear'
+    FILTER = 'Filter'

django_spire/contrib/queryset/filter_tools.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from django.db.models import QuerySet
+
+
+def filter_by_lookup_map(
+        queryset: QuerySet,
+        lookup_map: dict,
+        data: dict,
+        extra_filters: dict | None = None
+):
+    """
+    Filters a given queryset based on a lookup map and provided data. Additional filters
+    can also be applied if provided.
+
+    Parameters:
+        queryset (QuerySet): The queryset to be filtered.
+        lookup_map (dict): A dictionary mapping input data keys to filtering fields in
+            the queryset.
+        data (dict): A dictionary containing key-value pairs to filter the queryset.
+        extra_filters (list | None): Optional. A list of extra positional filter
+            arguments to be applied. Defaults to None.
+
+    Returns:
+        QuerySet: The filtered queryset.
+    """
+    if extra_filters is None:
+        extra_filters = {}
+
+    lookup_kwargs = {
+        lookup_map[k]: v
+        for k, v in data.items()
+        if k in lookup_map and v not in (None, "", [])
+    } | extra_filters
+
+    return queryset.filter(**lookup_kwargs)

django_spire/contrib/queryset/mixins.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+from abc import abstractmethod
+from typing import Type
+
+from django.core.handlers.wsgi import WSGIRequest
+from django.db.models import QuerySet
+from django.forms import Form
+from django_spire.contrib.form.utils import show_form_errors
+from django_spire.contrib.queryset.enums import SessionFilterActionEnum
+from django_spire.contrib.session.controller import SessionController
+
+
+class SessionFilterQuerySetMixin(QuerySet):
+
+    def process_session_filter(
+            self,
+            request: WSGIRequest,
+            session_key: str,
+            form_class: Type[Form],
+            is_from_body: bool = False,
+    ) -> QuerySet:
+        # Session keys must match to process new queryset data
+
+        data = json.loads(request.body.decode('utf-8')) if is_from_body else request.GET
+
+        try:
+            action = SessionFilterActionEnum(data.get('action'))
+        except ValueError:
+            action = None
+
+        form = form_class(data)
+
+        if form.is_valid():
+            session = SessionController(request=request, session_key=session_key)
+
+            if action == SessionFilterActionEnum.CLEAR:
+                session.purge()
+                return self
+
+            # Apply filters when the user submits the filter form
+            if (
+                    action == SessionFilterActionEnum.FILTER
+                    and session_key == data.get('session_filter_key')
+            ):
+
+                # Update session data
+                for key, value in form.cleaned_data.items():
+                    session.add_data(key, value)
+
+            # If the session is expired, return the unfiltered queryset
+            if session.is_expired:
+                return self
+
+            # When no new filter data is applied and session is NOT yet expired,
+            # return the original queryset
+            return self.bulk_filter(session.data)
+        else:
+            show_form_errors(request, form)
+            return self
+
+    @abstractmethod
+    def bulk_filter(self, filter_data: dict) -> QuerySet:
+        pass
+
+
+class SearchQuerySetMixin(QuerySet):
+
+    @abstractmethod
+    def search(self, value: str | None) -> QuerySet:
+        pass

django_spire/contrib/seeding/__init__.py

@@ -0,0 +1,3 @@
+from django_spire.contrib.seeding.model.django.seeder import DjangoModelSeeder
+
+__all__ = ["DjangoModelSeeder"]

django_spire/contrib/seeding/field/base.py

@@ -0,0 +1,43 @@
+from abc import ABC, abstractmethod
+
+from django_spire.contrib.seeding.field.cleaners import normalize_seeder_fields
+from django_spire.contrib.seeding.field.enums import FieldSeederTypesEnum
+
+
+class BaseFieldSeeder(ABC):
+    keyword: str = None
+    seed_keywords = FieldSeederTypesEnum._value2member_map_.keys()
+
+    def __init__(
+            self,
+            fields: dict = None,
+            default_to: str = "llm"
+    ):
+
+        self.fields = self._normalize_fields(fields or {})
+        self.default_to = default_to
+
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+
+        if cls.keyword is None:
+            message = 'Seeds must have a keyword'
+            raise ValueError(message)
+
+    def _normalize_fields(self, fields: dict) -> dict:
+        return normalize_seeder_fields(fields)
+
+    def filter_fields(self, seed_type: str) -> dict:
+        return {
+            k: v for k, v in self.fields.items()
+            if isinstance(v, tuple) and v[0] == seed_type
+        }
+
+    @property
+    def seeder_fields(self):
+        return self.filter_fields(self.keyword)
+
+    @abstractmethod
+    def seed(self, model_seeder_cls, count: int):
+        pass

django_spire/contrib/seeding/field/callable.py

@@ -0,0 +1,12 @@
+from django_spire.contrib.seeding.field.base import BaseFieldSeeder
+from django_spire.contrib.seeding.field.enums import FieldSeederTypesEnum
+
+
+class CallableFieldSeeder(BaseFieldSeeder):
+    keyword = FieldSeederTypesEnum.CALLABLE
+
+    def seed(self, manager = None, count = 1) -> list[dict]:
+        return [
+            {field_name: func[1]() for field_name, func in self.seeder_fields.items()}
+            for _ in range(count)
+        ]

django_spire/contrib/seeding/field/cleaners.py

@@ -0,0 +1,35 @@
+from django_spire.contrib.seeding.field.enums import FieldSeederTypesEnum
+
+import copy
+
+def normalize_seeder_fields(fields: dict) -> dict:
+    normalized = {}
+
+    for k, v in fields.items():
+        if v in ("exclude", ("exclude",)):
+            continue
+
+        if isinstance(v, tuple):
+            # Safely clone v[2] if it's a dict
+            extra = ()
+
+            if len(v) > 2:
+                extra_value = v[2]
+
+                if isinstance(extra_value, dict):
+                    extra = (copy.deepcopy(extra_value),)
+                else:
+                    extra = (extra_value,)
+
+            normalized[k] = (v[0],) + v[1:2] + extra
+
+        elif callable(v):
+            normalized[k] = ("callable", v)
+
+        elif isinstance(v, str) and v.lower() in FieldSeederTypesEnum._value2member_map_:
+            normalized[k] = (v.lower(),)
+
+        else:
+            normalized[k] = ("static", v)
+
+    return normalized

django_spire/contrib/seeding/field/custom.py

@@ -0,0 +1,65 @@
+from django.utils import timezone
+from faker import Faker
+
+from django_spire.contrib.seeding.field.base import BaseFieldSeeder
+from django_spire.contrib.seeding.field.enums import FieldSeederTypesEnum
+
+
+class CustomFieldSeeder(BaseFieldSeeder):
+    keyword = FieldSeederTypesEnum.CUSTOM
+
+    def in_order(self, values: list, index: int) -> any:
+        if not values:
+            raise ValueError(
+                "Cannot select from empty values list. "
+                "Make sure the related model has existing records before seeding foreign keys."
+            )
+        index = index % len(values)  # Index loops back on itself
+        return values[index]
+
+    def date_time_between(self, start_date: str, end_date: str):
+        faker = Faker()
+        naive_dt = faker.date_time_between(start_date=start_date, end_date=end_date)
+        return timezone.make_aware(naive_dt)
+
+    def fk_random(self, model_class, ids: list[int]):
+        faker = Faker()
+        return faker.random_element(elements=ids)
+
+    def fk_in_order(self, model_class, index: int, ids: list[int]):
+        """Takes a queryset, calls it then returns a random id"""
+        return self.in_order(values=ids, index=index)
+
+    def seed(self, manager, count) -> list[dict]:
+        data = []
+
+        foreign_keys = {}
+
+        for i in range(count):
+            row = {}
+
+            for field_name, config in self.seeder_fields.items():
+                method_name = config[1] if len(config) > 1 else field_name
+                kwargs = config[2] if len(config) > 2 else {}
+                method = getattr(self, method_name, None)
+
+                if not callable(method):
+                    message = f"Custom method '{method_name}' not found for field '{field_name}'"
+                    raise TypeError(message)
+
+                if method_name in ['in_order', 'fk_in_order']:
+                    kwargs["index"] = i
+
+                if method_name in ['fk_random', 'fk_in_order']:
+                    model_class = kwargs["model_class"]
+
+                    if model_class not in foreign_keys:
+                        foreign_keys[model_class] = list(model_class.objects.all().values_list('id', flat=True))
+
+                    kwargs['ids'] = foreign_keys[model_class]
+
+                row[field_name] = method(**kwargs)
+
+            data.append(row)
+
+        return data