Reference

def alertbox(text: str, title: str = "") -> None:
    """
    alertbox - caller stub for singleton GUIwrapperClass object method

    Args:
        text (str): prompt text
        title (str): title for popup. Defaults to empty string.
    """
    GUIwrapper.alertbox(text, title)

def clean_for_eval(expression: str) -> str:
    """
    clean_for_eval - clean regular expression after substitution

    delete leading zeros from integer constants to overcome eval() error

    Arguments:
        expression (str): regular expression to be cleaned

    Returns:
        str: cleaned regular expression
    """

    operator_char = [" ", "<", "=", ">", "+", "-", "*", "/", "%", "("]

    find_start = 0
    for char in operator_char:
        pos = expression.find(f"{char}0")
        while pos >= 0:
            if expression[pos + 2:pos + 3] in "0123456789":
                expression = expression[0:pos + 1] + expression[pos + 2:]
                find_start = pos
            else:
                find_start = pos + 1
            pos = expression.find(f"{char}0", find_start)

    return expression

def close_app_file(filename: str, msg: str, title: str) -> None:
    """
    close_app_file - close data file opened by an application

    Args:
        filename (str): filename
        msg (str): message for alert box
        title (str): title for alert box
    """

    close_app_windowtitle(filename)
    if file_locked(filename):
        close_app_windowtitle(os.path.splitext(os.path.basename(filename))[0])
    while file_locked(filename):
        alertbox(msg, title)

def confirmYesNo(text: str, title: str = "", buttons: list = ['Yes', 'No']) -> str:
    """
    confirmYesNo - caller stub for singleton GUIwrapperClass object method

    Args:
        text (str): prompt text
        title (str): title for popup. Defaults to empty string.
        buttons (list): label for buttons. Defaults to ['Yes', 'No'].

    Returns:
        str: label of pressed button
    """
    return GUIwrapper.confirmYesNo(text, title, buttons)

def confirm_yes_no(text: str, title: str = "", buttons: list = ['Yes', 'No']) -> str:
    """
    confirm_yes_no - caller stub for singleton GUIwrapperClass object method

    Args:
        text (str): prompt text
        title (str): title for popup. Defaults to empty string.
        buttons (list): label for buttons. Defaults to ['Yes', 'No'].

    Returns:
        str: label of pressed button
    """
    return confirmYesNo(text, title, buttons)

def convertRegExVB2Python(reVB: str) -> str:
    """
    convertRegExVB2Python - convert Microsoft VB / COM regular expression to Python regular expression

    Problem: syntax for regular expressions in the Microsoft VB / COM standard is different from Python.

    Differences in the area of the standard syntax:

    - for group replacements notation is \\n instead $n

    Differences if regular expressions are used together with Eval():

    - different numerical value for True: VB environment = -1, Python = 1
      -> boolean expressions need to be adjusted
    - string concatenation is '&' in VB and '+' in Python
      assumption: '+' is not used for source expressions even allowed
    - '+' may not be applied on int/str in Python
      -> numerical expressions must be bracketed in str()
    - language functions are to be replaced. Implemented:
      "Format" for numerical values

    Arguments:
        reVB (str): regular expression according to VB / COM standard for Microsoft RegEx engine

    Returns:
        str: converted regular expression for Python RegEx engine
    """

    def split_terms(regex: str, quotemark, delim: str = "&+") -> list[str]:

        terms: list[str] = []
        regex_idx: int = 0
        term_start: int = 0
        quotemark_cnt: int = 0
        bracket_cnt: int = 0

        regex += " "
        while regex_idx < len(regex):
            if regex[regex_idx] == quotemark:
                quotemark_cnt += 1
            elif regex[regex_idx] in "(){}[]":
                bracket_cnt += 1
            elif (
                (regex[regex_idx] in delim or regex_idx >= len(regex) - 1) and
                quotemark_cnt % 2 == 0 and
                bracket_cnt % 2 == 0
            ):
                term = regex[term_start:regex_idx].strip()
                if (term[-1] in quotemark) or (terms[-1][-1] in quotemark) or (term.lower().find("format(") >= 0):
                    terms.append(term)
                else:
                    terms[-1] = terms[-1] + "+" + term
                term_start = regex_idx + 1
            regex_idx += 1

        return terms

    def convert_other(term: str, embedstr: bool = True) -> str:

        compare_operator = [">", "<", "="]
        foundbool = False

        term_idx = 0
        while term_idx < len(term):
            if term[term_idx] in compare_operator:
                if term[term_idx:term_idx + 1] == "<>":
                    term = term[:term_idx] + "!=" + term[term_idx + 2:]
                if term[term_idx:term_idx + 1] == "=":
                    term = term[:term_idx] + "==" + term[term_idx + 1:]
                    term_idx += 1
                while term[term_idx] != ")" and term_idx < len(term):
                    term_idx += 1
                if term[term_idx] == ")":
                    term = term[0:term_idx] + ")*-1" + term[term_idx + 1:]
                    term_idx += 3
                    foundbool = True
                elif term_idx == len(term):
                    term = "(" + term + ")*-1"
                    foundbool = True
            term_idx += 1

        if foundbool:
            term = term.replace("*-1*1", "*-1").replace("*-1*-1", "*1")

        if embedstr:
            return "str(" + term + ")"
        else:
            return term

    def convert_term(term: str, quotemark) -> str:

        if term[0] == quotemark:
            return term
        elif term.lower()[0:len("format(")] == "format(":
            # only simple integer formatting accepted
            params = term[len("format") + 1:len(term) - 1].split(",")
            params[0] = convert_other(params[0], False)
            return f"\"{{:0{params[1].count('0')}d}}\".format({params[0]})"
        else:
            return convert_other(term)

    # check quotation mark -> RegEx for use with Eval()
    if reVB[0] == "'":
        quotemark = "'"
    elif reVB[0] == "\"":
        quotemark = "\""
    else:
        quotemark = ""

    if quotemark != "":
        # top-level split of  regular expression into string terms
        terms = split_terms(reVB, quotemark)
        rePy = ""
        for term in terms:
            rePy = convert_term(term, quotemark) if rePy == "" else rePy + " + " + convert_term(term, quotemark)
    else:
        rePy = reVB

    # replace groups
    for grp_idx in range(9, 0, -1):
        rePy = rePy.replace(f"${grp_idx}", rf"\{grp_idx}")

    return rePy

def convert_regexVB2python(reVB: str) -> str:
    """
    convert_regexVB2python - convert Microsoft VB / COM regular expression to Python regular expression

    Alternative caller for convertRegExVB2Python. See details there.

    Arguments:
        reVB (str): regular expression according to VB / COM standard for Microsoft RegEx engine

    Returns:
        str: converted regular expression for Python RegEx engine
    """

    return convertRegExVB2Python(reVB)

def convert_regexVB_2_python(reVB: str) -> str:
    """
    convert_regexVB_2_python - convert Microsoft VB / COM regular expression to Python regular expression

    Alternative caller for convertRegExVB2Python. See details there.

    Arguments:
        reVB (str): regular expression according to VB / COM standard for Microsoft RegEx engine

    Returns:
        str: converted regular expression for Python RegEx engine
    """

    return convertRegExVB2Python(reVB)

def copy_dictfields(source: dict, target: Any) -> None:
    """
    copy_dict_fields - copy fields from dict to target structure

    can be used to copy same named fields to a data class from TypedArgParser via <TypedArgParser object>.as_dict() or
    one dataclass to another via <dataclass>.asdict()

    Args:
        source (dict): source dictionary
        target (Any): target dictionary
    """
    copy_dictfields(source, target)

def copydictfields(source: dict, target: Any) -> None:
    """
    copydictfields - copy fields from dict to target structure

    can be used to copy same named fields to a data class from TypedArgParser via <TypedArgParser object>.as_dict() or
    one dataclass to another via <dataclass>.asdict()

    Args:
        source (dict): source dictionary
        target (Any): target dictionary
    """

    for key, value in source.items():
        if hasattr(target, key):
            target.key = value
        elif isinstance(target, dict):
            if key in target:
                target[key] = value

def exitFinished(title: str = "") -> None:
    """
    exitFinished - dummy finished message box.

    Args:
        title (str): title for message box. Defaults to empty string.
    """
    msg: str = "Fertig."

    GUIwrapper.alertbox(msg, title)

def exit_finished(title: str = "") -> None:
    """
    exit_finished - dummy finished message box.

    Args:
        title (str): title for message box. Defaults to empty string.
    """
    exitFinished(title)

def file_locked(filepath: str, waittime: float = 0.1) -> bool:
    """
    file_locked - check if file is locked

    Args:
        filepath (str): file to be checked
        waittime (float, optional): waiting time for check, defaults to 0.1.

    Returns:
        bool: lock indicator
    """

    if not (os.path.exists(filepath)):
        return False
    try:
        f = open(filepath, 'r')
        f.close()
    except OSError:
        return True

    lockfile = filepath + ".lckchk"
    if os.path.exists(lockfile):
        os.remove(lockfile)
    try:
        os.rename(filepath, lockfile)
        time.sleep(waittime)
        os.rename(lockfile, filepath)
        return False
    except OSError:
        return True

def find_last_changed_file(
    searchpath: str,
    searchpattern: str,
    searchstart: Optional[datetime.datetime] = None,
    timeout_sec: int = 10
) -> str:
    """
    find_last_changed_file - find latest changed file in searchpath matching filename pattern provided as searchpattern

    Args:
        searchpath (str): path to search in
        searchpattern (str): file pattern
        searchstart (datetime.datetime, optional): search for files changed after 'searchstart' only. Defaults to None.
        timeout_sec (int, optional): timeout period. Defaults to 10.

    Returns:
        str: name of file found (if any)
    """

    timenow = datetime.datetime.now(dateutil.tz.tz.tzlocal())
    if searchstart is None:
        searchstart = timenow - datetime.timedelta(seconds=5)
    if searchstart.tzinfo is None:
        searchstart = pytz.utc.localize(searchstart)
    lastchangedfile = ""
    # lastchangedtimestamp = searchstart - datetime.timedelta(seconds=1)
    lastchangedtimestamp = searchstart.timestamp() - 1

    while (lastchangedfile == "") and (datetime.datetime.now(dateutil.tz.tz.tzlocal()) <= timenow + datetime.timedelta(seconds=timeout_sec)):

        with os.scandir(searchpath) as searchpathscan:
            scanentry: os.DirEntry    # overcome PyCharm IDE error - workaround derived from https://youtrack.jetbrains.com/issue/PY-46041
            for scanentry in searchpathscan:
                if fnmatch.fnmatch(scanentry.name, searchpattern):
                    filemodified = scanentry.stat().st_mtime_ns / 1000000000
                    if filemodified >= searchstart.timestamp():
                        pathfilename = os.path.join(searchpath, scanentry.name)
                        while os.path.isfile(pathfilename) and is_file_locked(pathfilename):
                            time.sleep(0.5)
                        if os.path.isfile(pathfilename) and not is_file_locked(pathfilename):
                            if filemodified > lastchangedtimestamp and scanentry.stat().st_size > 0:
                                lastchangedfile = scanentry.name
                                lastchangedtimestamp = filemodified
        searchpathscan.close()

    return lastchangedfile

def get_real_apppath() -> tuple[str, str]:
    """
    get_real_apppath - find true application directory for frozen/bundled execution

    Returns:
        str: application path
    """

    if getattr(sys, 'frozen', False):
        application_path = os.path.dirname(sys.executable)
        running_mode = 'Frozen/executable'
    else:
        try:
            app_full_path = os.path.realpath(__file__)
            application_path = os.path.dirname(app_full_path)
            running_mode = "Non-interactive (e.g. 'python myapp.py')"
        except NameError:
            application_path = os.getcwd()
            running_mode = 'Interactive'

    return application_path, running_mode

def ignore_exceptions(func: Callable[..., Any]) -> Callable[..., Any]:
    """
    ignore_exceptions - decorator for ignoring exceptions using parameter in decorated function

    Args:
        func (Callable): function to be decorated

    Returns:
        Callable: wrapped function
    """

    @wraps(func)
    def wrapper(*args, **kwargs):
        result = None
        ignored_exceptions = kwargs.get('ignored_exceptions')
        # if ignored_exceptions:
        if isinstance(ignored_exceptions, tuple) and all(issubclass(e, BaseException) for e in ignored_exceptions):
            try:
                result = func(*args, **kwargs)
            except ignored_exceptions:
                pass
        else:
            result = func(*args, **kwargs)
        return result

    return wrapper

def ignore_exceptions_parameterized(ignored_exceptions: tuple[type[BaseException]]) -> Callable[[Callable[_P, _R]], Callable[_P, Optional[_R]]]:  # type: ignore
    """
    ignore_exceptions_parameterized - parameterized decorator for ignoring exceptions using closure

    Args:
        ignored_exceptions (tuple[BaseException]): exceptions to be ignored

    Returns:
        Callable: wrapped function
    """
    def ignore_exceptions_helper(func):

        @wraps(func)
        def wrapper(*args, **kwargs):
            result = None
            if ignored_exceptions:
                try:
                    result = func(*args, **kwargs)
                except ignored_exceptions:
                    pass
            else:
                result = func(*args, **kwargs)
            return result

        return wrapper

    return ignore_exceptions_helper

def initLogger(
    loggername: str,
    formatstr: str = "%(asctime)s\t%(levelname)s\t%(message)s",
    datefmtstr: str = "%d.%m.%Y %H:%M:%S",
    filename: str = ""
) -> logging.Logger:
    """
    initLogger - initialize standard logger object

    Args:
        loggername (str): name of logger
        formatstr (str, optional): format string for log entries. Defaults to "%(asctime)s\t%(levelname)s\t%(message)s".
        datefmtstr (str, optional): date format for log entries. Defaults to "%d.%m.%Y %H:%M:%S".
        filename (str, optional): name of log file. Defaults to "".

    Returns:
        logging.Logger: logger object
    """

    global loggers

    if loggers.get(loggername):
        logger = loggers.get(loggername)
    else:
        logger = logging.getLogger(loggername)
        logformatter = logging.Formatter(formatstr, datefmt=datefmtstr)
        if filename == "":
            loghandler = logging.FileHandler(os.path.join(tempfile.gettempdir(), loggername + "_Py.txt"))
        else:
            loghandler = logging.FileHandler(filename)
        loghandler.setFormatter(logformatter)
        loghandler.setLevel(logging.INFO)
        logger.addHandler(loghandler)
        logger.setLevel(logging.INFO)
        loggers[loggername] = logger

    assert logger is not None
    return logger

def init_logger(
    loggername: str,
    formatstr: str = "%(asctime)s\t%(levelname)s\t%(message)s",
    datefmtstr: str = "%d.%m.%Y %H:%M:%S",
    filename: str = ""
) -> logging.Logger:
    """
    init_logger - initialize standard logger object

    Args:
        loggername (str): name of logger
        formatstr (str, optional): format string for log entries. Defaults to "%(asctime)s\t%(levelname)s\t%(message)s".
        datefmtstr (str, optional): date format for log entries. Defaults to "%d.%m.%Y %H:%M:%S".
        filename (str, optional): name of log file. Defaults to "".

    Returns:
        logging.Logger: logger object
    """
    return initLogger(loggername, formatstr, datefmtstr, filename)

def inputbox(text: str, title: str = "", default: str = "") -> Any:
    """
    inputbox - caller stub for singleton GUIwrapperClass object method

    Args:
        text (str): prompt text
        title (str): title for popup. Defaults to empty string.
        default (str): default value. Defaults to empty string.

    Returns:
        Any: entered value
    """
    return GUIwrapper.inputbox(text, title, default)

def is_date(checkvalue: Any, checkformat="%d.%m.%Y") -> bool:
    """
    is_date - check if checkvalue is a date value

    Args:
        checkvalue (Any): value to be checked
        checkformat (str, optional): dateformat for check of checkvalue of type str. Defaults to "%d.%m.%Y".

    Returns:
        bool: checkvalue is date or not
    """
    return isdate(checkvalue, checkformat)

def is_file_locked(filepath: str, waittime: float = 0.1) -> bool:
    """
    is_file_locked - check if file is locked

    Args:
        filepath (str): file to be checked
        waittime (float, optional): waiting time for check. Defaults to 0.1.

    Returns:
        bool: lock indicator
    """
    return file_locked(filepath, waittime)

def isdate(checkvalue: Any, checkformat="%d.%m.%Y") -> bool:
    """
    isdate - check if checkvalue is a date value

    Args:
        checkvalue (Any): value to be checked
        checkformat (str, optional): dateformat for check of checkvalue of type str. Defaults to "%d.%m.%Y".

    Returns:
        bool: checkvalue is date or not
    """

    if checkvalue is None or checkvalue == "":
        return False
    # elif type(checkvalue).__name__ == "datetime" or type(checkvalue).__name__ == "date":
    elif isinstance(checkvalue, (datetime.datetime, datetime.date)):
        return True
    elif isinstance(checkvalue, str):
        try:
            check = bool(datetime.datetime.strptime(checkvalue, checkformat))
        except ValueError:
            check = False
        return check
    else:
        return False

def listbox(
    text: str,
    title: str = "",
    choices: list[str] = [],
    multiselect: bool = False
) -> Union[str, list[str]]:
    """
    listbox - caller stub for singleton GUIwrapperClass object method

    Args:
        text (str): prompt text
        title (str): title for popup. Defaults to empty string.
        choices (List[str]): Choices for listbox. Defaults to [].
        multiselect (bool): Flag for multi-select mode. Defaults to False.

    Returns:
        Union[str, List[str]]: selected option(s)
    """
    return GUIwrapper.listbox(text, title, choices, multiselect)

def load_textfile(txt_filename: str, mode: str = "str") -> Union[list[str], str]:
    """
    load_textfile - load textfile to list of strings or str

    Args:
        txt_filename (str): source text file
        mode (str, optional): return mode - 'list', 'str' or 'strcleaned'. Defaults to 'str'.

    Returns:
        Union[list[str], str]: content of textfile as list of string or string
    """

    txt: Union[list[str], str] = ""

    fileexists = os.path.isfile(txt_filename)

    # read to list of lines
    if mode == "list":
        if fileexists:
            # via pathlib
            # txt = pathlib.Path(txt_filename).read_text()
            # via normal open file
            with open(txt_filename, "r") as txt_file:
                txt = txt_file.readlines()
            txt_file.close()
        else:
            txt = []
    # read to single string incl. CR
    elif mode == "str":
        if fileexists:
            with open(txt_filename, "r") as txt_file:
                txt = txt_file.read()
            txt_file.close()
        else:
            txt = ""
    # read to single string without CR
    elif mode == "strcleaned":
        if fileexists:
            with open(txt_filename, "r") as txt_file:
                txt = txt_file.read().replace("\n", "")
            txt_file.close()
        else:
            txt = ""
    else:
        err_msg = "Invalid mode."
        raise Exception(err_msg)

    return txt

def logCLIargs() -> None:
    """
    logCLIargs - write command line interface parameters to specific CLI call log
    """

    if sys.argv[0] != "-c":
        loggerCLI.info(f"Name Python script: {sys.argv[0]}")
    else:
        stack = inspect.stack()
        loggerCLI.info(
            f"Name Python script: {stack[len(inspect.stack()) - 2].filename} (retrieved from call stack because call using switch -c)"
        )
    argcount = len(sys.argv)
    if argcount > 1:
        for i in range(1, argcount):
            loggerCLI.info(f"Arg {i}: {sys.argv[i]}")
        loggerCLI.info(f"Number of args passed: {argcount - 1}")
    else:
        loggerCLI.info("No args passed.")
    # loggerCLI.info("\n")
    loggerCLI.newline()

def logCLIparams(params) -> None:
    """
    logCLIparams - write parsed parameters to specific call log

    Args:
        params (_type_): params
    """

    loggerCLI.info("Parsed arguments (from command line or via parameter injected into parse_args):")
    for param in vars(params):  # params is NamespaceObject of type TapType and not iterable
        if param in params.class_variables or param in params.argument_buffer:
            loggerCLI.info(f"{param}: {getattr(params, param)}")
    # loggerCLI.info("\n")
    loggerCLI.newline()

def log_cli_args() -> None:
    """
    log_cli_args - write command line interface parameters to specific CLI call log
    """
    logCLIargs()

def log_cli_params(params) -> None:
    """
    log_cli_params - write parsed parameters to specific call log

    Args:
        params (_type_): params
    """
    logCLIparams(params)

def read_configfile(
    configfile: str,
    optionxform: Optional[Callable[[str], str]] = None,
    encoding: str = "utf-8"
) -> configparser.ConfigParser:
    """
    read_configfile - read config file with standardized boolean states into ConfigParser object

    Args:
        configfile (str): config file
        optionxform (callable[[str], str]], optional): callable to pass on to ConfigParser.optionxform. Defaults to None.
        encoding (str, optional): file encoding. Defaults to "utf-8".

    Raises:
        Exception: file 'configfile' does not exist.

    Returns:
        configparser.ConfigParser: config parser object
    """
    return readconfigfile(configfile, optionxform, encoding)