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

rattail/db/batch/handler.py

@@ -88,10 +88,10 @@ class BatchHandler(object):
         cancel = False
         for i, row in enumerate(data, 1):
             row.sequence = i
-            self.cognize_row(session, row)
-            batch.data_rows.append(row)
-            if i % 250 == 0:    # seems to help progres UI
-                session.flush()
+            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()
             if prog and not prog.update(i):
                 cancel = True
                 break
@@ -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):