Skip to content

See the Python API overview for an introduction to the midas python package.

This page contains the full API reference for the top-level midas module, which mostly contains definitions that are similar to those in midas.h for the C++ API.

Submodules are documented on other pages:

midas

This module contains python tools related to midas.

This file contains definitions that come from midas.h, plus some helper classes.

Classes:

  • MidasLogHandler –

    helps you integrate midas messages and python logging

  • MidasError –

    base class of exceptions that can get raised. The midas python interface doesn't use status codes when functions return, but raises exceptions instead.

  • MidasLib –

    contains the low-level tools for interacting with the midas C++ code. Users almost certainly don't need to know how it works (or even that it exists...).

midas.AT_EVALUATED = 3 module-attribute

midas.AT_INTERNAL = 1 module-attribute

midas.AT_PERIODIC = 4 module-attribute

midas.AT_PROGRAM = 2 module-attribute

midas.BM_NO_WAIT = 1 module-attribute

midas.BM_WAIT = 0 module-attribute

midas.EQ_EB = 1 << 7 module-attribute

midas.EQ_FRAGMENTED = 1 << 6 module-attribute

midas.EQ_INTERRUPT = 1 << 2 module-attribute

midas.EQ_MANUAL_TRIG = 1 << 5 module-attribute

midas.EQ_MULTITHREAD = 1 << 3 module-attribute

midas.EQ_PERIODIC = 1 << 0 module-attribute

midas.EQ_POLLED = 1 << 1 module-attribute

midas.EQ_SLOW = 1 << 4 module-attribute

midas.EQ_USER = 1 << 8 module-attribute

midas.GET_ALL = 1 module-attribute

midas.GET_NONBLOCKING = 2 module-attribute

midas.GET_RECENT = 4 module-attribute

midas.MAX_STRING_LENGTH = 256 module-attribute

midas.MODE_DELETE = 4 module-attribute

midas.MODE_READ = 1 module-attribute

midas.MODE_WRITE = 2 module-attribute

midas.MT_ALL = 255 module-attribute

midas.MT_CALL = 1 << 6 module-attribute

midas.MT_DEBUG = 1 << 2 module-attribute

midas.MT_ERROR = 1 << 0 module-attribute

midas.MT_INFO = 1 << 1 module-attribute

midas.MT_LOG = 1 << 4 module-attribute

midas.MT_TALK = 1 << 5 module-attribute

midas.MT_USER = 1 << 3 module-attribute

midas.RO_ALWAYS = 255 module-attribute

midas.RO_BOR = 1 << 3 module-attribute

midas.RO_EOR = 1 << 4 module-attribute

midas.RO_ODB = 1 << 8 module-attribute

midas.RO_PAUSE = 1 << 5 module-attribute

midas.RO_PAUSED = 1 << 2 module-attribute

midas.RO_RESUME = 1 << 6 module-attribute

midas.RO_RUNNING = 1 << 0 module-attribute

midas.RO_STOPPED = 1 << 1 module-attribute

midas.RO_TRANSITIONS = RO_BOR | RO_EOR | RO_PAUSE | RO_RESUME module-attribute

midas.RPC_BRPC = 18001 module-attribute

midas.RPC_JRPC = 18000 module-attribute

midas.RPC_MANUAL_TRIG = 17000 module-attribute

midas.STATE_PAUSED = 2 module-attribute

midas.STATE_RUNNING = 3 module-attribute

midas.STATE_STOPPED = 1 module-attribute

midas.TID_ARRAY = 13 module-attribute

midas.TID_BITFIELD = 11 module-attribute

midas.TID_BOOL = 8 module-attribute

midas.TID_BYTE = 1 module-attribute

midas.TID_CHAR = 3 module-attribute

midas.TID_DOUBLE = 10 module-attribute

midas.TID_DWORD = 6 module-attribute

midas.TID_FLOAT = 9 module-attribute

midas.TID_FLOAT32 = TID_FLOAT module-attribute

midas.TID_FLOAT64 = TID_DOUBLE module-attribute

midas.TID_INT = 7 module-attribute

midas.TID_INT16 = TID_SHORT module-attribute

midas.TID_INT32 = TID_INT module-attribute

midas.TID_INT64 = 17 module-attribute

midas.TID_INT8 = TID_SBYTE module-attribute

midas.TID_KEY = 15 module-attribute

midas.TID_QWORD = 18 module-attribute

midas.TID_SBYTE = 2 module-attribute

midas.TID_SHORT = 5 module-attribute

midas.TID_STRING = 12 module-attribute

midas.TID_STRUCT = 14 module-attribute

midas.TID_UINT16 = TID_WORD module-attribute

midas.TID_UINT32 = TID_DWORD module-attribute

midas.TID_UINT64 = TID_QWORD module-attribute

midas.TID_UINT8 = TID_BYTE module-attribute

midas.TID_WORD = 4 module-attribute

midas.TR_ASYNC = 2 module-attribute

midas.TR_DETACH = 4 module-attribute

midas.TR_MTHREAD = 8 module-attribute

midas.TR_PAUSE = 4 module-attribute

midas.TR_RESUME = 8 module-attribute

midas.TR_START = 1 module-attribute

midas.TR_STARTABORT = 16 module-attribute

midas.TR_STOP = 2 module-attribute

midas.TR_SYNC = 1 module-attribute

midas.have_numpy = True module-attribute

Whether we have numpy or not

midas.logger = logging.getLogger('midas') module-attribute

Default logger does nothing. See midas.MidasLogHandler for details of how to set up logging.

midas.status_codes = {'SUCCESS': 1, 'CM_SET_ERROR': 102, 'CM_NO_CLIENT': 103, 'CM_DB_ERROR': 104, 'CM_UNDEF_EXP': 105, 'CM_VERSION_MISMATCH': 106, 'CM_SHUTDOWN': 107, 'CM_WRONG_PASSWORD': 108, 'CM_UNDEF_ENVIRON': 109, 'CM_DEFERRED_TRANSITION': 110, 'CM_TRANSITION_IN_PROGRESS': 111, 'CM_TIMEOUT': 112, 'CM_INVALID_TRANSITION': 113, 'CM_TOO_MANY_REQUESTS': 114, 'CM_TRUNCATED': 115, 'CM_TRANSITION_CANCELED': 116, 'BM_CREATED': 202, 'BM_NO_MEMORY': 203, 'BM_INVALID_NAME': 204, 'BM_INVALID_HANDLE': 205, 'BM_NO_SLOT': 206, 'BM_NO_SEMAPHORE': 207, 'BM_NOT_FOUND': 208, 'BM_ASYNC_RETURN': 209, 'BM_TRUNCATED': 210, 'BM_MULTIPLE_HOSTS': 211, 'BM_MEMSIZE_MISMATCH': 212, 'BM_CONFLICT': 213, 'BM_EXIT': 214, 'BM_INVALID_PARAM': 215, 'BM_MORE_EVENTS': 216, 'BM_INVALID_MIXING': 217, 'BM_NO_SHM': 218, 'BM_CORRUPTED': 219, 'BM_INVALID_SIZE': 220, 'BM_TIMEOUT': 221, 'DB_CREATED': 302, 'DB_NO_MEMORY': 303, 'DB_INVALID_NAME': 304, 'DB_INVALID_HANDLE': 305, 'DB_NO_SLOT': 306, 'DB_NO_SEMAPHORE': 307, 'DB_MEMSIZE_MISMATCH': 308, 'DB_INVALID_PARAM': 309, 'DB_FULL': 310, 'DB_KEY_EXIST': 311, 'DB_NO_KEY': 312, 'DB_KEY_CREATED': 313, 'DB_TRUNCATED': 314, 'DB_TYPE_MISMATCH': 315, 'DB_NO_MORE_SUBKEYS': 316, 'DB_FILE_ERROR': 317, 'DB_NO_ACCESS': 318, 'DB_STRUCT_SIZE_MISMATCH': 319, 'DB_OPEN_RECORD': 320, 'DB_OUT_OF_RANGE': 321, 'DB_INVALID_LINK': 322, 'DB_CORRUPTED': 323, 'DB_STRUCT_MISMATCH': 324, 'DB_TIMEOUT': 325, 'DB_VERSION_MISMATCH': 326, 'SS_CREATED': 402, 'SS_NO_MEMORY': 403, 'SS_INVALID_NAME': 404, 'SS_INVALID_HANDLE': 405, 'SS_INVALID_ADDRESS': 406, 'SS_FILE_ERROR': 407, 'SS_NO_SEMAPHORE': 408, 'SS_NO_PROCESS': 409, 'SS_NO_THREAD': 410, 'SS_SOCKET_ERROR': 411, 'SS_TIMEOUT': 412, 'SS_SERVER_RECV': 413, 'SS_CLIENT_RECV': 414, 'SS_ABORT': 415, 'SS_EXIT': 416, 'SS_NO_TAPE': 417, 'SS_DEV_BUSY': 418, 'SS_IO_ERROR': 419, 'SS_TAPE_ERROR': 420, 'SS_NO_DRIVER': 421, 'SS_END_OF_TAPE': 422, 'SS_END_OF_FILE': 423, 'SS_FILE_EXISTS': 424, 'SS_NO_SPACE': 425, 'SS_INVALID_FORMAT': 426, 'SS_NO_ROOT': 427, 'SS_SIZE_MISMATCH': 428, 'SS_NO_MUTEX': 429, 'RPC_NO_CONNECTION': 502, 'RPC_NET_ERROR': 503, 'RPC_TIMEOUT': 504, 'RPC_EXCEED_BUFFER': 505, 'RPC_NOT_REGISTERED': 506, 'RPC_CONNCLOSED': 507, 'RPC_INVALID_ID': 508, 'RPC_SHUTDOWN': 509, 'RPC_NO_MEMORY': 510, 'RPC_DOUBLE_DEFINED': 511, 'RPC_MUTEX_TIMEOUT': 512, 'FE_ERR_ODB': 602, 'FE_ERR_HW': 603, 'FE_ERR_DISABLED': 604, 'FE_ERR_DRIVER': 605, 'FE_PARTIALLY_DISABLED': 606, 'FE_NOT_YET_READ': 607, 'HS_FILE_ERROR': 702, 'HS_NO_MEMORY': 703, 'HS_TRUNCATED': 704, 'HS_WRONG_INDEX': 705, 'HS_UNDEFINED_EVENT': 706, 'HS_UNDEFINED_VAR': 707, 'FTP_NET_ERROR': 802, 'FTP_FILE_ERROR': 803, 'FTP_RESPONSE_ERROR': 804, 'FTP_INVALID_ARG': 805, 'EL_FILE_ERROR': 902, 'EL_NO_MESSAGE': 903, 'EL_TRUNCATED': 904, 'EL_FIRST_MSG': 905, 'EL_LAST_MSG': 906, 'AL_INVALID_NAME': 1002, 'AL_ERROR_ODB': 1003, 'AL_RESET': 1004, 'AL_TRIGGERED': 1005} module-attribute

All midas status codes, as a dict

midas.status_codes_to_text = {v: k for k, v in status_codes.items()} module-attribute

Reverse mapping of status_codes - from int to string

midas.tid_np_formats = {TID_BYTE: np.uint8, TID_SBYTE: np.int8, TID_CHAR: np.uint8, TID_WORD: np.uint16, TID_SHORT: np.int16, TID_DWORD: np.uint32, TID_INT: np.int32, TID_BOOL: np.uint32, TID_FLOAT: np.float32, TID_DOUBLE: np.float64, TID_BITFIELD: np.uint32, TID_STRING: None, TID_ARRAY: None, TID_STRUCT: None, TID_KEY: None, TID_LINK: None, TID_QWORD: np.uint64, TID_INT64: np.int64} module-attribute

Optimal mapping from midas type to numpy data type

midas.tid_sizes = {TID_BYTE: 1, TID_SBYTE: 1, TID_CHAR: 1, TID_WORD: 2, TID_SHORT: 2, TID_DWORD: 4, TID_INT: 4, TID_BOOL: 4, TID_FLOAT: 4, TID_DOUBLE: 8, TID_BITFIELD: 4, TID_STRING: None, TID_ARRAY: None, TID_STRUCT: None, TID_KEY: None, TID_LINK: None, TID_INT64: 8, TID_QWORD: 8} module-attribute

Number of bytes each midas data type requires

midas.tid_texts = {TID_BYTE: 'Unsigned Byte', TID_SBYTE: 'Signed Byte', TID_CHAR: 'Char', TID_WORD: 'Unsigned Word', TID_SHORT: 'Signed Word', TID_DWORD: 'Unsigned Integer', TID_INT: 'Signed Integer', TID_BOOL: 'Boolean', TID_FLOAT: 'Float', TID_DOUBLE: 'Double', TID_BITFIELD: 'Bitfield', TID_STRING: 'String', TID_ARRAY: 'Array', TID_STRUCT: 'Struct', TID_KEY: 'Key', TID_LINK: 'Link', TID_QWORD: 'Unsigned 64-bit Integer', TID_INT64: 'Signed 64-bit Integer'} module-attribute

Friendly name of each midas data type

midas.tid_unpack_formats = {TID_BYTE: 'B', TID_SBYTE: 'b', TID_CHAR: 'B', TID_WORD: 'H', TID_SHORT: 'h', TID_DWORD: 'I', TID_INT: 'i', TID_BOOL: 'I', TID_FLOAT: 'f', TID_DOUBLE: 'd', TID_BITFIELD: 'I', TID_STRING: None, TID_ARRAY: None, TID_STRUCT: None, TID_KEY: None, TID_LINK: None, TID_QWORD: 'Q', TID_INT64: 'q'} module-attribute

How to unpack each midas data type with python's struct module

midas.MidasError

Bases: Exception

Exception type raised if the midas C library functions return a non-SUCCESS code.

Attributes:

  • code (int) –

    The return code

  • message (str) –

    Meaning of the return code, as defined in status_codes.

__init__(code, message)

midas.MidasLib

Bases: CDLL

Wrapper around the midas C library that will automatically raise exceptions if a called function returns a non-SUCCESS status code.

Attributes:

  • return_types (dict) –

    of {str: type} for {function_name: return type}. For functions that do NOT return a normal integer status code, what the return type is. Most users will not need to call any of these functions, but we record the types any way for completeness.

  • ignore_status_codes (dict) –

    of {str: [str]} for {function_name: list_of_statuses}. Which return codes should NOT raise an exception for certain functions.

  • db_key_name_arg (dict) –

    of {str: int} for {function_name: argument_index}. For certain functions we raise a KeyError if a path is not found in the ODB. This mapping tells us which functions to apply that logic to, and which argument contains the path we were searching for (so we can give a nicer error message).

__getitem__(name)

Overriding this function means we can register an error-checker for every function in the midas C library, without having to list them all manually.

Parameters:

  • name (str) –

    Name of function in the C library.

__init__(lib_path)

Parameters: lib_path (str): Path to the shared library to load.

midas.MidasLogHandler

Bases: Handler

This handler integrates with the python logging library, and will automatically write any messages to the midas message log.

Example usage

import logging
import midas.client

client = midas.client.MidasClient("pytest")
logger = logging.getLogger("mylogger") # Or anything else
handler = midas.MidasLogHandler(client) # Also has an optional 2nd argument for the message "facility"

logger.addHandler(handler)
logger.setLevel(logging.INFO) # Ask to log info/error messages, but not debug ones

logger.info("Some message that will be shown in stdout and in midas log")
logger.debug("This will not be shown or logged, as debug < info")
logger.error("This will be shown in stdout and in midas log (as an error message)")

__init__(client=None, facility='midas')

midas.MidasShutdown

Bases: MidasError

A specific exception raised when midas tells this client to shutdown. Either due to Ctrl-C in terminal or via RPC.

__init__(code, message)

midas.TransitionDeferredError

Bases: MidasError

A specific exception raised if this client tries to start/stop a run, but the transition is deferred by another client.

__init__(code, message)

midas.TransitionFailedError

Bases: MidasError

A specific exception raised if this client tries to start/stop a run, but the transition fails.

__init__(code, message)

midas.WaitTimeoutExpired

Bases: Exception

Exception type raised when the sequencer wait_xxx() functions time out.

midas.get_np_dtype(midas_tid)

Get the optimal numpy dtype for a given midas data type.

Parameters:

  • midas_tid (int) –

    one of midas.TID_xxx

Returns:

  • dtype –

    numpy datatype

midas.safe_to_json(input_str, use_ordered_dict=False, raise_if_bad_bytes=False)

Convert input_str to a json structure, with arguments that will catch bad bytes.

Parameters:

  • input_str (str) –

    JSON

  • use_ordered_dict (bool, default: False ) –

    Whether to preserve the order of keys in the JSON document by using OrderedDict instead of dict.

Returns:

midas.status_code_to_exception(code, ignore, keyname=None)

Raise an exception based on the return code from a midas C function status code.

Parameters:

  • code (int) –

    The function's return code

  • ignore (list of int) –

    Any return codes that should NOT cause an exception to be raised (in addition to "SUCCESS")

  • keyname (str, default: None ) –

    If the status code was "DB_NO_KEY", which ODB path could not be found.

Raises:

  • KeyError –

    if the code is "DB_NO_KEY"

  • TypeError –

    if the code is "DB_TYPE_MISMATCH"

  • MidasError –

    for any other code that isn't "SUCCESS"

midas.status_code_to_text(code)

Convert an integer midas status code to a string.

Parameters:

  • code (int) –

    status code from midas.status_codes

Returns:

  • str –

    text representation

midas.sys_is_big_endian()

Get whether this machine is big-endian.

Returns: