Python

Since December 2019, midas has shipped with python wrappers allowing midas clients to be written in python.

The main features are:

• A file reader, which works with python 2.7 and python 3.x
• A client library and frontend framework which work with python 3.x only

To use the python libraries, you must have installed midas, and compiled midas using cmake. The python code is found at $MIDASSYS/python. You can view example scripts and frontends on BitBucket.

Midas file reader

midas/file_reader.py is a pure-python tool that lets you read midas files. It presents a very pythonic interface, allowing you to do things like

for event in my_file:
  event.dump()

See the examples in midas/file_reader.py and examples/file_reader.py.

• It works with python 2.7 and python 3.
• It does not require the rest of midas to be compiled.

Client and frontend libraries

• midas/client.py provides pythonic access to a midas experiment, by wrapping midas' C library. It provides nice ODB access through functions like odb_set and odb_get, and can also handle event buffers, callback functions and more.
• midas/frontend.py builds upon the client and provides a framework for writing midas frontends in python. It supports periodic and polled equipment, and can be controlled just like a C frontend.

Many users write scripts in python or bash that call the odbedit command-line tool or the mhttpd web server. We hope that the pythonic midas client tools will simplify and robustify such scripts. The python frontend framework may prove particularly beneficial for controlling devices that natively talk in JSON or other text-based protocols that are tedious to deal with in C. It may also reduce the development time required to write frontends that do not have strict performance requirements.

• They work with python 3 only.
• They require the rest of midas to be compiled, as they use the midas C library. For the correct libraries to be built, you must compile using CMake
• They are designed for ease of use, rather than optimal performance. If performance is critical for your application, you should write your code in C.

Documentation

Documentation of the tools is written as docstrings in the source code (in $MIDASSYS/python/midas). We do not currently have a web version of the documentation.

The documentation assumes a reasonable familiarity with core midas concepts. See the rest of this wiki if you're unfamiliar with a term or concept in the python documentation.

Installation

We highly recommed using pip and/or virtualenv to manage your python packages, but you can also just edit your paths if desired.

To install this package with pip:

pip install -e $MIDASSYS/python --user
# The -e flag makes this an "editable" install. If you upgrade midas in future,
# python will automatically see the new code without you having to re-install.
# The --user flag may or may not be needed, depending on your pip setup.

To "install" by editing environment variables:

export PYTHONPATH=$PYTHONPATH:$MIDASSYS/python

Examples

You can now use import midas and import midas.client etc in your python scripts.

$MIDASSYS/python/examples contains several examples of complete clients and frontends written in python.

Here we show a very simple python script for interacting with the ODB. Note that we do not have any error-checking. If any call to the midas library fails, an exception will be raised.

import midas.client

"""
A simple example program that connects to a midas experiment,
reads an ODB value, then sets an ODB value.

Expected output is:

```
The experiment is currently stopped
The new value of /pyexample/eg_float is 5.670000
```
"""

if __name__ == "__main__":
    client = midas.client.MidasClient("pytest")

    # Read a value from the ODB. The return value is a normal python
    # type (an int in this case, but could also be a float, string, bool,
    # list or dict).
    state = client.odb_get("/Runinfo/State")

    if state == midas.STATE_RUNNING:
        print("The experiment is currently running")
    elif state == midas.STATE_PAUSED:
        print("The experiment is currently paused")
    elif state == midas.STATE_STOPPED:
        print("The experiment is currently stopped")
    else:
        print("The experiment is in an unexpected run state")


    # Update or create a directory in the ODB by passing a dict to `odb_set`
    client.odb_set("/pyexample", {"an_int": 1, "eg_float": 4.56})

    # Update a single value in the ODB
    client.odb_set("/pyexample/eg_float", 5.67)

    # Read the value back
    readback = client.odb_get("/pyexample/eg_float")

    print("The new value of /pyexample/eg_float is %f" % readback)

    # Delete the temporary directory we created
    client.odb_delete("/pyexample")

Tests

$MIDASSYS/python/tests contains a variety of test scripts. If you wish, you can run them using

cd $MIDASSYS/python/tests
python -munittest

However, note that running these tests will interact with whichever midas experiment is currently active. They will edit the ODB and start and stop runs. If you are running these tests, we suggest doing so in a "dummy"/test experiment.