Getting Started

Installing the SDK

The easiest way to get the Scrutiny Python SDK is to use pip.

pip install scrutinydebugger

After the installation, the SDK should be usable as well as all the other features (CLI, GUI, Server)`.

---

Quick introduction

Using the Scrutiny Python SDK starts by creating a ScrutinyClient object and connecting it to a running server.

from scrutiny import sdk
from scrutiny.sdk.client import ScrutinyClient

hostname = 'localhost'
port = 1234
client = ScrutinyClient()
with client.connect(hostname, port, wait_status=True):    # Establish a connection and wait for a first server status update
    print("Connected to server")
    server_status = client.get_server_status()       # Status is dynamic and updated by a background thread. Get an immutable reference
    if server_status.device_comm_state == sdk.DeviceCommState.ConnectedReady:
        print(f"Connected to device {server_status.device.display_name} ({server_status.device.session_id})")
    else:
        print("No device connected to the server")

Most operations with the Python SDK are synchronized, meaning they will block until completion. When relevant for performance, some operations will return a reference to a future object that can be waited for when necessary.

Operations that fail raise an exception. All exceptions defined in the Scrutiny SDK inherit the sdk.ScrutinySDKException.

See the Exceptions page

---

class scrutiny.sdk.client.ScrutinyClient

High-level client for communicating with a Scrutiny server over TCP.

Provides a thread-safe API to connect, watch variables, read/write memory, trigger datalogging, manage SFD files, and receive asynchronous events. A background worker thread handles all socket I/O and server message dispatch.

__init__(name=None, rx_message_callbacks=None, timeout=4.0, write_timeout=5.0, enabled_events=0)

Creates a client that can communicate with a Scrutiny server

Parameters:

• name (str | None) – Name of the client. Used for logging

• rx_message_callbacks (List[Callable[[ScrutinyClient, object], None]] | None) – A callback to call each time a server message is received. Called from a separate thread. Mainly used for debugging and testing

• timeout (float) – Default timeout to use when making a request to the server

• write_timeout (float) – Default timeout to use when writing to the device memory

• enabled_events (int) – A flag value constructed by ORing values from ScrutinyClient.Events. Can be changed later by invoking listen_events. See Using events for more details

---

Some methods will return an instance of a PendingRequest. These instances are handled to follow the progress of an operation that may take long time to execute.

class scrutiny.sdk.pending_request.PendingRequest

Base class for future-like request handles returned to the user.

Tracks the lifecycle of an asynchronous server request: whether it is still in flight, whether it succeeded or failed, and the reason for any failure. Subclasses add domain-specific result data on top of this common infrastructure.

wait_for_completion(timeout=None)

Wait for the request to complete

Params timeout:

Maximum wait time in seconds. Waits forever if None

Raises:

• TimeoutException – If the request does not complete in less than the specified timeout value

• OperationFailure – If an error happened that prevented the request to successfully complete

Parameters:

timeout (float | None) –

Return type:

None

property completed: bool

Indicates whether the request has completed or not

property is_success: bool

Indicates whether the request has successfully completed or not

property completion_datetime: datetime | None

The time at which the request has been completed. None if not completed yet

property failure_reason: str

When the request failed, this property contains the reason for the failure. Empty string if not completed or succeeded