django-spire 0.23.12__py3-none-any.whl → 0.24.0__py3-none-any.whl

django_spire/metric/report/report.py

@@ -0,0 +1,187 @@
+import inspect
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Literal, Callable, Any
+
+from django_spire.metric.report.enums import ColumnType
+from django_spire.metric.report.tools import get_text_alignment_css_class
+
+ColumnLiteralType = Literal['text', 'choice', 'number', 'dollar', 'percent']
+
+
+@dataclass
+class ReportColumn:
+    title: str
+    sub_title: str | None = None
+    type: ColumnType = ColumnType.TEXT
+    sub_type: ColumnType = ColumnType.TEXT
+
+    def css_class(self) -> str:
+        return get_text_alignment_css_class(self.type)
+
+
+@dataclass
+class ReportCell:
+    value: Any
+    sub_value: Any = None
+    type: ColumnType = ColumnType.TEXT
+    sub_type: ColumnType = ColumnType.TEXT
+
+    def css_class(self) -> str:
+        return get_text_alignment_css_class(self.type)
+
+    def cell_value_verbose(self, value):
+        if self.type == ColumnType.DOLLAR:
+            return f"${float(value):,.2f}"
+        elif self.type == ColumnType.NUMBER:
+            return f"{float(value):,.0f}"
+        elif self.type == ColumnType.PERCENT:
+            return f"{float(value):.1f}%"
+        elif self.type == ColumnType.DECIMAL_1:
+            return f"{float(value):.1f}"
+        elif self.type == ColumnType.DECIMAL_2:
+            return f"{float(value):.2f}"
+        elif self.type == ColumnType.DECIMAL_3:
+            return f"{float(value):.3f}"
+
+        return str(value)
+
+    def value_verbose(self):
+        return self.cell_value_verbose(self.value)
+
+    def sub_value_verbose(self):
+        return self.cell_value_verbose(self.sub_value)
+
+
+@dataclass
+class ReportRow:
+    cells: list[ReportCell] = field(default_factory=list)
+    bold: bool = False
+    page_break: bool = False
+    span_all_columns: bool = False
+    table_break: bool = False
+
+
+class BaseReport(ABC):
+    title: str
+    description: str | None = None
+    is_financially_accurate: bool = False
+    ColumnType: type[ColumnType] = ColumnType
+
+    def __init__(self):
+        if not self.title:
+            message = 'Report title is required'
+            raise ValueError(message)
+
+        self.columns: list[ReportColumn] = []
+        self.rows: list[ReportRow] = []
+
+    @property
+    def column_count(self) -> int:
+        return len(self.columns)
+
+    @property
+    def is_ready(self):
+        return len(self.columns) > 0
+
+    @property
+    def run_arguments(self) -> dict[str, dict[str, str]]:
+        arguments = {}
+        signature = inspect.signature(self.run)
+
+        for name, param in signature.parameters.items():
+            arguments[name] = {}
+            arguments[name]['default'] = param.default
+
+            choices_method = getattr(self, f'{name}_choices', None)
+
+            if choices_method and isinstance(choices_method, Callable):
+                arguments[name]['choices'] = choices_method()
+                arguments[name]['annotation'] = 'select'
+            else:
+                arguments[name]['annotation'] = param.annotation.__name__
+
+        return arguments
+
+    @abstractmethod
+    def run(self, **kwargs: Any):
+        raise NotImplementedError
+
+    def add_blank_row(self):
+        self.add_row(
+            cell_values=[' '],
+            span_all_columns=True,
+        )
+
+    def add_column(
+            self,
+            title: str,
+            sub_title: str | None = None,
+            type: ColumnType = ColumnType.TEXT,
+            sub_type: ColumnType = ColumnType.TEXT,
+
+    ):
+        self.columns.append(
+            ReportColumn(title=title, sub_title=sub_title, type=type, sub_type=sub_type)
+        )
+
+    def add_divider_row(
+            self,
+            title: str,
+            page_break: bool = False,
+    ):
+        self.add_row(
+            cell_values=[title],
+            bold=True,
+            page_break=page_break,
+            span_all_columns=True,
+        )
+
+    def add_footer_row(
+            self,
+            cell_values: list[Any],
+            cell_sub_values: list[Any] | None = None,
+    ):
+        self.add_row(
+            cell_values=cell_values,
+            cell_sub_values=cell_sub_values,
+            bold=True,
+        )
+
+    def add_row(
+            self,
+            cell_values: list[Any],
+            cell_sub_values: list[Any] | None = None,
+            bold: bool = False,
+            page_break: bool = False,
+            span_all_columns: bool = False,
+            table_break: bool = False,
+    ):
+        if span_all_columns or table_break:
+            if len(cell_values) > 1:
+                message = 'Cannot span all columns or have a table break with more than one cell value'
+                raise ValueError(message)
+
+        elif len(cell_values) != len(self.columns) or (
+                cell_sub_values is not None and len(cell_sub_values) != len(self.columns)):
+            message = f'Number of cell values ({len(cell_values)}) and sub values ({len(cell_sub_values) if cell_sub_values else "None"}) must match number of columns: {len(self.columns)}'
+            raise ValueError(message)
+
+        self.rows.append(
+            ReportRow(
+                cells=[
+                    ReportCell(
+                        value=cell_values[i],
+                        sub_value=cell_sub_values[i] if cell_sub_values else None,
+                        type=self.columns[i].type,
+                        sub_type=self.columns[i].sub_type
+                    )
+                    for i in range(len(cell_values))
+                ],
+                bold=bold,
+                page_break=page_break,
+                span_all_columns=span_all_columns,
+                table_break=table_break,
+            )
+        )

django_spire/metric/report/templates/django_spire/metric/report/element/report_sub_navigation_element.html

@@ -0,0 +1,34 @@
+{% load variable_types %}
+
+
+<div class="row">
+    <div class="col {% if depth %}ps-4{% endif %}">
+
+        {% if sub_nav_value|is_dict %}
+
+            {% for key, val in sub_nav_value.items %}
+
+                {% if val|is_dict %}
+
+                    <div class="fs--1 pb-1">{{ key }}</div>
+
+                    {% if key_stack is None %}
+                        {% include 'django_spire/metric/report/element/report_sub_navigation_element.html' with depth=True sub_nav_value=val key_stack=key %}
+                    {% else %}
+                        {% include 'django_spire/metric/report/element/report_sub_navigation_element.html' with depth=True sub_nav_value=val key_stack=key_stack|add:'|'|add:key %}
+                    {% endif %}
+
+                {% else %}
+                    <div class="fs--1 pb-1">
+                        <a href="?report_key_stack={{ key_stack }}|{{ key }}">> {{ key }}</a>
+                    </div>
+                {% endif %}
+
+            {% endfor %}
+
+        {% endif %}
+
+    </div>
+</div>
+
+

django_spire/metric/report/templates/django_spire/metric/report/form/report_form.html

@@ -0,0 +1,67 @@
+{% load string_formating %}
+
+<div class="row">
+    <div class="col-11 col-md-10 col-lg-8 col-xl-6 mx-auto my-3">
+
+        <div class="row">
+            <div class="col fs-5 text-center">
+                {{ report.title }}
+            </div>
+        </div>
+        {% if report.description %}
+            <div class="row">
+                <div class="col text-center text-muted fs--1 mb-3">
+                    {{ report.description }}
+                </div>
+            </div>
+        {% endif %}
+
+        <form class="form" method="GET">
+            <input class="form-control" type="hidden" name="report_key_stack"
+                   value="{{ request.GET.report_key_stack }}">
+            <input class="form-control" type="hidden" name="report_should_run" value="True">
+
+            {% for argument, params in report_run_arguments.items %}
+                <div class="row">
+                    <div class="col mb-2">
+
+                        <label class="form-label">
+                            {{ argument|underscores_to_spaces|title }}
+                        </label>
+                        {% if params.annotation == 'str' %}
+                            <input class="form-control" type="text" name="{{ argument }}" value="{{ params.default }}">
+                        {% elif params.annotation == 'int' %}
+                            <input class="form-control" type="number" name="{{ argument }}"
+                                   value="{{ params.default }}">
+                        {% elif params.annotation == 'float' %}
+                            <input class="form-control" type="number" name="{{ argument }}"
+                                   value="{{ params.default }}">
+                        {% elif params.annotation == 'bool' %}
+                            <br><input class="form-check-input" type="checkbox" name="{{ argument }}"
+                                       value="{{ params.default }}">
+                        {% elif params.annotation == 'select' %}
+                            <select class="form-select" name="{{ argument }}" aria-selected="{{ params.default }}">
+                                {% for key, val in params.choices %}
+                                    <option value="{{ key }}">{{ val }}</option>
+                                {% endfor %}
+                            </select>
+                        {% endif %}
+                    </div>
+                </div>
+            {% endfor %}
+
+            <div class="row">
+                <div class="col mt-3 text-center">
+                    <input class="btn btn-primary" type="submit" value="Run Report">
+                </div>
+            </div>
+            <div class="row">
+                <div class="col mt-3 text-center text-muted fs--1">
+                    This report has been informative {{ report_run_count }} times!
+                </div>
+            </div>
+        </form>
+
+    </div>
+</div>
+

django_spire/metric/report/templates/django_spire/metric/report/page/report_page.html

@@ -0,0 +1,37 @@
+{% extends 'django_spire/page/full_page.html' %}
+
+{% load variable_types %}
+
+{% block full_page_sub_navigation_title %}
+    Reports
+{% endblock %}
+
+{% block full_page_sub_navigation %}
+    {% if not report.is_ready %}
+        {% include 'django_spire/metric/report/element/report_sub_navigation_element.html' with depth=0 sub_nav_value=registry.report_names_classes %}
+    {% endif %}
+{% endblock %}
+
+{% block full_page_content %}
+    {% if report %}
+        {% if report.is_ready %}
+            {% include 'django_spire/metric/report/print/report_print.html' %}
+        {% else %}
+            {% include 'django_spire/metric/report/form/report_form.html' %}
+        {% endif %}
+    {% else %}
+        <div class="row">
+            <div class="col fs-5 my-3 text-center">
+                Top 10 Reports
+            </div>
+        </div>
+        {% for report_run in top_ten_report_runs %}
+            <div class="row">
+                <div class="col text-center pb-2">
+                    <a href="?report_key_stack={{ report_run.report_key_stack }}">{{ report_run.report_key_stack_verbose }}</a><br>
+                    <div class="text-muted fs--1">{{ report_run.run_count }} Total Runs</div>
+                </div>
+            </div>
+        {% endfor %}
+    {% endif %}
+{% endblock %}

django_spire/metric/report/templates/django_spire/metric/report/print/report_print.html

@@ -0,0 +1,73 @@
+{% load string_formating %}
+
+<div class="row mb-1 font-monospace">
+    <div class="col">
+        <div class="fw-bold">
+            {{ report.title }}
+        </div>
+    </div>
+</div>
+
+<div class="row mx-0 mb-3 text-muted fw-normal fs--2 border font-monospace">
+    {% if report.description %}
+        <div class="col-auto ps-1 pe-3">
+            Description: {{ report.description }}
+        </div>
+    {% endif %}
+        <div class="col-auto ps-1 pe-3">
+        Printed On: {% now "D, M j, Y" %} at {% now "g:i A" %}
+    </div>
+        <div class="col-auto ps-1 pe-3">
+        Financially Accurate: {% if report.is_financially_accurate %}True{% else %}False{% endif %}
+    </div>
+    {% for argument, value in report_run_arguments_values.items %}
+        <div class="col-auto ps-1 pe-3">
+            {{ argument|underscores_to_spaces|title }}: {{ value }}
+        </div>
+    {% endfor %}
+</div>
+
+<div class="row">
+    <div class="col fs--2">
+
+        <table class="table table-sm table-hover table-print">
+            <thead>
+            {% for column in report.columns %}
+                <th class="align-text-top {{ column.css_class }}">
+                    {{ column.title }}
+                    {% if column.sub_title %}
+                        <span class="text-muted fw-normal fs--2">
+                            <br>{{ column.sub_title }}
+                        </span>
+                    {% endif %}
+                </th>
+            {% endfor %}
+            </thead>
+            <tbody>
+            {% for row in report.rows %}
+                <tr class="{% if row.bold %}fw-bold{% endif %}"
+                    {% if row.page_break %}style="page-break-before: always;"{% endif %}>
+                    {% if row.span_all_columns %}
+                        <td colspan="{{ report.column_count }}">
+                            {% for cell in row.cells %}
+                                {{ cell.value|safe }}
+                            {% endfor %}
+                        </td>
+                    {% else %}
+                        {% for cell in row.cells %}
+                            <td class="{{ cell.css_class }}">
+                                {{ cell.value_verbose }}
+                                {% if cell.sub_value %}
+                                    <br>
+                                    {{ cell.sub_value_verbose }}
+                                {% endif %}
+                            </td>
+                        {% endfor %}
+                    {% endif %}
+                </tr>
+            {% endfor %}
+            </tbody>
+        </table>
+
+    </div>
+</div>

django_spire/metric/report/tests/test_urls/test_page_urls.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from django.urls import reverse
+
+from django_spire.core.tests.test_cases import BaseTestCase
+
+
+class ReportPageUrlsTests(BaseTestCase):
+    def setUp(self):
+        super().setUp()
+
+    def test_report_view_url_path(self):
+        response = self.client.get(
+            reverse('django_spire:metric:report:page:report')
+        )
+        assert response.status_code == 200

django_spire/metric/report/tools.py

@@ -0,0 +1,11 @@
+from django_spire.metric.report.enums import ColumnType
+
+
+def get_text_alignment_css_class(column_type: ColumnType) -> str:
+    if column_type in (ColumnType.DOLLAR, ColumnType.NUMBER, ColumnType.PERCENT, ColumnType.DECIMAL_1,
+                     ColumnType.DECIMAL_2, ColumnType.DECIMAL_3):
+        return 'text-end'
+    if column_type == ColumnType.CHOICE:
+        return 'text-center'
+
+    return 'text-start'

django_spire/metric/report/urls/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from django.urls import include, path
+
+
+app_name = 'report'
+
+urlpatterns = [
+    path('page/', include('django_spire.metric.report.urls.page_urls', namespace='page')),
+]

django_spire/metric/report/urls/page_urls.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from django.urls import path
+
+from django_spire.metric.report.views import page_views
+
+
+app_name = 'report'
+
+urlpatterns = [
+    path('',
+         page_views.report_view,
+         name='report'),
+]

django_spire/metric/report/views/page_views.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.conf import settings
+from django.urls import reverse
+
+from django_spire.auth.controller.controller import AppAuthController
+from django_spire.contrib import Breadcrumbs
+from django_spire.contrib.generic_views import portal_views
+from django_spire.core.utils import get_object_from_module_string
+from django_spire.metric.report.models import ReportRun
+from django_spire.metric.report.registry import ReportRegistry
+
+if TYPE_CHECKING:
+    from django.core.handlers.wsgi import WSGIRequest
+    from django.template.response import TemplateResponse
+
+
+@AppAuthController('report').permission_required('can_view')
+def report_view(request: WSGIRequest) -> TemplateResponse:
+    breadcrumbs = Breadcrumbs()
+
+    breadcrumbs.add_breadcrumb(
+        'Reports',
+        reverse('django_spire:metric:report:page:report'),
+    )
+
+    page_report_registry = ReportRegistry()
+
+    for report_registry in settings.DJANGO_SPIRE_REPORT_REGISTRIES:
+        report_registry_class = get_object_from_module_string(
+            report_registry
+        )
+
+        page_report_registry.add_registry(
+            report_registry_class()
+        )
+
+    context_data = {
+        'registry': page_report_registry,
+    }
+
+    if request.GET:
+        report_key_stack = request.GET.get('report_key_stack', None)
+
+        if report_key_stack:
+            report = page_report_registry.get_report_from_key_stack(report_key_stack)
+
+            if report:
+                for key in report_key_stack.split('|'):
+                    breadcrumbs.add_breadcrumb(
+                        key,
+                    )
+
+                context_data['report_run_arguments'] = report.run_arguments
+
+                context_data['report_run_arguments_values'] = {}
+
+                for argument in report.run_arguments:
+                    if context_data['report_run_arguments'][argument]['annotation'] == 'bool':
+                        get_request_value = request.GET.get(argument, False)
+                    else:
+                        get_request_value = request.GET.get(argument, None)
+
+                    context_data['report_run_arguments_values'][argument] = get_request_value
+
+                if request.GET.get('report_should_run', 'false').lower() == 'true':
+                    for argument, value in context_data['report_run_arguments_values'].items():
+                        if value is None:
+                            break
+                    else:
+                        ReportRun.objects.create(
+                            report_key_stack=report_key_stack,
+                        )
+                        report.run()
+
+                context_data['report'] = report
+                context_data['report_run_count'] = ReportRun.objects.run_count(report_key_stack)
+
+    else:
+        top_ten_report_runs = [
+            {
+                **report_run,
+                'report_key_stack_verbose': report_run['report_key_stack'].replace('|', ' > '),
+            }
+            for report_run in
+            ReportRun.objects.by_top_ten()
+        ]
+
+        context_data['top_ten_report_runs'] = top_ten_report_runs
+
+    return portal_views.template_view(
+        request,
+        page_title='Reports',
+        page_description='More Reporting Info',
+        breadcrumbs=breadcrumbs,
+        context_data=context_data,
+        template='django_spire/metric/report/page/report_page.html'
+    )

django_spire/metric/urls/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from django.urls import include, path
+
+
+app_name = 'metric'
+
+urlpatterns = [
+    path('report/', include('django_spire.metric.report.urls', namespace='report')),
+]

django_spire/settings.py

@@ -5,6 +5,7 @@ DJANGO_SPIRE_AUTH_CONTROLLERS = {
     'ai_chat': 'django_spire.ai.chat.auth.controller.BaseAiChatAuthController',
     'help_desk': 'django_spire.help_desk.auth.controller.BaseHelpDeskAuthController',
     'knowledge': 'django_spire.knowledge.auth.controller.BaseKnowledgeAuthController',
+    'report': 'django_spire.metric.report.auth.controller.BaseReportAuthController',
 }
 
 # AI Settings
@@ -23,6 +24,8 @@ DJANGO_SPIRE_AI_INTENT_CHAT_ROUTERS = {
     },
 }
 
+DJANGO_SPIRE_REPORT_REGISTRIES = []
+
 # Theme Settings
 DJANGO_SPIRE_DEFAULT_THEME = 'default-light'
 DJANGO_SPIRE_THEME_PATH = '/static/django_spire/css/themes/{family}/app-{mode}.css'

{django_spire-0.23.12.dist-info → django_spire-0.24.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-spire
-Version: 0.23.12
+Version: 0.24.0
 Summary: A project for Django Spire
 Author-email: Brayden Carlson <braydenc@stratusadv.com>, Nathan Johnson <nathanj@stratusadv.com>
 License: Copyright (c) 2025 Stratus Advanced Technologies and Contributors.