Add locate_product_for_entry() method for purchase batch handler

this logic needs to be customized for a client, so breaking it out from the
tailbone view code

rattail/batch/purchase.py

@@ -32,6 +32,7 @@ import six
 from sqlalchemy import orm
 
 from rattail.db import model, api
+from rattail.gpc import GPC
 from rattail.batch import BatchHandler
 from rattail.time import make_utc
 from rattail.vendors.invoices import require_invoice_parser
@@ -489,6 +490,54 @@ class PurchaseBatchHandler(BatchHandler):
         else:
             batch.status_code = batch.STATUS_OK
 
+    def locate_product_for_entry(self, session, entry, lookup_by_code=True):
+        """
+        Try to locate the product represented by the given "entry" - which is
+        assumed to be a "raw" string, e.g. as obtained from scanner or other
+        user input, or from a vendor-supplied spreadsheet etc.  (In other words
+        this method is not told "what" sort of entry it is being given.)
+
+        :param lookup_by_code: If set to ``False``, then the method will
+           attempt a lookup *only* on the product key field (either ``upc`` or
+           ``item_id`` depending on config).  If set to ``True`` (the default)
+           then the method will also attempt a lookup in the ``ProductCode``
+           table, aka. alternate codes.
+        """
+        # try to locate product by uuid before other, more specific key
+        product = session.query(model.Product).get(entry)
+        if product:
+            return product
+
+        product_key = self.config.product_key()
+        if product_key == 'upc':
+
+            # we first assume the user entry *does* include check digit
+            provided = GPC(entry, calc_check_digit=False)
+            product = api.get_product_by_upc(session, provided)
+            if product:
+                return product
+
+            # but we can also calculate a check digit and try that
+            checked = GPC(entry, calc_check_digit='upc')
+            product = api.get_product_by_upc(session, checked)
+            if product:
+                return product
+
+        elif product_key == 'item_id':
+
+            # try to locate product by item_id
+            product = api.get_product_by_item_id(session, entry)
+            if product:
+                return product
+
+        # if we made it this far, lookup by product key failed.
+
+        # okay then, let's maybe attempt lookup by "alternate" code
+        if lookup_by_code:
+            product = api.get_product_by_code(session, entry)
+            if product:
+                return product
+
     def locate_product(self, row):
         """
         Try to locate the product represented by the given row.  Default