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:

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

syncopy.shared.kwarg_decorators.unwrap_select

Contents

syncopy.shared.kwarg_decorators.unwrap_select#