Concrete Intermediate-level KATCP Client API (inspecting_client)¶

class katcp.inspecting_client.ExponentialRandomBackoff(delay_initial=1.0, delay_max=90.0, exp_fac=3.0, randomicity=0.95)¶

Bases: future.types.newobject.newobject

Methods

`ExponentialRandomBackoff.failed`()	Call whenever an action has failed, grows delay exponentially
`ExponentialRandomBackoff.next`()
`ExponentialRandomBackoff.success`()	Call whenever an action has succeeded, resets delay to minimum

exp_fac = None¶: Increase timeout by this factor for each consecutive failure

failed()¶

Call whenever an action has failed, grows delay exponentially

After calling failed(), the delay property contains the next delay

success()¶: Call whenever an action has succeeded, resets delay to minimum

class katcp.inspecting_client.InspectingClientAsync(host, port, ioloop=None, initial_inspection=None, auto_reconnect=True, logger=<logging.Logger object>)¶

Bases: future.types.newobject.newobject

Higher-level client that inspects a KATCP interface.

Note: This class is not thread-safe at present, it should only be called from the ioloop.

Note: always call stop() after start() and you are done with the container to make sure the container cleans up correctly.

Methods

`InspectingClientAsync.close`()
`InspectingClientAsync.connect`(**kwargs)	Connect to KATCP interface, starting what is needed
`InspectingClientAsync.future_check_request`(…)	Check if the request exists.
`InspectingClientAsync.future_check_sensor`(…)	Check if the sensor exists.
`InspectingClientAsync.future_get_request`(…)	Get the request object.
`InspectingClientAsync.future_get_sensor`(**kwargs)	Get the sensor object.
`InspectingClientAsync.handle_sensor_value`()	Handle #sensor-value informs just like #sensor-status informs
`InspectingClientAsync.inform_hook_client_factory`(…)	Return an instance of `_InformHookDeviceClient` or similar
`InspectingClientAsync.inspect`(**kwargs)	Inspect device requests and sensors, update model.
`InspectingClientAsync.inspect_requests`(**kwargs)	Inspect all or one requests on the device.
`InspectingClientAsync.inspect_sensors`(**kwargs)	Inspect all or one sensor on the device.
`InspectingClientAsync.is_connected`()	Connection status.
`InspectingClientAsync.join`([timeout])
`InspectingClientAsync.next`()
`InspectingClientAsync.preset_protocol_flags`(…)	Preset server protocol flags.
`InspectingClientAsync.request_factory`	Factory that produces KATCP Request objects.
`InspectingClientAsync.sensor_factory`	alias of `katcp.core.Sensor`
`InspectingClientAsync.set_ioloop`(ioloop)
`InspectingClientAsync.set_state_callback`(cb)	Set user callback for state changes
`InspectingClientAsync.simple_request`(…)	Create and send a request to the server.
`InspectingClientAsync.start`([timeout])	Note: always call stop() and wait until_stopped() when you are done with the container to make sure the container cleans up correctly.
`InspectingClientAsync.stop`([timeout])
`InspectingClientAsync.until_connected`([timeout])
`InspectingClientAsync.until_data_synced`([…])
`InspectingClientAsync.until_not_synced`([timeout])
`InspectingClientAsync.until_state`(desired_state)	Wait until state is desired_state, InspectingClientStateType instance
`InspectingClientAsync.until_stopped`([timeout])	Return future that resolves when the client has stopped
`InspectingClientAsync.until_synced`([timeout])
`InspectingClientAsync.update_sensor`(**kwargs)

connect(**kwargs)¶

Connect to KATCP interface, starting what is needed

Parameters:

timeout : float, None

Time to wait until connected. No waiting if None.

Raises:

:class:`tornado.gen.TimeoutError` if the connect timeout expires :

connected¶: Connection status.

future_check_request(**kwargs)¶

Check if the request exists.

Used internally by future_get_request. This method is aware of synchronisation in progress and if inspection of the server is allowed.

Parameters:

name : str

Name of the request to verify.

update : bool or None, optional

If a katcp request to the server should be made to check if the sensor is on the server. True = Allow, False do not Allow, None use the class default.

Notes

Ensure that self.state.data_synced == True if yielding to future_check_request from a state-change callback, or a deadlock will occur.

future_check_sensor(**kwargs)¶

Check if the sensor exists.

Used internally by future_get_sensor. This method is aware of synchronisation in progress and if inspection of the server is allowed.

Parameters:

name : str

Name of the sensor to verify.

update : bool or None, optional

If a katcp request to the server should be made to check if the sensor is on the server now.

Notes

Ensure that self.state.data_synced == True if yielding to future_check_sensor from a state-change callback, or a deadlock will occur.

future_get_request(**kwargs)¶

Get the request object.

Check if we have information for this request, if not connect to server and update (if allowed).

Parameters:

name : string

Name of the request.

update : bool or None, optional

True allow inspect client to inspect katcp server if the request is not known.

Returns:

Request created by :meth:`request_factory` or None if request not found. :

Notes

Ensure that self.state.data_synced == True if yielding to future_get_request from a state-change callback, or a deadlock will occur.

future_get_sensor(**kwargs)¶

Get the sensor object.

Check if we have information for this sensor, if not connect to server and update (if allowed) to get information.

Parameters:

name : string

Name of the sensor.

update : bool or None, optional

True allow inspect client to inspect katcp server if the sensor is not known.

Returns:

Sensor created by :meth:`sensor_factory` or None if sensor not found. :

Notes

Ensure that self.state.data_synced == True if yielding to future_get_sensor from a state-change callback, or a deadlock will occur.

handle_sensor_value()¶: Handle #sensor-value informs just like #sensor-status informs

inform_hook_client_factory(host, port, *args, **kwargs)¶

Return an instance of _InformHookDeviceClient or similar

Provided to ease testing. Dynamically overriding this method after instantiation but before start() is called allows for deep brain surgery. See katcp.fake_clients.TBD

inspect(**kwargs)¶

Inspect device requests and sensors, update model.

Returns:

Tornado future that resolves with: :

model_changes : Nested AttrDict or None

Contains sets of added/removed request/sensor names

Example structure:
{
    'requests':{
        'added': set(['req1', 'req2']),
        'removed': set(['req10', 'req20'])
    }
    'sensors': {
        'added': set(['sens1', 'sens2']),
        'removed': set(['sens10', 'sens20'])
    }
}
If there are no changes keys may be omitted. If an item is in both the ‘added’ and ‘removed’ sets that means that it changed.

If neither request not sensor changes are present, None is returned instead of a nested structure.

inspect_requests(**kwargs)¶

Inspect all or one requests on the device. Update requests index.

Parameters:

name : str or None, optional

Name of the request or None to get all requests.

timeout : float or None, optional

Timeout for request inspection, None for no timeout

Returns:

Tornado future that resolves with: :

changes : AttrDict

AttrDict with keys added and removed (of type set), listing the requests that have been added or removed respectively. Modified requests are listed in both. If there are no changes, returns None instead.

Example structure:
{
    'added': set(['req1', 'req2']),
    'removed': set(['req10', 'req20'])
}

inspect_sensors(**kwargs)¶

Inspect all or one sensor on the device. Update sensors index.

Parameters:

name : str or None, optional

Name of the sensor or None to get all sensors.

timeout : float or None, optional

Timeout for sensors inspection, None for no timeout

Returns:

Tornado future that resolves with: :

changes : AttrDict

AttrDict with keys added and removed (of type set), listing the sensors that have been added or removed respectively. Modified sensors are listed in both. If there are no changes, returns None instead.

Example structure:
{
    'added': set(['sens1', 'sens2']),
    'removed': set(['sens10', 'sens20'])
}

is_connected()¶: Connection status.

preset_protocol_flags(protocol_flags)¶

Preset server protocol flags.

Sets the assumed server protocol flags and disables automatic server version detection.

Parameters:	protocol_flags : katcp.core.ProtocolFlags instance

request_factory¶

Factory that produces KATCP Request objects.

signature: request_factory(name, description, timeout_hint), all parameters passed as kwargs

Should be set before calling connect()/start().

Methods

`Request.count`
`Request.index`

alias of Request

requests¶: A list of possible requests.

resync_delay = None¶: Set to an ExponentialRandomBackoff instance in _state_loop

sensor_factory¶: alias of katcp.core.Sensor

sensors¶: A list of known sensors.

set_state_callback(cb)¶

Set user callback for state changes

Called as cb(state, model_changes)

where state is an InspectingClientStateType instance, and model_changes is an AttrDict. The latter may contain keys requests and sensors to describe changes to requests or sensors respectively. These in turn have attributes added and removed which are sets of request/sensor names. Requests/sensors that have been modified will appear in both sets.

Warning

It is possible for model_changes to be None, or for either requests or sensors to be absent from model_changes.

simple_request(request, *args, **kwargs)¶

Create and send a request to the server.

This method implements a very small subset of the options possible to send an request. It is provided as a shortcut to sending a simple request.

Parameters:

request : str

The request to call.

*args : list of objects

Arguments to pass on to the request.

Keyword Arguments:

timeout : float or None, optional

Timeout after this amount of seconds (keyword argument).

mid : None or int, optional

Message identifier to use for the request message. If None, use either auto-incrementing value or no mid depending on the KATCP protocol version (mid’s were only introduced with KATCP v5) and the value of the use_mid argument. Defaults to None

use_mid : bool

Use a mid for the request if True. Defaults to True if the server supports them.

Returns:

future object. :

Examples

reply, informs = yield ic.simple_request('help', 'sensor-list')

start(timeout=None)¶: Note: always call stop() and wait until_stopped() when you are done with the container to make sure the container cleans up correctly.

state¶: Current client state.

synced¶: Boolean indicating if the device has been synchronised.

until_state(desired_state, timeout=None)¶

Wait until state is desired_state, InspectingClientStateType instance

Returns a future

until_stopped(timeout=None)¶

Return future that resolves when the client has stopped

See the DeviceClient.until_stopped docstring for parameter definitions and more info.

class katcp.inspecting_client.InspectingClientStateType¶

Bases: katcp.inspecting_client.InspectingClientStateType

States tuple for the inspecting client. Fields, all bool:

connected: bool: TCP connection has been established with the server.
synced: bool: The inspecting client and the user that interfaces through the state change callback are all synchronised with the current device state. Also implies connected = True and data_synced = True.
model_changed: bool: The device has changed in some way, resulting in the device model being out of date.
data_synced: bool: The inspecting client’s internal representation of the device is up to date, although state change user is not yet up to date.

Methods

`InspectingClientStateType.count`(value)
`InspectingClientStateType.index`(value, …)	Raises ValueError if the value is not present.

katcp.inspecting_client.RequestType¶: alias of katcp.inspecting_client.Request

exception katcp.inspecting_client.SyncError¶

Bases: exceptions.Exception

Raised if an error occurs during syncing with a device