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:

  1. 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.

  2. 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.

  3. 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.

  4. 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 makes up the first elements of the (remaining) positional argument list. Thus, the metafunction can now be called via func(*data, *args, **kwargs).

  5. 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(data1, data2, data3, cfg): same as above with multiple Syncopy data objects. Note: the cfg object has to be valid for all provided input objects!

  • func(data, cfg=cfg): same as above, but cfg itself is provided as keyword argument

  • func(data1, data2, cfg=cfg): same as above, but cfg itself is provided as keyword argument for multiple input objects.

  • 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(data1, data2, kw1=val1, kw2=val2): same as above with multiple input objects

Invalid call signatures:

  • func(data, cfg, cfg=cfg): cfg must not be provided as positional and keyword argument

  • func(data, cfg, kw1=val1): if cfg is provided, any non-default keyword-values must be provided as cfg entries

  • 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

See also

unwrap_select()

extract select keyword and process in-place data-selections

unwrap_io()

set up computeFunction()-calls based on parallel processing setup

detect_parallel_client()

controls parallel processing engine via parallel keyword

_append_docstring()

local helper for manipulating docstrings

_append_signature()

local helper for manipulating function signatures