Merge pull request #34 from cisagov/improvement/schema

Add schema validation for docopt arguments.

Author: felddy

.github/workflows/build.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: actions/checkout@v1
       - uses: actions/setup-python@v1
         with:
-          python-version: 3.7
+          python-version: 3.8
       - name: Cache pip test requirements
         uses: actions/cache@v1
         with:
@@ -45,7 +45,7 @@ jobs:
       - uses: actions/checkout@v1
       - uses: actions/setup-python@v1
         with:
-          python-version: 3.7
+          python-version: 3.8
       - name: Cache pip test requirements
         uses: actions/cache@v1
         with:
@@ -75,7 +75,7 @@ jobs:
       - uses: actions/checkout@v1
       - uses: actions/setup-python@v1
         with:
-          python-version: 3.7
+          python-version: 3.8
       - name: Cache pip build requirements
         uses: actions/cache@v1
         with:

.isort.cfg

@@ -7,6 +7,6 @@ import_heading_thirdparty=Third-Party Libraries
 import_heading_firstparty=cisagov Libraries
 
 # Should be auto-populated by seed-isort-config hook
-known_third_party=docopt,pkg_resources,pytest,setuptools
+known_third_party=docopt,pkg_resources,pytest,schema,setuptools
 # These must be manually set to correctly separate them from third party libraries
 known_first_party=example

setup.py

@@ -61,6 +61,7 @@ def package_vars(version_file):
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.6",
         "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
     ],
     python_requires=">=3.6",
     # What does your project relate to?
@@ -70,7 +71,7 @@ def package_vars(version_file):
     package_data={"example": ["data/*.txt"]},
     py_modules=[splitext(basename(path))[0] for path in glob("src/*.py")],
     include_package_data=True,
-    install_requires=["docopt", "setuptools >= 24.2.0"],
+    install_requires=["docopt", "setuptools >= 24.2.0", "schema"],
     extras_require={
         "test": [
             "pre-commit",

src/example/example.py

@@ -2,15 +2,23 @@
 
 """example is an example Python library and tool.
 
+Divide one integer by another and log the result. Also log some information
+from an environment variable and a package resource.
+
+EXIT STATUS
+    This utility exits with one of the following values:
+    0   Calculation completed successfully.
+    >0  An error occurred.
+
 Usage:
-  example [--log-level=LEVEL]
+  example [--log-level=LEVEL] <dividend> <divisor>
   example (-h | --help)
 
 Options:
   -h --help              Show this message.
   --log-level=LEVEL      If specified, then the log level will be set to
                          the specified value.  Valid values are "debug", "info",
-                         "warning", "error", and "critical". [default: warning]
+                         "warning", "error", and "critical". [default: info]
 """
 
 # Standard Python Libraries
@@ -21,51 +29,76 @@
 # Third-Party Libraries
 import docopt
 import pkg_resources
+from schema import And, Schema, SchemaError, Use
 
 from ._version import __version__
 
 DEFAULT_ECHO_MESSAGE = "Hello World from the example default!"
 
 
-def example_div(x, y):
+def example_div(dividend, divisor):
     """Print some logging messages."""
     logging.debug("This is a debug message")
     logging.info("This is an info message")
     logging.warning("This is a warning message")
     logging.error("This is an error message")
     logging.critical("This is a critical message")
-    return x / y
+    return dividend / divisor
 
 
 def main():
     """Set up logging and call the example function."""
     args = docopt.docopt(__doc__, version=__version__)
-    # Set up logging
-    log_level = args["--log-level"]
+    # Validate and convert arguments as needed
+    schema = Schema(
+        {
+            "--log-level": And(
+                str,
+                Use(str.lower),
+                lambda n: n in ("debug", "info", "warning", "error", "critical"),
+                error="Possible values for --log-level are "
+                + "debug, info, warning, error, and critical.",
+            ),
+            "<dividend>": Use(int, error="<dividend> must be an integer."),
+            "<divisor>": And(
+                Use(int),
+                lambda n: n != 0,
+                error="<divisor> must be an integer that is not 0.",
+            ),
+            str: object,  # Don't care about other keys, if any
+        }
+    )
+
     try:
-        logging.basicConfig(
-            format="%(asctime)-15s %(levelname)s %(message)s", level=log_level.upper()
-        )
-    except ValueError:
-        logging.critical(
-            f'"{log_level}" is not a valid logging level.  Possible values '
-            "are debug, info, warning, and error."
-        )
+        args = schema.validate(args)
+    except SchemaError as err:
+        # Exit because one or more of the arguments were invalid
+        print(err, file=sys.stderr)
         return 1
 
-    print(f"8 / 2 == {example_div(8, 2)}")
+    # Assign validated arguments to variables
+    dividend = args["<dividend>"]
+    divisor = args["<divisor>"]
+    log_level = args["--log-level"]
+
+    # Set up logging
+    logging.basicConfig(
+        format="%(asctime)-15s %(levelname)s %(message)s", level=log_level.upper()
+    )
+
+    logging.info(f"{dividend} / {divisor} == {example_div(dividend, divisor)}")
 
     # Access some data from an environment variable
     message = os.getenv("ECHO_MESSAGE", DEFAULT_ECHO_MESSAGE)
-    print(f'ECHO_MESSAGE="{message}"')
+    logging.info(f'ECHO_MESSAGE="{message}"')
 
     # Access some data from our package data (see the setup.py)
     secret_message = (
         pkg_resources.resource_string("example", "data/secret.txt")
         .decode("utf-8")
         .strip()
     )
-    print(f'Secret="{secret_message}"')
+    logging.info(f'Secret="{secret_message}"')
 
     # Stop logging and clean up
     logging.shutdown()

tests/test_example.py

@@ -18,7 +18,6 @@
     (2, 2, 1),
     (0, 1, 0),
     (8, 2, 4),
-    pytest.param(0, 0, 0, marks=pytest.mark.xfail(raises=ZeroDivisionError)),
 ]
 
 log_levels = (
@@ -27,7 +26,6 @@
     "warning",
     "error",
     "critical",
-    pytest.param("critical2", marks=pytest.mark.xfail),
 )
 
 # define sources of version strings
@@ -59,7 +57,7 @@ def test_release_version():
 @pytest.mark.parametrize("level", log_levels)
 def test_log_levels(level):
     """Validate commandline log-level arguments."""
-    with patch.object(sys, "argv", ["bogus", f"--log-level={level}"]):
+    with patch.object(sys, "argv", ["bogus", f"--log-level={level}", "1", "1"]):
         with patch.object(logging.root, "handlers", []):
             assert (
                 logging.root.hasHandlers() is False
@@ -71,6 +69,13 @@ def test_log_levels(level):
             assert return_code == 0, "main() should return success (0)"
 
 
+def test_bad_log_level():
+    """Validate bad log-level argument returns error."""
+    with patch.object(sys, "argv", ["bogus", "--log-level=emergency", "1", "1"]):
+        return_code = example.example.main()
+        assert return_code == 1, "main() should return failure"
+
+
 @pytest.mark.parametrize("dividend, divisor, quotient", div_params)
 def test_division(dividend, divisor, quotient):
     """Verify division results."""
@@ -96,3 +101,10 @@ def test_zero_division():
     """Verify that division by zero throws the correct exception."""
     with pytest.raises(ZeroDivisionError):
         example.example_div(1, 0)
+
+
+def test_zero_divisor_argument():
+    """Verify that a divisor of zero is handled as expected."""
+    with patch.object(sys, "argv", ["bogus", "1", "0"]):
+        return_code = example.example.main()
+        assert return_code == 1, "main() should exit with error"