def presetTree(name, branch = None, description = None):
"""
Returns a TreeDict instance registered as a preset with the name
`name`. This TreeDict instance (modified after being returned
from this function) will be applied as an update to the central
paramter tree when preset `name` is requested. If branch is not
None, it is applied to that branch. `description`, if given, adds
a description to the preset, displayed when presets are listed.
Example 1::
p = presetTree('box', 'dataset')
p.preset = 'box'
p.dimensions = (3,3,2)
In the above example, when preset `box` is applied, it changes
``p.dataset.datatype`` to ``'box'`` and ``p.dataset.dimensions``
to ``(3,3,2)`` (where ``p`` represents the central parameter
tree).
"""
checkNameValidity(name)
checkNameValidity(branch)
pt = TreeDict("preset")
registerPreset(name, pt, branch, description, ignore_context = False)
return pt
def __init__(self, prefix = None, branch = None, description = None, apply = None):
global _preset_context_stack
if prefix is not None:
prefix = prefix.lower()
if branch is not None:
branch = branch.lower()
checkNameValidity(prefix)
checkNameValidity(branch)
if _preset_context_stack:
context = _preset_context_stack[-1]
self.prefix = combineNames(context.prefix, prefix)
self.branch = combineNames(context.branch, branch)
self.apply = [l for l in context.apply]
else:
self.prefix = prefix
self.branch = branch
self.apply = []
# Update the apply
if apply is not None:
def addToCurrentStack(ap):
if type(ap) is dict or type(ap) is TreeDict:
d = {}
for k, v in ap.iteritems():
checkNameValidity(k)
d[combineNames(self.branch, k)] = v
self.apply.append(d)
elif type(ap) is str:
self.apply.append(ap)
elif type(ap) is list or type(ap) is tuple:
for v in ap:
addToCurrentStack(v)
else:
raise TypeError("Argument types to apply() must be dict, TreeDict, "
"a preset name (string), or a list/tuple of these.")
addToCurrentStack(apply)
if self.prefix is not None and description is not None:
registerPrefixDescription(self.prefix, description, ignore_context = True)
def addToCurrentStack(ap):
if type(ap) is dict or type(ap) is TreeDict:
d = {}
for k, v in ap.iteritems():
checkNameValidity(k)
d[combineNames(self.branch, k)] = v
self.apply.append(d)
elif type(ap) is str:
self.apply.append(ap)
elif type(ap) is list or type(ap) is tuple:
for v in ap:
addToCurrentStack(v)
else:
raise TypeError("Argument types to apply() must be dict, TreeDict, "
"a preset name (string), or a list/tuple of these.")
def registerPrefixDescription(prefix, description, ignore_context = False):
"""
Registers `description` as a help tag for preset prefix `prefix`.
When the preset list is requested with `Z -l`, presets with
`prefix` are listed as a separate group described by `description`.
For Example::
"""
global __preset_description_lookup
checkNameValidity(prefix)
if not ignore_context:
prefix = combineNames(getCurrentContext().prefix, prefix)
if prefix is None:
raise ValueError("Either prefix must be given or "
"this must be called within a group context.")
__preset_description_lookup[prefix.lower() + ".__description__"] = \
re.sub(r"\s+", " ", description)
def registerPreset(name, preset, branch = None, description = None,
apply = [], ignore_context = False):
"""
Manually register a preset `preset` with name `name`. The type of
`preset` determines how it is applied when requested -- if a
TreeDict, it is applied as an update to the parameter tree; if it
is a function or other callable, applying the preset is done by
calling the function with the parameter tree as the sole argument.
If description is not None, it gives the description for the
preset as appears in help contexts or by calling ``Z -l``.
Otherwise, if preset is a function, the docstring is used as the
description. If preset is a TreeDict instance, as returned by
presetTree, the attribute ``__description__`` may be set to the description.
If `ignore_context` is True, a list of additional applications may
be passed as well. This follows the same format as described in
:ref:`group`, with the two exceptions that it must be a list, even
if it's only a list of a single item, and that TreeDict instances
are not allowed. These are applied before the preset is
called/applied.
Note that this function is normally not needed, as using the
standard functions, :ref:`preset` and :ref:`presetTree`, do this
automatically.
"""
global __preset_staging
global __preset_unique_prefix
checkNameValidity(name)
checkNameValidity(branch)
if not ignore_context:
ctx = getCurrentContext()
name = combineNames(ctx.prefix, name)
branch = combineNames(ctx.branch, branch)
apply = ctx.apply
# Get the description
if description is None:
if type(preset) is TreeDict:
d = preset.get("__description__", "")
else:
d = preset.__doc__
else:
d = description
if d is None:
d = ""
description = re.sub(r"\s+", " ", d)
# Checks to make sure it's gonna work later on
if type(preset) is not TreeDict:
if not callable(preset):
raise TypeError("Preset '%s' must be TreeDict or callable with parameter tree." % name)
preset.__name__ = __preset_unique_prefix + name + str(id(preset))
__preset_staging[preset.__name__] = _PresetWrapper(
name, branch, preset, description, apply)
else:
__preset_staging[id(preset)] = _PresetWrapper(
name, branch, preset, description, apply)
