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, default_factory=None, metadata=None)[source]#

Base Parameter type to hold any type of Python object.

Parameters are a special kind of class attribute implemented as descriptor. Setting a Parameterized class attribute to a Parameter instance enables enhanced functionality, including type and range validation at assignment, support for constant and read-only parameters, documentation strings and dynamic parameter values.

Parameters can only be used as class attributes of Parameterized classes. Using them in standalone contexts or with non-Parameterized classes will not provide the described behavior.

Notes

Parameters provide lots of features.

Dynamic Behavior:

  • Parameters provide support for dynamic values, type validation, and range checking.

  • Parameters can be declared as constant or read-only.

Automatic Initialization:

  • Parameters can be set during object construction using keyword arguments. For example: myfoo = Foo(alpha=0.5); print(myfoo.alpha).

  • If custom constructors are implemented, they can still pass keyword arguments to the superclass to allow Parameter initialization.

Inheritance:

  • Parameterized classes automatically inherit parameters from their superclasses. Attributes can be selectively overridden.

Subclassing:

  • The Parameter class can be subclassed to create custom behavior, such as validating specific ranges or generating values dynamically.

GUI Integration:

  • Parameters provide sufficient metadata for auto-generating property sheets in graphical user interfaces, enabling user-friendly parameter editing.

Examples

Define a Parameterized class with parameters:

>>> import param
>>> class Foo(param.Parameterized):
...     alpha = param.Parameter(default=0.1, doc="The starting value.")
...     beta = param.Parameter(default=0.5, doc="The standard deviation.", constant=True)

When no initial value is provided the default is used:

>>> Foo().alpha
0.1

When an initial value is provided it is used:

>>> foo = Foo(alpha=0.5)
>>> foo.alpha
0.5

Constant parameters cannot be modified:

>>> foo.beta = 0.1  # Cannot be changed since it's constant
...
TypeError: Constant parameter 'beta' cannot be modified
__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, default_factory=None, metadata=None)[source]#

Initialize a new Parameter object with the specified attributes.

Parameters:

  • default (Any, optional) – The owning class’s value for the attribute represented by this parameter, which can be overridden in an instance. Default is None.

  • default_factory (callable, optional) –

    A callable used to generate the attribute value. It can be provided directly (in which case it is invoked with no arguments) or wrapped in a DefaultFactory for more advanced behavior (in which case it receives cls, self, and parameter as arguments). When specified, default_factory takes precedence over default. The factory is invoked once the Parameterized instance is initialized.

    Added in version 2.3.0.

  • doc (str | None, optional) – A documentation string describing the purpose of the parameter. Default is None.

  • label (str | None, optional) – An optional text label used when displaying this parameter, such as in a listing. If not specified, the parameter’s attribute name in the owning Parameterized object is used.

  • precedence (float | None, optional) – A numeric value, usually in the range 0.0 to 1.0, that determines the order of the parameter in a listing or user interface. A negative precedence indicates a parameter that should be hidden in such listings. Default is None.

  • instantiate (bool, optional) – Whether the default value of this parameter will be deepcopied when a Parameterized object is instantiated (True), or if the single default value will be shared by all Parameterized instances (False, the default). 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 deepcopied value. Default is False.

  • constant (bool, optional) – If True, the parameter value can only be set at the class level or in a Parameterized constructor call. The value is otherwise constant on the Parameterized instance, once it has been constructed. Default is False.

  • readonly (bool, optional) – If True, the parameter value cannot be modified at the class or instance level. Default is False.

  • pickle_default_value (bool, optional) –

    Whether the default value should be pickled. Set to False in rare cases, such as system-specific file paths.

    Deprecated since version 2.3.0.

  • allow_None (bool, optional) – If True, allows None as a valid parameter value. If the default value is None, this is automatically set to True. Default is False.

  • per_instance (bool, optional) – Whether to create a separate Parameter object for each instance of the Parameterized class (True), or share the same Parameter object across all instances (False). See also instantiate, which is conceptually similar but affects the parameter value rather than the parameter object. Default is True.

  • allow_refs (bool, optional) – If True, allows linking parameter references to this parameter, meaning the value will automatically reflect the current value of the reference that is passed in. Default is False.

  • nested_refs (bool, optional) – If True and allow_refs=True, inspects nested objects (e.g., dictionaries, lists, slices, tuples) for references and resolves them automatically. Default is False.

  • metadata (Mapping, optional) –

    An 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. Default is None.

    Added in version 2.3.0.

Examples

Define a parameter with a default value:

>>> import param
>>> class MyClass(param.Parameterized):
...     my_param = param.Parameter(default=10, doc="An example parameter.")
>>> instance = MyClass()
>>> instance.my_param
10

Use a constant parameter:

>>> class ConstantExample(param.Parameterized):
...     my_param = param.Parameter(default=5, constant=True)
>>> instance = ConstantExample()
>>> instance.my_param = 10  # Raises an error
...
TypeError: Constant parameter 'my_param' cannot be modified.

Methods

__init__([default, doc, label, precedence, ...])

Initialize a new Parameter object with the specified attributes.

deserialize(value)

Given a serializable Python value, return a value that the parameter can be set to.

schema([safe, subset, mode])

Generate a schema for the parameters of the Parameterized object.

serialize(value)

Given the parameter value, return a Python value suitable for serialization.

Attributes

name

default

default_factory

doc

precedence

instantiate

constant

readonly

pickle_default_value

allow_None

per_instance

watchers

owner

allow_refs

nested_refs

metadata

label

Get the label for this parameter.

rx

The reactive operations namespace.