brother_ql.backends.helpers.send() returns a status dictionary

brother_ql/backends/helpers.py

@@ -33,6 +33,13 @@ def send(instructions, printer_identifier=None, backend_identifier=None, blockin
     :param bool blocking: Indicates whether the function call should block while waiting for the completion of the printing.
     """
 
+    status = {
+      'instructions_sent': True, # The instructions were sent to the printer.
+      'outcome': 'unknown', # String description of the outcome of the sending operation like: 'unknown', 'sent', 'printed', 'error'
+      'printer_state': None, # If the selected backend supports reading back the printer state, this key will contain it.
+      'did_print': False, # If True, a print was produced. It defaults to False if the outcome is uncertain (due to a backend without read-back capability).
+      'ready_for_next_job': False, # If True, the printer is ready to receive the next instructions. It defaults to False if the state is unknown.
+    }
     selected_backend = None
     if backend_identifier:
         selected_backend = backend_identifier
@@ -52,13 +59,14 @@ def send(instructions, printer_identifier=None, backend_identifier=None, blockin
     start = time.time()
     logger.info('Sending instructions to the printer. Total: %d bytes.', len(instructions))
     printer.write(instructions)
+    status['outcome'] = 'sent'
+
     if not blocking:
-        return
+        return status
     if selected_backend == 'network':
         """ No need to wait for completion. The network backend doesn't support readback. """
-        return
+        return status
-    printing_completed = False
+
-    waiting_to_receive = False
     while time.time() - start < 10:
         data = printer.read()
         if not data:
@@ -69,20 +77,27 @@ def send(instructions, printer_identifier=None, backend_identifier=None, blockin
         except ValueError:
             logger.error("TIME %.3f - Couln't understand response: %s", time.time()-start, data)
             continue
+        status['printer_state'] = result
         logger.debug('TIME %.3f - result: %s', time.time()-start, result)
         if result['errors']:
             logger.error('Errors occured: %s', result['errors'])
-        if result['status_type'] == 'Printing completed':
+            status['outcome'] = 'error'
-            printing_completed = True
-        if result['status_type'] == 'Phase change' and result['phase_type'] == 'Waiting to receive':
-            waiting_to_receive = True
-        if printing_completed and waiting_to_receive:
             break
-    if not printing_completed:
+        if result['status_type'] == 'Printing completed':
+            status['did_print'] = True
+            status['outcome'] = 'printed'
+        if result['status_type'] == 'Phase change' and result['phase_type'] == 'Waiting to receive':
+            status['ready_for_next_job'] = True
+        if status['did_print'] and status['ready_for_next_job']:
+            break
+
+    if not status['did_print']:
         logger.warning("'printing completed' status not received.")
-    if not waiting_to_receive:
+    if not status['ready_for_next_job']:
         logger.warning("'waiting to receive' status not received.")
-    if (not printing_completed) or (not waiting_to_receive):
+    if (not status['did_print']) or (not status['ready_for_next_job']):
         logger.warning('Printing potentially not successful?')
-    if printing_completed and waiting_to_receive:
+    if status['did_print'] and status['ready_for_next_job']:
         logger.info("Printing was successful. Waiting for the next job.")
+
+    return status