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 similarInspectingClientAsync.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 similarProvided 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
andremoved
(of typeset
), listing the requests that have been added or removed respectively. Modified requests are listed in both. If there are no changes, returnsNone
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
andremoved
(of typeset
), listing the sensors that have been added or removed respectively. Modified sensors are listed in both. If there are no changes, returnsNone
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 anAttrDict
. The latter may contain keysrequests
andsensors
to describe changes to requests or sensors respectively. These in turn have attributesadded
andremoved
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 eitherrequests
orsensors
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