syncopy.shared.kwarg_decorators.unwrap_select

syncopy.shared.kwarg_decorators.unwrap_select(func)[source]

Decorator for handling in-place data selections via select keyword

Parameters

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

Returns

wrapper_select – Wrapped function; wrapper_select extracts select from keywords provided to func and uses it to set the ._selector property of the input object(s). After successfully calling func with the modified input, wrapper_select modifies func itself:

  1. The “Parameters” section in the docstring of func is amended by an entry explaining the usage of select (that mostly points to selectdata()). Note: func’s docstring is only extended if it has a “Parameters” section.

  2. If not already present, select is added as optional keyword (with default value None) to the signature of func.

Return type

callable

Notes

This decorator assumes that func has already been processed by unwrap_cfg() and hence expects func to obey standard Python call signature func(*args, **kwargs). In other words, unwrap_select() is intended as “inner” decorator of metafunctions, for instance

@unwrap_cfg
@unwrap_select
def somefunction(data, kw1="default", kw2=None, **kwargs):
...

Important The metafunction func must accept “anonymous” keywords via a **kwargs dictionary. This requirement is due to the fact that unwrap_cfg() cowardly refuses to change the byte-code of func, that is, select is not actually added as a new keyword to func, only the corresponding signature is manipulated. Thus, if func does not support a kwargs parameter dictionary, using this decorator will have strange consequences. Specifically, select will show up in func’s signature but it won’t be actually usable:

@unwrap_cfg
@unwrap_select
def somefunction(data, kw1="default", kw2=None):
...

>>> help(somefunction)
somefunction(data, kw1="default", kw2=None, select=None)
...
>>> somefunction(data, select=None)
TypeError: somefunction() got an unexpected keyword argument 'select'

See also

unwrap_cfg()

Decorator for processing cfg “structs”

detect_parallel_client()

controls parallel processing engine via parallel keyword