Concrete Intermediate-level KATCP Client API (inspecting_client)

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

Bases: object

Higher-level client that inspects a KATCP interface.

Note: This class is not threadsafe 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(*args, **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(...) 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(*args, **kwargs) Inspect device requests and sensors, update model
InspectingClientAsync.inspect_requests(...) Inspect all or one requests on the device.
InspectingClientAsync.inspect_sensors(*args, ...) Inspect all or one sensor on the device.
InspectingClientAsync.is_connected() Connection status.
InspectingClientAsync.join([timeout])
InspectingClientAsync.preset_protocol_flags(...) Preset server protocol flags.
InspectingClientAsync.request_factory Factory that produces KATCP Request objects
InspectingClientAsync.sensor_factory alias of 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() 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_synced([timeout])
InspectingClientAsync.update_sensor(*args, ...)
connect(*args, **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(*args, **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(*args, **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(*args, **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(*args, **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(*args, **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(*args, **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(*args, **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

Factory that produces a KATCP Sensor compatible instance.

signature: sensor_factory(sensor_type,
name, description, units, params)

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

Methods

Sensor.address
Sensor.attach
Sensor.boolean
Sensor.detach
Sensor.discrete
Sensor.float
Sensor.format_reading
Sensor.integer
Sensor.lru
Sensor.notify
Sensor.parse_params
Sensor.parse_type
Sensor.parse_value
Sensor.read
Sensor.read_formatted
Sensor.set
Sensor.set_formatted
Sensor.set_value
Sensor.status
Sensor.string
Sensor.timestamp
Sensor.value

alias of 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. :

start(timeout=None)

Note: always call stop() 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

class katcp.inspecting_client.InspectingClientStateType

Bases: katcp.inspecting_client.InspectingClientStateType

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

connected : TCP connection has been established with the server synced : 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 : The device has changed in some way, resulting in the device model
being out of date.
data_synced : 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(...)
InspectingClientStateType.index((value, ...) Raises ValueError if the value is not present.
katcp.inspecting_client.RequestType

alias of Request

exception katcp.inspecting_client.SyncError

Bases: exceptions.Exception

Raised if an error occurs during syncing with a device