Merge pull request #18 from timothyhull:timothyhull/issue17

timothyhull/best-practice-refactor-1

Author: timothyhull

namedtuple_maker/namedtuple_logger.py

@@ -9,7 +9,8 @@
         https://logbook.readthedocs.io/en/stable/
 
     Usage:
-        # Step 1, import the initialize_logging function into your application:
+        # Step 1, import the initialize_logging function into your
+        # application:
             from namedtuple_logger import initialize_logging()
             initialize_logging()
 
@@ -23,10 +24,15 @@
             app_log.info('Application logging started.')
 '''
 
-# Imports
+# Imports - Python Standard Library
+from os import path
+from sys import stdout
+
+# Imports - Third-Party
 import logbook
-from os import _exit, path
-from sys import exit, stderr, stdout
+
+# Imports - Local
+from namedtuple_maker.namedtuple_utils import graceful_exit
 
 # Constants
 LOG_FILE_PATH = path.curdir
@@ -46,27 +52,6 @@
 )
 
 
-def graceful_exit() -> None:
-    ''' Gracefully exit after a caught exception.
-
-        Args:
-            None.
-
-        Returns:
-            None.
-    '''
-    # Graceful exit with status code
-    try:
-
-        # Standard sys.exit
-        exit(1)
-
-    except SystemExit:
-
-        # Exit from an interactive REPL shell with os._exit
-        _exit(1)
-
-
 def initialize_logging(
     log_level: str = None,
     log_file: str = LOG_FILE,
@@ -111,8 +96,9 @@ def initialize_logging(
                 error_message += (f'{index + 1}. {level}\n')
 
             # Display the error message and gracefully exit
-            print(error_message, file=stderr)
-            graceful_exit()
+            graceful_exit(
+                error_message=error_message
+            )
 
         else:
             # Set logging level
@@ -153,9 +139,10 @@ def initialize_logging(
             )
 
         # Display error and gracefully exit
-        except FileNotFoundError as e:
-            print(f'\n{e!r}\n', file=stderr)
-            graceful_exit()
+        except FileNotFoundError as error:
+            graceful_exit(
+                error_object=error,
+            )
 
     else:
 
@@ -174,3 +161,5 @@ def initialize_logging(
     log_init_log.info(
         f'Started {logbook.get_level_name(log_level)} level logging.'
     )
+
+    return None

namedtuple_maker/namedtuple_maker.py

@@ -31,24 +31,28 @@ def your_function() -> Iterable:
 
     Logging Target:
         The application automatically creates a log file in the current
-        working directory, and writes log message to that file. To write log
-        messages to the console (STDOUT), set the LOG_TO_CONSOLE environment
-        variable to 'True'.
+        working directory, and writes log message to that file. To
+        write log messages to the console (STDOUT), set the
+        LOG_TO_CONSOLE environment variable to 'True'.
 
         Example logging target usage:
             export LOG_TO_CONSOLE=True
 '''
 
-# Imports
+# Imports - Python Standard Library
 from collections import namedtuple
 from typing import Callable, Iterable, List, NamedTuple
 from functools import wraps
-from namedtuple_maker.namedtuple_logger import initialize_logging
 from re import compile, VERBOSE
-from os import _exit, getenv
-from sys import exit, stderr
+from os import getenv
+
+# Imports - Third-Party
 import logbook
 
+# Imports - Local
+from namedtuple_maker.namedtuple_logger import initialize_logging
+from namedtuple_maker.namedtuple_utils import graceful_exit
+
 # Check for LOG_LEVEL environment variable
 log_level = getenv('LOG_LEVEL')
 
@@ -260,16 +264,17 @@ def convert_to_namedtuple(*args, **kwargs) -> namedtuple:
 
                     attribute_names (Iterable[str]):
                         Optional kwarg, any iterable object class
-                        including, list, tuple, dict_keys, dict_values, etc.
-                        with str values.
+                        including, list, tuple, dict_keys, dict_values,
+                        etc. with str values.
 
                     auto_attribute_names (bool):
                         Optional kwarg, automatically name attributes
-                        without user input or use of the attribute_names
-                        parameter. Default: False
+                        without user input or use of the
+                        attribute_names parameter. Default: False
 
             Returns: named_tuple (namedtuple):
-                Class NamedTuple instantiated from collections.namedtuple
+                Class NamedTuple instantiated from
+                collections.namedtuple
         '''
 
         # Log entry
@@ -587,8 +592,8 @@ def make_named_tuple(
                 Any iterable object to convert to a namedtuple.
 
             attribute_names (Iterable[str]):
-                Any iterable object of strings to supply field names for
-                a namedtuple.
+                Any iterable object of strings to supply field names
+                for a namedtuple.
 
             auto_attribute_names (bool):
                     Optional kwarg, automatically name attributes
@@ -640,7 +645,7 @@ def make_named_tuple(
             f'\t{iterable_input}'
         )
 
-    except TypeError as e:
+    except TypeError as error:
 
         # Set error message value
         error_message = (
@@ -655,22 +660,13 @@ def make_named_tuple(
             f'\t"iterable_input" value: {iterable_input}'
             f'\t"iterable_input" type: {type(iterable_input)}'
         )
-        application_log.exception(e)
-
-        # Write error message to STDERR
-        print(f'\n{error_message}')
-        print(f'{e!r}\n', file=stderr)
+        application_log.exception(error)
 
-        # Graceful exit with status code
-        try:
-
-            # Standard sys.exit
-            exit(1)
-
-        except SystemExit:
-
-            # Exit from an interactive REPL shell with os._exit
-            _exit(1)
+        # Display the error message and gracefully exit
+        graceful_exit(
+            error_message=error_message,
+            error_object=error
+        )
 
     # Log Entry
     # Log return of make_named_tuple function to named_tuple_converter
@@ -696,8 +692,9 @@ def run_make_named_tuple() -> NamedTuple:
 
         Returns:
             named_tuple (NamedTuple):
-                NamedTuple class object resulting from the make_named_tuple
-                function decorated by the named_tuple_converter function.
+                NamedTuple class object resulting from the
+                make_named_tuple function decorated by the
+                named_tuple_converter function.
     '''
 
     # Log Entry

namedtuple_maker/namedtuple_utils.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+''' Utility module with functions for the namedtuple-maker application.
+
+    Usage:
+        See individual function docstrings for usage instructions.
+'''
+
+# Imports - Python Standard Library
+from os import _exit
+from sys import exit, stderr
+from typing import AnyStr
+
+
+def graceful_exit(
+    error_message: AnyStr = None,
+    error_object: Exception = None
+):
+    ''' Gracefully exit a program after catching an exception.  Call the
+    graceful_exit function from within a higher-level except block.
+    Instead of using the raise keyword to display a stack trace and
+    exit, graceful_exit will display a friendly message, and exit the
+    program without displaying full trace stack details.
+
+    The graceful_exit function first attempts to use the sys.exit
+    function to exit the application.  If sys.exit raises a
+    SystemExit exception, usually as the result of running a program
+    within an interactive shell (IDLE, iPython, etc.), graceful_exit
+    will use the os._exit function.
+
+    Args:
+        error_message (AnyStr, optional):
+            String error message to display.
+
+        error_object (Exception):
+            Exception object from the source except block.  Write
+            the output to STDERR.
+
+    Usage:
+        # Step 1, import the graceful_exit() function into your
+        # application.
+            from graceful_exit import graceful exit.
+
+        # Step 2, define a try/except block to test your code for
+        # exceptions.
+            try:
+                my_function()
+            except NameError:
+                # TBD
+
+        # Step 3, call the graceful_exit function within the except
+        # block
+            try:
+                my_function()
+            except NameError as error:
+                graceful_exit(
+                    error_message='An error occurred',
+                    error_object=error
+                )
+
+        Returns:
+            N/A.
+    '''
+
+    # Display the optional error message
+    if error_message is not None:
+        print(f'\n{error_message}')
+
+    # Write the error_object to STDERR, use the shorthand for repr(error)
+    if error_object is not None:
+        print(f'{error_object!r}\n', file=stderr)
+
+    # Graceful exit with status code
+    try:
+
+        # Standard sys.exit
+        exit(1)
+
+    except SystemExit:
+
+        # Exit from an interactive REPL shell with os._exit
+        _exit(1)

tests/test_namedtuple_logger.py

@@ -13,11 +13,13 @@
 
 '''
 
-# Imports
-from namedtuple_maker.namedtuple_logger import initialize_logging
+# Imports - Third-Party
 from logbook import Logger
 # from pytest import raises
 
+# Imports - Local
+from namedtuple_maker.namedtuple_logger import initialize_logging
+
 # Constants
 LOG_FILE_INVALID = './bad_log_test_dir/log_file.log'
 LOG_INFO_MESSAGE = 'This is a log entry.'
@@ -27,9 +29,9 @@
 
 
 def test_initialize_logging_to_console(capfd) -> None:
-    ''' Test initialize_logging function for console output.  Writes mock
-        log messages to the console and verifies the log messages display
-        correctly.
+    ''' Test initialize_logging function for console output.  Writes
+        mock log messages to the console and verifies the log messages
+        display correctly.
 
         Args:
             capfd (pytest fixture):
@@ -56,6 +58,8 @@ def test_initialize_logging_to_console(capfd) -> None:
     log_output = capfd.readouterr().out
     assert LOG_INFO_MESSAGE in log_output
 
+    return None
+
 
 # def test_initialize_logging_invalid_log_file() -> None:
 #     ''' Test initialize logging function's ability to handle an invalid
@@ -72,3 +76,4 @@ def test_initialize_logging_to_console(capfd) -> None:
 #         initialize_logging(
 #             log_file=LOG_FILE_INVALID
 #         )
+#     return None