Tweak save_edit_row_form() of purchase batch view, to leverage handler

specifically this is to make use of handler's `update_row_quantity()` method,
when editing a row for ordering batches

docs/api/views/purchasing.batch.rst

@@ -0,0 +1,9 @@
+
+``tailbone.views.purchasing.batch``
+===================================
+
+.. automodule:: tailbone.views.purchasing.batch
+
+.. autoclass:: PurchasingBatchView
+
+   .. automethod:: save_edit_row_form

docs/conf.py

@@ -109,6 +109,9 @@ pygments_style = 'sphinx'
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+# Allow todo entries to show up.
+todo_include_todos = True
+
 
 # -- Options for HTML output ----------------------------------------------
 

docs/index.rst

@@ -52,6 +52,7 @@ Package API:
    api/views/batch.vendorcatalog
    api/views/core
    api/views/master
+   api/views/purchasing.batch
 
 
 Documentation To-Do

tailbone/views/purchasing/batch.py

@@ -2,7 +2,7 @@
 ################################################################################
 #
 #  Rattail -- Retail Software Framework
-#  Copyright © 2010-2019 Lance Edgar
+#  Copyright © 2010-2020 Lance Edgar
 #
 #  This file is part of Rattail.
 #
@@ -21,7 +21,7 @@
 #
 ################################################################################
 """
-Base views for purchasing batches
+Base class for purchasing batch views
 """
 
 from __future__ import unicode_literals, absolute_import
@@ -42,7 +42,8 @@ from tailbone.views.batch import BatchMasterView
 
 class PurchasingBatchView(BatchMasterView):
     """
-    Master view for purchase order batches.
+    Master view base class, for purchase batches.  The views for both
+    "ordering" and "receiving" batches will inherit from this.
     """
     model_class = model.PurchaseBatch
     model_row_class = model.PurchaseBatchRow
@@ -891,26 +892,56 @@ class PurchasingBatchView(BatchMasterView):
 #         self.handler.refresh_row(row)
 
     def save_edit_row_form(self, form):
+        """
+        Supplements or overrides the default logic, as follows:
+
+        *Ordering Mode*
+
+        So far, we only allow updating the ``cases_ordered`` and/or
+        ``units_ordered`` quantities; therefore the form data should have one
+        or both of those fields.
+
+        This data is then passed to the
+        :meth:`~rattail:rattail.batch.purchase.PurchaseBatchHandler.update_row_quantity()`
+        method of the batch handler.
+
+        Note that the "normal" logic for this method is not invoked at all, for
+        ordering batches.
+
+        .. note::
+           There is some logic in place for receiving mode, which sort of tries
+           to update the overall invoice total for the batch, since the form
+           data might cause those to need adjustment.  However the logic is
+           incomplete as of this writing.
+
+        .. todo::
+           Need to fully implement ``save_edit_row_form()`` for receiving batch.
+        """
         row = form.model_instance
         batch = row.batch
 
-        # first undo any totals previously in effect for the row
-        if batch.mode == self.enum.PURCHASE_BATCH_MODE_ORDERING and row.po_total_calculated:
-            batch.po_total_calculated -= row.po_total_calculated
-        elif batch.mode == self.enum.PURCHASE_BATCH_MODE_RECEIVING and row.invoice_total:
-            # TODO: pretty sure this should update the `_calculated` value instead?
-            # TODO: also, should update the value again after the super() call
-            batch.invoice_total -= row.invoice_total
+        if batch.mode == self.enum.PURCHASE_BATCH_MODE_ORDERING:
 
-        row = super(PurchasingBatchView, self).save_edit_row_form(form)
+            # let handler update data, per given order quantities
+            data = self.form_deserialized
+            self.handler.update_row_quantity(row, **data)
 
-        # TODO: is this needed?
-        # self.handler.refresh_row(row)
+        else: # *not* ordering mode
 
-        # now apply new totals based on current row quantity
-        if batch.mode == self.enum.PURCHASE_BATCH_MODE_ORDERING and row.po_unit_cost is not None:
-            row.po_total_calculated = row.po_unit_cost * self.handler.get_units_ordered(row)
-            batch.po_total_calculated = (batch.po_total_calculated or 0) + row.po_total_calculated
+            if batch.mode == self.enum.PURCHASE_BATCH_MODE_RECEIVING:
+
+                # TODO: should stop doing it this way! (use the ordering mode way instead)
+                # first undo any totals previously in effect for the row
+                if row.invoice_total:
+                    # TODO: pretty sure this should update the `_calculated` value instead?
+                    # TODO: also, should update the value again after the super() call
+                    batch.invoice_total -= row.invoice_total
+
+            # do the "normal" save logic...
+            row = super(PurchasingBatchView, self).save_edit_row_form(form)
+
+            # TODO: is this needed?
+            # self.handler.refresh_row(row)
 
         return row