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!)

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