Errors¶

The imperix Python library reports most failures by raising an exception, which identifies the type of problem and provides a message explaining what went wrong. In the API reference, each function’s Raises section lists the main errors that can occur during that operation.

Handling errors¶

A script can handle an error and continue running using try and except. If an operation inside try raises the exception named in except, Python runs the code in that except block.

In the example below, if the target cannot be found, the script refreshes the target list and tries again:

from imperix import Cockpit, NotFoundError

TARGET_MAC = "AA:BB:CC:DD:EE:FF"

with Cockpit() as cockpit:
   try:
      target = cockpit.targets[TARGET_MAC]
   except NotFoundError:
      cockpit.targets.refresh()
      # If the target is still not found, the script stops and reports the error.
      target = cockpit.targets[TARGET_MAC]

Disabling PWM when an error occurs¶

An error can stop an experiment before the script reaches the code to disable PWM. Place the experiment code under try and the code to disable PWM under finally so Python runs it whether the experiment finishes normally or is interrupted by an error:

try:
   project.enable_pwm()
   # Run the experiment
finally:
   project.disable_pwm()

API Reference¶

class imperix.CockpitError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Base class for all imperix library exceptions.

Parameters:

message – Human-readable error message.
code – JSON-RPC error code, when available.
data_code – Cockpit-specific error code, when available.
data_details – Additional error details returned by Cockpit.

code¶: JSON-RPC error code, or None.

data_code¶: Cockpit-specific error code, or None.

data_details¶: Additional structured details, or None.

class imperix.CockpitConnectionError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Raised when the library cannot start, connect to, or communicate with Cockpit.

This also covers a connection that closes during an operation and a connection that cannot be closed cleanly.

class imperix.VersionMismatchError(*, python_library_version: str, sdk_version: str)¶: Raised when the Python library is older than the ACG/CPP SDK.

class imperix.VersionMismatchWarning(*, python_library_version: str, sdk_version: str)¶

Warns that the ACG/CPP SDK is older than the Python library.

The connection remains usable on a best-effort basis.

class imperix.BusyError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶: Raised when Cockpit is already connected to another script.

class imperix.InvalidParamsError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Raised when one or more inputs are not valid for the requested operation.

For example, the selected file format may not be supported or a number may be outside the allowed range.

class imperix.NotFoundError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶: Raised when a target, project, user variable, module, or data logger used by the script is not available in Cockpit.

class imperix.InvalidStateError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Raised when the requested operation is not allowed in the current state.

For example, a project may not have a target linked, user code may not be running, or a module may not be ready for the requested action.

class imperix.UnsupportedOperationError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Raised when Cockpit cannot perform the requested operation.

For example, the script may ask Cockpit to create a module type that it does not recognize, or use an action that is not available for that type of module. Some operations also require a newer version of the ACG or CPP SDK. If the installed SDK is too old, update it before trying again.

class imperix.TimeoutError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Raised when an operation does not finish within the allowed time.

For example, Cockpit may take too long to answer, or a condition passed to wait_until() may not become true before the timeout.