ait.core.api module

AIT API

The ait.core.api module provides an Application Programming Interface (API) to your instrument by bringing together the core.cmd and core.tlm modules in a complementary whole, allowing you to script instrument interactions, e.g.:

# TBA
exception ait.core.api.APIError

Bases: exceptions.Exception

All AIT API exceptions are derived from this class

exception ait.core.api.APITimeoutError(timeout=0, msg=None)

Bases: exceptions.Exception

Raised when a timeout limit is exceeded

__init__(timeout=0, msg=None)

x.__init__(…) initializes x; see help(type(x)) for signature

msg
timeout
exception ait.core.api.FalseWaitError(msg=None)

Bases: exceptions.Exception

Raised when a ‘False’ boolean is passed as an argument to wait (in order to avoid infinite loop)

__init__(msg=None)

x.__init__(…) initializes x; see help(type(x)) for signature

msg
class ait.core.api.CmdAPI(destination, cmddict=None, verbose=False)

Provides an API to send commands to your Instrument via User Datagram Protocol (UDP) packets.

__init__(destination, cmddict=None, verbose=False)
send(command, *args, **kwargs)

Creates, validates, and sends the given command as a UDP packet to the destination (host, port) specified when this CmdAPI was created.

Returns True if the command was created, valid, and sent, False otherwise.

validate(command, *args, **kwargs)
class ait.core.api.GeventDeque(iterable=None, maxlen=None)

Bases: object

A Python collections.deque that can be used in a Gevent context.

__init__(iterable=None, maxlen=None)

Returns a new GeventDeque object initialized left-to-right (using append()) with data from iterable. If iterable is not specified, the new GeventDeque is empty.

If maxlen is not specified or is None, GeventDeques may grow to an arbitrary length. Otherwise, the GeventDeque is bounded to the specified maximum length. Once a bounded length GeventDeque is full, when new items are added, a corresponding number of items are discarded from the opposite end.

append(item)

Add item to the right side of the GeventDeque.

This method does not block. Either the GeventDeque grows to consume available memory, or if this GeventDeque has and is at maxlen, the leftmost item is removed.

appendleft(item)

Add item to the left side of the GeventDeque.

This method does not block. Either the GeventDeque grows to consume available memory, or if this GeventDeque has and is at maxlen, the rightmost item is removed.

clear()

Remove all elements from the GeventDeque leaving it with length 0.

count(item)

Count the number of GeventDeque elements equal to item.

extend(iterable)

Extend the right side of this GeventDeque by appending elements from the iterable argument.

extendleft(iterable)

Extend the left side of this GeventDeque by appending elements from the iterable argument. Note, the series of left appends results in reversing the order of elements in the iterable argument.

pop(block=True, timeout=None)

Remove and return an item from the right side of the GeventDeque. If no elements are present, raises an IndexError.

If optional args block is True and timeout is None (the default), block if necessary until an item is available. If timeout is a positive number, it blocks at most timeout seconds and raises the IndexError exception if no item was available within that time. Otherwise (block is False), return an item if one is immediately available, else raise the IndexError exception (timeout is ignored in that case).

popleft(block=True, timeout=None)

Remove and return an item from the right side of the GeventDeque. If no elements are present, raises an IndexError.

If optional args block is True and timeout is None (the default), block if necessary until an item is available. If timeout is a positive number, it blocks at most timeout seconds and raises the IndexError exception if no item was available within that time. Otherwise (block is False), return an item if one is immediately available, else raise the IndexError exception (timeout is ignored in that case).

remove()

Removes the first occurrence of item. If not found, raises a ValueError.

Unlike pop() and popleft() this method does not have an option to block for a specified period of time (to wait for item).

reverse()

Reverse the elements of the deque in-place and then return None.

rotate(n)

Rotate the GeventDeque n steps to the right. If n is negative, rotate to the left. Rotating one step to the right is equivalent to: d.appendleft(d.pop()).

maxlen

Maximum size of this GeventDeque or None if unbounded.

class ait.core.api.Instrument(cmdport=3075, tlmport=3076, defn=None)

Bases: object

__init__(cmdport=3075, tlmport=3076, defn=None)

x.__init__(…) initializes x; see help(type(x)) for signature

cmd
tlm
class ait.core.api.PacketBuffers

Bases: dict

__init__()

x.__init__(…) initializes x; see help(type(x)) for signature

create(name, capacity=60)
insert(name, packet)
class ait.core.api.TlmWrapper(packets)

Bases: object

__init__(packets)

x.__init__(…) initializes x; see help(type(x)) for signature

class ait.core.api.TlmWrapperAttr(buffers)

Bases: object

__init__(buffers)

x.__init__(…) initializes x; see help(type(x)) for signature

class ait.core.api.UIAPI

Bases: object

confirm(msg, _timeout=-1)

Send a confirm prompt to the GUI

Arguments:
msg (string):
The message to display to the user.
_timeout (int):
The optional amount of time for which the prompt should be displayed to the user before a timeout occurs. Defaults to -1 which indicates there is no timeout limit.
msgBox(promptType, _timeout=-1, **options)

Send a user prompt request to the GUI

Arguments:
promptType (string):
The prompt type to send to the GUI. Currently the only type supported is ‘confirm’.
_timeout (int):
The optional amount of time for which the prompt should be displayed to the user before a timeout occurs. Defaults to -1 which indicates there is no timeout limit.
options (dict):
The keyword arguments that should be passed to the requested prompt type. Check prompt specific sections below for information on what arguments are expected to be present.
Raises:
ValueError:
If the prompt type received is an unexpected value

Confirm Prompt

Display a message to the user and prompt them for a confirm/deny response to the message.

Arguments:
msg (string):
The message to display to the user
Returns:
True if the user picks ‘Confirm’, False if the user picks ‘Deny’
Raises:
KeyError:
If the options passed to the prompt handler doesn’t contain a msg attribute.
APITimeoutError:
If the timeout value is reached without receiving a response.
class ait.core.api.UdpTelemetryServer(listener, pktbuf, defn=None)

Bases: gevent.server.DatagramServer

Listens for telemetry packets delivered via User Datagram Protocol (UDP) to a particular (host, port).

__init__(listener, pktbuf, defn=None)

Creates a new UdpTelemetryServer.

The server listens for UDP packets matching the given PacketDefinition defn.

The listener is either a port on localhost, a tuple containing (hostname, port), or a gevent.socket.socket.

If the optional defn is not specified, the first PacketDefinition (alphabetical by name) in the default telemetry dictionary (i.e. tlm.getDefaultDict()) is used.

handle(data, address)
start()

Starts this UdpTelemetryServer.

packets

The packet buffer.

ait.core.api.wait(cond, msg=None, _timeout=10, _raiseException=True)

Waits either a specified number of seconds, e.g.:

wait(1.2)

or for a given condition to be True. Conditions may be take several forms: Python string expression, lambda, or function, e.g.:

wait('instrument_mode == "SAFE"')
wait(lambda: instrument_mode == "SAFE")

def isSafe(): return instrument_mode == "SAFE"
wait(isSafe)

The default _timeout is 10 seconds. If the condition is not satisfied before the timeout has elapsed, an :exception:APITimeoutError exception is raised.

The :exception:APITimeoutError exception may be supressed in favor of returning True on success (i.e. condition satisfied) and False on failure (i.e. timeout exceeded) by setting the _raiseException parameter to False.

The :exception:FalseWaitError will be thrown only if a boolean with value “False” is passed as an argument to wait. The purpose of this is to avoid infinite loops and catch conditional arguments are not passed in as strings and therefore evaluated before the wait function gets called.

These parameters are prefixed with an underscore so they may also be used to control exception handling when sending commands. Since methods that generate commands take keyword arguments, we did not want these parameter names to conflict with command parameter names.