param.Parameter

class param.Parameter(default=None, *, doc=None, label=None, precedence=None, instantiate=False, constant=False, readonly=False, pickle_default_value=True, allow_None=False, per_instance=True, allow_refs=False, nested_refs=False)

An attribute descriptor for declaring parameters.

Parameters are a special kind of class attribute. Setting a Parameterized class attribute to be a Parameter instance causes that attribute of the class (and the class’s instances) to be treated as a Parameter. This allows special behavior, including dynamically generated parameter values, documentation strings, constant and read-only parameters, and type or range checking at assignment time.

For example, suppose someone wants to define two new kinds of objects Foo and Bar, such that Bar has a parameter delta, Foo is a subclass of Bar, and Foo has parameters alpha, sigma, and gamma (and delta inherited from Bar). She would begin her class definitions with something like this:

class Bar(Parameterized):
    delta = Parameter(default=0.6, doc='The difference between steps.')
    ...
class Foo(Bar):
    alpha = Parameter(default=0.1, doc='The starting value.')
    sigma = Parameter(default=0.5, doc='The standard deviation.',
                    constant=True)
    gamma = Parameter(default=1.0, doc='The ending value.')
    ...

Class Foo would then have four parameters, with delta defaulting to 0.6.

Parameters have several advantages over plain attributes:

1. Parameters can be set automatically when an instance is constructed: The default constructor for Foo (and Bar) will accept arbitrary keyword arguments, each of which can be used to specify the value of a Parameter of Foo (or any of Foo’s superclasses). E.g., if a script does this:

   myfoo = Foo(alpha=0.5)
   

   myfoo.alpha will return 0.5, without the Foo constructor needing special code to set alpha.

   If Foo implements its own constructor, keyword arguments will still be accepted if the constructor accepts a dictionary of keyword arguments (as in def __init__(self,**params):), and then each class calls its superclass (as in super(Foo,self).__init__(**params)) so that the Parameterized constructor will process the keywords.

2. A Parameterized class need specify only the attributes of a Parameter whose values differ from those declared in superclasses; the other values will be inherited. E.g. if Foo declares:

   delta = Parameter(default=0.2)
   

   the default value of 0.2 will override the 0.6 inherited from Bar, but the doc will be inherited from Bar.

3. The Parameter descriptor class can be subclassed to provide more complex behavior, allowing special types of parameters that, for example, require their values to be numbers in certain ranges, generate their values dynamically from a random distribution, or read their values from a file or other external source.

4. The attributes associated with Parameters provide enough information for automatically generating property sheets in graphical user interfaces, allowing Parameterized instances to be edited by users.

Note that Parameters can only be used when set as class attributes of Parameterized classes. Parameters used as standalone objects, or as class attributes of non-Parameterized classes, will not have the behavior described here.

__init__(default=None, *, doc=None, label=None, precedence=None, instantiate=False, constant=False, readonly=False, pickle_default_value=True, allow_None=False, per_instance=True, allow_refs=False, nested_refs=False)

Initialize a new Parameter object and store the supplied attributes:

default: the owning class’s value for the attribute represented by this Parameter, which can be overridden in an instance.

doc: docstring explaining what this parameter represents.

label: optional text label to be used when this Parameter is shown in a listing. If no label is supplied, the attribute name for this parameter in the owning Parameterized object is used.

precedence: a numeric value, usually in the range 0.0 to 1.0, which allows the order of Parameters in a class to be defined in a listing or e.g. in GUI menus. A negative precedence indicates a parameter that should be hidden in such listings.

instantiate: controls whether the value of this Parameter will be deepcopied when a Parameterized object is instantiated (if True), or if the single default value will be shared by all Parameterized instances (if False). For an immutable Parameter value, it is best to leave instantiate at the default of False, so that a user can choose to change the value at the Parameterized instance level (affecting only that instance) or at the Parameterized class or superclass level (affecting all existing and future instances of that class or superclass). For a mutable Parameter value, the default of False is also appropriate if you want all instances to share the same value state, e.g. if they are each simply referring to a single global object like a singleton. If instead each Parameterized should have its own independently mutable value, instantiate should be set to True, but note that there is then no simple way to change the value of this Parameter at the class or superclass level, because each instance, once created, will then have an independently instantiated value.

constant: if true, the Parameter value can be changed only at the class level or in a Parameterized constructor call. The value is otherwise constant on the Parameterized instance, once it has been constructed.

readonly: if true, the Parameter value cannot ordinarily be changed by setting the attribute at the class or instance levels at all. The value can still be changed in code by temporarily overriding the value of this slot and then restoring it, which is useful for reporting values that the _user_ should never change but which do change during code execution.

pickle_default_value: whether the default value should be pickled. Usually, you would want the default value to be pickled, but there are rare cases where that would not be the case (e.g. for file search paths that are specific to a certain system).

per_instance: whether a separate Parameter instance will be created for every Parameterized instance. True by default. If False, all instances of a Parameterized class will share the same Parameter object, including all validation attributes (bounds, etc.). See also instantiate, which is conceptually similar but affects the Parameter value rather than the Parameter object.

allow_None: if True, None is accepted as a valid value for this Parameter, in addition to any other values that are allowed. If the default value is defined as None, allow_None is set to True automatically.

allow_refs: if True allows automatically linking parameter references to this Parameter, i.e. the parameter value will automatically reflect the current value of the reference that is passed in.

nested_refs: if True and allow_refs=True then even nested objects such as dictionaries, lists, slices, tuples and sets will be inspected for references and will be automatically resolved.

default, doc, and precedence all default to None, which allows inheritance of Parameter slots (attributes) from the owning-class’ class hierarchy (see ParameterizedMetaclass).

Methods

__init__([default, doc, label, precedence, ...])	Initialize a new Parameter object and store the supplied attributes:
deserialize(value)	Given a serializable Python value, return a value that the parameter can be set to
schema([safe, subset, mode])
serialize(value)	Given the parameter value, return a Python value suitable for serialization

Attributes

name
default
doc
precedence
instantiate
constant
readonly
pickle_default_value
allow_None
per_instance
watchers
owner
allow_refs
nested_refs
label
rx