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 theIndexError
exception if no item was available within that time. Otherwise (block is False), return an item if one is immediately available, else raise theIndexError
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 theIndexError
exception if no item was available within that time. Otherwise (block is False), return an item if one is immediately available, else raise theIndexError
exception (timeout is ignored in that case).
-
remove
(item)¶ Removes the first occurrence of item. If not found, raises a ValueError.
Unlike
pop()
andpopleft()
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 disablespawn_tree_locals
,spawning_greenlet
, andspawning_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 aTypeError
earlier instead of anAttributeError
later.Changed in version 20.12.1: Greenlet objects now function as context managers. Exiting the
with
suite ensures that the greenlet has completed byjoining
the greenlet (blocking, with no timeout). If the body of the suite raises an exception, the greenlet iskilled
with the default arguments and not joined in that case.- args – The arguments passed to the
-
-
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 agevent.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 returningTrue
on success (i.e. condition satisfied) andFalse
on failure (i.e. timeout exceeded) by setting the_raise_exception
parameter toFalse
.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.