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 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
()¶ 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=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 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, _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 returningTrue
on success (i.e. condition satisfied) andFalse
on failure (i.e. timeout exceeded) by setting the_raiseException
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.