karrio-server-documents 2025.5.2__py3-none-any.whl

karrio/server/documents/admin.py

@@ -0,0 +1,93 @@
+import django.forms as forms
+from django.contrib import admin
+from django.conf import settings
+from django.utils.translation import gettext_lazy as _
+from django.utils.html import format_html
+from django.urls import reverse
+
+import karrio.server.documents.models as models
+import karrio.server.documents.serializers.base as serializers
+
+
+class DocumentTemplateAdminForm(forms.ModelForm):
+    class Meta:
+        model = models.DocumentTemplate
+        fields = "__all__"
+        widgets = {
+            "template": forms.Textarea(attrs={"rows": 30, "cols": 100}),
+            "related_object": forms.Select(
+                choices=[
+                    (c.name, c.name) for c in list(serializers.TemplateRelatedObject)
+                ]
+            ),
+        }
+
+
+class DocumentTemplateAdmin(admin.ModelAdmin):
+    form = DocumentTemplateAdminForm
+    list_display = ("slug", "name", "related_object", "active", "created_at", "preview_link")
+    search_fields = ("name", "description", "slug", "related_object")
+    list_filter = ("slug", "active")
+    readonly_fields = ("created_by", "full_preview_url")
+
+    def preview_link(self, obj):
+        """Return a clickable preview link that opens in a new tab"""
+        url = obj.preview_url
+        return format_html(
+            '<a href="{}" target="_blank" rel="noopener noreferrer">Preview</a>',
+            url
+        )
+
+    preview_link.short_description = "Preview"
+
+    def full_preview_url(self, obj):
+        """Return the full absolute URL for the preview"""
+        if obj.pk:
+            request = self.request if hasattr(self, 'request') else None
+            if request:
+                relative_url = obj.preview_url
+                absolute_url = request.build_absolute_uri(relative_url)
+                return format_html(
+                    '<a href="{}" target="_blank" rel="noopener noreferrer">{}</a>',
+                    absolute_url, absolute_url
+                )
+            else:
+                # Fallback if request is not available
+                relative_url = obj.preview_url
+                return f"(Relative URL: {relative_url})"
+        return "Save the template first to generate preview URL"
+
+    full_preview_url.short_description = "Full Preview URL"
+
+    def get_queryset(self, request):
+        if settings.MULTI_ORGANIZATIONS:
+            return models.DocumentTemplate.objects.all().filter(
+                link__org__users__id=request.user.id
+            )
+
+        return super().get_queryset(request)
+
+    def save_model(self, request, obj, form, change):
+        # Store request for use in full_preview_url method
+        self.request = request
+        obj.created_by = request.user
+        super().save_model(request, obj, form, change)
+
+        if settings.MULTI_ORGANIZATIONS:
+            import karrio.server.serializers as serializers
+
+            serializers.link_org(obj, request)
+
+    def change_view(self, request, object_id, form_url='', extra_context=None):
+        # Store request for use in full_preview_url method
+        self.request = request
+        return super().change_view(request, object_id, form_url, extra_context)
+
+    def add_view(self, request, form_url='', extra_context=None):
+        # Store request for use in full_preview_url method
+        self.request = request
+        return super().add_view(request, form_url, extra_context)
+
+
+# Register your models here.
+admin.site.register(models.DocumentTemplate, DocumentTemplateAdmin)

karrio/server/documents/apps.py

@@ -0,0 +1,13 @@
+from django.apps import AppConfig
+from django.utils.translation import gettext_lazy as _
+
+
+class DocumentsConfig(AppConfig):
+    name = "karrio.server.documents"
+    verbose_name = _("Documents")
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        from karrio.server.documents import signals
+
+        signals.register_all()

karrio/server/documents/filters.py

@@ -0,0 +1,14 @@
+import karrio.server.filters as filters
+import karrio.server.documents.models as models
+
+
+class DocumentTemplateFilter(filters.FilterSet):
+    name = filters.CharFilter(field_name="name", lookup_expr="icontains")
+    related_object = filters.CharFilter(
+        field_name="related_object", lookup_expr="icontains"
+    )
+    active = filters.BooleanFilter(field_name="active")
+
+    class Meta:
+        model = models.DocumentTemplate
+        fields: list = []

karrio/server/documents/generator.py

@@ -0,0 +1,298 @@
+import io
+import typing
+import base64
+import jinja2
+import weasyprint
+from django.db.models import Sum
+import weasyprint.text.fonts as fonts
+
+import karrio.lib as lib
+import karrio.server.documents.utils as utils
+import karrio.server.core.dataunits as dataunits
+import karrio.server.orders.models as order_models
+import karrio.server.manager.models as manager_models
+import karrio.server.documents.models as document_models
+import karrio.server.orders.serializers as orders_serializers
+import karrio.server.manager.serializers as manager_serializers
+
+FONT_CONFIG = fonts.FontConfiguration()
+PAGE_SEPARATOR = '<p style="page-break-before: always"></p>'
+STYLESHEETS = [
+    weasyprint.CSS(url="https://cdn.jsdelivr.net/npm/bulma@0.9.3/css/bulma.min.css"),
+    weasyprint.CSS(
+        string="""
+        @page { margin: 1cm }
+        @font-face {
+            font-family: 'system';
+            src: local('Arial');
+        }
+        body { font-family: 'system', sans-serif; }
+    """
+    ),
+]
+UNITS = {
+    "PAGE_SEPARATOR": PAGE_SEPARATOR,
+    "CountryISO": lib.units.CountryISO.as_dict(),
+    **dataunits.REFERENCE_MODELS,
+}
+
+
+class TemplateRenderingError(Exception):
+    """Custom exception for template rendering errors"""
+
+    def __init__(self, message, line_number=None, template_error=None):
+        self.message = message
+        self.line_number = line_number
+        self.template_error = template_error
+        super().__init__(self.message)
+
+
+class Documents:
+    @staticmethod
+    def generate(
+        template: str,
+        data: dict = {},
+        related_object: str = None,
+        **kwargs,
+    ) -> io.BytesIO:
+        options = kwargs.get("options") or {}
+        metadata = kwargs.get("metadata") or {}
+
+        # Build contexts based on related_object and provided data
+        shipment_contexts = data.get("shipments_context") or lib.identity(
+            get_shipments_context(data["shipments"])
+            if "shipments" in data and related_object == "shipment"
+            else []
+        )
+        order_contexts = data.get("orders_context") or lib.identity(
+            get_orders_context(data["orders"])
+            if "orders" in data and related_object == "order"
+            else []
+        )
+
+        # For generic contexts, include the full data structure
+        generic_contexts = data.get("generic_context") or lib.identity(
+            [{"data": data}] if related_object is None else []
+        )
+
+        # If no specific contexts are provided but we have a related_object, create a context with the data
+        if not shipment_contexts and not order_contexts and not generic_contexts:
+            # For fallback cases, always wrap data to maintain legacy behavior
+            generic_contexts = [{"data": data}]
+
+        filename = lib.identity(
+            dict(filename=kwargs.get("doc_name")) if kwargs.get("doc_name") else {}
+        )
+
+        def safe_render_prefetch(ctx):
+            """Safely render prefetch templates with error handling"""
+            result = {}
+            for key, value in options.get("prefetch", {}).items():
+                try:
+                    template_obj = jinja2.Template(value)
+                    rendered = template_obj.render(
+                        **ctx,
+                        metadata=metadata,
+                        units=UNITS,
+                        utils=utils,
+                        lib=lib,
+                    )
+                    result[key] = str(rendered or "")
+                except jinja2.TemplateError as e:
+                    # Log the error but continue with empty string
+                    result[key] = ""
+            return result
+
+        try:
+            jinja_template = jinja2.Template(template)
+        except jinja2.TemplateSyntaxError as e:
+            raise TemplateRenderingError(
+                f"Template syntax error: {e.message}",
+                line_number=e.lineno,
+                template_error=e,
+            )
+
+        all_contexts = shipment_contexts + order_contexts + generic_contexts
+
+        # If no contexts are available, create a default one
+        if not all_contexts:
+            all_contexts = [{"data": data} if data else {}]
+
+        rendered_pages = []
+        for ctx in all_contexts:
+            try:
+                # Add prefetch data safely
+                ctx_with_prefetch = {**ctx, "prefetch": safe_render_prefetch(ctx)}
+
+                rendered_page = jinja_template.render(
+                    **ctx_with_prefetch,
+                    metadata=metadata,
+                    units=UNITS,
+                    utils=utils,
+                    lib=lib,
+                )
+                rendered_pages.append(rendered_page)
+            except jinja2.UndefinedError as e:
+                raise TemplateRenderingError(
+                    f"Template variable error: {str(e)}. Available variables: {list(ctx.keys())}",
+                    template_error=e,
+                )
+            except jinja2.TemplateRuntimeError as e:
+                raise TemplateRenderingError(
+                    f"Template runtime error: {str(e)}",
+                    line_number=getattr(e, "lineno", None),
+                    template_error=e,
+                )
+            except jinja2.TemplateError as e:
+                raise TemplateRenderingError(
+                    f"Template error: {str(e)}",
+                    line_number=getattr(e, "lineno", None),
+                    template_error=e,
+                )
+            except Exception as e:
+                raise TemplateRenderingError(
+                    f"Unexpected error during template rendering: {str(e)}",
+                    template_error=e,
+                )
+
+        content = PAGE_SEPARATOR.join(rendered_pages)
+
+        # Handle PDF generation errors
+        try:
+            buffer = io.BytesIO()
+            html = weasyprint.HTML(string=content, encoding="utf-8")
+            html.write_pdf(
+                buffer,
+                stylesheets=STYLESHEETS,
+                font_config=FONT_CONFIG,
+                optimize_size=("fonts", "images"),
+            )
+            return buffer
+        except Exception as e:
+            raise TemplateRenderingError(
+                f"PDF generation error: {str(e)}", template_error=e
+            )
+
+    @staticmethod
+    def generate_template(
+        document: document_models.DocumentTemplate,
+        data: dict,
+        **kwargs,
+    ) -> io.BytesIO:
+        return Documents.generate(
+            template=document.template,
+            data=data,
+            options=document.options,
+            metadata=document.metadata,
+            related_object=document.related_object,
+            **kwargs,
+        )
+
+    @staticmethod
+    def generate_shipment_document(slug: str, shipment, **kwargs) -> dict:
+        template = document_models.DocumentTemplate.objects.get(slug=slug)
+        carrier = kwargs.get("carrier") or getattr(
+            shipment, "selected_rate_carrier", None
+        )
+        params = dict(
+            shipments_context=[
+                dict(
+                    shipment=manager_serializers.Shipment(shipment).data,
+                    line_items=get_shipment_item_contexts(shipment),
+                    carrier=get_carrier_context(carrier),
+                    orders=orders_serializers.Order(
+                        get_shipment_order_contexts(shipment),
+                        many=True,
+                    ).data,
+                )
+            ]
+        )
+        document = Documents.generate_template(template, params).getvalue()
+
+        return dict(
+            doc_format="PDF",
+            doc_name=f"{template.name}.pdf",
+            doc_type=(template.metadata or {}).get("doc_type") or "commercial_invoice",
+            doc_file=base64.b64encode(document).decode("utf-8"),
+        )
+
+
+# -----------------------------------------------------------
+# contexts data parsers
+# -----------------------------------------------------------
+# region
+
+
+def get_shipments_context(shipment_ids: str) -> typing.List[dict]:
+    if shipment_ids == "sample":
+        return [utils.SHIPMENT_SAMPLE]
+
+    ids = shipment_ids.split(",")
+    shipments = manager_models.Shipment.objects.filter(id__in=ids)
+
+    return [
+        dict(
+            shipment=manager_serializers.Shipment(shipment).data,
+            line_items=get_shipment_item_contexts(shipment),
+            carrier=get_carrier_context(shipment.selected_rate_carrier),
+            orders=orders_serializers.Order(
+                get_shipment_order_contexts(shipment), many=True
+            ).data,
+        )
+        for shipment in shipments
+    ]
+
+
+def get_shipment_item_contexts(shipment):
+    items = order_models.LineItem.objects.filter(
+        commodity_parcel__parcel_shipment=shipment
+    )
+    distinct_items = [
+        __ for _, __ in ({item.parent_id: item for item in items}).items()
+    ]
+
+    return [
+        {
+            **orders_serializers.LineItem(item.parent or item).data,
+            "ship_quantity": items.filter(parent_id=item.parent_id).aggregate(
+                Sum("quantity")
+            )["quantity__sum"],
+            "order": (orders_serializers.Order(item.order).data if item.order else {}),
+        }
+        for item in distinct_items
+    ]
+
+
+def get_shipment_order_contexts(shipment):
+    return (
+        order_models.Order.objects.filter(
+            line_items__children__commodity_parcel__parcel_shipment=shipment
+        )
+        .order_by("-order_date")
+        .distinct()
+    )
+
+
+def get_carrier_context(carrier=None):
+    if carrier is None:
+        return {}
+
+    return carrier.data.to_dict()
+
+
+def get_orders_context(order_ids: str) -> typing.List[dict]:
+    if order_ids == "sample":
+        return [utils.ORDER_SAMPLE]
+
+    ids = order_ids.split(",")
+    orders = order_models.Order.objects.filter(id__in=ids)
+
+    return [
+        dict(
+            order=orders_serializers.Order(order).data,
+        )
+        for order in orders
+    ]
+
+
+# endregion

karrio/server/documents/migrations/0001_initial.py

@@ -0,0 +1,69 @@
+# Generated by Django 3.2.11 on 2022-03-14 14:49
+
+from django.conf import settings
+import django.contrib.postgres.fields
+import django.core.validators
+from django.db import migrations, models
+import django.db.models.deletion
+import functools
+import karrio.server.core.models.base
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="DocumentTemplate",
+            fields=[
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "id",
+                    models.CharField(
+                        default=functools.partial(
+                            karrio.server.core.models.base.uuid,
+                            *(),
+                            **{"prefix": "doc_"}
+                        ),
+                        editable=False,
+                        max_length=50,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                (
+                    "slug",
+                    models.SlugField(
+                        max_length=20,
+                        validators=[
+                            django.core.validators.RegexValidator("^[a-z0-9_]+$")
+                        ],
+                    ),
+                ),
+                ("name", models.CharField(max_length=50)),
+                ("template", models.TextField()),
+                ("description", models.CharField(blank=True, max_length=50, null=True)),
+                ("related_objects", models.JSONField(blank=True, null=True)),
+                (
+                    "created_by",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Document Template",
+                "verbose_name_plural": "Document Templates",
+                "db_table": "document-template",
+                "ordering": ["-created_at"],
+            },
+            bases=(karrio.server.core.models.base.ControlledAccessModel, models.Model),
+        ),
+    ]

karrio/server/documents/migrations/0002_alter_documenttemplate_related_objects.py

@@ -0,0 +1,18 @@
+# Generated by Django 3.2.12 on 2022-03-21 20:47
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('documents', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='documenttemplate',
+            name='related_objects',
+            field=models.CharField(max_length=25),
+        ),
+    ]

karrio/server/documents/migrations/0003_rename_related_objects_documenttemplate_related_object.py

@@ -0,0 +1,18 @@
+# Generated by Django 3.2.12 on 2022-03-21 20:47
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('documents', '0002_alter_documenttemplate_related_objects'),
+    ]
+
+    operations = [
+        migrations.RenameField(
+            model_name='documenttemplate',
+            old_name='related_objects',
+            new_name='related_object',
+        ),
+    ]

karrio/server/documents/migrations/0004_documenttemplate_active.py

@@ -0,0 +1,18 @@
+# Generated by Django 3.2.13 on 2022-06-18 09:09
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('documents', '0003_rename_related_objects_documenttemplate_related_object'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='documenttemplate',
+            name='active',
+            field=models.BooleanField(default=True, help_text='disable template flag. to filter out from active document downloads'),
+        ),
+    ]

karrio/server/documents/migrations/0005_alter_documenttemplate_description_and_more.py

@@ -0,0 +1,23 @@
+# Generated by Django 4.1.3 on 2022-12-10 17:09
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("documents", "0004_documenttemplate_active"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="documenttemplate",
+            name="description",
+            field=models.CharField(blank=True, db_index=True, max_length=50, null=True),
+        ),
+        migrations.AlterField(
+            model_name="documenttemplate",
+            name="name",
+            field=models.CharField(db_index=True, max_length=50),
+        ),
+    ]

karrio/server/documents/migrations/0006_documenttemplate_metadata.py

@@ -0,0 +1,25 @@
+# Generated by Django 4.1.7 on 2023-02-22 15:35
+
+from django.db import migrations, models
+import functools
+import karrio.server.core.models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("documents", "0005_alter_documenttemplate_description_and_more"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="documenttemplate",
+            name="metadata",
+            field=models.JSONField(
+                blank=True,
+                default=functools.partial(
+                    karrio.server.core.models._identity, *(), **{"value": {}}
+                ),
+                null=True,
+            ),
+        ),
+    ]

karrio/server/documents/migrations/0007_alter_documenttemplate_related_object.py

@@ -0,0 +1,18 @@
+# Generated by Django 4.2.11 on 2024-05-27 17:53
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("documents", "0006_documenttemplate_metadata"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="documenttemplate",
+            name="related_object",
+            field=models.CharField(blank=True, max_length=25, null=True),
+        ),
+    ]

karrio/server/documents/migrations/0008_documenttemplate_options.py

@@ -0,0 +1,26 @@
+# Generated by Django 4.2.16 on 2024-10-17 04:48
+
+from django.db import migrations, models
+import functools
+import karrio.server.core.models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("documents", "0007_alter_documenttemplate_related_object"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="documenttemplate",
+            name="options",
+            field=models.JSONField(
+                blank=True,
+                default=functools.partial(
+                    karrio.server.core.models._identity, *(), **{"value": {}}
+                ),
+                null=True,
+            ),
+        ),
+    ]