django-reportkit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. django_reportkit/__init__.py +10 -0
  2. django_reportkit/apps.py +21 -0
  3. django_reportkit/conf.py +35 -0
  4. django_reportkit/errors/__init__.py +5 -0
  5. django_reportkit/errors/exceptions.py +43 -0
  6. django_reportkit/errors/handlers.py +37 -0
  7. django_reportkit/errors/messages.py +36 -0
  8. django_reportkit/exports/__init__.py +5 -0
  9. django_reportkit/exports/formats.py +60 -0
  10. django_reportkit/exports/policy.py +49 -0
  11. django_reportkit/exports/runner.py +32 -0
  12. django_reportkit/jobs/__init__.py +3 -0
  13. django_reportkit/jobs/backends/__init__.py +6 -0
  14. django_reportkit/jobs/backends/base.py +14 -0
  15. django_reportkit/jobs/backends/celery.py +17 -0
  16. django_reportkit/jobs/backends/sync.py +15 -0
  17. django_reportkit/jobs/backends/thread.py +20 -0
  18. django_reportkit/jobs/cleanup.py +48 -0
  19. django_reportkit/jobs/models.py +89 -0
  20. django_reportkit/jobs/service.py +147 -0
  21. django_reportkit/jobs/storage.py +26 -0
  22. django_reportkit/jobs/tasks.py +11 -0
  23. django_reportkit/management/__init__.py +0 -0
  24. django_reportkit/management/commands/__init__.py +0 -0
  25. django_reportkit/management/commands/cleanup_report_files.py +17 -0
  26. django_reportkit/migrations/0001_initial.py +44 -0
  27. django_reportkit/migrations/__init__.py +0 -0
  28. django_reportkit/models.py +3 -0
  29. django_reportkit/reports/__init__.py +7 -0
  30. django_reportkit/reports/base.py +45 -0
  31. django_reportkit/reports/columns.py +28 -0
  32. django_reportkit/reports/mixins/__init__.py +5 -0
  33. django_reportkit/reports/mixins/access.py +58 -0
  34. django_reportkit/reports/mixins/document.py +111 -0
  35. django_reportkit/reports/mixins/filters.py +39 -0
  36. django_reportkit/reports/model.py +76 -0
  37. django_reportkit/reports/params.py +65 -0
  38. django_reportkit/reports/registry.py +44 -0
  39. django_reportkit/reports/rows.py +17 -0
  40. django_reportkit/rest/__init__.py +3 -0
  41. django_reportkit/rest/errors.py +27 -0
  42. django_reportkit/rest/permissions.py +16 -0
  43. django_reportkit/rest/serializers.py +147 -0
  44. django_reportkit/rest/urls.py +28 -0
  45. django_reportkit/rest/views.py +257 -0
  46. django_reportkit/templates/django_reportkit/base.html +28 -0
  47. django_reportkit/templates/django_reportkit/error.html +9 -0
  48. django_reportkit/templates/django_reportkit/job.html +32 -0
  49. django_reportkit/templates/django_reportkit/preview.html +35 -0
  50. django_reportkit/urls.py +10 -0
  51. django_reportkit/views/__init__.py +5 -0
  52. django_reportkit/views/export.py +62 -0
  53. django_reportkit/views/jobs.py +101 -0
  54. django_reportkit/views/mixins.py +39 -0
  55. django_reportkit/views/preview.py +75 -0
  56. django_reportkit/views/urls.py +15 -0
  57. django_reportkit-0.1.0.dist-info/METADATA +212 -0
  58. django_reportkit-0.1.0.dist-info/RECORD +61 -0
  59. django_reportkit-0.1.0.dist-info/WHEEL +5 -0
  60. django_reportkit-0.1.0.dist-info/licenses/LICENSE +21 -0
  61. django_reportkit-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,10 @@
1
+ """
2
+ Django reports on top of pyreportkit.
3
+ """
4
+
5
+ from django.db.models import Avg, Count, Max, Min, Sum
6
+
7
+ from .reports import Column, ModelReport, Report, ReportParams, register
8
+
9
+ __version__ = "0.1.0"
10
+ __all__ = ["Avg", "Column", "Count", "Max", "Min", "ModelReport", "Report", "ReportParams", "Sum", "register"]
@@ -0,0 +1,21 @@
1
+ from django.apps import AppConfig
2
+ from django.utils.translation import gettext_lazy as _
3
+
4
+
5
+ class ReportKitConfig(AppConfig):
6
+ """
7
+ Django application for pyreportkit reports: templates, the ReportJob model and its cleanup command.
8
+ """
9
+
10
+ name = "django_reportkit"
11
+ label = "django_reportkit"
12
+ verbose_name = _("Reports")
13
+ default_auto_field = "django.db.models.BigAutoField"
14
+
15
+ def ready(self):
16
+ """
17
+ Import every installed app's reports module, so reports registered with @register are known at startup.
18
+ """
19
+ from django.utils.module_loading import autodiscover_modules
20
+
21
+ autodiscover_modules("reports")
@@ -0,0 +1,35 @@
1
+ from django.conf import settings
2
+
3
+ DEFAULTS = {
4
+ "PAGINATE_BY": 50,
5
+ # Rows above which a format is generated in the background instead of during the request; None never moves it.
6
+ "DIRECT_LIMITS": {"pdf": 2000, "docx": 2000, "xlsx": 20000, "xlsx-data": 100000, "html": 5000},
7
+ # Rows above which a format is refused with a suggestion to use another one; None has no limit.
8
+ "MAX_ROWS": {"pdf": 50000, "docx": 50000, "xlsx": 100000, "xlsx-data": None, "html": 20000},
9
+ "JOB_BACKEND": "django_reportkit.jobs.backends.ThreadBackend",
10
+ "JOB_STORAGE": "default", # A key of settings.STORAGES.
11
+ "JOB_DIRECTORY": "reports",
12
+ "JOB_TTL_HOURS": 24,
13
+ "STATUS_POLL_SECONDS": 3,
14
+ "PDF_WORKERS": 1,
15
+ }
16
+
17
+
18
+ class ReportKitSettings:
19
+ """
20
+ Read settings.REPORTKIT over the defaults on every access, so overridden settings (as in tests) apply at once.
21
+ """
22
+
23
+ def __getattr__(self, name):
24
+ """
25
+ Return one setting; dictionaries are merged key by key over their defaults.
26
+ """
27
+ if name not in DEFAULTS:
28
+ raise AttributeError(f"Unknown django-reportkit setting: {name}")
29
+ configured = getattr(settings, "REPORTKIT", {}).get(name, DEFAULTS[name])
30
+ if isinstance(DEFAULTS[name], dict):
31
+ return {**DEFAULTS[name], **configured}
32
+ return configured
33
+
34
+
35
+ reportkit_settings = ReportKitSettings()
@@ -0,0 +1,5 @@
1
+ from .exceptions import ExportTooLargeError, ReportError, ReportFilterError, UnknownFormatError
2
+ from .handlers import error_response, log_error
3
+ from .messages import friendly_message
4
+
5
+ __all__ = ["ExportTooLargeError", "ReportError", "ReportFilterError", "UnknownFormatError", "error_response", "friendly_message", "log_error"]
@@ -0,0 +1,43 @@
1
+ class ReportError(Exception):
2
+ """
3
+ Base class of the errors django-reportkit shows to users with a friendly message.
4
+ """
5
+
6
+
7
+ class ReportFilterError(ReportError):
8
+ """
9
+ The filter form is invalid; errors holds the form errors.
10
+ """
11
+
12
+ def __init__(self, errors):
13
+ """
14
+ Keep the form errors.
15
+ """
16
+ super().__init__("The report filters are invalid.")
17
+ self.errors = errors
18
+
19
+
20
+ class UnknownFormatError(ReportError):
21
+ """
22
+ The requested export format is not offered by the report.
23
+ """
24
+
25
+ def __init__(self, format):
26
+ """
27
+ Keep the format name.
28
+ """
29
+ super().__init__(f"Unknown or disabled export format: {format}")
30
+ self.format = format
31
+
32
+
33
+ class ExportTooLargeError(ReportError):
34
+ """
35
+ The report has more rows than the format allows; alternative names a format that can hold it, if any.
36
+ """
37
+
38
+ def __init__(self, format, rows, limit, alternative=None):
39
+ """
40
+ Keep the numbers needed to explain the refusal.
41
+ """
42
+ super().__init__(f"{rows} rows exceed the {format} limit of {limit}.")
43
+ self.format, self.rows, self.limit, self.alternative = format, rows, limit, alternative
@@ -0,0 +1,37 @@
1
+ import logging
2
+
3
+ from django.shortcuts import render
4
+ from django.utils.http import url_has_allowed_host_and_scheme
5
+
6
+ from .exceptions import ReportError
7
+ from .messages import friendly_message, status_code
8
+
9
+ logger = logging.getLogger("django_reportkit")
10
+
11
+
12
+ def log_error(error, report=None):
13
+ """
14
+ Log an error: expected report errors as warnings, anything else with its traceback.
15
+ """
16
+ name = type(report).__name__ if report is not None else "report"
17
+ if isinstance(error, ReportError):
18
+ logger.warning("%s: %s", name, error)
19
+ else:
20
+ logger.exception("%s failed", name, exc_info=error)
21
+
22
+
23
+ def error_response(request, error, report=None):
24
+ """
25
+ Log the error and render the friendly error page with the matching status.
26
+ """
27
+ log_error(error, report)
28
+ context = {"message": friendly_message(error), "report": report, "back_url": back_url(request)}
29
+ return render(request, "django_reportkit/error.html", context, status=status_code(error))
30
+
31
+
32
+ def back_url(request):
33
+ """
34
+ Return the referring page when it belongs to this site, for the error page's back link.
35
+ """
36
+ referer = request.META.get("HTTP_REFERER")
37
+ return referer if referer and url_has_allowed_host_and_scheme(referer, allowed_hosts={request.get_host()}, require_https=request.is_secure()) else None
@@ -0,0 +1,36 @@
1
+ from django.utils.translation import gettext as _
2
+
3
+ from .exceptions import ExportTooLargeError, ReportFilterError, UnknownFormatError
4
+
5
+
6
+ def friendly_message(error):
7
+ """
8
+ Return the message a user sees for an error; technical details stay in the logs.
9
+ """
10
+ if isinstance(error, ReportFilterError):
11
+ return _("Please correct the report filters.")
12
+ if isinstance(error, UnknownFormatError):
13
+ return _("This report cannot be downloaded in that format.")
14
+ if isinstance(error, ExportTooLargeError):
15
+ message = _("The report has %(rows)s rows, more than %(limit)s allowed for this format.") % {"rows": f"{error.rows:,}", "limit": f"{error.limit:,}"}
16
+ if error.alternative:
17
+ message += " " + _("Download it as Excel (data) instead, or narrow the filters.")
18
+ else:
19
+ message += " " + _("Narrow the filters and try again.")
20
+ return message
21
+ if isinstance(error, ImportError):
22
+ return _("This format is not available on the server right now.")
23
+ return _("The report could not be created. Please try again later.")
24
+
25
+
26
+ def status_code(error):
27
+ """
28
+ Return the HTTP status that matches the error.
29
+ """
30
+ if isinstance(error, (ReportFilterError, UnknownFormatError)):
31
+ return 400
32
+ if isinstance(error, ExportTooLargeError):
33
+ return 413
34
+ if isinstance(error, ImportError):
35
+ return 503
36
+ return 500
@@ -0,0 +1,5 @@
1
+ from .formats import FORMATS, ExportFormat, get_format
2
+ from .policy import Delivery, ExportPolicy
3
+ from .runner import ExportRunner
4
+
5
+ __all__ = ["Delivery", "ExportFormat", "ExportPolicy", "ExportRunner", "FORMATS", "get_format"]
@@ -0,0 +1,60 @@
1
+ from dataclasses import dataclass
2
+
3
+ from django.utils.translation import gettext_lazy as _
4
+
5
+ from ..conf import reportkit_settings
6
+ from ..errors.exceptions import UnknownFormatError
7
+
8
+ XLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
9
+ DOCX = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
10
+
11
+
12
+ @dataclass(frozen=True)
13
+ class ExportFormat:
14
+ """
15
+ One downloadable format: the pyreportkit exporter it uses, the file it produces and how to export large reports.
16
+ """
17
+
18
+ name: str
19
+ exporter: str
20
+ extension: str
21
+ content_type: str
22
+ label: str
23
+
24
+ def options(self):
25
+ """
26
+ Return the pyreportkit export options; imported lazily so missing optional exporters fail only when used.
27
+ """
28
+ if self.name == "pdf":
29
+ from reportkit.exporters.pdf import PdfOptions
30
+
31
+ return {"options": PdfOptions(workers=reportkit_settings.PDF_WORKERS)}
32
+ if self.name == "xlsx-data":
33
+ from reportkit.exporters.excel import ExcelOptions
34
+
35
+ return {"options": ExcelOptions(mode="data", streaming=True)}
36
+ return {}
37
+
38
+ def filename(self, slug):
39
+ """
40
+ Return the download file name.
41
+ """
42
+ return f"{slug}.{self.extension}"
43
+
44
+
45
+ FORMATS = {
46
+ "pdf": ExportFormat("pdf", "pdf", "pdf", "application/pdf", _("PDF")),
47
+ "xlsx": ExportFormat("xlsx", "xlsx", "xlsx", XLSX, _("Excel")),
48
+ "xlsx-data": ExportFormat("xlsx-data", "xlsx", "xlsx", XLSX, _("Excel (data)")),
49
+ "docx": ExportFormat("docx", "docx", "docx", DOCX, _("Word")),
50
+ "html": ExportFormat("html", "html", "html", "text/html; charset=utf-8", _("HTML")),
51
+ }
52
+
53
+
54
+ def get_format(report, name):
55
+ """
56
+ Return the export format when the report offers it.
57
+ """
58
+ if name not in report.formats or name not in FORMATS:
59
+ raise UnknownFormatError(name)
60
+ return FORMATS[name]
@@ -0,0 +1,49 @@
1
+ from enum import Enum
2
+
3
+ from ..conf import reportkit_settings
4
+ from ..errors.exceptions import ExportTooLargeError
5
+
6
+
7
+ UNLIMITED = "xlsx-data"
8
+
9
+
10
+ class Delivery(Enum):
11
+ """
12
+ How an export reaches the user.
13
+ """
14
+
15
+ DIRECT = "direct"
16
+ BACKGROUND = "background"
17
+
18
+
19
+ class ExportPolicy:
20
+ """
21
+ Decide whether an export runs directly, in the background, or is refused according to configured row limits.
22
+ """
23
+
24
+ @classmethod
25
+ def decide(cls, format, rows, formats):
26
+ """
27
+ Validate the export size and return its delivery method.
28
+ """
29
+ cls.validate_size(format, rows, formats)
30
+ return cls.delivery(format, rows)
31
+
32
+ @staticmethod
33
+ def validate_size(format, rows, formats):
34
+ """
35
+ Reject exports exceeding the format's maximum row limit.
36
+ """
37
+ maximum = reportkit_settings.MAX_ROWS.get(format.name)
38
+
39
+ if maximum is not None and rows > maximum:
40
+ alternative = UNLIMITED if UNLIMITED in formats and format.name != UNLIMITED else None
41
+ raise ExportTooLargeError(format.name, rows, maximum, alternative)
42
+
43
+ @staticmethod
44
+ def delivery(format, rows):
45
+ """
46
+ Choose direct or background delivery using the configured direct row limit.
47
+ """
48
+ direct = reportkit_settings.DIRECT_LIMITS.get(format.name)
49
+ return Delivery.BACKGROUND if direct is not None and rows > direct else Delivery.DIRECT
@@ -0,0 +1,32 @@
1
+ from tempfile import TemporaryFile
2
+
3
+ from django.utils.translation import override
4
+ from reportkit.builders import ReportExport
5
+
6
+
7
+ class ExportRunner:
8
+ """
9
+ Write a report in one format to a temporary file on disk, never to memory, ready to be streamed or stored.
10
+ """
11
+
12
+ @staticmethod
13
+ def write(report, format, target):
14
+ """
15
+ Export the report to a path or a binary stream in its language.
16
+ """
17
+ with override(report.params.language):
18
+ ReportExport.export_to(report.document(), format.exporter, target, report.context(), **format.options())
19
+
20
+ @classmethod
21
+ def to_temporary_file(cls, report, format):
22
+ """
23
+ Return an open temporary file holding the export, positioned at its start; closing it deletes it.
24
+ """
25
+ spool = TemporaryFile()
26
+ try:
27
+ cls.write(report, format, spool)
28
+ except BaseException:
29
+ spool.close()
30
+ raise
31
+ spool.seek(0)
32
+ return spool
@@ -0,0 +1,3 @@
1
+ """
2
+ Background exports; import the modules directly (models need the app registry).
3
+ """
@@ -0,0 +1,6 @@
1
+ from .base import JobBackend
2
+ from .celery import CeleryBackend
3
+ from .sync import SyncBackend
4
+ from .thread import ThreadBackend
5
+
6
+ __all__ = ["CeleryBackend", "JobBackend", "SyncBackend", "ThreadBackend"]
@@ -0,0 +1,14 @@
1
+ from abc import ABC, abstractmethod
2
+
3
+
4
+ class JobBackend(ABC):
5
+ """
6
+ Run background export jobs; submit() receives the job id once the job is saved.
7
+ """
8
+
9
+ @abstractmethod
10
+ def submit(self, job_id):
11
+ """
12
+ Arrange for the job to run.
13
+ """
14
+ raise NotImplementedError
@@ -0,0 +1,17 @@
1
+ from django.db import transaction
2
+
3
+ from .base import JobBackend
4
+
5
+
6
+ class CeleryBackend(JobBackend):
7
+ """
8
+ Send the job to a Celery worker after the transaction commits (pip install "django-reportkit[celery]").
9
+ """
10
+
11
+ def submit(self, job_id):
12
+ """
13
+ Queue the job's task.
14
+ """
15
+ from ..tasks import run_report_job
16
+
17
+ transaction.on_commit(lambda: run_report_job.delay(job_id))
@@ -0,0 +1,15 @@
1
+ from .base import JobBackend
2
+
3
+
4
+ class SyncBackend(JobBackend):
5
+ """
6
+ Run the job at once, inside the request: for tests and development; the request waits for the file.
7
+ """
8
+
9
+ def submit(self, job_id):
10
+ """
11
+ Run the job now.
12
+ """
13
+ from ..service import ReportJobs # Deferred: the service imports the backends' module.
14
+
15
+ ReportJobs.run(job_id)
@@ -0,0 +1,20 @@
1
+ import threading
2
+
3
+ from django.db import transaction
4
+
5
+ from .base import JobBackend
6
+
7
+
8
+ class ThreadBackend(JobBackend):
9
+ """
10
+ Run the job in a thread of the web process after the transaction commits: no extra service needed, but a job is
11
+ lost if the process restarts, so use Celery in production.
12
+ """
13
+
14
+ def submit(self, job_id):
15
+ """
16
+ Start a daemon thread for the job once the job row is committed.
17
+ """
18
+ from ..service import run_job # Deferred: the service imports the backends' module.
19
+
20
+ transaction.on_commit(lambda: threading.Thread(target=run_job, args=(job_id,), name=f"report-job-{job_id}", daemon=True).start())
@@ -0,0 +1,48 @@
1
+ import logging
2
+ from datetime import timedelta
3
+
4
+ from django.db.models import Q
5
+ from django.utils import timezone
6
+
7
+ from .models import ReportJob
8
+ from .storage import delete_export
9
+
10
+
11
+ logger = logging.getLogger(__name__)
12
+ FAILED_JOB_RETENTION = timedelta(days=1)
13
+
14
+
15
+ def delete_expired_jobs(now=None):
16
+ """
17
+ Delete expired jobs with their files, and failed jobs older than a day; return how many were deleted.
18
+ """
19
+ now = now or timezone.now()
20
+ count = 0
21
+
22
+ for job in expired_jobs(now).iterator(chunk_size=200):
23
+ if delete_job(job):
24
+ count += 1
25
+
26
+ return count
27
+
28
+
29
+ def expired_jobs(now):
30
+ """
31
+ Return completed expired jobs and failed jobs past their retention period.
32
+ """
33
+ failed_before = now - FAILED_JOB_RETENTION
34
+ return ReportJob.objects.filter(Q(status=ReportJob.Status.DONE, expires_at__lte=now) | Q(status=ReportJob.Status.FAILED, finished_at__lte=failed_before)).order_by("pk")
35
+
36
+
37
+ def delete_job(job):
38
+ """
39
+ Delete a job and its stored export, retaining the record when cleanup fails.
40
+ """
41
+ try:
42
+ if job.file:
43
+ delete_export(job.file)
44
+ job.delete()
45
+ return True
46
+ except Exception:
47
+ logger.exception("Failed to delete report job %s", job.pk)
48
+ return False
@@ -0,0 +1,89 @@
1
+ import uuid
2
+
3
+ from django.conf import settings
4
+ from django.db import models
5
+ from django.utils import timezone
6
+ from django.utils.translation import gettext_lazy as _
7
+
8
+
9
+ class ReportJob(models.Model):
10
+ """
11
+ A report exported in the background: what to build (report class, format, parameters), its progress, and the
12
+ stored file until it expires.
13
+ """
14
+
15
+ class Status(models.TextChoices):
16
+ PENDING = "pending", _("Waiting")
17
+ RUNNING = "running", _("Generating")
18
+ DONE = "done", _("Ready")
19
+ FAILED = "failed", _("Failed")
20
+
21
+ id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
22
+
23
+ report = models.CharField(_("report"), max_length=255)
24
+
25
+ title = models.CharField(_("title"), max_length=255, blank=True)
26
+
27
+ format = models.CharField(_("format"), max_length=20)
28
+
29
+ params = models.JSONField(_("parameters"), default=dict)
30
+
31
+ user = models.ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True, on_delete=models.CASCADE, related_name="report_jobs")
32
+
33
+ status = models.CharField(_("status"), max_length=10, choices=Status.choices, default=Status.PENDING)
34
+
35
+ rows = models.PositiveIntegerField(_("rows"), default=0)
36
+
37
+ file = models.CharField(_("file"), max_length=500, blank=True)
38
+
39
+ filename = models.CharField(_("file name"), max_length=255, blank=True)
40
+
41
+ error = models.TextField(_("error"), blank=True)
42
+
43
+ created_at = models.DateTimeField(_("created"), auto_now_add=True)
44
+
45
+ started_at = models.DateTimeField(_("started"), null=True, blank=True)
46
+
47
+ finished_at = models.DateTimeField(_("finished"), null=True, blank=True)
48
+
49
+ expires_at = models.DateTimeField(_("expires"), null=True, blank=True)
50
+
51
+ class Meta:
52
+ app_label = "django_reportkit"
53
+ ordering = ["-created_at"]
54
+ indexes = [models.Index(fields=["status", "expires_at"])]
55
+ verbose_name = _("report job")
56
+ verbose_name_plural = _("report jobs")
57
+
58
+ def __str__(self):
59
+ """
60
+ Show the report title, format and status.
61
+ """
62
+ return f"{self.title or self.report} ({self.format}, {self.status})"
63
+
64
+ @property
65
+ def finished(self):
66
+ """
67
+ Return whether the job has stopped, successfully or not.
68
+ """
69
+ return self.status in (self.Status.DONE, self.Status.FAILED)
70
+
71
+ @property
72
+ def expired(self):
73
+ """
74
+ Return whether the job has passed its expiration time.
75
+ """
76
+ return self.expires_at is not None and self.expires_at <= timezone.now()
77
+
78
+ @property
79
+ def downloadable(self):
80
+ """
81
+ Return whether the job has a completed, unexpired export file.
82
+ """
83
+ return self.status == self.Status.DONE and bool(self.file) and not self.expired
84
+
85
+ def can_access(self, user):
86
+ """
87
+ Return whether the authenticated user owns the job or has staff access.
88
+ """
89
+ return bool(user and user.is_authenticated and (user.pk == self.user_id or user.is_staff))