Tool

Description

Represents a generic Tool that can be attached to the Jubilee machine. Each Tool has a unique index, a name, and can be activated, configured, and associated with specific tool-specific behaviors. Designed to be subclassed for specialized tools (e.g., PipetteTool).

Constructor

Tool(index: int, name: str, **kwargs)

Initializes a Tool with a given tool index and name.

Parameter	Type	Description
index	int	Tool number assigned on the machine (matches config.g).
name	str	Human-readable name for the tool.
kwargs	dict	Any additional attributes to attach to the tool dynamically.

Key Properties

Property	Type	Description
index	int	The tool index number on the machine.
name	str	Name of the tool.
is_active_tool	bool	Whether the tool is currently active.
tool_offset	float or None	Z-offset value associated with the tool (from machine config).
_machine	Machine or None	Reference to the connected Machine object after loading.

Important Methods

Method	Returns	Description
post_load()	None	Called automatically after a tool is loaded. Can be overridden to customize behavior.

• Default post_load does nothing, but specialized tools (e.g., PipetteTool) can override it to perform actions like calibration checks.

Decorators

requires_active_tool

@requires_active_tool

Ensures that a method can only be executed if the tool is currently the active tool on the machine.

If not active, raises ToolStateError.

Associated Errors

Error Name	Description
ToolStateError	Raised when trying to operate a tool that is not active.
ToolConfigurationError	Raised if a tool is initialized with invalid parameters.

Short Example

from science_jubilee.tools import Tool

# Create a new tool instance
pipette = Tool(index=3, name="Pipette")

# Attach it to a machine and activate it
m.load_tool(pipette)
m.pickup_tool(pipette)

# Now pipette is the active tool and can be used safely

Important Notes

• The Tool class is designed to be minimal and flexible: specialized tools should subclass and extend it.
• is_active_tool must be True for operations that require physical movement or control.
• Dynamic attribute support via **kwargs allows attaching extra configuration (e.g., volume capacity for pipettes) without modifying the core class.

Related Concepts

• Machine
• Deck
• Pipette