function_helper.py

# -*- coding: utf-8 -*-
"""
@file
@brief  Various function needed when using the windows used to ask for parameters
"""
import sys
import re
import inspect
import datetime
from pyquickhelper.loghelper.flog import guess_machine_parameter


def get_function_list(module):
    """
    Extracts all functions in a module.

    @param      module      a object module
    @return                 the list of function included in a module, dictionary { name, object }
    """
    res = {}
    d = module.__dict__
    for k, v in d.items():
        if isinstance(v, get_function_list.__class__):
            res[k] = v
    return res


def has_unknown_parameters(func):
    """
    Returns True if the function contains a parameter like ``**params``.

    @param      func    function
    @return             True if the function contains something like ``**params``
    """
    # de = func.__defaults__
    # na = func.__code__.co_varnames
    keys = inspect.signature(func)
    return "**" in str(keys)


def extract_function_information(function):
    """
    Extracts information about a function.
    The function assumes all parameters receive a default value.

    @param          function        function object
    @return                         dictionary { info : value }

    The returned dictionary will be composed as follows:
        - name:     name of the function
        - nbpar:    number of parameters
        - param:    list of parameters (dictionary) and their default value
        - types:    type of parameters (dictionary), if the default value does not exist,
                    the function will look in the help looking for the following:
                    @code
                      param    name  (type)
                    @endcode
        - help:     documentation of the function
        - helpparam: help associated to each parameters (dictionary),
                     assuming they are described in the documentation using
                     the same format as this docstring
        - module:   module which defines the function
    """
    if function.__doc__ is None:
        raise RuntimeError(
            "the function given to FrameFunction should be documented: help is displayed,"
            " if you want parameter to be described, use javadoc format to do so: "
            "@<tag>  param_name  param_meaning with tag=param")

    res = dict()
    res["name"] = function.__name__
    nbp = function.__code__.co_argcount
    par = function.__code__.co_varnames[:nbp]
    res["nbpar"] = len(par)
    defd = function.__defaults__ if function.__defaults__ is not None else []
    dec = len(par) - len(defd)

    typ = {}
    p = {}
    for pos, a in enumerate(par):
        if a == 'fLOG':
            continue
        p2 = pos - dec
        if p2 >= 0:
            b = defd[p2]
            typ[a] = b.__class__
        else:
            b = ""
            typ[a] = None
        if not a.startswith("_"):
            p[a] = b

    res["types"] = typ
    res["param"] = p
    res["help"] = function.__doc__

    mod = function.__module__
    mod = sys.modules.get(mod, None)
    res["module"] = mod

    regex = re.compile("@" + "param +([a-zA-Z0-9_]+) +(.+)")
    alls = regex.findall(res["help"])
    p = {}
    for a, b in alls:
        a = a.strip()
        if a == "fLOG":
            continue
        p[a] = b.strip()
    res["helpparam"] = p

    reg = re.compile(
        "@" + "param +([a-zA-Z_][a-zA-Z_0-9]*?) +[(]([a-zA-Z]+?)[)]")
    alls = reg.findall(res["help"])
    typ = {k: v for k, v in alls}  # pylint: disable=R1721
    keys = list(res["types"])
    for a in keys:
        b = res["types"][a]
        if b is None or isinstance(None, b):
            b = typ.get(a, None)
            if b is not None:
                if "|" in b:
                    e, ee = b.split("|")
                    e = eval(e)
                    ee = eval(ee)
                    res["types"][a] = lambda v, e=e, ee=ee: ee if (
                        len(v) == 0 or v == str(ee)) else e(v)
                elif b == "datetime":
                    res["types"][a] = datetime.datetime
                else:
                    res["types"][a] = eval(b)

    # If no default value, we assume the type is str.
    keys = list(res["types"])
    for a in keys:
        b = res["types"][a]
        if b is None:
            res[b] = str

    return res


def private_adjust_parameters(param):
    """
    Change the value of some parameters when they are NULL:
    *user*. Changes the parameters inplace.

    @param      param       list of parameters
    """
    res = guess_machine_parameter()
    for k in param:
        if param[k] is None and k.lower() in ["user", "username"]:
            res[k] = res.get("USERNAME", res["USER"])


def private_get_function(function_name):
    """
    Returns the function object from its name, the name
    must contains a dot "." otherwise the function will assume
    it is defined in module @see md default_functions.

    @param      function_name   name of the function
    @return                     object
    """
    if "." in function_name:
        module = function_name.split(".")
        name = module[-1]
        fname = ".".join(module[:-1])

        if fname in sys.modules:
            mod = sys.modules[fname]
        else:
            mod = __import__(fname, globals(), locals(), [], 0)

        if name not in mod.__dict__:
            raise KeyError("module %s, function %s not in %s (path %s)" %
                           (module, name, str(mod.__dict__.keys()), mod.__file__))
        return mod.__dict__[name]
    else:
        from .default_functions import file_grep, file_list, file_split, file_head, test_regular_expression
        if function_name == "file_grep":
            return file_grep
        elif function_name == "file_list":
            return file_list
        elif function_name == "file_split":
            return file_split
        elif function_name == "file_head":
            return file_head
        elif function_name == "test_regular_expression":
            return test_regular_expression
        else:
            raise NameError("unknown exception " + function_name)