def __call__(self, f):
name = f.__name__
registerPreset(combineNames(self.prefix, name), f, branch = self.branch,
apply = self.apply, ignore_context = True)
return cleanedPreset(f)
def preset(prefix=None, branch = None, apply = None):
"""
A decorator that registers a function as a preset. The function
it decorates must accept take the parameter tree it's modifying as
its sole parameter.
`preset` may be used with or without arguments. If used with
arguments, it can take any combination of three arguments.
`prefix` prepends a tag to the preset name, separated by a period.
These are added in addition to those given by the current group
context, if present. For example::
@preset(prefix = 'pr')
def box(p):
# ....
defines a preset callable as ``pr.box``.
`branch` specifies the operating branch of the preset. If given,
the parameter tree passed to the function will be this branch of
the current tree. For example::
@preset(branch = 'data')
def box(b):
# b is the data branch of the parameter tree
`apply` allows an alternative way to modify the parameter tree
before it is passed to this function. The format is the same as
that for the `apply` parameter of :ref:`group`. The typical use
case would be to apply other presets before this one -- for
example, if 'data_setup' is another preset::
@preset(apply = 'data_setup')
def box(p):
# ...
applies ``data_setup`` prior to calling `box`.
Within a ``with group(...):`` construct (see :ref:`group`), prefix
tags and branches are appended to those specified by the with
statement(s).
Example 1::
# Registers a preset with name 'box' that sets leaf
# 'dataset.style' to 'a box' in the main parameter tree.
@preset
def box(p):
p.datset.style = 'a box'
Example 2::
# Same as example 1, except that the prefix is called 'data.box'.
@preset('data', branch = 'dataset')
def box(b):
# Now `b` is the 'dataset' branch of the central parameter tree
b.style = 'a box'
Example 3 -- within a group::
# Same as example 2
with group(prefix = 'data', branch = 'dataset'):
@preset
def box(b):
b.style = 'a box'
"""
if type(prefix) is str or prefix is None:
return PresetContext(prefix, branch, apply = apply)
else:
f = cleanedPreset(prefix)
registerPreset(f.__name__, f, ignore_context = False)
return f
