puzzlepiece.piece module

class puzzlepiece.piece.Piece(puzzle=None, custom_horizontal=None, param_defaults=None, *args, **kwargs)

Bases: QGroupBox

A single Piece object is an unit of automation - an object that is meant to represent a single physical instrument (like a laser) or a particular functionality (like a plotter or a parameter scan).

Pieces can be assembled into a Puzzle using the Puzzle’s add_piece() method.

Create custom Pieces by inheriting from this class, and overriding define_params(), define_actions(), and custom_layout().

Parameters:

• puzzle – The parent Puzzle.

• custom_horizontal – Display the custom layout to the right of the main controls. (Deprecated, use custom_horizontal).

• param_defaults – An optional dictionary of default param values. These will be set without calling the corresponding param setters or changed signals. See also param_defaults in puzzlepiece.puzzle.Puzzle.add_piece(),

puzzle

Reference to the parent Puzzle.

stop

Boolean flag. See call_stop()

params

A dictionary of this Piece’s params (see BaseParam). You can also directly index the Piece object with the param name.

Type:

dict

custom_horizontal = False

You can specify a couple options when creating your Piece:

class MyPiece(pzp.Piece):
    # These settings are optional
    custom_horizontal = True # Show your custom layout to the right of the params and actions
    param_wrap = 2 # The number of columns the params are displayed in
    action_wrap = 3 # The number of columns the actions are displayed in

param_wrap = 1

See above (custom_horizontal).

action_wrap = 2

See above (custom_horizontal).

custom_layout()

Override to generate a custom QLayout that this Piece will display.

Return type:

QtWidgets.QLayout

define_params()

Override to define params using decorators from puzzlepiece.param.

define_actions()

Override to define actions using decorators from puzzlepiece.action.

setup()

Only called if the Puzzle debug flag is False. Override to set up necessary hardware libraries.

open_popup(popup, name=None, modal=True)

Open a popup window for this Piece. A popup is a puzzlepiece.piece.Popup object, which is like a Piece but floats in a separate window attached to the main Puzzle. This can be used for handling additional tasks that you don’t want to clutter the main Piece. See puzzlepiece.piece.Popup for details on implementing a Popup.

Parameters:

• popup – a puzzlepiece.piece.Popup _class_ to instantiate

• name – text to show as the window title

• modal – if True, the Popup will be attached to the Puzzle, always appearing with it and without a taskbar entry. If False, it will be an independent window that can be minimised.

Return type:

puzzlepiece.piece.Popup

call_stop()

This method is called by the parent Puzzle when a global stop is called.

By default, it sets the stop flag to True. Detect the flag in you code to stop processes.

Alternatively, this can be overriden to support more complex actions.

handle_close(event=None)

Only called if the Puzzle debug flag is False. Override to disconnect hardware etc when the main window closes.

If there is a param with the name “connected”, it will be set to False in this method by default (see puzzlepiece.param.connect() and puzzlepiece.param.connect() for hardware connection handling).

elevate()

If this Piece resides in a Folder, this method switches the tab to make this Piece visible.

toggle_pop_out()

Pop this Piece out of the Puzzle into its own modal window.

puzzlepiece.piece.ensurer(ensure_function)

An ensurer is a decorator that can be placed on getters, setters, and actions, and it will run ahead of these functions. The intended behaviour is performing checks ahead of running the function - for example checking if a laser is connected ahead of trying to set its power. This way one ensurer can be written and used in multiple places easily.

Note that the method being decorated should raise an exception if the check fails! This way execution will stop if the condition is not met. This is not mandatory though - custom behaviour is allowed.

For example, an ensurer can be defined as a Piece’s method (in the main body of the class).:

@puzzlepiece.piece.ensurer
def _ensure_connected(self):
    if not self.params['connected'].get_value():
        raise Exception('Laser not connected')

This can then be used when defining a param (below the param-defining decorator):

@puzzlepiece.param.spinbox(self, 'power', 0.)
@self._ensure_connected
def power(self, value):
    self.laser.set_power(value)

@puzzlepiece.param.spinbox(self, 'wavelength', 0.)
@self._ensure_connected
def wavelength(self, value):
    self.laser.set_wavelength(value)

It can also be called directly if preferred, optionally with capture_exception=True which will return True if the check passes, or False if the check raises an Exception:

# This should raise an Exception is the check fails
self._ensure_connected()

# This will not raise an Exception is the check fails
if self._ensure_connected(capture_exception=True):
    print("laser is connected!")

class puzzlepiece.piece.Popup(parent_piece, puzzle, custom_horizontal=False, *args, **kwargs)

Bases: Piece

A Popup is similar to a Piece, but floats in a separate window attached to the main Puzzle. This can be used for handling additional tasks that you don’t want to clutter the main Piece. For example you can have a camera Piece which can open a Popup to set the camera’s region of interest with an interactive plot window.

A Popup can be created and displayed by calling puzzlepiece.piece.Piece.open_popup().

A Popup is attached to a specific Piece and knows it through its parent_piece attribute, but it can also access other Pieces through the Puzzle, which it knows through its puzzle attribute.

A Popup can have params, actions, and custom layouts just like a normal Piece, and are created by overriding define_params(), define_actions(), and custom_layout() like for a Piece.

You can access the QDialog the Popup resides in by using its parent() method (a general method that all QWidgets have).

Parameters:

• puzzle – The parent Puzzle.

• parent_piece – The parent Piece.

• custom_horizontal – A bool, the custom layout is displayed to the right of the main controls if True.

property parent_piece

A reference to this Popup’s parent Piece, the one that created it through puzzlepiece.piece.Piece.open_popup().

add_child_params(param_names)

Given a list of param names referring to params of the parent Piece, add corresponding child params to this Popup.

This lets you quickly make a Settings popup that adjusts the hidden params of a Piece.

See puzzlepiece.param.BaseParam.make_child_param() for details.

Parameters:

param_names – List of the parent_piece’s param names to make children from.

add_invisible_params()

Add all hidden params from the parent Piece to this Popup. This lets you quickly make a Settings popup that adjusts the hidden params of a Piece.

See puzzlepiece.param.BaseParam.make_child_param() for details, as well as puzzlepiece.action.settings() for a quick way to define a Settings Popup.

add_child_actions(action_names)

Given a list of action names referring to actions of the parent Piece, add corresponding child actions to this Popup.

This lets you surface additional actions in a Popup without cluttering the main Piece.

See puzzlepiece.action.Action.make_child_action() for details.

Parameters:

action_names – List of the parent_piece’s action names to make children from.

add_invisible_actions()

Add all hidden actions from the parent Piece to this Popup. This lets you quickly make a Settings popup that displays additional actions for a Piece.

See puzzlepiece.param.BaseParam.make_child_action() for details, as well as puzzlepiece.action.settings() for a quick way to define a Settings Popup.

close()

Close the popup.

handle_close()

Called when the Popup is closed. Override to perform actions when the user closes this Popup - for example delete related plot elements.

In contrast to puzzlepiece.piece.Piece.handle_close(), this is called even if the Puzzle debug flag is True.