puzzlepiece.param module

class puzzlepiece.param.BaseParam(name, value, setter=None, getter=None, visible=True, format='{}', _type=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.

changed: A Qt signal emitted when the value changes

set_value(value=None)[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.)
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_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

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, *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)

class puzzlepiece.param.ParamProgress(name, value, setter=None, getter=None, visible=True, format='{}', _type=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

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(self, value):
    print(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(self, value):
    self.sdk.set_position(value)

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

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(self, value):
    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(self, value):
    return self.sdk.discover_devices()

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

@serial_number.set_setter(self)
def serial_number(self, 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.