APFTask Python library

All task implementations use the functions defined in the APFTask module to interact with the apftask service, whether they use the apftask command line interface, or directly use the APFTask module. The latter is the preferred approach for task implementations written in Python.

Task-agnostic functions

This group of functions can be used with any task, either as part of a task’s implementation, or to query other tasks.

APFTask.Event()

threading.Event() is a factory function, not a class definition. This is effectively subclassing the base threading.Event class, adding an abort_waitFor boolean that can be used to signal waitFor() that it should return to the caller.

APFTask.get(task, suffixes)

Return a dictionary of the most current values of the requested set of suffixes for the given task. Each keyword is specified by its suffix: for example, to request values for the KTL keywords GENERIC_CONTROL and GENERIC_STATUS, one would set task to ‘GENERIC’, and keywords to (‘CONTROL’, ‘STATUS’).

APFTask.list()

List the available tasks defined in the apftask service. This is done by confirming that apftask.TASK_CONTROL exists.

APFTask.lookup(task)

Confirm that task is a valid task in the apftask KTL service. This is done by confirming that apftask.TASK_CONTROL exists.

APFTask.status(task)

Report on the status of either a single task, or a sequence of tasks.

APFTask.version()

Return a version number for this module. The version number is computed by multiplying the major CVS revision of each individual component by 1,000, directly adding the minor version, and summing the results. SVN revision numbers are strictly added.

Functions to modify other tasks

This group of functions performs operations on other tasks, as opposed to being used internally as part of a task’s implementation.

APFTask.abort(task)

Request that task stop running and exit.

APFTask.pause(task)

Request that task temporarily pause execution; invoke proceed() to request that task resume execution.

APFTask.proceed(task)

Request that task resume execution. proceed() is typically invoked after having first invoked pause().

Functions used within a task

This group of functions is intended for use as part of a task’s implementation.

APFTask.call(task, auto, function, *args, **kwargs)

Call the specified function with the provided arguments and keyword arguments (args and kwargs respectively) while transparently monitoring the status of the _INTERRUPT and _CONTROL keywords associated with the specified task. If auto is set to True, call() will automatically pause if the _CONTROL mode is set to ‘Pause’. If auto is False, a ControlMode exception will be raised instead. If at any point _INTERRUPT goes True, a ControlMode or a Tripwire exception will be raised, depending on the cause.

Upon success, the return value from the specified function will be passed to the caller.

Warning

the function will be called in a background thread. Some libraries, such as tkinter, require that all function calls be made from the same thread.

APFTask.do(task, auto, *command)

Execute the specified command while transparently monitoring the status of the _INTERRUPT and _CONTROL keywords associated with the specified task. If auto is set to True, do() will automatically pause if the _CONTROL mode is set to ‘Pause’. If auto is False, a ControlMode exception will be raised instead. If at any point _INTERRUPT goes True, a ControlMode or a Tripwire exception will be raised, depending on the cause.

Upon success, the return status from the specified command will be returned.

Note that the command must be specified as a sequence of strings, not as a single string; for example, (‘gshow’, ‘-s’, ‘apftask’), not ‘gshow -s apftask’.

APFTask.establish(task, process)

Establish the designated process (specified as an integer process ID) as the running implementation of the designated task.

APFTask.increment(task, suffix, amount=1)

Increment a task keyword by the specified amount. The keyword is treated as an integer, regardless of its native type. For example, the caller might specify a task name and the ‘STEP’ suffix; this will result in ‘STEP’ being incremented by one.

APFTask.message(task, text)

Write a text string out to the TASK_MESSAGE keyword.

APFTask.phase(task, phase)

Set the task’s PHASE keyword to the specified value.

APFTask.set(task, suffix=None, value=None, pairs=None, wait=True)

Set a series of keyword/value pairs. Each keyword is specified by its suffix: for example, to set GENERIC_CONTROL one would set task to ‘GENERIC’, and suffix to ‘CONTROL’. To set multiple keywords in one operation, use the pairs argument, which is expected to be a sequence of two-item dictionaries, each with keys ‘suffix’ and ‘value’. Using the above example, the dictionary would contain: {‘suffix’: ‘CONTROL’, ‘value’: ‘Proceed’}

APFTask.step(task, step)

Set the task’s STEP keyword to the specified value.

APFTask.validate(task, process=None)

Confirm that the designated process (specified as an integer process ID) running on the current hostname is the valid running implementation of the designated task.

APFTask.wait(task, auto, timeout=None, wake=None)

Wrapper to waitFor(), setting the expression to None.

APFTask.waitFor(task, auto, expression=None, timeout=None, wake=None)

Similar to do(), except that the arguments are expected to be valid arguments for ktl.waitFor(). Setting expression to None means that only the internal apftask controls will be watched for; this mode is used by call() and do(), and makes an effective way to wait for activity to occur, and do the right thing when the control mode changes. The wake argument is expected to be a threading.Event instance, as generated by the Event() factory function. The wake argument can be used to signal waitFor() that it should return to the caller.