parameter-design

Parameter Design

Ownership and Lifecycle

Code owns the schema; the user owns the value. A parameter's name, style, page, range, default and help text are yours to declare and re-assert. Its value is the user's, and nothing you write may quietly discard it.

Extensions reinitialize on every source-file save, so every creation path must be get-or-create, never create-blindly:

def ensureCustomPage(comp, name):
    for page in comp.customPages:
        if page.name == name:
            return page
    return comp.appendCustomPage(name)

def ensureCustomPar(comp, page, name, style, **attrs):
    """Get-or-create one custom par: the Par, or the ParGroup for a tuplet."""
    # Probe the WHOLE COMP by tupletName. Names are a flat per-COMP namespace,
    # and a multi-value style (RGB, XYZ) is stored as <name>r/<name>g/<name>b,
    # so a probe by .name never finds it and append*() (replace=True) would
    # re-create it on every reinit.
    found = [p for p in comp.customPars if p.tupletName == name]
    if not found:
        getattr(page, 'append' + style)(name)
        found = [p for p in comp.customPars if p.tupletName == name]
    elif found[0].style not in STYLE_FAMILY.get(style, (style,)):
        raise ValueError('par %s is %s, declared %s -- refusing to replace it'
                         % (name, found[0].style, style))
    for p in found:                          # symmetric: schema attrs re-applied
        for key, value in attrs.items():     # on every reinit; the user's state
            if key not in ('val', 'expr', 'bindExpr', 'mode', 'export'):
                setattr(p, key, value)       # is never touched -- and a typo RAISES
    return found[0] if len(found) == 1 else found[0].parGroup

# TD reports a tuplet's style by family: RGB reads 'RGBA', XY/XYZ read 'XYZW'.
STYLE_FAMILY = {'RGB': ('RGB', 'RGBA'), 'XY': ('XY', 'XYZW'), 'XYZ': ('XYZ', 'XYZW')}

Four rules that make it safe: