Parameters and Parameterized objects#

Fundamentally, what Param does is allow you to control how certain user-visible attributes (“parameters”) of a Python class or instance will behave when their value is get or set. A user of that class can set those attributes to control the class, but only if the mechanisms provided by Param and configured by the programmer allow it. In this way, Param allows the author of a class to implement and constrain what a user can do with that class or an instance of it, setting up a clear contract of what is and is not allowed, and how that attribute will behave. To do this, Param provides two main new types of Python object: Parameter objects, and Parameterized objects.

A parameter is a special kind of Python 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, not just an ordinary attribute. Parameters support special behavior, including dynamically generated parameter values, documentation strings, constant and read-only parameters, type or range checking at assignment time, and values dependent on those of other parameters.

More concretely, a Python Parameter object inherits from param.Parameter and stores various metadata attributes describing how a corresponding Python attribute of a Parameterized object should behave. By convention, we will use a capital ‘P’ Parameter to refer to the Parameter object itself, and a lower-case ‘p’ parameter to refer to the Python attribute it controls (i.e., the Parameter’s “value”).

A Parameterized class is a Python class that inherits from param.Parameterized and can accept Parameter objects as class attributes. A Parameterized class or instance uses the Parameter objects to determine how the corresponding attribute should behave.

There are many specific types of Parameter with different behavior, discussed in Parameter Types, but here we will cover the common behavior between all Parameter types when used in a Parameterized object.

Parameter metadata#

Each Parameter type can define additional behavior and associated metadata, but the metadata supported for all Parameter types includes:

  • default: Default value for this parameter at the class level, which will also be the value at the Parameterized instance level if it hasn’t been set separately on the instance.

  • default_factory: Optional callable to generate the default value for this parameter, which takes precedence over default when set. The callable is called on creation of a Parameterized instance. It can either be passed directly (in which case it is invoked with 0 arguments), or can be wrapped in a DefaultFactory for advanced use cases (in which case the factory is invoked with the arguments cls, self and parameter), such as setting the class level value with on_class=True. On instance creation, the factory is called after the Parameterized instance is initialized.

  • name: String name of this parameter, which is typically determined by the attribute name of this Parameter in the owning Parameterized object, and is not set directly by a programmer.

  • label: Optional long name used for a verbose listing; defaults to the name.

  • allow_None: Whether this parameter accepts None as an allowed value, in addition to whatever other types it accepts. Automatically set to True if the default value of this Parameter is None.

  • doc: Docstring describing this parameter, which can be used by automatic documentation systems.

  • constant: Parameter whose value can only be changed at the class level or in a Parameterized constructor. Once the Parameterized instance has been created, the value is constant except in the context of with param.edit_constant(obj) (see below).

  • readonly: Parameter whose value cannot be set by a user either on an instance or at the class level. Can still be changed inside a codebase by temporarily overriding this value, e.g. to report internal state.

  • instantiate: Whether to deepcopy the default value into a Parameterized instance when it is created. False by default for Parameter and most of its subtypes, but some Parameter types commonly used with mutable containers default to instantiate=True to avoid interaction between separate Parameterized instances, and users can control this when declaring the Parameter (see below).

  • per_instance: whether a separate Parameter instance will be created for every Parameterized instance created. Similar to instantiate, but applies to the Parameter object rather than to its value.

  • precedence: Optional numeric value controlling whether this parameter is visible in a listing and if so in what order.

  • allow_refs: Whether to allow the Parameter to accept references to other Parameters that will be dynamically resolved.

  • nested_refs: Whether references should be resolved even when they are nested inside a container.

  • metadata: Optional arbitrary mapping, to be used to store additional metadata than cannot be declared with the other attributes. Useful for third-party libraries to extend Param.

Most of these settings (apart from name) are accepted as keyword arguments to the Parameter’s constructor, with default mostly also accepted as the only positional argument:

import param
from param import Parameter, Parameterized

p = Parameter(default=42, doc="The answer", constant=True)
p.default

42

p.allow_None

False

p.doc

'The answer'

Parameter objects and instances#

In most cases, a Parameter will not be declared on its own as above; the Parameter object by itself is little more than a container for the metadata above. Until it is put into a class, most of those declarations are not meaningful, because what the Parameter object does is to specify how the corresponding Python attribute of that class should be handled. For example, we can define a Parameterized class with a couple of Parameter objects, and we’ll then be able to access the corresponding attributes of that class:

class A(Parameterized):
    question = Parameter("What is it?", doc="The question")
    answer = Parameter(default=2, constant=True, doc="The answer")
    ultimate_answer = Parameter(default=42, readonly=True, doc="The real answer")

a = A(question="How is it?", answer="6")

Here, we created a Parameterized class A, with parameters question and answer, each with default values. We then instantiated a Python object a of type A. Without having to write a constructor for A, we were able to provide our own values for question and answer, while inheriting the default value of ultimate_answer. This approach gives a lot of (but not too much!) configurability to the user of this class, without much effort by the class author. Any values we provide at instantiation need to be allowed by the Parameter declaration; e.g. here we could not provide a value for ultimate_answer when declaring a, because that parameter is declared read only:

with param.exceptions_summarized():
    A(ultimate_answer="no")

TypeError: Read-only parameter 'ultimate_answer' cannot be modified

Now that we have a Parameterized instance a, we can access the attributes we defined just as if they were normal Python instance attributes, and we’ll get the values we provided:

a.question

'How is it?'

a.answer

'6'

Meanwhile, the Parameterized class A (not the instance a) still has the default values, accessible as class attributes and used for any future objects instantiated of type A:

A.question

'What is it?'

A.answer

2

b = A()
b.answer

2

If accessing the attribute always gives us a value whether on the instance or the class, what happened to the Parameter objects? They are stored on the Parameterized instance or class, and are accessible via a special param accessor object at either the instance or class levels, via attribute or key:

a.param['question']

<param.parameterized.Parameter at 0x7f253c10eae0>

a.param.question

<param.parameterized.Parameter at 0x7f253c10eae0>

a.param.question.name

'question'

a.param.question.default

'What is it?'

A.param.question.default

'What is it?'

Once the Parameterized instance is created, the attributes can continue to be modified on it as often as you like, as long as the value is allowed by the Parameter object involved. E.g. question can still be changed, while answer is constant and cannot be changed after the Parameterized object has been instantiated:

with param.exceptions_summarized():
    a.question = True
    a.answer = 5

TypeError: Constant parameter 'answer' cannot be modified

a.question

True

Note that if for some reason you do need to change the value of a constant parameter (typically inside of your Parameterized object’s own code), you can do so using the param.edit_constant context manager:

with param.edit_constant(a):
    a.answer = 30
a.answer

30

In most cases, the only time you need to worry about the difference between a Parameter and a regular Python attribute is when you first declare it; after that it will sit there happily behaving as instructed, noticeable only when a user attempts something the declarer of that Parameter has not allowed. You can safely leave the various metadata items at their defaults most of the time, but they are all there for when your particular application requires a certain behavior.

Parameter inheritance#

Parameter objects and their metadata are inherited in a hierarchy of Parameterized objects. Let’s see how that works:

class A(Parameterized):
    question = Parameter("What is it?", doc="The question")
    answer = Parameter(default=2, constant=True, doc="The answer")
    ultimate_answer = Parameter(default=42, readonly=True, doc="The real answer")

class B(A):
    ultimate_answer = Parameter(default=84)

b = B()
b.question

'What is it?'

A.question = "How are you?"

b.question

'How are you?'

Here you can see that B inherits question from A, and as long as question has not been set explicitly on b, b.question will report the value from where that Parameter was defined, i.e. A in this case. If question is subsequently set on b, b.question will no longer be affected by the value in A:

b.question = "Why?"
A.question = "Who?"
b.question

'Why?'

As you can see, parameters not specified in B are still fully usable in it, if they were declared in a superclass. Metadata associated with that parameter is also inherited, if not explicitly overidden in B.

b.param.ultimate_answer.constant

True

b.param.ultimate_answer.readonly

True

b.ultimate_answer

84

b.param.ultimate_answer.default

84

b.param.ultimate_answer.doc

'The real answer'

Looking at the metadata values of ultimate_answer on b or B you can see that:

  • All the default metadata values like constant, allow_none, 
, were inherited from the base Parameter object provided by Param

  • The read_only and doc metadata values were inherited from A

  • The default metadata value of ultimate_answer in B overrode the value provided in A.

Parameter inheritance like this lets you (a) use a parameter in many subclasses without having to define it more than once, and (b) control the value of that parameter conveniently across the entire set of subclasses and instances, as long as that attribute has not been set on those objects already. Using inheritance in this way is a very convenient mechanism for setting default values and other “global” parameters, whether before a program starts executing or during it.

help(b) or help(B) will list all parameters. You can also prefix or suffix a Parameterized object with ? in an IPython console/Notebook to display the help:

B?

Param help

Parameter value instantiation#

So much of the parameter metadata is there to help you control whether and how the parameter value is instantiated on Parameterized objects as they are created or new Parameterized subclasses as they are defined. Depending on how you want to use that Parameter and what values it might take, controlling instantiation can be very important when mutable values are involved. While the default behavior shown above is appropriate for immutable attributes, what happens if the value (unlike Python strings) is mutable? Things get a lot more complex.

s = [1, 2, 3]

class C(Parameterized):
    s1 = Parameter(s, doc="A sequence")
    s2 = Parameter(s, doc="Another sequence")

c = C()

Here, both parameters s1 and s2 effectively point to the same underlying sequence s:

c.s1 is c.s2

True

s[1] *= 5

s

[1, 10, 3]

c.s1

[1, 10, 3]

c.s1[2] = 'a'

c.s1

[1, 10, 'a']

c.s2

[1, 10, 'a']

As you can see, there is only one actual sequence here, and s, s1, and s2 all point to it. In some cases such behavior is desirable, e.g. if the mutable object is a specific global list (e.g. a set of search paths) with a unique identity and all of the parameters are meant to point to that specific item. In other cases, it’s the contents of the mutable item that are important, and no sharing of contents is intended. Luckily, Param supports that case as well, if you provide instantiate=True (default is False):

s = [1,2,3]

class D(Parameterized):
    s1 = Parameter(default=s, doc="A sequence", instantiate=True)
    s2 = Parameter(default=s, doc="Another sequence", instantiate=True)

d = D()

Now, parameters s1 and s2 point to their own copies of the sequence, independent of each other and of the original argument s:

d.s1 is d.s2

False

s *= 2

s

[1, 2, 3, 1, 2, 3]

d.s1

[1, 2, 3]

d.s1[2] = 'a'

d.s2

[1, 2, 3]

Of course, copying the data into each instance like that costs memory, and moreover prevents controlling all instances at once by setting a class attribute as we saw earlier, which is why instantiate is not True by default. As a rule of thumb, set instantiate=True if and only if (a) your Parameter can take mutable values, and (b) you want those values to be independent between Parameterized instances.

Parameter object instantiation#

instantiate controls how parameter values behave, but similar issues arise for Parameter objects, which offer similar control via the per_instance metadata declaration. per_instance (True by default) provides a logically distinct Parameter object for every Parameterized instance, allowing each such instance to have different metadata for that parameter. For example, we can set the label separately for each instance without clobbering each other:

d1 = D()
d2 = D()
d1.param.s1.label = "sequence 1"
d2.param.s1.label = "(sequence 1)"
d2.param.s1.label

'(sequence 1)'

d1.param.s1.label

'sequence 1'

This capability is useful for situations with dynamically updated metadata, e.g. if you need setting one parameter’s value (e.g. ‘Continent’) to change the allowed values of another parameter (e.g. ‘Country’). The underlying Parameter objects are copied lazily (only when actually changed), so that objects are not actually multiplied unless necessary. If you do want parameters to share a single Parameter object so that you can control its behavior globally, you can achieve that with per_instance=False, though the effects can be confusing in the same way as instantiate=True for mutable objects (above):

class E(Parameterized):
    a = Parameter(default=3.14, label="pi", per_instance=False)

e1 = E()
e2 = E()
e2.param.a.label = "Pie"
e1.param.a.label

'Pie'

Instantiating with shared parameters#

When creating a large collection of Parameterized objects of the same type, the overhead of having separate parameters for each object can be significant. If you want, you can create the objects to share parameter values for efficiency, and also so that you can easily change a value on all such objects at the same time.

As an example, let’s say you’ve defined a Parameter value to be independent, such that changing one instance’s value will not affect the others:

class S(param.Parameterized):
    l = Parameter(default=[1,2,3], instantiate=True)

ss = [S() for i in range(10)]
ss[0].l[2] = 5
ss[1].l

[1, 2, 3]

Here changing the value of l on ss[0] doesn’t affect ss[1] or any other instances.

What if you as a user of this class are creating a very large number of similar objects and actually do want them to share the same parameter value, either to save memory or to make it easy to change all of their values at once? In that case you can use the context manager shared_parameters, and any Parameterized objects created within that context will share parameter values, such that changing one of them will affect all of them:

with param.shared_parameters():
    ps = [S() for i in range(10)]
    
ps[0].l[2] = 5
ps[1].l

[1, 2, 5]

This approach can provide significant speedup and memory savings in certain cases, but should only be used for good reasons, since it can cause confusion for any code expecting instances to be independent as they have been declared.

Default Factory#

It is sometimes useful to dynamically set the default value of a Parameter, e.g. based on the system state, or just randomly. A typical example would be assigning a unique identifier to each new instance of a class. The default_factory keyword and attribute (added in version 2.3.0) can be set to a factory callable to dynamically compute the parameter value.

The default_factory can be any callable that can be invoked without requiring positional arguments (e.g. def foo(): ..., def foo(*args): ..., def foo(**kwargs): ..., etc.). In addition, the callable can be wrapped as an instance of param.parameterized.DefaultFactory, in which case it is called with the three arguments cls, self, and parameter:

  • When an instance is created, the callable receives the Parameterized class as cls, the instance itself as self, and the instance-level Parameter object as parameter.

  • During class creation (typically when a module defining Parameterized classes is imported), and only if the DefaultFactory is initialized with on_class=True (default is False), the callable is instead passed the Parameterized class as cls, None for self (since no instance exists yet), and the class-level Parameter object as parameter. on_class=True is the only case where the callable can influence the class-level attribute value.

Important

Parameters all have a default value. When default_factory is set, it takes precedence over default as the source of the default value for a new instance. For example, updating a Parameter’s attribute at the class level has no effect on the current and future instances of this class if the Parameter underlying the attribute has a default_factory.

Let’s see how this works. We’ll start with the most common use-case: simple factory functions that generate a parameter value used at the instance level. In this example, every new instance of the Object class will have its uuid and created_at attributes dynamically computed on instantiation.

import datetime
import functools
import time
import uuid

def uuid4():
    return str(uuid.uuid4())

class Object(Parameterized):
    uuid = param.String(default_factory=uuid4)
    created_at = param.Date(default_factory=functools.partial(datetime.datetime.now, tz=datetime.timezone.utc))

obj1 = Object()
obj1

Object(created_at=datetime.datetime(2025, 11, 25, 10, 30, 45, 130462, tzinfo=datetime.timezone.utc), name='Object00031', uuid='2fbe65fe-d2a6-4a28-ae16-a5a95ad63f02')

time.sleep(0.5)
obj2 = Object()
obj2

Object(created_at=datetime.datetime(2025, 11, 25, 10, 30, 45, 635710, tzinfo=datetime.timezone.utc), name='Object00032', uuid='1f3bafab-45f4-4cc7-9645-7454cf30957b')

Wrapping the factory in DefaultFactory is useful for more advanced use cases. In the next example, we reproduce the behavior of the name Parameter all Parameterized classes inherit:

  • At the class-level, it is set to the class name. To enable this, we need to instantiate the DefaultFactory wrapper with on_class=True so the factory gets also called on class creation.

  • At the instance-level, it is set to the class name suffixed with an incremented count, allowing to easily distinguish instances of the same class. This automatic value is disabled if that class-level value is overridden, and applies only to the affected class and not its subclasses.

debug_id_counter = 0

def debug_id(cls, self, parameter):
    global debug_id_counter
    if self:
        # When the class value is overriden.
        if getattr(cls, parameter.name) != cls.__name__:
            return getattr(cls, parameter.name)
        else:
            name = f'{cls.__name__}{debug_id_counter:05d}'
            debug_id_counter += 1
            return name
    else:
        return cls.__name__

class Object(Parameterized):
    debug_id = param.String(
        default_factory=param.parameterized.DefaultFactory(
            debug_id,
            on_class=True,
        )
    )

class SubObject(Object):
    pass

Object.debug_id, SubObject.debug_id

('Object', 'SubObject')

Object().debug_id, Object().debug_id, Object().debug_id

('Object00000', 'Object00001', 'Object00002')

SubObject().debug_id, SubObject().debug_id, SubObject().debug_id

('SubObject00003', 'SubObject00004', 'SubObject00005')

Object.debug_id = 'overridden'
Object().debug_id, SubObject().debug_id

('overridden', 'SubObject00006')

import param

Arbitrary Metadata#

Parameters may include arbitrary metadata as a mapping stored in the metadata attribute (default is None). This attribute is not used internally by Param, instead it is meant to enable rich functionality in third-party libraries, or to be leveraged in your own code base to extend Parameters with information that cannot be declared with the other attributes available. Note that a shallow copy of the mapping you’ll pass will be made on class creation and on instance-level parameter creation. This behavior is not specific to the metadata attribute, it is how Param handles attributes with value that are mutable containers (lists, dicts, sets).

extra_info = {'library': {'config': True}}

class P(param.Parameterized):
    s = param.String(metadata=extra_info)

P.param['s'].metadata

{'library': {'config': True}}

p = P()
p.param.s.metadata

{'library': {'config': True}}

P.param['s'].metadata is extra_info  # shallow copy made on class creation

False

p.param['s'].metadata is P.param['s'].metadata  # shallow copy made when the instance-level Parameter is created

False

To provide a more concrete example on how third-party libraries can benefit from the metadata attribute, we’ll give an example with Panel, a library to build web apps written in Python only. Panel already integrates with Param, and makes it easy to display a Parameterized instance as an app component, each Parameter type being automatically mapped to a widget type (e.g., a Number Parameter is displayed as a float slider). Customizing the automatically created widget requires additional work in Panel (e.g., using the Widget.from_param(<parameter>) API). To simplify this process, Panel could inspect the metadata attribute for custom widget configuration, and apply it on widget creation:

import panel as pn

pn.extension()

class MyPanelView(param.Parameterized):
    percentage = param.Number(default=0, bounds=(0, 100), metadata={'panel': {'width': 100}})

pn.Param(MyPanelView())

Parameterized Abstract Base Class#

Param supports two ways of declaring a class as an abstract base class (ABC), which is a good approach to define an interface subclasses should implement:

  • Added in version 2.3.0, an abstract Parameterized class can be created by inheriting from ParameterizedABC, which is equivalent as inheriting from ABC from the Python abc module.

  • A Parameterized class can be annotated with the class attribute __abstract set to True to declare it as abstract.

We recommend adopting the first approach that is more generic and powerful. The second approach is specific to Param (inspect.isabstract(class) won’t return True for example) and preserved for compatibility reasons.

Warning

It is recommended not to mix the two approaches.

Let’s start with an example using the first approach, declaring the ProcessorABC interface with a run method subclasses must implement.

import abc

class ProcessorABC(param.ParameterizedABC):
    x = param.Number()
    y = param.Number()

    @abc.abstractmethod
    def run(self): pass

Subclasses that do not implement the interface cannot be instantiated, this is the standard behavior of a Python ABC.

class BadProcessor(ProcessorABC):
    def run_not_implemented(self): pass

with param.exceptions_summarized():
    BadProcessor()

TypeError: Can't instantiate abstract class BadProcessor without an implementation for abstract method 'run'

A valid subclass can be instantiated and used.

class GoodProcessor(ProcessorABC):
    def run(self):
        return self.x * self.y

GoodProcessor(x=2, y=4).run()

8

Let’s see now how using the second approach differs from the first one by creating a new base class, this time a simple Parameterized subclass with a class attribute __abstract set to True

class ProcessorBase(param.Parameterized):
    __abstract = True

    x = param.Number()
    y = param.Number()

    def run(self): raise NotImplementedError("Subclasses must implement the run method")

Param does not validate that subclasses correctly implement the interface. In this example, calling the non-implemented method will execute the method inherited from the base class.

class BadProcessor(ProcessorBase):
    def run_not_implemented(self): pass

bp = BadProcessor()
with param.exceptions_summarized():
    bp.run()

NotImplementedError: Subclasses must implement the run method

class GoodProcessor(ProcessorBase):
    def run(self):
        return self.x * self.y

GoodProcessor(x=2, y=4).run()

8

Parameterizes classes have an abstract property that returns True whenever a class is declared as abstract in the two supported approaches.

ProcessorABC.abstract, ProcessorBase.abstract, GoodProcessor.abstract

(True, True, False)

The descendents function returns a list of all the descendents of a class including the parent class. It supports a concrete keyword that can be set to True to filter out abstract classes. Note that with the first approach, BadProcessor isn’t returned as it doesn’t implement the interface of the abstract class.

param.descendents(ProcessorABC, concrete=True)

[__main__.GoodProcessor]

param.descendents(ProcessorBase, concrete=True)

[__main__.BadProcessor, __main__.GoodProcessor]

Displaying Parameterized objects#

Most of the important behavior of Parameterized is to do with instantiation, getting, and setting, as described above. Parameterized also provides a few public methods for creating string representations of the Parameterized object and its parameters:

  • Parameterized.__str__(): A concise, non-executable representation of the name and class of this object

  • Parameterized.__repr__(): A representation of this object and its parameter values as if it were Python code calling the constructor (classname(parameter1=x,parameter2=y,...))

  • Parameterize.param._repr_html_(): A rich HTML representation of the object with its parameters listed in a table together with their metadata.

  • Parameterized.param.pprint(): Customizable, hierarchical pretty-printed representation of this Parameterized and (recursively) any of its parameters that are Parameterized objects. See Serialization and Persistence for details on customizing pprint.

import param

class Q(param.Parameterized):
    a = param.Number(default=39, bounds=(0,50), doc='Number a')
    b = param.String(default="str", doc='A string')

class P(Q):
    c = param.ClassSelector(default=Q(), class_=Q, doc='An instance of Q')
    e = param.ClassSelector(default=param.Parameterized(), class_=param.Parameterized, doc='A Parameterized instance')
    f = param.Range(default=(0,1), doc='A range')

p = P(f=(2,3), c=P(f=(42,43)), name="demo")

p.__str__()

'<P demo>'

p.__repr__()

"P(a=39, b='str', c=P(a=39, b='str', c=Q(a=39, b='str', name='Q00048'), e=Parameterized(name='Parameterized00049'), f=(42, 43), name='P00047'), e=Parameterized(name='Parameterized00052'), f=(2, 3), name='demo')"

The HTML representation of a Parameterized instance or class is displayed when you call <obj>.param in a Notebook.

p.param
P()
NameValueTypeRange

a

 39 Number >=0, <=50

b

 'str' String

c
P()
NameValueTypeRange

a

 39 Number >=0, <=50

b

 'str' String

c
Q()
NameValueTypeRange

a

 39 Number >=0, <=50

b

 'str' String

name

 'Q00048' String nullable constant
 ClassSelector Q

e
Parameterized()
NameValueTypeRange

name

 'Parameterized00049' String nullable constant
 ClassSelector Parameterized

f

 (42, 43) Range

name

 'P00047' String nullable constant
 ClassSelector Q

e
Parameterized()
NameValueTypeRange

name

 'Parameterized00052' String nullable constant
 ClassSelector Parameterized

f

 (2, 3) Range

name

 'demo' String nullable constant
P.param
P
NameDefaultTypeRange

a

 39 Number >=0, <=50

b

 'str' String

c
Q()
NameValueTypeRange

a

 39 Number >=0, <=50

b

 'str' String

name

 'Q00045' String nullable constant
 ClassSelector Q

e
Parameterized()
NameValueTypeRange

name

 'Parameterized00046' String nullable constant
 ClassSelector Parameterized

f

 (0, 1) Range

name

 'P' String nullable constant
p.param.pprint(separator="\n")

"P(c=P(c=Q(),     e=Parameterized(),     f=(42,43)),\n e=Parameterized(),\n f=(2,3),\n name='demo')"

Notice that in the case of a circular reference (p.c = P(c=p)) the representation will show an ellipsis (...) rather than recursively printing the subobject:

p.c=P(c=p)
p.param.pprint()

"P(c=P(c=...,     e=Parameterized()), e=Parameterized(), f=(2,3), name='demo')"

Parameterized namespace#

Param allows you to create Parameterized objects by inheriting from the Parameterized base class. Param has evolved over time to reduce its footprint and reserve as few as possible attributes on this namespace, to reduce the risk of name clashes and allow you to freely define your attribute names. Param reserves a few names that are described below, make sure not to override, unless it is stated it is allowed:

  • Public attributes:

    • name: Parameterized classes and instances have a name String Parameter, that by default is set to the class name when accessed from the class and to the class name appended with a 5 digit number, starting at 00000, when accessed from the instance. You can override this Parameter by your own String Parameter if you need to.

    • param: Property that helps keep the Parameterized namespace clean and disambiguate between Parameter objects and parameter values, it gives access to a namespace that offers various methods (see the section below) to update and inspect the Parameterized object at hand.

  • Private attributes:

    • _param__parameters: Store the object returned by .param on the class

    • _param__private: Store various internal data on Parameterized class and instances

class P(param.Parameterized):
    a = param.Number()
    b = param.String()

p = P()
print(f'{P.name=}, {p.name=}')

P.name='P', p.name='P00056'

def namespace(obj):
    return [o for o in dir(obj) if not o.startswith('__')]

namespace(P)

['_param__parameters', '_param__private', 'a', 'b', 'name', 'param']

namespace(p)

['_param__parameters', '_param__private', 'a', 'b', 'name', 'param']

Other Parameterized methods#

Like .param.pprint, the remaining “utility” or convenience methods available for a Parameterized class or object are provided via the .param subobject:

  • .param.update(**kwargs): Set parameter values from the given param=value keyword arguments (or a dict or iterable), delaying watching and dependency handling until all have been updated. .param.update can also be used as a context manager to temporarily set values, that are restored to their original values when the context manager exits.

p.param.update(a=0, b='start');
print(p.a, p.b)

0 start

with p.param.update(a=1, b='temp'):
    print(f'In the context manager: {p.a=}, {p.b=}')
print(f'After the context manager exits: {p.a=}, {p.b=}')

In the context manager: p.a=1, p.b='temp'
After the context manager exits: p.a=0, p.b='start'

  • .param.values(onlychanged=False): A dict of name,value pairs for all parameters of this object

p.param.values()

{'a': 0, 'b': 'start', 'name': 'P00056'}

  • .param.objects(instance=True): Parameter objects of this instance or class

p.param.objects()

{'name': <param.parameterized.String at 0x7f252ce7d380>,
 'a': <param.parameters.Number at 0x7f252cfa3370>,
 'b': <param.parameterized.String at 0x7f252ce7dd20>}

  • .param.add_parameter(param_name,param_obj): Dynamically add a new Parameter to this object’s class

  • .param.get_value_generator(name): Returns the underlying value-generating callable for this parameter, or the underlying static value if none

  • .param.force_new_dynamic_value(name): For a Dynamic parameter, generate a new value and return it

  • .param.inspect_value(name): For a Dynamic parameter, return the current value of the named attribute without modifying it.

Specialized Parameter types#

As you can see above, a Parameter provides a lot of power already on its own, but in practice you will want to use much more specific parameter types that reject invalid inputs and keep your code clean and simple. A specialized Parameter acts as a “contract” with the users of the code you write, declaring and defending precisely what configuration is allowed and how to achieve it. If you need to accept specific inputs like that but don’t add an appropriate Parameter type, you’ll be stuck adding exceptions and validation code throughout your codebase, whereas anything you can express at the Parameter level will be enforced automatically without any further checks or code.

For instance, what if you want to accept a numeric parameter, but (for some reason) can only accept numbers that are even integers? You’ll need a custom Parameter class to express a restriction like that. In this case you can do it by overriding the _validate_value method of the Parameter class:

import numbers

class EvenInteger(param.Parameter):
    """Integer Parameter that must be even"""

    def _validate_value(self, val, allow_None):
        super()._validate_value(val, allow_None)
        if not isinstance(val, numbers.Number):
            raise ValueError(
                f"EvenInteger parameter {self.name!r} must be a number, not {val!r}."
            )
        
        if not (val % 2 == 0):
            raise ValueError(
                f"EvenInteger parameter {self.name!r} must be even, not {val!r}."
            )

class P(param.Parameterized):
    n = param.Number()
    b = EvenInteger()
    
p=P()
P(n=5, b=4)
P(b=4, n=5, name='P00003')

P(b=4, n=5, name='P00003')

with param.exceptions_summarized():
    P(n=5, b="four")

ValueError: EvenInteger parameter 'b' must be a number, not 'four'.

with param.exceptions_summarized():
    P(n=5, b=5)

ValueError: EvenInteger parameter 'b' must be even, not 5.

Luckily, you don’t often need to write a custom Parameter class like this, because the most common cases are already provided in Param, as listed in the Parameter Types manual. If you need something more specific than the existing types, start with the one that comes closest to restricting its value to the desired set of values without excluding any allowable values. In this case all integer powers of 2 are also integers, so you’d start with param.Integer rather than param.Parameterized as above. You can then make a new subclass and add validation as above to further restrict the values to precisely what you allow. Here if you inherited from param.Integer you would no longer need to check if the input is a number, as param.Integer already does that as long as you call super as above. Your custom type can override any aspects of the Parameter if needed, e.g. to accept different items in the constructor, store additional data, add additional constraints, and so on. The existing Parameter types in param/__init__.py act as a rich source of examples for you to start with and crib from.