django-importexport-flow 0.1.0__tar.gz

django_importexport_flow-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Octolo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

django_importexport_flow-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: django-importexport-flow
+Version: 0.1.0
+Summary: Declarative export and import definitions for Django (queryset, tabular/PDF, hooks).
+Author-email: Octolo <dev@octolo.tech>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/octolo/django-importexport-flow
+Project-URL: Repository, https://github.com/octolo/django-importexport-flow
+Project-URL: Documentation, https://github.com/octolo/django-importexport-flow/blob/main/docs/README.md
+Project-URL: Issues, https://github.com/octolo/django-importexport-flow/issues
+Keywords: django,reporting,export,csv,excel,pdf,contenttypes
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=3.2
+Requires-Dist: django-boosted>=1.0.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=3.0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-django>=4.5; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: django-stubs>=5.0.0; extra == "dev"
+Requires-Dist: weasyprint>=62.0; extra == "dev"
+Dynamic: license-file
+
+# django-importexport-flow
+
+Declarative reporting for Django: **target model** (`ContentType`), **manager** path, **`filter_config` / `filter_request` / `filter_mandatory`**, **`order_by`**, and **columns** on **`ExportConfigTable`**. Optional **PDF** (`ExportConfigPdf`) and **CSV / XLSX / JSON** export from the admin.
+
+**Documentation:** [docs/README.md](docs/README.md)
+
+## Install
+
+```bash
+pip install django-importexport-flow
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django.contrib.contenttypes",
+    "django_boosted",
+    "django_importexport_flow",
+]
+```
+
+```bash
+python manage.py migrate django_importexport_flow
+```
+
+## Documentation index
+
+| Topic | Doc |
+|-------|-----|
+| Install & settings | [docs/installation.md](docs/installation.md) |
+| Purpose | [docs/purpose.md](docs/purpose.md) |
+| Repository layout | [docs/structure.md](docs/structure.md) |
+| Filters & admin export | [docs/filters-and-export.md](docs/filters-and-export.md) |
+| Development | [docs/development.md](docs/development.md) |
+| AI / tooling notes | [docs/AI.md](docs/AI.md) |
+
+## License
+
+MIT

django_importexport_flow-0.1.0/README.md

@@ -0,0 +1,39 @@
+# django-importexport-flow
+
+Declarative reporting for Django: **target model** (`ContentType`), **manager** path, **`filter_config` / `filter_request` / `filter_mandatory`**, **`order_by`**, and **columns** on **`ExportConfigTable`**. Optional **PDF** (`ExportConfigPdf`) and **CSV / XLSX / JSON** export from the admin.
+
+**Documentation:** [docs/README.md](docs/README.md)
+
+## Install
+
+```bash
+pip install django-importexport-flow
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django.contrib.contenttypes",
+    "django_boosted",
+    "django_importexport_flow",
+]
+```
+
+```bash
+python manage.py migrate django_importexport_flow
+```
+
+## Documentation index
+
+| Topic | Doc |
+|-------|-----|
+| Install & settings | [docs/installation.md](docs/installation.md) |
+| Purpose | [docs/purpose.md](docs/purpose.md) |
+| Repository layout | [docs/structure.md](docs/structure.md) |
+| Filters & admin export | [docs/filters-and-export.md](docs/filters-and-export.md) |
+| Development | [docs/development.md](docs/development.md) |
+| AI / tooling notes | [docs/AI.md](docs/AI.md) |
+
+## License
+
+MIT

django_importexport_flow-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "django-importexport-flow"
+version = "0.1.0"
+description = "Declarative export and import definitions for Django (queryset, tabular/PDF, hooks)."
+readme = "README.md"
+authors = [{ name = "Octolo", email = "dev@octolo.tech" }]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = [
+    "django",
+    "reporting",
+    "export",
+    "csv",
+    "excel",
+    "pdf",
+    "contenttypes",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Framework :: Django",
+    "Framework :: Django :: 3.2",
+    "Framework :: Django :: 4.0",
+    "Framework :: Django :: 4.1",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+dependencies = [
+    "Django>=3.2",
+    "django-boosted>=1.0.0",
+    "openpyxl>=3.1.5",
+    "pandas>=3.0.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/octolo/django-importexport-flow"
+Repository = "https://github.com/octolo/django-importexport-flow"
+Documentation = "https://github.com/octolo/django-importexport-flow/blob/main/docs/README.md"
+Issues = "https://github.com/octolo/django-importexport-flow/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3",
+    "pytest-django>=4.5",
+    "ruff>=0.5",
+    "mypy>=1.0",
+    "django-stubs>=5.0.0",
+    "weasyprint>=62.0",
+]
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["django_importexport_flow*"]
+exclude = ["tests*"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+plugins = ["mypy_django_plugin.main"]
+mypy_path = "src"
+
+[tool.django-stubs]
+django_settings_module = "tests.settings"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

django_importexport_flow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

django_importexport_flow-0.1.0/src/django_importexport_flow/__init__.py

@@ -0,0 +1,81 @@
+"""django-importexport-flow package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("django-importexport-flow")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "ExportConfigPdf",
+    "ExportConfigTable",
+    "ExportDefinition",
+    "ImportDefinition",
+    "ImportRequest",
+    "ExportRequest",
+    "ExportManager",
+    "__version__",
+    "get_export_definitions",
+    "serialize_export_configuration",
+    "serialize_import_definition",
+    "import_import_definition",
+    "serialize_report_import",
+    "import_report_import",
+]
+
+
+def __getattr__(name: str):
+    if name == "ExportManager":
+        from .managers import ExportManager
+
+        return ExportManager
+    if name == "serialize_export_configuration":
+        from .utils.serialization import serialize_export_configuration
+
+        return serialize_export_configuration
+    if name == "serialize_import_definition":
+        from .utils.serialization import serialize_import_definition
+
+        return serialize_import_definition
+    if name == "import_import_definition":
+        from .utils.serialization import import_import_definition
+
+        return import_import_definition
+    if name == "serialize_report_import":
+        from .utils.serialization import serialize_report_import
+
+        return serialize_report_import
+    if name == "import_report_import":
+        from .utils.serialization import import_report_import
+
+        return import_report_import
+    if name == "get_export_definitions":
+        from .utils import get_export_definitions
+
+        return get_export_definitions
+    if name == "ExportDefinition":
+        from .models import ExportDefinition
+
+        return ExportDefinition
+    if name == "ExportConfigPdf":
+        from .models import ExportConfigPdf
+
+        return ExportConfigPdf
+    if name == "ExportConfigTable":
+        from .models import ExportConfigTable
+
+        return ExportConfigTable
+    if name == "ImportDefinition":
+        from .models import ImportDefinition
+
+        return ImportDefinition
+    if name == "ImportRequest":
+        from .models import ImportRequest
+
+        return ImportRequest
+    if name == "ExportRequest":
+        from .models import ExportRequest
+
+        return ExportRequest
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

django_importexport_flow-0.1.0/src/django_importexport_flow/admin/__init__.py

@@ -0,0 +1,23 @@
+"""Django admin registration for django-importexport-flow."""
+
+from __future__ import annotations
+
+# Load modules so @admin.register runs.
+from . import export_definition  # noqa: F401
+from . import import_definition  # noqa: F401
+from . import import_request  # noqa: F401
+from . import export_request  # noqa: F401
+
+from .export_definition import (
+    ExportConfigPdfInline,
+    ExportConfigTableInline,
+    ExportDefinitionAdmin,
+)
+from .import_definition import ImportDefinitionAdmin
+
+__all__ = [
+    "ExportConfigPdfInline",
+    "ExportConfigTableInline",
+    "ExportDefinitionAdmin",
+    "ImportDefinitionAdmin",
+]

django_importexport_flow-0.1.0/src/django_importexport_flow/admin/export_definition.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from django.contrib import admin
+from django.contrib import messages
+from django.core.exceptions import PermissionDenied
+from django.urls import reverse
+from django.utils.translation import gettext_lazy as _
+
+from django_boosted import AdminBoostModel, admin_boost_view
+
+from ..forms import ExportConfigurationImportForm
+from ..models import ExportConfigPdf, ExportConfigTable, ExportDefinition
+from ..utils.serialization import import_export_configuration, serialize_export_configuration
+from .generate_export import GenerateExportMixin
+from .import_config import run_json_configuration_import
+
+
+class ExportConfigPdfInline(admin.StackedInline):
+    model = ExportConfigPdf
+    extra = 0
+    classes = ("collapse",)
+    fields = ("template", "configuration")
+
+
+class ExportConfigTableInline(admin.StackedInline):
+    model = ExportConfigTable
+    extra = 0
+    classes = ("collapse",)
+    fields = ("columns", "configuration")
+
+
+@admin.register(ExportDefinition)
+class ExportDefinitionAdmin(GenerateExportMixin, AdminBoostModel):
+    list_display = ("name", "target", "manager", "uuid")
+    search_fields = ("name", "description", "uuid")
+    readonly_fields = (
+        "uuid",
+        "created_by",
+        "updated_by",
+        "created_at",
+        "updated_at",
+    )
+    inlines = (ExportConfigPdfInline, ExportConfigTableInline)
+    fieldsets = (
+        (None, {"fields": ("name", "uuid", "description")}),
+        (
+            _("Model and queryset"),
+            {"fields": ("target", "manager", "order_by")},
+        ),
+        (
+            _("Filters"),
+            {"fields": ("filter_config", "filter_request", "filter_mandatory")},
+        ),
+        (
+            _("Audit"),
+            {"fields": ("created_by", "updated_by", "created_at", "updated_at")},
+        ),
+    )
+
+    @admin_boost_view("json", _("Export configuration (JSON)"))
+    def export_configuration_json(self, request, obj):
+        return serialize_export_configuration(obj)
+
+    @admin_boost_view("adminform", _("Import configuration (JSON)"))
+    def import_configuration_json(self, request, form=None):
+        if not self.has_add_permission(request) and not self.has_change_permission(
+            request
+        ):
+            raise PermissionDenied
+        if form is None:
+            return {"form": ExportConfigurationImportForm()}
+        imported = run_json_configuration_import(
+            request,
+            form,
+            import_export_configuration,
+            log_label="import_export_configuration",
+        )
+        if imported is None:
+            return {"form": form}
+        messages.success(
+            request,
+            _("Imported export “%(name)s”.") % {"name": imported.name},
+        )
+        opts = self.model._meta
+        url = reverse(
+            f"admin:{opts.app_label}_{opts.model_name}_change",
+            args=[imported.pk],
+            current_app=self.admin_site.name,
+        )
+        return {"redirect_url": url}

django_importexport_flow-0.1.0/src/django_importexport_flow/admin/export_request.py

@@ -0,0 +1,47 @@
+"""Admin for :class:`~django_importexport_flow.models.ExportRequest` (export audit)."""
+
+from __future__ import annotations
+
+from django.contrib import admin
+from django.utils.translation import gettext_lazy as _
+
+from ..models import ExportRequest
+
+
+@admin.register(ExportRequest)
+class ExportRequestAdmin(admin.ModelAdmin):
+    list_display = (
+        "uuid",
+        "export_definition",
+        "export_format",
+        "status",
+        "output_bytes",
+        "created_at",
+        "completed_at",
+        "initiated_by",
+        "created_by",
+        "updated_by",
+        "updated_at",
+    )
+    list_filter = ("status", "export_format", "created_at")
+    search_fields = ("uuid",)
+    readonly_fields = (
+        "uuid",
+        "export_definition",
+        "export_format",
+        "filter_payload",
+        "status",
+        "output_bytes",
+        "error_trace",
+        "created_at",
+        "completed_at",
+        "initiated_by",
+        "created_by",
+        "updated_by",
+        "updated_at",
+    )
+    ordering = ("-created_at",)
+
+    def has_add_permission(self, request):
+        """Rows are created by *Generate export* only."""
+        return False

django_importexport_flow-0.1.0/src/django_importexport_flow/admin/generate_export.py

@@ -0,0 +1,133 @@
+"""Admin mixin: generate table export with filter_request (GET) + filter_config merge."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import traceback
+from typing import Any
+
+from django.contrib import messages
+from django.core.exceptions import PermissionDenied, ValidationError
+from django.http import HttpResponse
+from django.utils import timezone
+from django.utils.translation import gettext_lazy as _
+
+from django_boosted import admin_boost_view
+from django_boosted.decorators import AdminBoostViewConfig
+
+from ..utils.export import definition_has_table_config, run_table_export
+from ..forms import make_export_form_class
+from ..models import ExportRequest
+from ..utils.http import content_disposition_attachment
+
+logger = logging.getLogger(__name__)
+
+
+def safe_download_stem(
+    raw_name: str | None,
+    *,
+    fallback: str = "export",
+    max_len: int = 80,
+) -> str:
+    """Sanitize a title or name for use as a download filename stem (no extension)."""
+    base = re.sub(r"[^\w\-.]+", "_", raw_name or "").strip("_") or fallback
+    return base[:max_len]
+
+
+def _safe_export_filename(name: str) -> str:
+    return safe_download_stem(name, fallback="export")
+
+
+def _export_timestamp_for_filename() -> str:
+    """Local time, second precision, safe for filenames (e.g. ``20260329_143045``)."""
+    return timezone.localtime(timezone.now()).strftime("%Y%m%d_%H%M%S")
+
+
+def _filter_payload_snapshot(cleaned_data: dict[str, Any]) -> dict[str, Any]:
+    """JSON-safe subset: ``export_format`` and ``fr_*`` keys only."""
+    subset = {
+        k: v
+        for k, v in cleaned_data.items()
+        if k == "export_format" or k.startswith("fr_")
+    }
+    return json.loads(json.dumps(subset, default=str))
+
+
+def dated_export_filename(safe_stem: str, ext: str) -> str:
+    """
+    ``safe_stem`` = basename without extension (already sanitized).
+    ``ext`` must include the leading dot (e.g. ``.csv``).
+    """
+    return f"{safe_stem}_{_export_timestamp_for_filename()}{ext}"
+
+
+class GenerateExportMixin:
+    @admin_boost_view(
+        "adminform",
+        _("Generate export"),
+        config=AdminBoostViewConfig(permission="change"),
+    )
+    def generate_export(self, request, obj, form=None):
+        if not self.has_change_permission(request, obj):
+            raise PermissionDenied
+        FormClass = make_export_form_class(obj)
+        if form is None:
+            return {"form": FormClass()}
+        if not form.is_valid():
+            return {"form": form}
+        if not definition_has_table_config(obj):
+            messages.error(
+                request,
+                _("Add a table configuration (columns) before exporting."),
+            )
+            return {"form": form}
+        cleaned = form.cleaned_data
+        payload = _filter_payload_snapshot(cleaned)
+        export_fmt = str(cleaned.get("export_format") or "")
+        user = (
+            request.user
+            if getattr(request.user, "is_authenticated", False)
+            else None
+        )
+        try:
+            content, content_type, ext = run_table_export(obj, cleaned)
+        except (ValidationError, ValueError) as exc:
+            ExportRequest.objects.create(
+                export_definition=obj,
+                export_format=export_fmt,
+                filter_payload=payload,
+                status=ExportRequest.Status.FAILURE,
+                error_trace=str(exc),
+                completed_at=timezone.now(),
+                initiated_by=user,
+            )
+            messages.error(request, str(exc))
+            return {"form": form}
+        except Exception:
+            logger.exception("Table export failed for export definition %r", getattr(obj, "pk", None))
+            ExportRequest.objects.create(
+                export_definition=obj,
+                export_format=export_fmt,
+                filter_payload=payload,
+                status=ExportRequest.Status.FAILURE,
+                error_trace=traceback.format_exc(),
+                completed_at=timezone.now(),
+                initiated_by=user,
+            )
+            messages.error(request, _("Export failed."))
+            return {"form": form}
+        ExportRequest.objects.create(
+            export_definition=obj,
+            export_format=export_fmt,
+            filter_payload=payload,
+            status=ExportRequest.Status.SUCCESS,
+            output_bytes=len(content),
+            completed_at=timezone.now(),
+            initiated_by=user,
+        )
+        filename = dated_export_filename(_safe_export_filename(obj.name), ext)
+        response = HttpResponse(content, content_type=content_type)
+        response["Content-Disposition"] = content_disposition_attachment(filename)
+        return response

django_importexport_flow-0.1.0/src/django_importexport_flow/admin/import_config.py

@@ -0,0 +1,57 @@
+"""Shared admin logic for JSON report configuration import."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from django.contrib import messages
+from django.core.exceptions import ValidationError
+from django.core.serializers.base import DeserializationError
+from django.db import IntegrityError
+from django.http import HttpRequest
+from django.utils.translation import gettext_lazy as _
+
+logger = logging.getLogger(__name__)
+
+
+def run_json_configuration_import(
+    request: HttpRequest,
+    form: Any,
+    import_fn: Callable[[dict[str, Any]], Any],
+    *,
+    log_label: str,
+) -> Any | None:
+    """
+    Call ``import_fn(form.import_data)`` and surface errors via messages.
+
+    Returns the imported instance on success, or ``None`` on failure (the view
+    should then return ``{"form": form}``).
+    """
+    try:
+        return import_fn(form.import_data)
+    except (ValueError, ValidationError) as exc:
+        messages.error(request, str(exc))
+        return None
+    except DeserializationError as exc:
+        logger.warning("%s JSON deserialize failed: %s", log_label, exc)
+        messages.error(
+            request,
+            _("Could not read the configuration from this file."),
+        )
+        return None
+    except IntegrityError as exc:
+        logger.warning("%s import integrity error: %s", log_label, exc)
+        messages.error(
+            request,
+            _("Import failed: this configuration conflicts with existing data."),
+        )
+        return None
+    except Exception:
+        logger.exception("%s failed", log_label)
+        messages.error(
+            request,
+            _("Import failed. Check the file format and try again."),
+        )
+        return None