rename experiment daq api

Makefile

@@ -2,7 +2,7 @@
 # are defined in the RULES file.
 
 TOP = .
-SUBDIRS = src
+SUBDIRS = src doc
 
 .PHONY: support dev-config
 .PHONY: db backup deploy-web-portal undeploy-web-portal deploy-ds-web-service undeploy-ds-web-service deploy-daq-web-service undeploy-daq-web-service deploy-cat-web-service undeploy-cat-web-service deploy-proc-web-service undeploy-proc-web-service
@@ -30,6 +30,9 @@ destroy-db:
 backup:
 	$(TOP)/sbin/dm_backup.sh 
 
+api-doc:
+	make -C doc/sphinx html
+
 configure-web-portal: dist
 	$(TOP)/sbin/dm_configure_web_portal.sh
 

src/python/dm/common/api/dmApi.py

 #!/usr/bin/env python
 
 import json
+from functools import wraps
+from decorator import decorator
 from dm.common.exceptions.dmException import DmException
 from dm.common.utility.loggingManager import LoggingManager
 
@@ -34,3 +36,25 @@ class DmApi(object):
                 cls.getLogger().exception('%s' % ex)
                 raise DmException(exception=ex)
         return decorate
+
+    # Exception decorator for api calls
+    # Use two decorators for the sake of documentation
+    @classmethod
+    def execute2(cls, *dargs, **dkwargs):
+        def internalCall(func):
+            @wraps(func)
+            def wrappedCall(func, *args, **kwargs):
+                try:
+                    response = func(*args, **kwargs)
+                    return response
+                except DmException, ex:
+                    raise
+                except Exception, ex:
+                    cls.getLogger().exception('%s' % ex)
+                    raise DmException(exception=ex)
+            return decorator(wrappedCall, func)
+        if len(dargs) == 1 and callable(dargs[0]):
+            return internalCall(dargs[0])
+        else:
+            return internalCall
+

src/python/dm/daq_web_service/api/experimentRestApi.py → src/python/dm/daq_web_service/api/experimentDaqApi.py

@@ -13,13 +13,61 @@ from dm.common.objects.pluginInfo import PluginInfo
 from dm.common.objects.daqInfo import DaqInfo
 from daqRestApi import DaqRestApi
 
-class ExperimentRestApi(DaqRestApi):
+class ExperimentDaqApi(DaqRestApi):
+    ''' 
+    This class is used to access experiment interface provided by the
+    DAQ service on a DM experiment station.
+    '''
     
     def __init__(self, username=None, password=None, host=None, port=None, protocol=None):
+        ''' 
+        Constructor.
+
+        :param username: DM username
+        :type username: str
+
+        :param password: DM password
+        :type password: str
+
+        :param host: DM service host
+        :type host: str
+
+        :param port: DM service port
+        :type port: int
+
+        :param protocol: DM service protocol
+        :type protocol: str
+
+        >>> api = ExperimentDaqApi(username='dm', password='XYZ', host='bluegill1', port=22236, protocol='https')
+        '''
         DaqRestApi.__init__(self, username, password, host, port, protocol)
 
-    @DaqRestApi.execute
+    @DaqRestApi.execute2
     def startDaq(self, experimentName, dataDirectory, daqInfo={}):
+        '''
+        Start data acquisition (real-time directory monitoring and file upload).
+
+        :param experimentName: experiment name
+        :type experimentName: str
+
+        :param dataDirectory: data directory URL
+        :type dataDirectory: str
+
+        :param daqInfo: DAQ info
+        :type dataDirectory: dict
+
+        :returns: DAQ id
+
+        :raises InvalidRequest: in case of empty experiment name or data directory
+
+        :raises AuthorizationError: in case user is not authorized to manage DM station
+
+        :raises ObjectNotFound: in case experiment does not exist
+
+        :raises DmException: in case of any other errors
+
+        >>> daqId = api.startDaq(experimentName='test01', dataDirectory='/home/dm/test')
+        '''
         if not experimentName:
             raise InvalidRequest('Experiment name must be provided.')
         if not dataDirectory:
@@ -29,8 +77,27 @@ class ExperimentRestApi(DaqRestApi):
         responseDict = self.sendSessionRequest(url=url, method='POST')
         return DaqInfo(responseDict)
 
-    @DaqRestApi.execute
+    @DaqRestApi.execute2
     def stopDaq(self, experimentName, dataDirectory):
+        '''
+        Stop data acquisition (real-time directory monitoring and file upload).
+
+        :param experimentName: experiment name
+        :type experimentName: str
+
+        :param dataDirectory: data directory URL
+        :type dataDirectory: str
+
+        :raises InvalidRequest: in case of empty experiment name or data directory
+
+        :raises AuthorizationError: in case user is not authorized to manage DM station
+
+        :raises ObjectNotFound: in case experiment does not exist, or if there are no active DAQs for a given experiment and data directory
+
+        :raises DmException: in case of any other errors
+
+        >>> api.stopDaq(experimentName='test01', dataDirectory='/home/dm/test')
+        '''
         if not experimentName:
             raise InvalidRequest('Experiment name must be provided.')
         if not dataDirectory:
@@ -100,6 +167,6 @@ class ExperimentRestApi(DaqRestApi):
 # Testing.
 
 if __name__ == '__main__':
-    api = ExperimentRestApi('sveseli', 'sveseli', 'zagreb.svdev.net', 33336, 'http')
+    api = ExperimentDaqApi('sveseli', 'sveseli', 'zagreb.svdev.net', 33336, 'http')
     print api.startDaq('experiment1', '/tmp/data/experiment1')
 

src/python/dm/daq_web_service/cli/getDaqInfoCli.py

 #!/usr/bin/env python
 
 from daqWebServiceSessionCli import DaqWebServiceSessionCli
-from dm.daq_web_service.api.experimentRestApi import ExperimentRestApi
+from dm.daq_web_service.api.experimentDaqApi import ExperimentDaqApi
 from dm.common.exceptions.invalidRequest import InvalidRequest
 
 class GetDaqInfoCli(DaqWebServiceSessionCli):
@@ -24,7 +24,7 @@ Description:
     Retrieves detailed information for the specified data acquisition.
         """)
         self.checkArgs()
-        api = ExperimentRestApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
+        api = ExperimentDaqApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
         daqInfo = api.getDaqInfo(self.getId())
         print daqInfo.getDisplayString(self.getDisplayKeys(), self.getDisplayFormat())
 

src/python/dm/daq_web_service/cli/getProcessingPluginsCli.py

 #!/usr/bin/env python
 
-from dm.daq_web_service.api.experimentRestApi import ExperimentRestApi
+from dm.daq_web_service.api.experimentDaqApi import ExperimentDaqApi
 from daqWebServiceSessionCli import DaqWebServiceSessionCli
 
 class GetProcessingPluginsCli(DaqWebServiceSessionCli):
@@ -14,7 +14,7 @@ class GetProcessingPluginsCli(DaqWebServiceSessionCli):
 Description:
     Retrieves list of known processing plugins.
         """)
-        api = ExperimentRestApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
+        api = ExperimentDaqApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
         plugins = api.getProcessingPlugins()
         for plugin in plugins:
             print plugin.getDisplayString(self.getDisplayKeys(), self.getDisplayFormat())

src/python/dm/daq_web_service/cli/getUploadInfoCli.py

 #!/usr/bin/env python
 
 from daqWebServiceSessionCli import DaqWebServiceSessionCli
-from dm.daq_web_service.api.experimentRestApi import ExperimentRestApi
+from dm.daq_web_service.api.experimentDaqApi import ExperimentDaqApi
 from dm.common.exceptions.invalidRequest import InvalidRequest
 
 class GetUploadInfoCli(DaqWebServiceSessionCli):
@@ -24,7 +24,7 @@ Description:
     Retrieves detailed information for the specified data upload id.
         """)
         self.checkArgs()
-        api = ExperimentRestApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
+        api = ExperimentDaqApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
         uploadInfo = api.getUploadInfo(self.getId())
         print uploadInfo.getDisplayString(self.getDisplayKeys(), self.getDisplayFormat())
 

src/python/dm/daq_web_service/cli/listDaqsCli.py

@@ -3,7 +3,7 @@
 from daqWebServiceSessionCli import DaqWebServiceSessionCli
 
 from dm.common.constants import dmProcessingStatus
-from dm.daq_web_service.api.experimentRestApi import ExperimentRestApi
+from dm.daq_web_service.api.experimentDaqApi import ExperimentDaqApi
 from dm.common.exceptions.invalidRequest import InvalidRequest
 
 class ListDaqsCli(DaqWebServiceSessionCli):
@@ -27,7 +27,7 @@ Description:
     Retrieves all known daqs.
         """)
         self.checkArgs()
-        api = ExperimentRestApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
+        api = ExperimentDaqApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
         daqs = api.listDaqs(self.getStatus())
         for daq in daqs:
             print daq.getDisplayString(self.getDisplayKeys(), self.getDisplayFormat())

src/python/dm/daq_web_service/cli/listUploadsCli.py

@@ -3,7 +3,7 @@
 from daqWebServiceSessionCli import DaqWebServiceSessionCli
 
 from dm.common.constants import dmProcessingStatus
-from dm.daq_web_service.api.experimentRestApi import ExperimentRestApi
+from dm.daq_web_service.api.experimentDaqApi import ExperimentDaqApi
 from dm.common.exceptions.invalidRequest import InvalidRequest
 
 class ListUploadsCli(DaqWebServiceSessionCli):
@@ -27,7 +27,7 @@ Description:
     Retrieves all known uploads.
         """)
         self.checkArgs()
-        api = ExperimentRestApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
+        api = ExperimentDaqApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
         uploads = api.listUploads(self.getStatus())
         for upload in uploads:
             print upload.getDisplayString(self.getDisplayKeys(), self.getDisplayFormat())

src/python/dm/daq_web_service/cli/startDaqCli.py

 #!/usr/bin/env python
 
-from dm.daq_web_service.api.experimentRestApi import ExperimentRestApi
+from dm.daq_web_service.api.experimentDaqApi import ExperimentDaqApi
 from dm.common.exceptions.invalidRequest import InvalidRequest
 from daqWebServiceSessionCli import DaqWebServiceSessionCli
 
@@ -33,7 +33,7 @@ Description:
     file processing plugins.
         """)
         self.checkArgs()
-        api = ExperimentRestApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
+        api = ExperimentDaqApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
         daqInfo = self.splitArgsIntoDict()
         self.updateDaqInfoFromOptions(daqInfo)
         daqInfo = api.startDaq(self.getExperimentName(), self.getDataDirectory(), daqInfo=daqInfo)

src/python/dm/daq_web_service/cli/stopDaqCli.py

 #!/usr/bin/env python
 
-from dm.daq_web_service.api.experimentRestApi import ExperimentRestApi
+from dm.daq_web_service.api.experimentDaqApi import ExperimentDaqApi
 from dm.common.exceptions.invalidRequest import InvalidRequest
 from daqWebServiceSessionCli import DaqWebServiceSessionCli
 
@@ -24,7 +24,7 @@ Description:
     Stop DAQ for a given experiment and data directory.
         """)
         self.checkArgs()
-        api = ExperimentRestApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
+        api = ExperimentDaqApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
         daqInfo = api.stopDaq(self.getExperimentName(), self.getDataDirectory())
         print daqInfo.getDisplayString(self.getDisplayKeys(), self.getDisplayFormat())
 

src/python/dm/daq_web_service/cli/stopUploadCli.py

 #!/usr/bin/env python
 
 from daqWebServiceSessionCli import DaqWebServiceSessionCli
-from dm.daq_web_service.api.experimentRestApi import ExperimentRestApi
+from dm.daq_web_service.api.experimentDaqApi import ExperimentDaqApi
 from dm.common.exceptions.invalidRequest import InvalidRequest
 
 class StopUploadCli(DaqWebServiceSessionCli):
@@ -24,7 +24,7 @@ Description:
     Aborts specified data upload.
         """)
         self.checkArgs()
-        api = ExperimentRestApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
+        api = ExperimentDaqApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
         uploadInfo = api.stopUpload(self.getId())
         print uploadInfo.getDisplayString(self.getDisplayKeys(), self.getDisplayFormat())
 

src/python/dm/daq_web_service/cli/uploadCli.py

 #!/usr/bin/env python
 
 from daqWebServiceSessionCli import DaqWebServiceSessionCli
-from dm.daq_web_service.api.experimentRestApi import ExperimentRestApi
+from dm.daq_web_service.api.experimentDaqApi import ExperimentDaqApi
 from dm.common.exceptions.invalidRequest import InvalidRequest
 from dm.common.constants import dmProcessingMode
 
@@ -49,7 +49,7 @@ Description:
     to file processing plugins.
         """)
         self.checkArgs()
-        api = ExperimentRestApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
+        api = ExperimentDaqApi(self.getLoginUsername(), self.getLoginPassword(), self.getServiceHost(), self.getServicePort(), self.getServiceProtocol())
         daqInfo = self.splitArgsIntoDict()
         self.updateDaqInfoFromOptions(daqInfo)
         uploadInfo = api.upload(self.getExperimentName(), self.getDataDirectory(), daqInfo=daqInfo)