Param API reference#

Reactive API#

bind(function, *args[, watch])

Given a function, returns a wrapper function that binds the values of some or all arguments to Parameter values and expresses Param dependencies on those values, so that the function can be invoked whenever the underlying values change and the output will reflect those updated values.

rx([obj])

rx allows wrapping objects and then operating on them interactively while recording any operations applied to them.

These methods and properties are available under the .rx namespace of reactive expressions (rx).

bool()

__bool__ cannot be implemented so it is provided as a method.

in_(other)

Replacement for the in statement.

is_(other)

Replacement for the is statement.

is_not(other)

Replacement for the is not statement.

len()

__len__ cannot be implemented so it is provided as a method.

pipe(func, /, *args, **kwargs)

Apply chainable functions.

updating()

Returns a new expression that is True while the expression is updating.

when(*dependencies[, initial])

Returns a reactive expression that emits the contents of this expression only when the dependencies change.

where(x, y)

Returns either x or y depending on the current state of the expression, i.e. replaces a ternary if statement.

value

Returns the current state of the reactive expression by evaluating the pipeline.

watch([fn, onlychanged, queued, precedence])

Adds a callable that observes the output of the pipeline.

Parameterized objects#

Parameterized

Base class for named objects that support Parameters and message formatting.

ParameterizedFunction

Acts like a Python function, but with arguments that are Parameters.

Parameterized helpers#

param.parameterized.Event(what, name, obj, ...)

Object representing an event that triggers a Watcher.

param.parameterized.Watcher(*args, **kwargs)

Object declaring a callback function to invoke when an Event is triggered on a watched item.

batch_watch(parameterized[, enable, run])

param.parameterized.batch_call_watchers(...)

Context manager to batch events to provide to Watchers on a parameterized object.

concrete_descendents(parentclass)

Return a dictionary containing all subclasses of the specified parentclass, including the parentclass.

depends(func, *dependencies[, watch, on_init])

Annotates a function or Parameterized method to express its dependencies.

discard_events(parameterized)

Context manager that discards any events within its scope triggered on the supplied parameterized object.

edit_constant(parameterized)

Temporarily set parameters on Parameterized object to constant=False to allow editing them.

output(func, *output, **kw)

output allows annotating a method on a Parameterized class to declare that it returns an output of a specific type.

param.parameterized.register_reference_transform(...)

Appends a transform to extract potential parameter dependencies from an object.

param.parameterized.resolve_ref(reference[, ...])

Resolves all parameters a dynamic reference depends on.

param.parameterized.resolve_value(value[, ...])

Resolves the current value of a dynamic reference.

script_repr(val[, imports, prefix, ...])

Variant of pprint() designed for generating a (nearly) runnable script.

Parameters#

Parameter

An attribute descriptor for declaring parameters.

String

A String Parameter, with a default value and optional regular expression (regex) matching.

Bytes

A Bytes Parameter, with a default value and optional regular expression (regex) matching.

Color

Color parameter defined as a hex RGB string with an optional # prefix or (optionally) as a CSS3 color name.

Boolean

Binary or tristate Boolean Parameter.

Event

An Event Parameter is one whose value is intimately linked to the triggering of events for watchers to consume.

Dynamic

Parameter whose value can be generated dynamically by a callable object.

Number

A numeric Dynamic Parameter, with a default value and optional bounds.

Integer

Numeric Parameter required to be an Integer

Magnitude

Numeric Parameter required to be in the range [0.0-1.0].

Tuple

A tuple Parameter (e.g.

NumericTuple

A numeric tuple Parameter (e.g.

XYCoordinates

A NumericTuple for an X,Y coordinate.

Range

A numeric range with optional bounds and softbounds.

Date

Date parameter of datetime or date type.

DateRange

A datetime or date range specified as (start, end).

CalendarDate

Parameter specifically allowing dates (not datetimes).

CalendarDateRange

A date range specified as (start_date, end_date).

List

Parameter whose value is a list of objects, usually of a specified type.

HookList

Parameter whose value is a list of callable objects.

Path

Parameter that can be set to a string specifying the path of a file or folder.

Filename

Parameter that can be set to a string specifying the path of a file.

Foldername

Parameter that can be set to a string specifying the path of a folder.

Selector

Parameter whose value must be one object from a list of possible objects.

FileSelector

Given a path glob, allows one file to be selected from those matching.

ListSelector

Variant of Selector where the value can be multiple objects from a list of possible objects.

MultiFileSelector

Given a path glob, allows multiple files to be selected from the list of matches.

ClassSelector

Parameter allowing selection of either a subclass or an instance of a class or tuple of classes.

Dict

Parameter whose value is a dictionary.

Array

Parameter whose value is a numpy array.

Series

Parameter whose value is a pandas Series.

DataFrame

Parameter whose value is a pandas DataFrame.

Callable

Parameter holding a value that is a callable object, such as a function.

Action

A user-provided function that can be invoked like a class or object method using ().

Composite

A Parameter that is a composite of a set of other attributes of the class.

Parameter helpers#

get_soft_bounds(bounds, softbounds)

For each soft bound (upper and lower), if there is a defined bound (not equal to None) and does not exceed the hard bound, then it is returned.

guess_bounds(params, **overrides)

Given a dictionary of Parameter instances, return a corresponding set of copies with the bounds appropriately set.

guess_param_types(**kwargs)

Given a set of keyword literals, promote to the appropriate parameter type based on some simple heuristics.

param_union(*parameterizeds[, warn])

Given a set of Parameterized objects, returns a dictionary with the union of all param name,value pairs across them.

ParamOverrides(overridden, dict_[, ...])

A dictionary that returns the attribute of a specified object if that attribute is not present in itself.

.param namespace#

These methods and properties are available under the .param namespace of Parameterized classes and instances.

add_parameter(param_name, param_obj)

Add a new Parameter object into this object's class.

debug(msg, *args, **kw)

Print msg merged with args as a debugging statement.

defaults()

Return {parameter_name:parameter.default} for all non-constant Parameters.

deserialize_parameters(serialization[, ...])

deserialize_value(pname, value[, mode])

force_new_dynamic_value(name)

Force a new value to be generated for the dynamic attribute name, and return it.

get_param_values([onlychanged])

Return a list of name,value pairs for all Parameters of this object.

get_value_generator(name)

Return the value or value-generating object of the named attribute.

inspect_value(name)

Return the current value of the named attribute without modifying it.

log(level, msg, *args, **kw)

Print msg merged with args as a message at the indicated logging level.

message(msg, *args, **kw)

Print msg merged with args as a message.

method_dependencies(name[, intermediate])

Given the name of a method, returns a PInfo object for each dependency of this method.

objects([instance])

Returns the Parameters of this instance or class

outputs()

Returns a mapping between any declared outputs and a tuple of the declared Parameter type, the output method, and the index into the output if multiple outputs are returned.

params([parameter_name])

Return the Parameters of this class as the dictionary {name: parameter_object}

params_depended_on(*args, **kwargs)

Given the name of a method, returns a PInfo object for each dependency of this method.

pprint([imports, prefix, unknown_value, ...])

(Experimental) Pretty printed representation that may be evaluated with eval.

print_param_defaults()

Print the default values of all cls's Parameters.

print_param_values()

Print the values of all this object's Parameters.

schema([safe, subset, mode])

Returns a schema for the parameters on this Parameterized object.

set_default(param_name, value)

Set the default value of param_name.

set_dynamic_time_fn(time_fn[, sublistattr])

Set time_fn for all Dynamic Parameters of this class or instance object that are currently being dynamically generated.

set_param(*args, **kwargs)

For each param=value keyword argument, sets the corresponding parameter of this object or class to the given value.

serialize_parameters([subset, mode])

serialize_value(pname[, mode])

trigger(*param_names)

Trigger watchers for the given set of parameter names.

unwatch(watcher)

Remove the given Watcher object (from watch or watch_values) from this object's list.

update([arg])

For the given dictionary or iterable or set of param=value keyword arguments, sets the corresponding parameter of this object or class to the given value.

values([onlychanged])

Return a dictionary of name,value pairs for the Parameters of this object.

verbose(msg, *args, **kw)

Print msg merged with args as a verbose message.

warning(msg, *args, **kw)

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

watch(fn, parameter_names[, what, ...])

Register the given callback function fn to be invoked for events on the indicated parameters.

watch_values(fn, parameter_names[, what, ...])

Easier-to-use version of watch specific to watching for changes in parameter values.

watchers

Dictionary of instance watchers.

Logging#

param.parameterized.get_logger([name])

param.parameterized.logging_level(level)

Temporarily modify param's logging level.

Serialization#

Classes used to support string serialization of Parameters and Parameterized objects.

param.serializer.JSONNullable(json_type)[source]#

Express a JSON schema type as nullable to easily support Parameters that allow_None

class param.serializer.JSONSerialization[source]#

Class responsible for specifying JSON serialization, deserialization and JSON schemas for Parameters and Parameterized classes and objects.

classmethod array_schema(p, safe=False)[source]#
classmethod calendardate_schema(p, safe=False)[source]#
classmethod class__schema(class_, safe=False)[source]#
classmethod classselector_schema(p, safe=False)[source]#
classmethod dataframe_schema(p, safe=False)[source]#
classmethod date_schema(p, safe=False)[source]#
classmethod declare_numeric_bounds(schema, bounds, inclusive_bounds)[source]#

Given an applicable numeric schema, augment with bounds information

classmethod deserialize_parameter_value(pobj, pname, value)[source]#

Deserialize a single parameter value.

classmethod deserialize_parameters(pobj, serialization, subset=None)[source]#

Deserialize a serialized object representing one or more Parameters into a dictionary of parameter values.

classmethod dict_schema(p, safe=False)[source]#
classmethod dumps(obj)[source]#
classmethod integer_schema(p, safe=False)[source]#
json_schema_literal_types = {<class 'int'>: 'integer', <class 'float'>: 'number', <class 'str'>: 'string', <class 'NoneType'>: 'null'}#
classmethod list_schema(p, safe=False)[source]#
classmethod listselector_schema(p, safe=False)[source]#
classmethod loads(serialized)[source]#
classmethod number_schema(p, safe=False)[source]#
classmethod numerictuple_schema(p, safe=False)[source]#
classmethod objectselector_schema(p, safe=False)[source]#
classmethod param_schema(ptype, p, safe=False, subset=None)[source]#
classmethod range_schema(p, safe=False)[source]#
classmethod schema(pobj, safe=False, subset=None)[source]#
classmethod selector_schema(p, safe=False)[source]#
classmethod serialize_parameter_value(pobj, pname)[source]#

Serialize a single parameter value.

classmethod serialize_parameters(pobj, subset=None)[source]#

Serialize the parameters on a Parameterized object into a single serialized object, e.g. a JSON string.

classmethod tuple_schema(p, safe=False)[source]#
unserializable_parameter_types = ['Callable']#
classmethod xycoordinates_schema(p, safe=False)[source]#
class param.serializer.Serialization[source]#

Base class used to implement different types of serialization.

classmethod deserialize_parameter_value(pobj, pname, value)[source]#

Deserialize a single parameter value.

classmethod deserialize_parameters(pobj, serialized, subset=None)[source]#

Deserialize a serialized object representing one or more Parameters into a dictionary of parameter values.

classmethod schema(pobj, subset=None)[source]#
classmethod serialize_parameter_value(pobj, pname)[source]#

Serialize a single parameter value.

classmethod serialize_parameters(pobj, subset=None)[source]#

Serialize the parameters on a Parameterized object into a single serialized object, e.g. a JSON string.

exception param.serializer.UnsafeserializableException[source]#
exception param.serializer.UnserializableException[source]#