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)
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_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_requests(*args, **kwargs)

Inspect all or one requests on the device.

Parameters:

name : str or None, optional

Name of the sensor or None to get all requests.

timeout : float or None, optional

Timeout for request inspection, None for no timeout

TODO Return value :

inspect_sensors(*args, **kwargs)

Inspect all or one sensor on the device.

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

TODO Return value :

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’)

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

Methods

Request.count
Request.index

alias of Request

requests

A list of possible requests.

sensor_factory

Factory that produces a KATCP Sensor compatible instance.

signature: sensor_factory(name,

sensor_type, 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 InspectingClientStateType instance, and model_changes ...

TODO More docs on what the callback is called with

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.

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