get_function_params

privex.helpers.common.get_function_params(obj: Union[type, callable], check_parents=False, **kwargs) → Union[Dict[str, inspect.Parameter], privex.helpers.collections.DictObject, Dict[type, Dict[str, inspect.Parameter]]]

Extracts a function/method’s signature (or class constructor signature if a class is passed), and returns it as a dictionary.

Primarily used by construct_dict() - but may be useful for other purposes.

If you’ve passed a class, you can set check_parents to True to obtain the signatures of the passed class’s constructor AND all of it’s parent classes, returned as a dictionary mapping classes to dictionaries of parameters.

If you’ve set check_parents to True, but you want the parameters to be a flat dictionary (just like when passing a function or class without check_parents), you can also pass merge=True, which merges each class’s constructor parameters into a dictionary mapping names to inspect.Parameter objects.

If any parameters conflict, children’s constructor parameters always take precedence over their parent’s version, much in the same way that Python’s inheritance works.

Basic (with functions):

>>> def some_func(x, y, z=123, *args, **kwargs):
...    pass

Get all normal parameters (positional and kwargs - excluding catch-all *args / **kwargs parameter types):

>>> params = get_function_params(some_func)
>>> params
{'x': <Parameter "x">, 'y': <Parameter "y">, 'z': <Parameter "z=123">}

Get raw parameter name and value (as written in signature) / access default values:

>>> str(params.z.name)     # You can also access it via params['z']
'z=123'
>>> params.z.default  # You can also access it via params['z']
123

Get only required parameters:

>>> get_function_params(some_func, ignore_defaults=True)
{'x': <Parameter "x">, 'y': <Parameter "y">}

Get only parameters with defaults:

>>> get_function_params(some_func, ignore_positional=True)
{'z': <Parameter "z=123">}

Example Usage (with classes and sub-classes):

>>> class BaseClass:
...     def __init__(self, a, b, c=1234, **kwargs):
...         pass

>>> class Example(BaseClass):
...     def __init__(self, d, e='hello', f=None, a='overridden', **kwargs):
...         super().__init__(a=a, d=d, e=e, f=f, **kwargs)

If we pass the class Example on it’s own, we get a dictionary of just it’s own parameters:

>>> get_function_params(Example)
{'d': <Parameter "d">, 'e': <Parameter "e='hello'">, 'f': <Parameter "f=None">}

However, if we set check_parents=True, we now get a dictionary containing Example’s constructor parameters, AND BaseClass’s (it’s parent class) constructor parameters, organised by class:

>>> get_function_params(Example, True)
{
    <class '__main__.Example'>: {
        'd': <Parameter "d">, 'e': <Parameter "e='hello'">, 'f': <Parameter "f=None">,
        'a': <Parameter "a='overridden'">
    },
    <class '__main__.BaseClass'>: {'a': <Parameter "a">, 'b': <Parameter "b">, 'c': <Parameter "c=1234">}
}

We can also add the optional kwarg merge=True, which merges the parameters of the originally passed class, and it’s parents.

This is done in reverse order, so that children’s conflicting constructor parameters take priority over their parents, as can be seen below with a which is shown as a='overridden' - the overridden parameter of the class Example with a default value, instead of the parent’s a which makes a mandatory:

>>> get_function_params(Example, True, merge=True)
{
    'a': <Parameter "a='overridden'">, 'b': <Parameter "b">, 'c': <Parameter "c=1234">,
    'd': <Parameter "d">, 'e': <Parameter "e='hello'">, 'f': <Parameter "f=None">
}

Parameters

• obj (type|callable) – A class (not an instance) or callable (function / lambda) to extract and filter the parameter’s from. If a class is passed, the parameters of the constructor will be returned (__init__), excluding the initial self parameter.

• check_parents (bool) – (Default: False) If obj is a class and this is True, will recursively grab the constructor parameters for all parent classes, and return the parameters as a dictionary of {<class X>: {'a': <Parameter 'a'>}, <class Y>: {'b': <Parameter 'b'>}, unless merge is also set to True.

Key bool ignore_xargs

(Default: True) Filter out any catch-all positional arguments (e.g. *args)

Key bool ignore_xkwargs

(Default: True) Filter out any catch-all keyword arguments (e.g. **kwargs)

Key bool ignore_defaults

(Default: False) Filter out any parameter which has a default value (e.g. args usable as kwargs)

Key bool ignore_positional

(Default: False) Filter out any parameter which doesn’t have a default value (mandatory args)

Key bool merge

(Default: False) If this is True, when check_parents is enabled, all parameters will be flatted into a singular dictionary, e.g. {'a': <Parameter 'a'>, 'b': <Parameter "b">}

Returns