puzzlepiece.param module

class puzzlepiece.param.BaseParam(name, value, setter=None, getter=None, visible=True, format='{}', _type=None, piece=None, *args, **kwargs)[source]

Bases: QWidget

A param object represents a gettable/settable value within a Piece. This can be a general variable for some operation, a setting of a physical device (like laser power), a readout from a physical device (counts from a spectrometer), or something that can be measured and set (the position of a movable stage).

A general param is just a variable with a GUI presence (if needed) that can be read from and written to by Pieces. It can then have getter and setter functions that are called when you get/set the value of the param.

To set and get the value of the param, use the set_value() and get_value() methods.

In most cases, you will not instantiate a param directly, but rather use decorators defined within this module (like puzzlepiece.param.spinbox() ) to register params within a Piece’s define_params() method.

Parameters:

name – A unique (per Piece) id name for the param
value – Default value (can be None)
setter – A function to be called when setting the param, taking the value as argument. It may return a new value.
getter – A function to be called when obtaining the value of the param, raturning the new value.
visible – If True, the Piece will generate display a GUI component for the param.
format – Default format for displaying the param if a custom input is not defined, and in puzzplepiece.parse.format(). For example {:.2f}, see https://pyformat.info/ for further details.
_type – int, float, str etc - the type of the param value. Can be inferred if a default value is passed.
piece – The parent Piece, can be None (currently only used for threaded sets and gets).

changed: A Qt signal emitted when the value changes

set_value(value=None, skip_setter=False, skip_getter=False)[source]

Set the value of the param. If a setter is registered, it will be called.

If the setter returns a value, this will become the new value of this param.

If the setter doesn’t return a value, the getter will be called if present, and the value it returns will become the new value of this param.

If the setter doesn’t return a value, and there is no getter, the value provided as an argument will become the new value of this param

Parameters:

value – The value this param should be set to (if None, we grab the value from the param’s input box.)
skip_setter – Skips the param’s setter and sets the internal value directly.
skip_getter – Skips the param’s getter and sets the internal value directly.

Returns:

The new value of the param.

get_value()[source]

Get the value for this param. If a getter is registered, it will be called, and the returned value becomes the params new value, and is returned by this method.

Returns:: Value of the param (retuned by the getter if registered, otherwise the value currently stored by the param).

set_value_threaded(value=None, skip_setter=False, skip_getter=False)[source]

Call set_value() in a thread. While set_value() itself is by default threadsafe, the setter/getter may not be depending on the user’s implementation. See puzzlepiece.threads for further notes, and be mindful when using this.

Can also be called by holding control while clicking the set button or pressing enter in a param’s input box.

Parameters:

value – The value this param should be set to (if None, we grab the value from the param’s input box.)
skip_getter – Skips the param’s getter and sets the internal value directly.
skip_getter – Skips the param’s getter and sets the internal value directly.

get_value_threaded()[source]

Call get_value() in a thread. While get_value() itself is by default threadsafe, the getter may not be depending on the user’s implementation. See puzzlepiece.threads for further notes, and be mindful when using this.

Can also be called by holding control while clicking the set button or pressing enter in a param’s input box.

set_setter(piece)[source]: Create a decorator to register a setter for this param. This would be used within puzzlepiece.piece.Piece.define_params() as @param.set_setter(self) decorating a function.

set_getter(piece)[source]: Create a decorator to register a getter for this param. This would be used within puzzlepiece.piece.Piece.define_params() as @param.set_getter(self) decorating a function.

property value: Current, internally stored value. The getter is not called when this property is accessed.

_make_input(value=None, connect=None)[source]

Create an input box for the GUI display of this param. This should be overriden to implement custom param display types (like the spinboxes, text inputs, and checkboxes provided by default).

Parameters:

value – The value to put into the input box by default.
connect – A function that will be connected to the value changed signal of the input.

Return type:

(QWidget - input box, bool - whether a setter button is needed)

_input_set_value(value)[source]

Set the value of the input box. This should be overriden to implement custom param display types.

As this is a low-level method used internally, it should not emit valueChanged signals for its input box. To stop this from happening, use Qt’s blockSignals method:

self.input.blockSignals(True)
self.input.setText(value)
self.input.blockSignals(False)

_input_get_value()[source]

Set the value of the input box. This should be overriden to implement custom param display types.

Return type:: Should return the velue with correct type, as specified by self._type

make_child_param(kwargs=None)[source]

Create and return a child param. The child will be of the same type as the parent - a checkbox, spinbox, etc.

The child param will keep in sync with the parent, and you can have multiple child params active at any time. The parent’s getter will be called when you get_value() on the child. The parent’s setter will be called when you set_value() on a child.

You may need to override this method when creating BaseParam subclasses that have a different call signature for __init__. Additional arguments can then be provided with kwargs.

See puzzlepiece.piece.Popup.add_child_params() for a quick way of adding child params to a Popup.

Parameters:: kwargs – Additional arguments to pass to __init__ when creating the child.

set_group(group)[source]

Make this param a part of a named group. Params that share a group name are displayed together in a frame. This only has an effect when called before the Piece layout is constructed, so should be called in puzzlepiece.piece.Piece.define_params().

In most cases it’s easier to use the puzzlepiece.param.group() decorator - check its documentation for more details on grouping.

property type: The fixed type of this param. The values set with puzzlepiece.param.BaseParam.set_value() will be cast to this type, and those returned by puzzlepiece.param.BaseParam.get_value() will be of this type.

property visible: Bool flag indicating whether the param is displayed in the GUI.

class puzzlepiece.param.ParamInt(name, value, v_min, v_max, setter, getter=None, visible=True, v_step=1, *args, **kwargs)[source]

Bases: BaseParam

A param with an integer input field. See the spinbox() decorator below for how to use this in your Piece.

class puzzlepiece.param.ParamFloat(name, value, v_min, v_max, setter, getter=None, visible=True, v_step=1, *args, **kwargs)[source]

Bases: ParamInt

A param with a float input field. See the spinbox() decorator below for how to use this in your Piece.

class puzzlepiece.param.ParamSlider(name, value, v_min, v_max, setter, getter=None, visible=True, v_step=1, *args, **kwargs)[source]

Bases: ParamFloat

A param with a slider, float or int depending on provided value and step. See the slider() decorator below for how to use this in your Piece.

class puzzlepiece.param.ParamText(name, value, setter=None, getter=None, visible=True, format='{}', _type=None, piece=None, *args, **kwargs)[source]

Bases: BaseParam

A param with a text input field. See the text() decorator below for how to use this in your Piece.

class puzzlepiece.param.ParamCheckbox(name, value, setter, getter=None, visible=True, *args, **kwargs)[source]

Bases: BaseParam

A param with a checkbox input field. See the checkbox() decorator below for how to use this in your Piece.

This param runs puzzlepiece.param.Param.set_value() automatically when the checkbox is pressed, so an additional setter button is not displayed.

class puzzlepiece.param.ParamArray(name, value, setter=None, getter=None, visible=True, _type=None, *args, **kwargs)[source]

Bases: BaseParam

A param that stores a numpy array. There is no GUI input, the Param simply displays the dimensions of the array, and indicates when the data has been updated.

The array can be modified through programmatic interaction with setter or getter functions (for example the array can be obtained from a hardware spectrometer), or treated as a variable and set using set_value().

property set_partial

Use this property to set values to slices of the stored numpy array, using any slicing methods that a numpy array accepts:

puzzle['piece'].params['image'].set_partial[100:200, :] = 128

This will call the param’s setter if there’s one, and in general acts like set_value().

class puzzlepiece.param.ParamDropdown(name, value, values, setter=None, getter=None, visible=True, *args, **kwargs)[source]

Bases: BaseParam

A param storing a string that also provides a dropdown. The user can edit the text field directly, and pressing enter will add the current value to the dropdown. A list of values can also be provided when creating this param, and they will populate the dropdown as soon as the app starts.

The default param value provided here as value will either be selected from the dropdown if in values, or inserted into the text field as if a user typed it if not in values.

Parameters:: values – List of default values available in the dropdown (can be None)

make_child_param(kwargs=None)[source]

Create and return a child param. The child will be of the same type as the parent - a checkbox, spinbox, etc.

The child param will keep in sync with the parent, and you can have multiple child params active at any time. The parent’s getter will be called when you get_value() on the child. The parent’s setter will be called when you set_value() on a child.

You may need to override this method when creating BaseParam subclasses that have a different call signature for __init__. Additional arguments can then be provided with kwargs.

See puzzlepiece.piece.Popup.add_child_params() for a quick way of adding child params to a Popup.

Parameters:: kwargs – Additional arguments to pass to __init__ when creating the child.

class puzzlepiece.param.ParamProgress(name, value, setter=None, getter=None, visible=True, format='{}', _type=None, piece=None, *args, **kwargs)[source]

Bases: BaseParam

A param with a progress bar. See the progress() decorator below for how to use this in your Piece.

iter(iterable)[source]

Iterable wrapper that automatically updates the progress bar while the provided iterable is iterated over. This is quite similar to how the console progress bar tqdm works: https://tqdm.github.io/

For example:

for i in piece.params['progress'].iter(range(10)):
    print(i)
    # this will automatically update the progress bar as the iteration goes on
    puzzle.process_events() # you may need to refresh the Puzzle to display changes

Parameters:: iterable – an iterable to wrap
Return type:: iterable

class puzzlepiece.param.ParamConnected(name='connected', visible=True, *args, **kwargs)[source]

Bases: BaseParam

A param with for establishing a connection to hardware. See the connect() and disconnect() decorators below for how to use this in your Piece.

You can also instance this param directly, but this is needed only if multiple instances are required, in which case they can’t all be called “connected” (the default):

def define_params(self):
    self.params["another_connection"] = pzp.param.ParamConnected("another_connection", piece=self)
    @self.params["another_connection"].set_connect
    def connect():
        print("Connecting...")

set_connect(function)[source]

Sets the connecting function, can be used as a decorator. See connect().

Parameters:: function – a method that will be called when the param is set to True. It should take no arguments.

set_disconnect(function)[source]

Sets the disconnecting function, can be used as a decorator. See disconnect().

Parameters:: function – a method that will be called when the param is set to False. It should take no arguments.

puzzlepiece.param.base_param(piece, name, value, visible=True, format='{}')[source]

A decorator generator for registering a BaseParam in a Piece’s define_params() method with a given setter.

This will simply display the current value with no option to edit it.

To register a param and mark a function as its setter, do this:

@puzzlepiece.param.base_param(self, 'param_name', 0)
def param_setter(value):
    print(self, value)

To register a param without a setter, call this function to get a decorator, and then pass None to that to indicate that a setter doesn’t exist:

puzzlepiece.param.base_param(self, 'param_name', 0)(None)

Some of the decorators here decorate getters, and some decorate setters, depending on what is the more sensible default – a readout() decorates a getter, as it is meant to display obtained values, and a spinbox() decorates a setter, as it’s meant to be an easy way to input and set values. If you need to also register the other function, use the puzzlepiece.param.BaseParam.set_getter() and puzzlepiece.param.BaseParam.set_setter() decorators:

@puzzlepiece.param.base_param(self, 'position', 0)
def position(value):
    self.sdk.set_position(value)

@position.set_getter(self)
def position():
    return self.sdk.get_position()

It’s also allowed to provide “self” as the first argument of the setter/getter method for added clarity, but since self exists locally within define_params() this is technically not required:

@puzzlepiece.param.base_param(self, 'param_name', 0)
def param_setter(self, value):
    print(self, value)

Parameters:

piece – The Piece this param should be registered with. Usually self, as this method should be called from within puzzlepiece.piece.Piece.define_params()
name – a unique (per Piece) name for the param
value – default display value for the param. If there is a setter, the setter will not be called, and the stored value will remain None until the param is explicitly set (either through set_value(), or pressing the set button.)
visible – bool flag, determined if a GUI component will be shown for this param.
format – Default format for displaying the param if a custom input is not defined, and in puzzplepiece.parse.format(). For example {:.2f}, see https://pyformat.info/ for further details.

Returns:

A decorator that can be applied to a setter function. The decorator returns the param object when called.

puzzlepiece.param.readout(piece, name, visible=True, format='{}', _type=None)[source]

A decorator generator for registering a BaseParam in a Piece’s define_params() method with a given getter.

This will simply display the current value with no option to edit it.

See base_param() for more details.

puzzlepiece.param.spinbox(piece, name, value, v_min=-1000000000.0, v_max=1000000000.0, visible=True, v_step=1)[source]

A decorator generator for registering a ParamInt or ParamFloat in a Piece’s define_params() method with a given setter.

The type of param registered depends on whether the value given is an int of a float.

This will display a Qt spinbox - a numeric input box.

See base_param() for more details.

Parameters:

v_min – The minimum value accepted by the spinbox.
v_max – The maximum value accepted by the spinbox.
v_step – The step change when spinbox buttons are used.

puzzlepiece.param.slider(piece, name, value, v_min=0, v_max=1, visible=True, v_step=0.05)[source]

A decorator generator for registering a ParamSlider in a Piece’s define_params() method with a given setter.

This will display a slider with the specified properties and a label. It will be an int or a float slider depending on the type of the values provided here.

See base_param() for more details.

puzzlepiece.param.text(piece, name, value, visible=True)[source]

A decorator generator for registering a ParamText in a Piece’s define_params() method with a given setter.

This will display a single line textbox.

See base_param() for more details.

puzzlepiece.param.checkbox(piece, name, value, visible=True)[source]

A decorator generator for registering a ParamCheckbox in a Piece’s define_params() method with a given setter.

This will display a checkbox as the input, and the param takes the values 0 and 1 for unchecked and checked states.

This param runs puzzlepiece.param.Param.set_value() automatically when the checkbox is pressed, so an additional setter button is not displayed.

See base_param() for more details.

puzzlepiece.param.array(piece, name, visible=True)[source]

A decorator generator for registering a ParamArray in a Piece’s define_params() method with a given getter.

This will display the shape of the stored array with no option to edit it and an indicator showing when the value changes.

See base_param() for more details.

puzzlepiece.param.dropdown(piece, name, value, visible=True)[source]

A decorator generator for registering a ParamDropdown in a Piece’s define_params().

It should decorate a function that returns a list of default values to populate the dropdown, for example:

@puzzlepiece.param.dropdown(self, 'param_name', '')
def param_values():
    return self.sdk.discover_devices()

It can also be used with a set list of defaults, or with no defaults at all:

puzzlepiece.param.dropdown(self, 'param_name', 'one')(['one', 'two', 'three'])
puzzlepiece.param.dropdown(self, 'param_name', 'four')(None)

Setters and getters can then be added using puzzlepiece.param.BaseParam.set_getter() and puzzlepiece.param.BaseParam.set_setter() decorators:

@puzzlepiece.param.dropdown(self, 'serial_number', '')
def serial_number():
    return self.sdk.discover_devices()

@serial_number.set_getter(self)
def serial_number():
    return self.sdk.get_serial()

@serial_number.set_setter(self)
def serial_number(value):
    return self.sdk.set_serial(value)

The returned param displays a dropdown and stores a string. The user can edit the dropdown’s text field directly, and pressing enter will add the current value to the dropdown.

The default param value provided here as value will either be selected from the dropdown if available, or inserted into the text field as if a user typed it otherwise.

puzzlepiece.param.progress(piece, name, visible=True)[source]

A decorator generator for registering a ParamProgress in a Piece’s define_params() method with a given getter.

This will display the current progress value on a scale of 0 to 1 with no option to edit it.

See base_param() for more details.

puzzlepiece.param.connect(piece, visible=True)[source]

A decorator generator that creates/updates a ParamConnected for a Piece, with a given connect function. It should be called within define_params().

A red/green connect button will be shown in the Piece, and the connection can be made/unmade by setting the “connected” param to True/False.

Use in combination with disconnect() to create the connect/disconnect flow for your hardware:

def define_params(self):
    @pzp.param.connect(self)
    def connect():
        if self.puzzle.debug:
            return True
        print("Connecting...")
        return True

    @pzp.param.disconnect(self)
    def disconnect():
        if self.puzzle.debug:
            # Return False to acknowledge that disconnecting was successful
            return False
        print("Connecting...")
        return False

See base_param() for more details on using decorators to register params.

puzzlepiece.param.disconnect(piece, visible=True)[source]

A decorator generator that creates/updates a ParamConnected for a Piece, with a given disconnect function. It should be called within define_params().

See disconnect() for more details on establishing the connection flow, and base_param() for more details on using decorators to register params.

puzzlepiece.param.group(name)[source]

Decorator that makes a param a part of a named group. Params that share a group name are displayed together in a frame. This only has an effect when called before the Piece layout is constructed, so should be done in puzzlepiece.piece.Piece.define_params().

This decorator should be added above the main param-defining decorator, for example (within define_params()):

@pzp.param.group("name")
@pzp.param.text(self, "test1", "")
def test1(value):
    print(value)

# If there is no setter/getter, we can use `set_group` directly:
pzp.param.text(self, "test2", "")(None)
self["test2"].set_group("name")