Merge pull request #31 from MichaelCurrin/status-enhancements

Status enhancements

README.md

@@ -104,7 +104,7 @@ Given a configured script `hello.sh` in the targets directory.
     $ ./unicron.py --verbose
     2020-01-06 12:22:00 INFO:unicron hello.sh - Success.
     ```
-4. Scheduling - add a command to the _crontab_ file.
+4. Scheduling - add a command to the _crontab_ file. Here run every 30 minutes and only send mail if at least one job fails (since verbose flag is omitted).
     ```bash
     $ crontab -e
     ```
@@ -113,7 +113,6 @@ Given a configured script `hello.sh` in the targets directory.
     PATH=/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin
     MAILTO=my-user
 
-    # Run every 30 minutes and only send mail on failure.
     */30 *    *    *    *    cd ~/repos/uni-cron/unicron && ./unicron.py
     ```
 
@@ -219,16 +218,27 @@ The example output below is for the script which was setup using [Installation](
     ```bash
     $ make run
     unicron/unicron.py -v
+    2020-01-13 22:49:12,770 INFO:unicron.py unicron - Task count: 1
     2020-01-13 22:49:12,770 DEBUG:unicron.py hello.sh - Executing, since no run record found.
     2020-01-13 22:49:12,781 INFO:unicron.py hello.sh - Success.
+    2020-01-13 22:49:12,781 INFO:unicron.py unicron - Suceeded: 1; Failed: 0; Skipped: 0
     ```
 - Second run.
     ```bash
     $ make run
     unicron/unicron.py -v
+    2020-01-13 22:49:30,438 INFO:unicron.py unicron - Task count: 1
     2020-01-13 22:49:30,438 INFO:unicron.py hello.sh - Skipping, since already ran today.
+    2020-01-13 22:49:30,438 INFO:unicron.py unicron - Suceeded: 0; Failed: 0; Skipped: 1
     ```
 
+Once Unicron has attempted all tasks, if any task failed then Unicron will exit with an error status. This can be useful for control flow when using cron and `mail`. If running through `make`, the error will appear as follows:
+
+```
+...
+make: *** [run] Error 1
+```
+
 ### View logs
 
 Run this command to tail the app and task logs. Sample output is for the run commands above.
@@ -243,9 +253,13 @@ $ make log
 
 
 ==> app.log <==
+2020-01-13 22:49:12,770 INFO:unicron.py unicron - Task count: 1
 2020-01-13 22:49:12,770 DEBUG:unicron.py hello.sh - Executing, since no run record found.
 2020-01-13 22:49:12,781 INFO:unicron.py hello.sh - Success.
+2020-01-13 22:49:12,781 INFO:unicron.py unicron - Suceeded: 1; Failed: 0; Skipped: 0
+2020-01-13 22:49:30,438 INFO:unicron.py unicron - Task count: 1
 2020-01-13 22:49:30,438 INFO:unicron.py hello.sh - Skipping, since already ran today.
+2020-01-13 22:49:30,438 INFO:unicron.py unicron - Suceeded: 0; Failed: 0; Skipped: 1
 ```
 
 

unicron/unicron.py

@@ -31,6 +31,7 @@
 import logging
 import subprocess
 import os
+import sys
 import textwrap
 from pathlib import Path
 
@@ -99,7 +100,7 @@ def run_in_shell(cmd):
     the CalledProcessError and then that message is shown. During development
     of this project, the OSError was experienced so this is covered below too.
 
-    :return success: True if not error, False otherwise.
+    :return success: True if ran without error, False otherwise.
     :return output: Text result of the command. If there was an error, this
         will be the error message.
     """
@@ -209,7 +210,7 @@ def execute(task_name):
     a log file dedicated to that task. This makes it easy to view the
     executable's history later.
 
-    :return: None
+    :return status: True if ran without error, False otherwise.
     """
     last_run_path = mk_last_run_path(task_name)
 
@@ -254,6 +255,8 @@ def get_tasks():
 def handle_tasks():
     """
     Find tasks, check their run status for today and run any if needed.
+
+    :return: tuple of results.
     """
     success = fail = skipped = 0
 
@@ -274,16 +277,17 @@ def handle_tasks():
         else:
             skipped += 1
 
-    results = dict(success=success, fail=fail, skipped=skipped)
-    msg = f"Results: {results}"
+    msg = f"Succeeded: {success}; Failed: {fail}; Skipped: {skipped}"
     app_logger.info(msg, extra=extra)
 
+    return success, fail, skipped
+
 
 def main():
     """
     Main command-line argument parser.
 
-    :return: None
+    :return: None. Exit script on error code if there are any failures.
     """
     global VERBOSE  # pylint: disable=global-statement
 
@@ -302,7 +306,10 @@ def main():
     if args.verbose:
         VERBOSE = True
 
-    handle_tasks()
+    _, fail, _ = handle_tasks()
+
+    if fail != 0:
+        sys.exit(1)
 
 
 if __name__ == "__main__":