Class Parameter

source code

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.