syncopy.shared.kwarg_decorators.unwrap_cfg#

syncopy.shared.kwarg_decorators.unwrap_cfg(func)[source]#

Decorator that unwraps cfg “structure” in metafunction call

Parameters:

func (callable) – Typically a Syncopy metafunction such as freqanalysis()

Returns:

wrapper_cfg – Wrapped function; wrapper_cfg extracts keyword arguments from a possibly provided cfg option “structure” based on the following logic:

Probe positional argument list of func for regular Python dict or StructDict. Every hit is assumed to be a cfg option “structure” and removed from the list. Raises a SPYValueError if (a) more than one dict (or StructDict) is found in provided positional arguments (b) keywords are provided in addition to cfg (c) cfg is provided as positional as well as keyword argument.
If no cfg is found in positional arguments, check func’s keyword arguments for a provided cfg entry. Raises a SPYValueError if cfg was provided as positional argument as well as keyword. A SPYTypeError if cfg keyword entry is not a Python dict or StructDict.
If cfg was found either in positional or keyword arguments, then (a) process its “linguistic” boolean keys (convert any “yes”/”no” entries to True /False) and then (b) extract any existing “data”/”dataset” entry/entries. Raises a SPYValueError if cfg contains both a “data” and “dataset” entry.
Perform the actual unwrapping: at this point, a provided cfg only contains keyword arguments of func. If the (first) input object data was provided as cfg entry, it already exists in the local namespace. If not, then by convention, data is the first element of the (remaining) positional argument list. Thus, the metafunction can now be called via func(data, *args, **kwargs).
Amend the docstring of func: add a one-liner mentioning the possibility of using cfg when calling func to the header of its docstring. Append a paragraph to the docstrings’ “Notes” section illustrating how to call func with a cfg option “structure” that specifically uses func and its input parameters. Note: both amendments are only inserted in func’s docstring if the respective sections already exist.

Return type:

callable

Notes

This decorator is primarily intended as bookkeeper for Syncopy metafunctions. It permits “FieldTrip-style” calls of Syncopy metafunctions by “Pythonizing” (processing and subsequent unpacking) of dict-like cfg objects. This standardization allows all other Syncopy decorators (refer to See also section) to safely use standard Python *args and **kwargs input arguments.

Supported call signatures:

func(cfg, data): cfg exclusively contains keyword arguments of func, data is a Syncopy data object.
func(data, cfg): same as above
func(data, cfg=cfg): same as above, but cfg itself is provided as keyword argument
func(cfg): cfg contains a field data or dataset (not both!) holding one or more Syncopy data objects used as input of func
func(cfg=cfg): same as above with cfg being provided as keyword
func(data, kw1=val1, kw2=val2): standard Python call style with keywords being provided explicitly
func(data, cfg, kw2=val2): valid if cfg does NOT contain ‘kw2’

Invalid call signatures:

func(data, cfg, cfg=cfg): cfg must not be provided as positional and keyword argument
func(cfg, {}): every dict in func’s positional argument list is interpreted as cfg “structure”
func(data, cfg=value): cfg must be a Python dict or StructDict
func(data, cfg, kw1=val1): invalid if keyword ‘kw1’ also appears in cfg

syncopy.shared.kwarg_decorators.unwrap_cfg

Contents

syncopy.shared.kwarg_decorators.unwrap_cfg#