In batch handlers, let cognize_row() return False to skip the row.

rattail/db/batch/handler.py

@@ -88,7 +88,7 @@ class BatchHandler(object):
         cancel = False
         for i, row in enumerate(data, 1):
             row.sequence = i
-            self.cognize_row(session, row)
+            if self.cognize_row(session, row) is not False:
                 batch.data_rows.append(row)
                 if i % 250 == 0:    # seems to help progres UI
                     session.flush()
@@ -101,6 +101,19 @@ class BatchHandler(object):
         return not cancel
 
     def cognize_row(self, session, row):
+        """
+        This method should further populate the row's fields, using database
+        lookups and business rules etc. as needed.  Each handler class must
+        define this method.
+
+        :param session: SQLAlchemy database session object.
+
+        :param row: A batch row instance, whose fields reflect the initial
+           source data only, e.g. that which was parsed from a file.
+
+        :returns: Typically this method needn't return anything.  However if it
+           returns ``False`` then the row will *not* be added to the batch.
+        """
         raise NotImplementedError
 
     def executable(self, batch):