From f7506e9fe00f3944e1c35a97de7b9de170adce67 Mon Sep 17 00:00:00 2001
From: Sinisa Veseli <sveseli@aps.anl.gov>
Date: Mon, 6 Mar 2017 22:25:49 +0000
Subject: [PATCH] starting to document DS experiment API
---
doc/sphinx/source/dm.ds_web_service.api.rst | 12 ++++
doc/sphinx/source/index.rst | 1 +
.../daq_web_service/api/experimentDaqApi.py | 2 +-
.../dm/ds_web_service/api/experimentDsApi.py | 56 ++++++++++++++++++-
4 files changed, 68 insertions(+), 3 deletions(-)
create mode 100644 doc/sphinx/source/dm.ds_web_service.api.rst
diff --git a/doc/sphinx/source/dm.ds_web_service.api.rst b/doc/sphinx/source/dm.ds_web_service.api.rst
new file mode 100644
index 00000000..da6ab6d5
--- /dev/null
+++ b/doc/sphinx/source/dm.ds_web_service.api.rst
@@ -0,0 +1,12 @@
+.. automodule:: dm.ds_web_service.api
+
+.. currentmodule:: dm.ds_web_service.api
+
+ExperimentDsApi
+-----------------
+
+.. autoclass:: dm.ds_web_service.api.experimentDsApi.ExperimentDsApi()
+ :show-inheritance:
+ :members: __init__, getExperimentTypes, getExperiments
+
+
diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst
index d7220f53..ea388478 100644
--- a/doc/sphinx/source/index.rst
+++ b/doc/sphinx/source/index.rst
@@ -12,6 +12,7 @@ The `dm` package contains python APIs for accessing Data Management services.
:maxdepth: 4
:caption: Contents:
+ dm.ds_web_service.api
dm.daq_web_service.api
dm.aps_bss.api
diff --git a/src/python/dm/daq_web_service/api/experimentDaqApi.py b/src/python/dm/daq_web_service/api/experimentDaqApi.py
index 4dc9f83f..802ebf5e 100755
--- a/src/python/dm/daq_web_service/api/experimentDaqApi.py
+++ b/src/python/dm/daq_web_service/api/experimentDaqApi.py
@@ -38,7 +38,7 @@ class ExperimentDaqApi(DaqRestApi):
:param protocol: DM service protocol
:type protocol: str
- >>> api = ExperimentDaqApi(username='dm', password='XYZ', host='bluegill1', port=22236, protocol='https')
+ >>> api = ExperimentDaqApi(username='dm', password='XYZ', host='bluegill1', port=33336, protocol='https')
'''
DaqRestApi.__init__(self, username, password, host, port, protocol)
diff --git a/src/python/dm/ds_web_service/api/experimentDsApi.py b/src/python/dm/ds_web_service/api/experimentDsApi.py
index cf2314f3..f898f866 100755
--- a/src/python/dm/ds_web_service/api/experimentDsApi.py
+++ b/src/python/dm/ds_web_service/api/experimentDsApi.py
@@ -10,18 +10,70 @@ from dm.common.objects.experimentType import ExperimentType
from dsRestApi import DsRestApi
class ExperimentDsApi(DsRestApi):
+ '''
+ Data Management API for accessing experiment interface provided by the
+ DS service.
+ '''
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 = ExperimentDsApi(username='dm', password='XYZ', host='bluegill1', port=22236, protocol='https')
+ '''
DsRestApi.__init__(self, username, password, host, port, protocol)
- @DsRestApi.execute
+ @DsRestApi.execute2
def getExperimentTypes(self):
+ '''
+ Get list of allowed experiment types.
+
+ :returns: list of ExperimentType objects
+
+ :raises AuthorizationError: in case user is not logged in
+
+ :raises DmException: in case of any other errors
+
+ >>> experimentTypeList = api.getExperimentTypes()
+ >>> for experimentType in experimentTypeList:
+ >>> print experimentType['id'], experimentType['name']
+ '''
+
url = '%s/experimentTypes' % (self.getContextRoot())
responseData = self.sendSessionRequest(url=url, method='GET')
return self.toDmObjectList(responseData, ExperimentType)
- @DsRestApi.execute
+ @DsRestApi.execute2
def getExperiments(self):
+ '''
+ Get list of known experiments.
+
+ :returns: list of Experiment objects
+
+ :raises AuthorizationError: in case user does not have DM administrator role
+
+ :raises DmException: in case of any other errors
+
+ >>> experimentList = api.getExperiments()
+ >>> for experiment in experimentList:
+ >>> print experiment['id'], experiment['name']
+ '''
+
url = '%s/experiments' % (self.getContextRoot())
responseData = self.sendSessionRequest(url=url, method='GET')
return self.toDmObjectList(responseData, Experiment)
--
GitLab