puzzlepiece.piece module

class puzzlepiece.piece.Piece(puzzle=None, custom_horizontal=False, *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.

Parameters:

• puzzle – The parent Puzzle.

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

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

param_layout(wrap=1)

Genereates a QGridLayout for the params. Override to set a different wrapping.

Parameters:

wrap – the number of columns the params are displayed in .

Return type:

QtWidgets.QGridLayout

action_layout(wrap=2)

Genereates a QGridLayout for the actions. Override to set a different wrapping.

Parameters:

wrap – the number of columns the actions are displayed in.

Return type:

QtWidgets.QGridLayout

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_readouts()

Mostly deprecated.

Override to define readouts (params with getters). This is no different that defining them in define_params(), but may be a convenient way to organise the definitions within your custom class.

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)

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

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)

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

elevate()

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

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.

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().

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.