param

Param is a zero-dependency Python library designed for two primary purposes:

1. Rich, Declarative Attributes: It allows you to create classes with Parameter objects that include extended metadata. This metadata supports runtime type validation, range validation, documentation strings, default values/factories, and nullability. It is conceptually similar to Pydantic, Python's dataclasses, or Traitlets.
2. Reactive Programming: It provides APIs for declaring complex reactive dependencies. This enables automatic updates when attributes change and allows other frameworks to introspect these dependencies to implement reactive workflows.

Param is commonly used as a foundation for building user interfaces, graphical applications, and responsive systems. It serves as the core engine for HoloViz's Panel and HoloViews libraries.

A Parameter can be linked to another object (a reference) so that it updates automatically when that object changes.

To allow a parameter to accept a reference (like another parameter, a bound function, or a reactive expression) instead of a static value, you must set allow_refs=True when defining the parameter.

Supported References:

• Another Parameter object.
• A bound function created via param.bind().
• A reactive expression created via rx() or .rx().

When the source of the reference changes, the target parameter is automatically updated to the new resolved value.

import param

class X(param.Parameterized):
    source = param.Number()

class Y(param.Parameterized):
    # Must set allow_refs=True to accept dynamic references
    target = param.Number(allow_refs=True)

x = X(source=1)
y = Y()

# 1. Reference to another Parameter
y.target = x.param['source']
print(y.target)  # 1
x.source = 2
print(y.target)  # 2

# 2. Reference to a bound function
y.target = param.bind(lambda x: x + 10, x.param['source'])
print(y.target)  # 12
x.source = 3
print(y.target)  # 13

# 3. Reference to a reactive expression
y.target = x.param['source'].rx() * 20
print(y.target)  # 20
x.source = 5
print(y.target)  # 100

Subclasses of a Parameterized class inherit all parameter metadata from their parents. You can selectively override specific aspects of a parameter (like bounds or default) in the subclass while keeping other metadata intact.

Metadata inheritance works at both the class level and the instance level. Class-level attribute changes in a parent class will affect all instances of the child class unless the child has overridden that specific parameter.

import param

class Processor(param.Parameterized):
    retries = param.Integer(default=3, bounds=(0, 10))
    verbose = param.Boolean(default=False)

class CustomProcessor(Processor):
    # Overriding bounds and default, but inheriting other metadata
    retries = param.Integer(bounds=(0, 100))
    verbose = param.Boolean(default=True)

# Check inheritance
print(CustomProcessor.param['retries'].default)  # 3 (inherited)
print(CustomProcessor.param['retries'].bounds)    # (0, 100) (overridden)

Param provides APIs to trigger immediate side-effects when parameters change. These are identified by the watch keyword or the watch noun in the method name.

1. obj.param.watch(fn, *parameters, ...): A low-level API to attach a callback to specific parameter changes. The callback receives one or more param.parameterized.Event objects containing metadata about the change (e.g., old, new, name, obj).
2. @param.depends(*parameter_names, watch=True): A decorator for methods within a Parameterized class. When the specified parameters change, the decorated method is automatically called. Unlike the standard @param.depends, using watch=True ensures the method is triggered on change, but it does not receive an Event object as an argument.
3. param.bind(fn, *references, watch=True, **kwargs): Binds a function to one or more references (parameters, bound functions, or reactive expressions). If watch=True, the function is automatically invoked whenever the referenced values change.

import param

def debug_event(event: param.parameterized.Event):
    print(event)

class SideEffectExample(param.Parameterized):
    a = param.String()
    b = param.String()

    def __init__(self, **params):
        super().__init__(**params)
        # 1. Low-level watch
        self.param.watch(debug_event, 'a')

    # 2. Automatic dependency with watch=True
    @param.depends('b', watch=True)
    def print_b(self):
        print(f"print_b: {self.b=}")

# 3. Function binding with watch=True
def print_c(c):
    print(f"print_c: {c=}")

sfe = SideEffectExample()
param.bind(print_c, sfe.param.c, watch=True)

sfe.a = 'foo'  # Triggers debug_event
sfe.b = 'bar'  # Triggers print_b
sfe.c = 'baz'  # Triggers print_c

Param supports dynamic parameter values, making it ideal for simulations, machine learning, or parameter sweeps.

Using Callables

You can set a parameter to a callable (like a lambda). The callable is evaluated every time the parameter is accessed, but the code using the parameter sees only the returned value.

import random
import param

class B(param.Parameterized):
    a = param.Integer(2)
    b = param.Integer(3)
    def __call__(self):
        return str(self.a + self.b)

# 'a' will return a new random integer every time it is accessed
o2 = B(a=lambda: random.randint(0, 5))
print(o2.a)  # Returns an integer

Using numbergen

For more robust exploration, use the numbergen module. numbergen objects are picklable and support arithmetic operations, allowing you to build complex parameter sweeps or Monte Carlo simulations.

import numbergen as ng

# Combine choices and random distributions
o3 = B(a=ng.Choice(choices=[2, 4, 6]),
       b=1 + 2 * ng.UniformRandomInt(ubound=3))

# Accessing parameters will trigger the generation logic
print(o3())

import numbergen as ng

o3 = B(a=ng.Choice(choices= [2, 4, 6]),
       b = 1 + 2 * ng.UniformRandomInt(ubound=3))