A Task Executor GUI

To build up the Task GUI, we distinguish each task button as a function, several of these functions can be grouped in a Python module (a .py file) and all the modules plus additional information needed for the Task GUI is kept in a Python package. The CSL Operator GUI shown in the screenshot above, is located in the package camtest.csl and has the following layout:

Each of these .py files form a group of buttons in the above Task GUI. The __init__.py file is special, it defines camtest.csl as a package, and it also defines the command to start the Task GUI [see section The __init__.py files]. The icons folder contains the graphics for the task buttons and the application icon.

Simply starting the CSL Task GUI from the commandline would be done as follows:

Let’s build our own simple Task GUI and start with the most stated and useless function, Hello, World!. We will eventually build a Task GUI with tasks of increasing complexity and guide you through the different steps.

Create a folder yakka[1] that will be our Task GUI package. In the folder create an empty file __init__.py and a file named hello.py.

The hello.py file shall contain the following code:

Make sure you are at the same directory level as the yakka folder and then execute the following command from your terminal. That command will start the Task GUI as shown in the screenshot below.

We see the task appearing in the screenshot above. The task text is blue which means it will run immediately when clicked. The tasks name is the name of the function and the task group name is the name of the .py file. The icon is the standard icon used for the task buttons. When you click the task button, the Console shows the following output:

What do we see in this output:

Let’s add another task that takes an argument 'name' as a string with the default value of "John".

In the screenshot above, you can see the effect of the small changes we made in the hello.py. The tasks button group is now called 'Hello Tasks' and the new task we added got the 'Hello…​' name instead of the function name. The new task icon has a different color because it is selected. You can also see in the arguments panel that the type hint is picked up and shown in grey and the default name is also filled in grey in the text field. When I put my name there and press the 'Run' button, you can see that the function is called with the proper argument.

A Task is a function that is decorated with the @exec_task decorator. Such a function or task becomes a button in the Task GUI with a default icon. How the task is presented in the Task GUI and how the task is executed depends on the arguments that are passed into the decorator. In this section we will describe these arguments and what their effect is visually and behind the scenes.

The default behaviour is as follows: The function is decorated with @exec_task() without any arguments. The task name will be the function name, the task icon will be . When the task is selected, an arguments panel will be shown with a 'Run' button and the Task icon will look like . Click on the 'Run' button will execute the task in the selected Jupyter kernel (by default the 'python3' kernel). This is the behaviour that we have seen in the previous sections.

If you check back on Figure 1, you can see that each of the tasks is visualised with a nice icon and a proper task name, most task names are black but there are some blue task names. All these features are the result from optional parameters on the decorator. Let’s describe these parameters now in the following paragraphs. Remember all decorator parameters are optional.

So what about passing arguments to the task. Since a task is just a function, you write your function parameters like any other Python function. The Task GUI will interpret your function parameters and create a panel with input fields that match the type of your parameter (in case you used type hints).

Suppose we have a task to capture an image from a camera and save this image into a file in a folder. Such a function could look like the code below. How that looks in the GUI is shown in the TAB next to the code snippet.

There are five parameters for the capture_image function and one return value. The GUI shows these parameters in the arguments panel below the task button where you can fill in their values before pressing 'Run'. I have already filled the camera name, the exposure time and aperture, but all arguments are of type str since no type hint was used in the functions parameter list. There is also a message saying the return values will be captured in the variable response. This variable will be overwritten when the function is executed and is accessible from the Jupyter kernel.

For any given simple function, this is the default behaviour. You do not have to provide more information to run such a function from the Task GUI. All arguments will be passed into the function as strings. When you didn’t provide a value, None will be passed as an argument. In the screenshot above I have already pressed the 'Run' button, and you can see in the output panel what the arguments look like and what their type is.

Now let’s add type hints to the parameters of our function. We will use the string type for the camera name and the filename and location, and we will use a float for the exposure time and an integer for the aperture. For the location, we want to provide a default value.

If you now have a look at the arguments panel, you will see a lot of small things have changed. Behind the input fields for each parameter there is now the expected type in grey text. The location had a default value which is put as a placeholder in the input text field and there is a small copy icon aligned at the right in that text field. Pressing this icon will copy the default text into the input field and make this text editable. I again already pressed the 'Run' button, and you can see in the output console that the type of the exposure_time argument is 'float', and the type of the aperture argument is 'int'. The return string is also printed with the arguments filled in.

One more thing, sometimes you need to be able to input a None instead of an integer, float, or string. You can do this with the typing class Optional, e.g. Optional[int] allows you to use either None or an integer as argument.

But we can do better. For the filename and location, it would be nice if we could open a file selector box and navigate in our directory structure to select these values. We have done that in the following code snippet where the filename has type hint 'FileName' and location has type hint 'Directory'. These are what we call a TypeVar and both are bound to the Path type. The default for location now has changed to a Path value instead of a string.

Another change we added was the capture_response parameter of the decorator. The return value of the function is no longer captured in the variable response, but in the variable new_image.

If you now select the GUI tab above, the changes in the code result in two new icons ( and ) that replace the type behind the filename and location input fields. If you click these icons, a file selector box will open and allow you to select either a filename or a folder from your local disk. If you look at the code snippet printed in the output console, the filename and location arguments to the function are now of type PosixPath.

The change with the added decorator parameter capture_response is apparent in the arguments panel where it now says the return values will be captured in 'new_image', but also in the output console you can see that the variable name in which the return value is captured is new_image. So, this function will now, when it is executed, make the return value available in the kernel as the variable named new_image.

Let’s go one step further and change the type of the camera name. We have only a limited number of camera’s around the house and we don’t like to type their name all the time, so, we are going to create a dropdown list (or ComboBox) where we can select the camera we want to capture. Luckily, we do not have to worry about coding this dropdown menu, the Task GUI understands the type hint Enum and will automatically create a dropdown box for this parameter. In the following code snippet, we have created a CameraName enumeration class and use it as a type hint for the camera parameter.

In the GUI, you can see that the input field for the camera parameter is now a dropdown list. I selected the GARDEN camera already. In the output console, the argument for the function is CameraName.GARDEN, and in the f-string that creates the return value, we have to use camera.name because that camera variable is now an Enum object.

Let’s move from the function’s parameters to its return value(s). Up to now, we have always returned a string which was then printed in rich text in the output console. But what if we have a more complex return value like a table? It turns out that Rich Renderables like Text, Table, Panel, Syntax, etc. all are printed nicely in the output console when you return them from your task.

In the following example, I simulated a task that prints a table from our last bird count day in the backyard. Of course, in a real task this would take additional arguments like the date and other criteria and load the data from a database, but this example should give you a hunch of what is possible. The table is a Rich Table and is returned by the task.

If you run your function in the kernel, as a GUI App or as a script, your function can output information by e.g. printing, logging, or even displaying images and plots. Output is handled slightly different depending on how you run your function. We will focus here on running in the kernel. For more details about running the GUI App or a script, see Running your tasks.

Actually, our table example above with the bird count can also serve as function output. If we print the table with Rich Console, the output is caught and shown in the output console of the Task GUI almost exactly like if you return the table from the function. Any Rich Renderable that you print in your function will be shown as expected in the output console of the Task GUI.

Another type that we would want to inspect is the image type. Our camera example above returned a string to illustrate the behaviour we wanted to demonstrate, but we can also use the IPython display function to show images in a separate window. Let’s load one of our bird house pictures in the following example. This loads the image from disk and displays the image in a separate window. You will see in the output console that the image —which is still returned by the task— is captured in the response variable and is now printed as <IPython.core.display.Image object>. So, we return the actual image object in the variable response. We can see this image in the Jupyter QtConsole that can be opened from the second button (]) in the Task GUI toolbar. This button will open a new window with a Jupyter Python Console where you have a Python prompt. Type response at the prompt and the image will be shown. You can now further process this image if needed from the Python REPL.

As a small recap, type hints that are recognised by the Task GUI are: str, int, float, bool, list, tuple, and subclasses of Enum. Then, there are a number of types defined by the Task GUI that can be used for paths, i.e. FileName as a type for a filename including extension but without the directory part, FilePath as a type for a full file path which is the relative or absolute path to a file including the filename and extension, and Directory which is the location of a file, i.e. the path to the file without the filename.

Then we have a few special cases for more complex arguments to a function. The first one is a FixedList which is a list with a fixed number of elements of specific types. Additionally, there is the ListList which is a dynamic list of fixed lists, and finally, there is the CallBack type which makes your argument dependent on the outcome of a function call at the moment that you select the task and the arguments panel is created. The following sections will describe these type hints in more detail.

TBW → defining a new type hint

Since the task that is executed by the GUI is in fact a simple function, it can also return results. These results are normally captured in a variable response which is overwritten by new values each time a task is executed from the GUI, even if the task doesn’t return anything explicitly in which case response will be None.

The developer of the task can decide to capture the result of a task in a different variable or set of variables. This can be specified in the decorator parameter capture_response which can be a string or a tuple of strings. See an example below. The task generate_model returns three values of which we only need the 'model' and the 'hexhw'. In the capture_response you see that the second unused return value is captured in the _ and therefore ignored. If you need to ignore more return values, the *_ is a valid choice.

The GUI tab above shows the arguments panel when selecting the generate_model task. It tells you in which variables the return values will be available, i.e. model, _, hexhw. The Console tab shows a screenshot of the Jupyter Console where we inspected the model and hexhw variables.

Notice that the capture_response represents what you would actually write in your Python script when calling the function directly.

If you do not specify a path for an icon, the Task GUI will use the same icon for all task buttons. This becomes boring very rapidly, but also is error-prone since it will be hard to find your task and the wrong button can be pressed by accident. Looking back at Figure 1 you will see that we have created different icons for the different tasks. It gives our Task GUI not only a nice look-and-feel, but also makes it easier to recognise tasks and find the appropriate button.

The icon file type can be PNG or SVG. The latter is preferred because of its scalability. For a task button we need two icons that represent a normal state of the button and the selected state. By default, the normal state icon is and the selected state icon is . By convention, the selected state icon is the same as the normal state icon with a different accent of colors. The default icon size is 30×30 pixels.

The icons are specified as a parameter icons of the exec_task decorator and is a tuple with two Path elements. The first is the normal icon filepath, the second is the selected icon filepath. As an example, the decorator for the switch_on_camera task from Figure 1.

When your task is an immediate run task, only the normal state icon will be used.

TBW

TBW

The tasks and functions get their input from the arguments that are provided through the arguments panel. Sometimes however you will need input from the user and in the task this is then requested through the input() function. When you use this function, the message that you pass to the function will be printed on stdout and the REPL will be waiting on stdin for your reply.

Since we are now running your task from within the Task GUI, the task will be blocked and we need a way to provide the input on stdin. The current implementation is a little awkward, but we are working on it to make it more intuitive.

Whenever you use an input('prompt') function in your task (or any functions that you call from there), you will need an input_request argument in the @exec_task decorator. The input_request parameter is a tuple of strings where each string is a pattern that can match part of the 'prompt'. A simple example is given below:

The above code will match "[Y/n]" as part of the 'prompt' and the Task GUI will show the dialog from the next screenshot. That dialog asks you to answer the question from the output console with Yes or No. So, make sure that it is clear from your prompt message when the user needs to answer Yes and when she needs to answer No.

We are looking into a better handling of input requests. The problem is that it’s not in all circumstance clear when input is requested and what the question is. That’s why we ask to adapt your prompt message to a clear Yes/No answer.

So, why do we need the input_request parameter in the decorator? When you run your task in the kernel, any request on stdin will automatically be recognised by the kernel, communicated to the client and the Yes/No message dialog above will appear. In principle, since the kernel is capable of detecting the input request, we do not need the parameter for the decorator. However, when you run the same task as a GUI App or a script, an input request can not be detected and we need another way to identify an input request. Therefor, it is recommended to always provide the input_request parameter when input is requested from the task.

The __init__.py file is usually empty, but can contain a few definitions which are picked up by the Task GUI. If you have several TABs in your GUI with task buttons, these TABs were created from sub-packages. The __init__.py file for a sub-package can define the UI_TAB_DISPLAY_NAME to specify a name for the TAB instead of the package name. The __init__.py file of the root package, i.e. the one you used with the --module-path commandline option, can define the order in which the TABs appear in the Task GUI. Define a list of sub-package names in the variable UI_TAB_ORDER. The TABS will appear in that order in the GUI.

You can define the UI_TAB_HIDE variable in the __init__.py file and assign a Callable, e.g. a function, that returns a bool. When True, the sub-package TAB will be hidden. This can be used to hide/unhide certain tabs for users/developers.

Of course, if you have functions that are used by different tasks in seperate modules, you would want to define those functions also in the __init__.py file.

The __init__.py file for the project I’m working on currently (see Figure 1) looks like the code given below. We define a function to start the Task GUI with all required options. This function is then used as an entry_point in the setup.py file of our project. That way we can start the Task Gui with a simple command csl_ui.

The commandline option --cmd-log accepts one argument which must be an existing directory where the command log files will be written. The command log is a file that contains the code line that was executed to run the task, preceded with the timestamp when the task started and followed by the duration, i.e. the time it took to finish the task.

As an example, I reran the capture_image_camera_name task again and the entry for this task in the log file looks like this.

When an error occurred and an exception is raised, the Exception message is printed in the command log file. The following log entry shows the function raise_an_exception that raised a division by zero error.

The command log file will be located in the folder that was given with the --cmd-log commandline argument. There will be only a command log file when the argument is present. The filename will be based on the current date, e.g. 2023-04-13-cmd-log.txt.

Apart from tasks that print status information in the output console, there are sometimes specific items that you want to keep track of without the need to execute a task for this. In the project for which this application was developed, we needed to know about two identifiers at all time, i.e. the identifier for the configuration of our equipment (we call it the Setup) and the identifier of the currently running test (we call it the obsid). So, we developed a function which will repeatedly request these identifiers from the microservice that controls the configuration and display them in the status bar at the bottom of the Task GUI. The code snippet below defines a function show_setup_and_obs_id() which is decorated with @exec_recurring_task. The decorator takes a parameter status_type which can be 'NORMAL' or 'PERMANENT'. When status_type is NORMAL the message will be printed on the left side of the status bar, when status_type is PERMANENT the message will be printed on the right side of the statusbar. The example below is specific for our project, in your case, you will want to put different things in the status bar. The GUI in the TAB shows the output of the function.

The return value of a recurring task shall be of type str. Make sure the string is not too long so it will fit nicely in the status bar.

The recurring task can in principle be defined in any module that is located in the module-path, i.e. where also the usual tasks are defined, but it is preferred to have a separate module recurring.py to contain the task definition. It is also possible to define more than one recurring task e.g. one with status_type=NORMAL and another with status_type=PERMANENT. Both functions will be executed in different threads every second.

The recurring functions are executed every second in a separate thread so they don’t block the Task GUI. Take care that your recurring function doesn’t take longer than a fraction of a second to execute.