Typed report context (#9431)

* add typed report context

* make it py3.9 compatible

* fix docs

* debug docs

* fix for py 3.9

* add requested error codes

src/backend/InvenTree/order/models.py

@@ -1,6 +1,7 @@
 """Order model definitions."""
 
 from decimal import Decimal
+from typing import Any, Optional
 
 from django.contrib.auth.models import User
 from django.core.exceptions import ValidationError
@@ -177,6 +178,92 @@ class TotalPriceMixin(models.Model):
         return total
 
 
+class BaseOrderReportContext(report.mixins.BaseReportContext):
+    """Base context for all order models.
+
+    Attributes:
+        description: The description field of the order
+        extra_lines: Query set of all extra lines associated with the order
+        lines: Query set of all line items associated with the order
+        order: The order instance itself
+        reference: The reference field of the order
+        title: The title (string representation) of the order
+    """
+
+    description: str
+    extra_lines: Any
+    lines: Any
+    order: Any
+    reference: str
+    title: str
+
+
+class PurchaseOrderReportContext(report.mixins.BaseReportContext):
+    """Context for the purchase order model.
+
+    Attributes:
+        description: The description field of the PurchaseOrder
+        reference: The reference field of the PurchaseOrder
+        title: The title (string representation) of the PurchaseOrder
+        extra_lines: Query set of all extra lines associated with the PurchaseOrder
+        lines: Query set of all line items associated with the PurchaseOrder
+        order: The PurchaseOrder instance itself
+        supplier: The supplier object associated with the PurchaseOrder
+    """
+
+    description: str
+    reference: str
+    title: str
+    extra_lines: report.mixins.QuerySet['PurchaseOrderExtraLine']
+    lines: report.mixins.QuerySet['PurchaseOrderLineItem']
+    order: 'PurchaseOrder'
+    supplier: Optional[Company]
+
+
+class SalesOrderReportContext(report.mixins.BaseReportContext):
+    """Context for the sales order model.
+
+    Attributes:
+        description: The description field of the SalesOrder
+        reference: The reference field of the SalesOrder
+        title: The title (string representation) of the SalesOrder
+        extra_lines: Query set of all extra lines associated with the SalesOrder
+        lines: Query set of all line items associated with the SalesOrder
+        order: The SalesOrder instance itself
+        customer: The customer object associated with the SalesOrder
+    """
+
+    description: str
+    reference: str
+    title: str
+    extra_lines: report.mixins.QuerySet['SalesOrderExtraLine']
+    lines: report.mixins.QuerySet['SalesOrderLineItem']
+    order: 'SalesOrder'
+    customer: Optional[Company]
+
+
+class ReturnOrderReportContext(report.mixins.BaseReportContext):
+    """Context for the return order model.
+
+    Attributes:
+        description: The description field of the ReturnOrder
+        reference: The reference field of the ReturnOrder
+        title: The title (string representation) of the ReturnOrder
+        extra_lines: Query set of all extra lines associated with the ReturnOrder
+        lines: Query set of all line items associated with the ReturnOrder
+        order: The ReturnOrder instance itself
+        customer: The customer object associated with the ReturnOrder
+    """
+
+    description: str
+    reference: str
+    title: str
+    extra_lines: report.mixins.QuerySet['ReturnOrderExtraLine']
+    lines: report.mixins.QuerySet['ReturnOrderLineItem']
+    order: 'ReturnOrder'
+    customer: Optional[Company]
+
+
 class Order(
     StatusCodeMixin,
     StateTransitionMixin,
@@ -300,7 +387,7 @@ class Order(
         line.target_date = None
         line.order = self
 
-    def report_context(self):
+    def report_context(self) -> BaseOrderReportContext:
         """Generate context data for the reporting interface."""
         return {
             'description': self.description,
@@ -456,7 +543,7 @@ class PurchaseOrder(TotalPriceMixin, Order):
         super().clean_line_item(line)
         line.received = 0
 
-    def report_context(self):
+    def report_context(self) -> PurchaseOrderReportContext:
         """Return report context data for this PurchaseOrder."""
         return {**super().report_context(), 'supplier': self.supplier}
 
@@ -979,7 +1066,7 @@ class SalesOrder(TotalPriceMixin, Order):
         super().clean_line_item(line)
         line.shipped = 0
 
-    def report_context(self):
+    def report_context(self) -> SalesOrderReportContext:
         """Generate report context data for this SalesOrder."""
         return {**super().report_context(), 'customer': self.customer}
 
@@ -1802,6 +1889,26 @@ class SalesOrderLineItem(OrderLineItem):
         return self.shipped >= self.quantity
 
 
+class SalesOrderShipmentReportContext(report.mixins.BaseReportContext):
+    """Context for the SalesOrderShipment model.
+
+    Attributes:
+        allocations: QuerySet of SalesOrderAllocation objects
+        order: The associated SalesOrder object
+        reference: Shipment reference string
+        shipment: The SalesOrderShipment object itself
+        tracking_number: Shipment tracking number string
+        title: Title for the report
+    """
+
+    allocations: report.mixins.QuerySet['SalesOrderAllocation']
+    order: 'SalesOrder'
+    reference: str
+    shipment: 'SalesOrderShipment'
+    tracking_number: str
+    title: str
+
+
 class SalesOrderShipment(
     InvenTree.models.InvenTreeAttachmentMixin,
     InvenTree.models.InvenTreeNotesMixin,
@@ -1835,7 +1942,7 @@ class SalesOrderShipment(
         """Return the API URL associated with the SalesOrderShipment model."""
         return reverse('api-so-shipment-list')
 
-    def report_context(self):
+    def report_context(self) -> SalesOrderShipmentReportContext:
         """Generate context data for the reporting interface."""
         return {
             'allocations': self.allocations,
@@ -2198,7 +2305,7 @@ class ReturnOrder(TotalPriceMixin, Order):
         line.received_date = None
         line.outcome = ReturnOrderLineStatus.PENDING.value
 
-    def report_context(self):
+    def report_context(self) -> ReturnOrderReportContext:
         """Generate report context data for this ReturnOrder."""
         return {**super().report_context(), 'customer': self.customer}