ait.core.api module

exception ait.core.api.APIError

Bases: Exception

All AIT API exceptions are derived from this class

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

Bases: Exception

Raised when a timeout limit is exceeded

__init__(timeout=0, msg=None)

Initialize self. See help(type(self)) for accurate signature.

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

Bases: Exception

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

__init__(msg=None)

Initialize self. See help(type(self)) for accurate signature.

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

Bases: object

Provides an API to send commands to your Instrument via User Datagram Protocol (UDP) packets if udp_dest argument is set, else, command is sent via ZMQ topic.

__init__(udp_dest=None, cmddict=None, verbose=False, cmdtopic=None)

Initialize self. See help(type(self)) for accurate signature.

parse_args(command, *args)

Iterates over presumably naively parsed arguments and enforces the associated argument type definitions from the command def when possible.

If number of arguments exceeds the command definition’s argument count, those extra arguments will be included in the result.

Returns A new argument array where argument type adheres to argument definition

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(item)

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=None, packets=None)

Bases: object

__init__(cmdport=None, packets=None)
cmd
tlm
class ait.core.api.PacketBuffers

Bases: dict

__init__()

Initialize self. See help(type(self)) for accurate signature.

create(name, capacity=60)
insert(name, packet)
class ait.core.api.TlmMonitor(pktbufs, defns)

Bases: gevent._gevent_cgreenlet.Greenlet

__init__(pktbufs, defns)
Parameters:
  • args – The arguments passed to the run function.
  • kwargs – The keyword arguments passed to the run function.
  • run (callable) – The callable object to run. If not given, this object’s _run method will be invoked (typically defined by subclasses).

Changed in version 1.1b1: The run argument to the constructor is now verified to be a callable object. Previously, passing a non-callable object would fail after the greenlet was spawned.

Changed in version 1.3b1: The GEVENT_TRACK_GREENLET_TREE configuration value may be set to a false value to disable spawn_tree_locals, spawning_greenlet, and spawning_stack. The first two will be None in that case, and the latter will be empty.

Changed in version 1.5: Greenlet objects are now more careful to verify that their parent is really a gevent hub, raising a TypeError earlier instead of an AttributeError later.

Changed in version 20.12.1: Greenlet objects now function as context managers. Exiting the with suite ensures that the greenlet has completed by joining the greenlet (blocking, with no timeout). If the body of the suite raises an exception, the greenlet is killed with the default arguments and not joined in that case.

class ait.core.api.TlmWrapper(packets)

Bases: object

__init__(packets)

Initialize self. See help(type(self)) for accurate signature.

class ait.core.api.TlmWrapperAttr(buffers)

Bases: object

__init__(buffers)

Initialize self. See help(type(self)) for accurate 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.
msg_box(prompt_type, _timeout=-1, **options)

Send a user prompt request to the GUI

Arguments:
prompt_type (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, _raise_exception=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 _raise_exception 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.