diff options
Diffstat (limited to 'vendor/voclient/voapps/task/vaopackage.py')
| -rw-r--r-- | vendor/voclient/voapps/task/vaopackage.py | 453 |
1 files changed, 453 insertions, 0 deletions
diff --git a/vendor/voclient/voapps/task/vaopackage.py b/vendor/voclient/voapps/task/vaopackage.py new file mode 100644 index 00000000..a894e612 --- /dev/null +++ b/vendor/voclient/voapps/task/vaopackage.py @@ -0,0 +1,453 @@ +""" +The VAO Package and Tasking Interfaces. + +The tasking interface defines the python-side classes needed to manage and +execute host processes that implement the "VAO Package" binary interface. +These classes load the package (i.e. execute the binary as a connected +processes and interogate it for a list of available tasks). The VOTask +interface is used to set the input parameters, execute the task and process +the result parameter set (PSet). + +The VOPSet interface manages a collection of VOParam parameter objects: +input parameters will typically define options for the host task (e.g. +input file, processing options, etc), while output parameters may contain +arbitrary objects returned by the task (e.g. a FITS file or VOTable) or +strings which make up the stdout/stderr streams of the task. A VOParam has +attributes needed to describe the type of parameter, by selecting +parameters of the same name from a PSet (e.g. 'msgs') an application can +process multiple output objects as needed. + +A 'task' is a computational component which can be executed as a process by +the host operating system (or a related environment such as a cluster). +Tasks may be written in any language so long as the defined tasking +interface is observed. The 'package' refered to here should not be +confused with a Python package. A Python package is an element of Python, +a 'package' as referred to here is a collection of tasks and their +associated metadata. + +""" + +import sys +import os +import re +import glob + + + +# Module Globals and Functions + +""" The Package search path. +""" +vopkg_path = ['.'] # always include the cwd +vopkg_extn = ".vop" + +pkg_list = [] # scan package dirs to get list of packages +pkg_struct = None # dictionary of package data in the form + # key = pkgname + # value = tuple(<path>, [<tasklist>]) + + +def setPkgDirs (dirs): + ''' Set the VO package search path as an absolute list of directories. + @param dirs list of directory to use as search path + + Returns: Nothing + ''' + vopkg_path = [.] + dirs + + +def addPkgDir (dir): + ''' Append the given directory to the package search path. + @param dir the directory to add to the search path + + Returns: Nothing + ''' + vopkg_path.append(dir) + + +def getPkgDirs (): + ''' Get the VO package search path as a list of directories. + + Returns: Nothing + ''' + return (vopkg_path) + + +def pkgList (pattern=None): + ''' Get the list of available packages. + @param pattern the package name pattern to match + + Returns: A list available package names. + ''' + + pat = pattern # construct the pattern string + if (pattern == None): + pat = "*" + + pkg_list = [] # scan package dirs to get list of packages + for dir in vopkg_path: + if os.path.isdir(dir): + pfiles = glob.glob(dir + "/" + pat + vopkg_extn) + for f in pfiles: + root,ext = os.path.splitext(os.path.basename(f)) + pkg_list.append(root) + pkg_struct[root] = [ f ] + else: + root,ext = os.path.splitext(os.path.basename(dir)) + if (re.search(pattern,root)): + pkg_list.append(root) + pkg_struct[root] = [ dir ] + + # Save just the package names as a valid list. + pkg_list = pkg_struct.keys() + + # Scan the package list, to get a list of tasks in each package. + for pkg in pkg_list: + tlist = vop_taskList (pkg_struct[pkg][0]) # get task list + pkg_struct[pkg].append(tlist) # save in struct + + + +def scan (): + ''' Force a re-scan of the package search path for available package + files. Each directory in the path is searched for a ".vop" file + indicating a VO package executable, this file is then interrogated + for a list of tasks. This allows new package files to be installed + (or removed) as the module is running. + + Returns: Nothing + ''' + lst = pkgList ("*") # scan all packages + + +def loadPackage (name, file=None): + ''' Load the package. Effectively all this does is create a VOPackage + object from the metadata for the named package, this requires + that we start the package binary to get the metadata information. + If a 'file' parameter is specified we open that file regardless of + the name, allowing any VOPackage file to be used dynamically. + + When a package is loaded, bindings for each of the tasks are generated + automatically in order to allow direct access to the task. As an + example: + + >>> vop = loadPackage ("vo-cli") # from search path + >>> results = vop.voregistry (searchTerm="quasar") + >>> printResultPset (results) # user-defined function + + When developing a package or when an app needs to explicitly include + a new package, it may be accessed directly as: + + >>> vop = loadPackage ("vo-cli",file="/path/devpkg.e") + + @param name the package name + @param file the package binary file to execute + + Returns: The loaded VOPackage object + ''' + pass + +def taskList (pkg, pattern=None): + ''' List the tasks available in a package. + @param pkg the package name + @param pattern the task pattern name to match + + Returns: A list of tasks available in the package who's name + matches the 'pattern' string. + ''' + pass + +def pkgAttrs (pkg): + ''' Get the attributes for the named package, i.e. create a dictionary + of package metadata. + @param pkg the package name + + Returns: A dictionary of the package attributes. + ''' + pass + +def taskAttrs (pkg, task): + ''' Get the attributes for the named task in the package, i.e. create + a dictionary of task metadata. + @param pkg the package name + @param task the task name + + Returns: A dictionary of the task attributes. + ''' + pass + + +class VOPackageError (Exception): + ''' A base class for VO Package errors. Use of this exception is TBD. + ''' + pass + + +class VOPackage: + ''' A class defining a VOPackage object. A VOPackage is a collection + of tasks as well as metadata about the package itself. The + functional part of the package is implemented in a binary file + executing as a connected process, task discovery and execution are + implemented as commands sent to the package binary, results are + returned over the IPC channel as a stream of parameter objects. + ''' + + # Class attributes + name = None # package name + descr = None # description string + author = None # package author + contact = None # contact email address + iconUrl = None # URL to package icon + version = None # package version string + dir = None # the directory containing the package + binfile = None # the name of the package binary + + def __init__ (self, dirs): + pass + + def __iter__ (self, dirs): # get next task in the package + pass + + def taskList (self, pattern=None): + ''' Get the list of tasks in the package which match a pattern string. + If no pattern is specified, all tasks are returned. + @param pattern the parameter name to match + + Returns: A list of available tasks who's name matches + the pattern string. + ''' + pass + + def pkgAttrs (self): + ''' Get the attributes for the VO Package as a dictionary string. + + Returns: A dictionary of the package attributes + ''' + pass + + +class VOTaskError (Exception): + ''' A base class for Task execution errors. + ''' + pass + +class VOTaskParameterError (VOTaskError): + ''' an exception indicating an error in the task calling parameters + ''' + pass + +class VOTaskExecutionError (VOTaskError): + ''' an exception indicating an error when executing the task + ''' + pass + + +class VOTask: + ''' A class defining a VO Task object. + ''' + + name = None # task name + pkg = None # parent package name + descr = None # task description string + params = None # task input parameter set + + status = None # task execution return status (OK or ERROR) + msg = None # task execution return error message + + + def __init__ (self, name, pkg, descr, params): + ''' create the VOTask instance + ''' + pass + + def taskAttrs (self): + ''' Get the attributes of the task as a dictionary. + + Returns: A dictionary of the task attributes + ''' + pass + + def setParams (pset): + ''' Set the task parameter pset. Parameters in the pset argument + will be used set the values for the task parameter pset, i.e. + the argument pset can be just a subset of the task parameters, + we'll match the names and set the values for only those params. + If the argument pset contains a parameter not already in the + task input pset, it will be added as a new parameter. + @param pset parameter set to load + + Returns: A dictionary of the task attributes + ''' + pass + + def getParams (): + ''' Set the task parameter pset. + + Returns: The task parameter pset. + ''' + pass + + def setCallback (pattern, func): + ''' Set a callback function to be run whenever a parameter name + that matches the pattern is encountered. Pattern applies only + to the output parameter set. + @param pattern the parameter name to match + @param func the function to be called when parameter encountered + + Returns: nothing + ''' + pass + + def executeSync (self): + ''' Execute the task as a synchronous process. + @throws VOTaskParameterError thrown when parameters are invalid + @throws VOTaskExecutionError thrown when there is an error is + executing a task, e.g. a segfault. + + Returns: The result pset. + ''' + pass + + def executeASync (self): + ''' Execute the task as a asynchronous process. + + Returns: Nothing + ''' + pass + + def wait (self): + ''' Wait for the exit of an asynchronous execution + @throws VOTaskParameterError thrown when parameters are invalid + @throws VOTaskExecutionError thrown when there is an error is + executing a task, e.g. a segfault. + + Returns: The result pset. + ''' + pass + + def status (self): + ''' Get the status of an executing asynchronous task. + + Returns: Task exec status ('Pending','Running','Done','Error') + ''' + pass + + +class VOPset: + ''' A class defining a PSet object. + ''' + + name = None # pset name + pkg = None # package name + task = None # task name associated with pset + description = None # pset description name + + def __init__ (self, name, type, descr, encoding): + ''' create the VOPset instance + ''' + pass + + def loadPset (pkg=None, task=None, saveFile=None): + ''' Load the pset from the named task in the package. If 'saveFile' + is specified the pset is restored from that file. + @param pkg package name + @param task task name + @param saveFile name of the saved parameter file to load + + Returns: The loaded PSet + ''' + pass + + def savePset (saveFile): + ''' Save the PSet to the named file. Serialization of the PSet is + TBD, probably some sort of simple XML schema. + @param saveFile name of the saved parameter file + + Returns: Nothing + ''' + pass + + def paramSet (pattern=None): + ''' Create pset from params who's name matches the 'pattern' string. + If no pattern is specified, all parameters are returned. + @param pattern parameter pattern name to match + + Returns: The constructed PSet + ''' + pass + + def paramList (pattern=None): + ''' Get list of params who's name matches the 'pattern' string. If + no pattern is specified, all parameters are returned. + @param pattern parameter pattern name to match + + Returns: Nothing + ''' + pass + + def addParam (name, type, description, encoding=None): + ''' Add a new parameter with the specified attributes to the pset. + @param name name of the parameter to add + @param type parameter type value + @param descr parameter description string + @param encoding parameter encoding + + Returns: The created parameter + ''' + pass + + def delParam (name): + ''' Delete the named parameter from the pset. + @param name name of the parameter to delete + + Returns: Nothing + ''' + pass + + def getParam (name): + ''' Get the parameter with the given name. + @param name name of the parameter to retrieve + + Returns: Requested parameter + ''' + pass + + +class VOParam: + ''' A class defining a Parameter object. + ''' + + name = None # parameter name + type = None # parameter type (string/int/real/bool/blob) + desc = None # parameter description string + encoding = None # encoding of param (i.e. mime type) + + + def __init__ (self, name, type, descr, encoding): + ''' create the VOParam instance + ''' + pass + + def paramAttrs (): + ''' Get the parameter attributes. + + Returns: A dictionary of parameter attrbutes + ''' + pass + + def getValue (): + ''' Get the value of the parameter (may be a list) + + Returns: The parameter's value + ''' + pass + + def setValue (val): + ''' Set the value of a parameter. + @param val the value of the paramter (arbitrary type) + + Returns: Nothing + ''' + pass + + |