docs: def directory_script_runner(
          log,
          pathToScriptDirectory,
          databaseName,
          loginPath,
          force=True,
          waitForResult=True,
          successRule=None,
          failureRule=None):
      """A function to run all of the mysql scripts in a given directory (in a modified date order, oldest first) and then act on the script file in accordance with the succcess or failure of its execution
  
      As it's insecure to pass in mysql database credentials via the command-line, run the following command from the terminal 
  
      .. code-block:: bash
  
          mysql_config_editor set --login-path=<uniqueLoginName> --host=localhost --user=<myUsername> --password
          > Enter password:
  
      This will store your credentials in an encrypted file located at '~/.mylogin.cnf'. This function takes advantage of the `--login-path` so as not to compromise the user's credentials. Use `mysql_config_editor print --all` to see all of the login-paths set.
  
      **Key Arguments:**
          - ``log`` -- logger
          - ``pathToScriptDirectory`` -- the path to the directory containing the sql script to be run
          - ``databaseName`` -- the name of the database 
          - ``force`` -- force the script to run, skipping over lines with errors, Default *True*
          - ``loginPath`` -- the local-path as set with `mysql_config_editor`
          - ``waitForResult`` -- wait for the mysql script to finish execution? If 'False' the MySQL script will run in background (do not wait for completion), or if 'delete' the script will run then delete regardless of success status. Default *True*. [True|False|delete]
          - ``successRule`` -- what to do if script succeeds. Default *None* [None|delete|subFolderName]
          - ``failureRule`` -- what to do if script fails. Default *None* [None|delete|subFolderName]
  
      **Return:**
          - None
  
      **Usage:**
  
          To run the scripts in the directroy and not act on the script file use something similar to:
  
          .. code-block:: python 
  
              from fundamentals.mysql import directory_script_runner
              directory_script_runner(
                  log=log,
                  pathToScriptDirectory="/path/to/mysql_scripts",
                  databaseName="imports",
                  loginPath="myLoginDetails"
              )
  
          To delete successful scripts and archive failed scripts for later inspection:
  
          .. code-block:: python 
  
              from fundamentals.mysql import directory_script_runner
              directory_script_runner(
                  log=log,
                  pathToScriptDirectory="/path/to/mysql_scripts",
                  databaseName="imports",
                  loginPath="myLoginDetails",
                  successRule="delete",
                  failureRule="failed"
              )
  
          This creates a folder at `/path/to/mysql_scripts/failed` and moves the failed scripts into that folder.
  
          Finally to execute the scripts within a directory but not wait for the results to return (much fast but you lose error checking in the MySQL scripts):
  
          .. code-block:: python 
  
              from fundamentals.mysql import directory_script_runner
              directory_script_runner(
                  log=log,
                  pathToScriptDirectory="/path/to/mysql_scripts",
                  databaseName="imports",
                  loginPath="myLoginDetails",
                  waitForResults=False
              )
  
          Setting ``waitForResults`` = 'delete' will trash the script once it has run (or failed ... be very careful!)
      """
      log.debug('starting the ``directory_script_runner`` function')
  
      # COMPILE A DICTIONARY OF SCRIPTS / MODIFIED TIMES
      scriptList = {}
      for d in os.listdir(pathToScriptDirectory):
          filePath = os.path.join(pathToScriptDirectory, d)
          filename = os.path.basename(filePath)
          extension = filePath.split(".")[-1]
          if os.path.isfile(filePath) and extension == "sql":
              modified = datetime.datetime.strptime(time.ctime(
                  os.path.getmtime(filePath)), "%a %b %d %H:%M:%S %Y")
              scriptList[str(modified) + filename] = filePath
  
      # FORCE MYSQL SCRIPT?
      if force:
          force = "--force"
      else:
          force = ""
  
      # ORDER THE DICTIONARY BY MODIFIED TIME - OLDEST FIRST
      scriptList = collections.OrderedDict(sorted(scriptList.items()))
      for k, v in scriptList.iteritems():
          scriptname = os.path.basename(v)
          if waitForResult == True:
              cmd =  """mysql --login-path=%(loginPath)s %(force)s %(databaseName)s < "%(v)s" """ % locals(
              )
              p = Popen(cmd, stdout=PIPE, stderr=PIPE, close_fds=True,
                        env={'PATH': os.getenv('PATH') + ":/usr/local/bin:/usr/bin:", "MYSQL_TEST_LOGIN_FILE": os.getenv('HOME') + "/.mylogin.cnf"}, shell=True)
              stdout, stderr = p.communicate()
  
              if len(stderr):
                  log.error(
                      "MySQL Script `%(scriptname)s` Failed: '%(stderr)s'" % locals())
                  if failureRule == None or failureRule == False:
                      pass
                  elif failureRule == "delete":
                      os.remove(v)
                  elif "/" not in failureRule:
                      moveTo = pathToScriptDirectory + "/" + failureRule
                      # Recursively create missing directories
                      if not os.path.exists(moveTo):
                          os.makedirs(moveTo)
                      moveTo = moveTo + "/" + scriptname
                      try:
                          log.debug("attempting to rename file %s to %s" %
                                    (v, moveTo))
                          os.rename(v, moveTo)
                      except Exception, e:
                          log.error(
                              "could not rename file %s to %s - failed with this error: %s " % (v, moveTo, str(e),))
              else:
                  if successRule == None or successRule == False:
                      pass
                  elif successRule == "delete":
                      os.remove(v)
                  elif "/" not in successRule:
                      moveTo = pathToScriptDirectory + "/" + successRule
                      # Recursively create missing directories
                      if not os.path.exists(moveTo):
                          os.makedirs(moveTo)
                      moveTo = moveTo + "/" + scriptname
                      try:
                          log.debug("attempting to rename file %s to %s" %
                                    (v, moveTo))
                          os.rename(v, moveTo)
                      except Exception, e:
                          log.error(
                              "could not rename file %s to %s - failed with this error: %s " % (v, moveTo, str(e),))
          else:
              if waitForResult == "delete":
                  cmd =  """mysql --login-path=%(loginPath)s %(force)s  %(databaseName)s < "%(v)s" > /dev/null 2>&1 & rm "%(v)s" """ % locals()
              else:
                  cmd =  """mysql --login-path=%(loginPath)s %(force)s  %(databaseName)s < "%(v)s" > /dev/null 2>&1 """ % locals()
              p = Popen(cmd, close_fds=True,
                        env={'PATH': os.getenv('PATH') + ":/usr/local/bin:/usr/bin:", "MYSQL_TEST_LOGIN_FILE": os.getenv('HOME') + "/.mylogin.cnf"}, shell=True, stdin=None, stdout=None, stderr=None)
  
      log.debug('completed the ``directory_script_runner`` function')
      return None