puzzlepiece.puzzle module

class puzzlepiece.puzzle.Puzzle(app=None, name='Puzzle', debug=True, bottom_buttons=True, *args, **kwargs)[source]

Bases: QWidget

A container for puzzlepiece.piece.Piece objects, meant to be the main QWidget (window) of an automation application. It keeps track of the Piece objects it contains and lets them communicate.

Parameters:

app – A QtApp created to contain this QWidget.
name – A name for the window.
debug (bool) – Sets the Puzzle.debug property, if True the app should launch in debug mode and Pieces shouldn’t communicate with hardware.
bottom_buttons (bool) – Whether the bottom buttons of the Puzzle (Tree, Export, STOP) should be shown.

property pieces

A PieceDict, effectively a dictionary of Piece objects. Can be used to access Pieces from within other Pieces.

You can also directly index the Puzzle object with the Piece name.

property globals: A dictionary, can be used for API modules that need to be shared by multiple Pieces.

property debug: A bool flag. Pieces should act in debug mode if True.

add_piece(name, piece, row, column, rowspan=1, colspan=1)[source]

Adds a Piece to the grid layout, and registers it with the Puzzle.

Parameters:

name – Identifying string for the Piece.
piece – A Piece object or a class defining one (which will be automatically instantiated).
row – Row index for the grid layout.
column – Column index for the grid layout.
rowspan – Height in rows.
column – Width in columns.

Return type:

puzzlepiece.piece.Piece

add_folder(row, column, rowspan=1, colspan=1)[source]

Adds a tabbed Folder to the grid layout, and returns it.

Parameters:

row – Row index for the grid layout.
column – Column index for the grid layout.
rowspan – Height in rows.
column – Width in columns.

Return type:

puzzlepiece.puzzle.Folder

register_piece(name, piece)[source]: Registers a Piece object with the Puzzle. This is done by default when a Piece is added with add_piece(), puzzlepiece.puzzle.Folder.add_piece(), or puzzlepiece.puzzle.Grid.add_piece(), so this method should rarely be called manually.

process_events()[source]: Forces the QApplication to process events that happened while a callback was executing. Can for example update plots while a long process is running, or run any keyboard shortcuts pressed while proecessing.

run_worker(worker)[source]: Add a Worker to the Puzzle’s Threadpool and runs it. See puzzlepiece.threads for more details on how to set up a Worker.

custom_excepthook(exctype, value, traceback)[source]: Override or replace this method to call a custom handler whenever an exception is raised. This will run after the defatult exception handler (sys.__excepthook__), but before a GUI alert is displayed.

run(text)[source]: Execute script commands for this Puzzle as described in puzzlepiece.parse.run().

get_values(text)[source]

Get the values from multiple params as a list.

Parameters:: text – A string of comma-separated param strings as described in puzzlepiece.parse.parse_params().
Return type:: list

record_values(text, dictionary=None)[source]

Get the values from multiple params and record them in a dictionary. Useful for storing metadata about a measurement.

Parameters:

text – A string of comma-separated param strings as described in puzzlepiece.parse.parse_params().
dictionary – If provided, this function will write the param names and values to this dictionary. Otherwise, a new one is created and returned.

Return type:

dict

puzzlepiece.puzzle.QApp: A QApplication has to be constructed before any Qt objects (including the Puzzle and the Pieces), so this is a convenient shortcut to the QApplication class (see https://doc.qt.io/qt-6/qapplication.html).

class puzzlepiece.puzzle.Folder(puzzle, *args, **kwargs)[source]

Bases: QTabWidget

A tabbed group of Piece or Grid objects within the Puzzle.

Best created with puzzlepiece.puzzle.Puzzle.add_folder().

add_piece(name, piece)[source]

Adds a Piece as a tab to this Folder, and registers it with the parent Puzzle.

Parameters:

name – Identifying string for the Piece.
piece – A Piece object or a class defining one (which will be automatically instantiated).

Return type:

puzzlepiece.piece.Piece

add_grid(name)[source]

Adds a Grid as a tab to this Folder.

Parameters:: name – Identifying string for the Grid.
Return type:: puzzlepiece.puzzle.Grid

class puzzlepiece.puzzle.Grid(puzzle, *args, **kwargs)[source]

Bases: QWidget

A grid layout for Piece objects. For when you need multiple Pieces within a single Folder tab.

Best created with puzzlepiece.puzzle.Puzzle.add_folder().

add_piece(name, piece, row, column, rowspan=1, colspan=1)[source]

Adds a Piece to the grid layout, and registers it with the parent Puzzle.

Parameters:

name – Identifying string for the Piece.
piece – A Piece object or a class defining one (which will be automatically instantiated).
row – Row index for the grid layout.
column – Column index for the grid layout.
rowspan – Height in rows.
column – Width in columns.

Return type:

puzzlepiece.piece.Piece

class puzzlepiece.puzzle.PieceDict[source]

Bases: object

A dictionary wrapper that enforces single-use of keys, and raises a more useful error when a Piece tries to use another Piece that hasn’t been registered.

keys()[source]

class puzzlepiece.puzzle.Globals[source]

Bases: object

A dictionary wrapper used for puzzlepiece.puzzle.Puzzle.globals. It behaves like a dictionary, allowing puzzlepiece.piece.Piece objects to share device APIs with each other.

Additionally, require() and release() can be used to keep track of the Pieces using a given variable, so that the API can be loaded once and then unloaded once all the Pieces are done with it.

require(name)[source]

Register that a Piece is using the variable with a given name. This will increase an internal counter to indicate the Piece having a hold on the variable.

Returns False if this is the first time a variable is being registered (and thus setup is needed) or True if the variable has been registered already.

For example, this can be used within setup():

def setup(self):
    if not self.puzzle.globals.require('sdk'):
        # Load the SDK if not done already by a different Piece
        self.puzzle.globals['sdk'] = self.load_sdk()

Parameters:: name – a dictionary key for the required variable
Return type:: bool

release(name)[source]

Indicate that a Piece is done using the variable with a given name. This will decrease an internal counter to indicate the Piece is releasing its hold on the variable.

Returns False if the counter is non-zero (so different Pieces are still using this variable) or True if all Pieces are done with the variable (in that case the SDK can be safely shut down for example).

For example, this can be used within handle_close():

def handle_close(self):
    if self.puzzle.globals.release('sdk'):
        # Unload the SDK if all Pieces are done with it
        self.puzzle.globals['sdk'].stop()

Parameters:: name – a dictionary key for the variable being released
Return type:: bool

keys()[source]

class puzzlepiece.puzzle.PretendPuzzle[source]

Bases: object

A placeholder object used if no Puzzle is provided when creating a puzzlepiece.puzzle.Piece. Its debug attribute is always True.

debug = True

process_events()[source]: Like puzzlepiece.puzzle.Puzzle.process_events().