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 aSPYValueError
if (a) more than one dict (orStructDict
) 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. ASPYTypeError
if cfg keyword entry is not a Python dict orStructDict
.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 abovefunc(data, cfg=cfg)
: same as above, but cfg itself is provided as keyword argumentfunc(cfg)
: cfg contains a field data or dataset (not both!) holding one or more Syncopy data objects used as input of funcfunc(cfg=cfg)
: same as above with cfg being provided as keywordfunc(data, kw1=val1, kw2=val2)
: standard Python call style with keywords being provided explicitlyfunc(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 argumentfunc(cfg, {})
: every dict in func’s positional argument list is interpreted as cfg “structure”func(data, cfg=value)
: cfg must be a Python dict orStructDict
func(data, cfg, kw1=val1)
: invalid if keyword ‘kw1’ also appears in cfg
See also
unwrap_select
extract select keyword and process in-place data-selections
process_io
set up
computeFunction()
-calls based on parallel processing setupdetect_parallel_client
controls parallel processing engine via parallel keyword
_append_docstring
local helper for manipulating docstrings
_append_signature
local helper for manipulating function signatures