Spec 24062: Support Python 3

 - added some mocking for unittests
 - added additional documentation
 - added execeptions to handle_response, since it would otherwise just swallow anything not 200

Author: labkey-ians

labkey/__init__.py

@@ -14,8 +14,9 @@
 # limitations under the License.
 #
 from labkey import query, experiment  # wiki, messageboard
+from pkg_resources import get_distribution
 
-__title__ = 'labkey'
-__version__ = '0.3.0'
+__title__ = get_distribution('labkey').project_name
+__version__ = get_distribution('labkey').version
 __author__ = 'LabKey Software'
-__license__ = 'Apache 2.0'
+__license__ = 'Apache License 2.0'

labkey/experiment.py

@@ -18,6 +18,7 @@
 
 from requests.exceptions import SSLError
 from labkey.utils import build_url, handle_response
+from labkey.exceptions import ServerContextError
 
 
 # EXAMPLE
@@ -49,8 +50,8 @@
 # --------
 # /EXAMPLE
 
-# TODO Incorporate logging
 
+# TODO Incorporate logging
 def load_batch(server_context, assay_id, batch_id):
     """
     Loads a batch from the server.
@@ -74,12 +75,12 @@ def load_batch(server_context, assay_id, batch_id):
     }
 
     try:
-        response = session.post(load_batch_url, data=json.dumps(payload), headers=headers)
+        response = session.post(load_batch_url, data=json.dumps(payload, sort_keys=True), headers=headers)
         json_body = handle_response(response)
         if json_body is not None:
             loaded_batch = Batch.from_data(json_body['batch'])
     except SSLError as e:
-        raise Exception("Failed to match server SSL configuration. Failed to load batch.")
+        raise ServerContextError(e)
 
     return loaded_batch
 
@@ -132,13 +133,13 @@ def save_batches(server_context, assay_id, batches):
 
     try:
         # print(payload)
-        response = session.post(save_batch_url, data=json.dumps(payload), headers=headers)
+        response = session.post(save_batch_url, data=json.dumps(payload, sort_keys=True), headers=headers)
         json_body = handle_response(response)
         if json_body is not None:
             resp_batches = json_body['batches']
             return [Batch.from_data(resp_batch) for resp_batch in resp_batches]
     except SSLError as e:
-        raise Exception("Failed to match server SSL configuration. Failed to save batch.")
+        raise ServerContextError(e)
 
     return None
 

labkey/query.py

@@ -49,6 +49,7 @@
 
 from requests.exceptions import SSLError
 from labkey.utils import build_url, handle_response
+from labkey.exceptions import ServerContextError
 
 
 _query_headers = {
@@ -59,14 +60,27 @@
 
 
 class Pagination:
+    """
+    Enum of paging styles
+    """
     PAGINATED = 'paginated'
     SELECTED = 'selected'
     UNSELECTED = 'unselected'
     ALL = 'all'
     NONE = 'none'
 
 
-def delete_rows(server_context, schema_name, query_name, rows, container_path=None, transacted=None, timeout=_default_timeout):
+def delete_rows(server_context, schema_name, query_name, rows, container_path=None, timeout=_default_timeout):
+    """
+    Delete a set of rows from the schema.query
+    :param server_context: A LabKey server context. See utils.create_server_context.
+    :param schema_name: schema of table
+    :param query_name: table name to delete from
+    :param rows: Set of rows to delete
+    :param container_path: labkey container path if not already set in context
+    :param timeout: timeout of request in seconds (defaults to 30s)
+    :return:
+    """
     url = build_url(server_context, 'query', 'deleteRows.api', container_path=container_path)
 
     payload = {
@@ -76,7 +90,8 @@ def delete_rows(server_context, schema_name, query_name, rows, container_path=No
     }
 
     # explicit json payload and headers required for form generation
-    delete_rows_response = _make_request(server_context, url, json.dumps(payload), headers=_query_headers, timeout=timeout)
+    delete_rows_response = _make_request(server_context, url, json.dumps(payload, sort_keys=True),
+                                         headers=_query_headers, timeout=timeout)
     return delete_rows_response
 
 
@@ -89,6 +104,24 @@ def execute_sql(server_context, schema_name, sql, container_path=None,
                 parameters=None,
                 required_version=None,
                 timeout=_default_timeout):
+    """
+    Execute a string a labkey sql against a LabKey server.
+
+    :param server_context: A LabKey server context. See utils.create_server_context.
+    :param schema_name: schema of table
+    :param sql: String of labkey sql to execute
+    :param container_path: labkey container path if not already set in context
+    :param max_rows: max number of rows to return
+    :param sort: comma separated list of column names to sort by
+    :param offset: number of rows to offset results by
+    :param container_filter: enumeration of the various container filters available. See:
+        https://www.labkey.org/download/clientapi_docs/javascript-api/symbols/LABKEY.Query.html#.containerFilter
+    :param save_in_session: save query result as a named view to the session
+    :param parameters: parameter values to pass through to a parameterized query
+    :param required_version: Api version of response
+    :param timeout: timeout of request in seconds (defaults to 30s)
+    :return:
+    """
     url = build_url(server_context, 'query', 'executeSql.api', container_path=container_path)
 
     payload = {
@@ -122,6 +155,16 @@ def execute_sql(server_context, schema_name, sql, container_path=None,
 
 
 def insert_rows(server_context, schema_name, query_name, rows, container_path=None, timeout=_default_timeout):
+    """
+    Insert row(s) into table
+    :param server_context: A LabKey server context. See utils.create_server_context.
+    :param schema_name: schema of table
+    :param query_name: table name to insert into
+    :param rows: set of rows to insert
+    :param container_path: labkey container path if not already set in context
+    :param timeout: timeout of request in seconds (defaults to 30s)
+    :return:
+    """
     url = build_url(server_context, 'query', 'insertRows.api', container_path=container_path)
 
     payload = {
@@ -131,7 +174,8 @@ def insert_rows(server_context, schema_name, query_name, rows, container_path=No
     }
 
     # explicit json payload and headers required for form generation
-    insert_rows_response = _make_request(server_context, url, json.dumps(payload), headers=_query_headers, timeout=timeout)
+    insert_rows_response = _make_request(server_context, url, json.dumps(payload, sort_keys=True),
+                                         headers=_query_headers, timeout=timeout)
     return insert_rows_response
 
 
@@ -152,6 +196,30 @@ def select_rows(server_context, schema_name, query_name, view_name=None,
                 required_version=None,
                 timeout=_default_timeout
                 ):
+    """
+    Query data from a labkey server
+    :param server_context: A LabKey server context. See utils.create_server_context.
+    :param schema_name: schema of table
+    :param query_name: table name to select from
+    :param view_name: pre-existing named view
+    :param filter_array: set of filter objects to apply
+    :param container_path: folder path if not already part of server_context
+    :param columns: set of columns to retrieve
+    :param max_rows: max number of rows to retrieve
+    :param sort: comma separated list of column names to sort by, prefix a column with '-' to sort descending
+    :param offset: number of rows to offset results by
+    :param container_filter: enumeration of the various container filters available. See:
+        https://www.labkey.org/download/clientapi_docs/javascript-api/symbols/LABKEY.Query.html#.containerFilter
+    :param parameters: Set of parameters to pass along to a parameterized query
+    :param show_rows: An enumeration of various paging styles
+    :param include_total_count: Boolean value that indicates whether to include a total count value in response
+    :param include_details_column: Boolean value that indicates whether to include a Details link column in results
+    :param include_update_column: Boolean value that indicates whether to include an Update link column in results
+    :param selection_key:
+    :param required_version: decimal value that indicates the response version of the api
+    :param timeout: Request timeout in seconds (defaults to 30s)
+    :return:
+    """
     # TODO: Support data_region_name
     url = build_url(server_context, 'query', 'getQuery.api', container_path=container_path)
 
@@ -210,6 +278,17 @@ def select_rows(server_context, schema_name, query_name, view_name=None,
 
 
 def update_rows(server_context, schema_name, query_name, rows, container_path=None, timeout=_default_timeout):
+    """
+    Update a set of rows
+
+    :param server_context: A LabKey server context. See utils.create_server_context.
+    :param schema_name: schema of table
+    :param query_name: table name to update
+    :param rows: Set of rows to update
+    :param container_path: labkey container path if not already set in context
+    :param timeout: timeout of request in seconds (defaults to 30s)
+    :return:
+    """
     url = build_url(server_context, 'query', 'updateRows.api', container_path=container_path)
 
     payload = {
@@ -219,7 +298,8 @@ def update_rows(server_context, schema_name, query_name, rows, container_path=No
     }
 
     # explicit json payload and headers required for form generation
-    update_rows_response = _make_request(server_context, url, json.dumps(payload), headers=_query_headers, timeout=timeout)
+    update_rows_response = _make_request(server_context, url, json.dumps(payload, sort_keys=True),
+                                         headers=_query_headers, timeout=timeout)
     return update_rows_response
 
 
@@ -229,7 +309,7 @@ def _make_request(server_context, url, payload, headers=None, timeout=_default_t
         raw_response = session.post(url, data=payload, headers=headers, timeout=timeout)
         return handle_response(raw_response)
     except SSLError as e:
-        raise Exception('Failed to match server SSL configuration. Ensure the server_context is configured correctly.')
+        raise ServerContextError(e)
 
 
 # TODO: Provide filter generators.
@@ -240,8 +320,13 @@ def _make_request(server_context, url, payload, headers=None, timeout=_default_t
 #
 # https://www.labkey.org/download/clientapi_docs/javascript-api/symbols/LABKEY.Filter.html
 class QueryFilter:
-
+    """
+    Filter object to simplify generation of query filters
+    """
     class Types:
+        """
+        Enumeration of acceptable filter types
+        """
         HAS_ANY_VALUE = '',
 
         EQUAL = 'eq',

labkey/utils.py

@@ -20,6 +20,7 @@
 
 from requests.adapters import HTTPAdapter
 from requests.packages.urllib3.poolmanager import PoolManager
+from labkey.exceptions import RequestError, RequestAuthorizationError, QueryNotFoundError, ServerNotFoundError
 
 
 # _ssl.c:504: error:14077410:SSL routines:SSL23_GET_SERVER_HELLO:sslv3 alert handshake failure
@@ -100,25 +101,16 @@ def handle_response(response):
     if sc == 200 or sc == 207:
         return response.json()
     elif sc == 401:
-        print(str(sc) + ": Authorization failed.")
+        raise RequestAuthorizationError(response)
     elif sc == 404:
-        msg = str(sc) + ": "
-        decoded = response.json()
-        if 'exception' in decoded:
-            msg += decoded['exception']
-        else:
-            msg += 'Not found.'
-        print(msg)
-    elif sc == 500:
-        msg = str(sc) + ": "
-        decoded = response.json()
-        if 'exception' in decoded:
-            msg += decoded['exception']
-        else:
-            msg += 'Internal Server Error.'
-        print(msg)
+        try:
+            response.json()  # attempt to decode response
+            raise QueryNotFoundError(response)
+        except ValueError:
+            # could not decode response
+            raise ServerNotFoundError(response)
     else:
-        print(str(sc))
-        print(response.json())
+        raise RequestError(response)
 
     return None
+

samples/load_batch_example.py

@@ -8,8 +8,8 @@
 server_context = create_server_context('localhost:8080', project_name, 'labkey', use_ssl=False)
 
 print("Load an Assay batch from the server")
-assay_id = 1168  # provide one from your server
-batch_id = 95  # provide one from your server
+assay_id = 2809  # provide one from your server
+batch_id = 120  # provide one from your server
 run_group = load_batch(server_context, assay_id, batch_id)
 
 if run_group is not None:

samples/query_examples.py

@@ -9,6 +9,7 @@
 
 from __future__ import unicode_literals
 from labkey.utils import create_server_context
+from labkey.exceptions import RequestError, QueryNotFoundError, ServerContextError, ServerNotFoundError
 from labkey.query import select_rows, update_rows, Pagination, QueryFilter, \
     insert_rows, delete_rows, execute_sql
 from requests.exceptions import Timeout
@@ -26,21 +27,74 @@
 column1 = 'Group Assignment'
 column2 = 'Participant ID'
 
+
 ###################
 # Test basic select_rows
 ###################
 result = select_rows(server_context, schema, table)
 if result is not None:
+    print(result['rows'][0])
     print("select_rows: There are " + str(result['rowCount']) + " rows.")
 else:
     print('select_rows: Failed to load results from ' + schema + '.' + table)
 
+
+###################
+# Test error handling
+###################
+# catch base error
+try:
+    result = select_rows(server_context, schema, 'badtable')
+    print(result)
+except RequestError:
+    print('Caught base error')
+
+# catch table not found error
+try:
+    result = select_rows(server_context, schema, 'badtable')
+    print(result)
+except QueryNotFoundError:
+    print('Caught bad table')
+
+# catch schema error
+try:
+    result = select_rows(server_context, 'badSchema', table)
+    print(result)
+except QueryNotFoundError:
+    print('Caught bad schema')
+
+# catch SSL error
+ssl_server_context = create_server_context(labkey_server, project_name, contextPath, use_ssl=True)
+try:
+    result = select_rows(ssl_server_context, schema, table)
+    print(result)
+except ServerContextError:
+    print('Caught SSL Error')
+
+
+# catch bad context path
+bad_server_context = create_server_context(labkey_server, project_name, '', use_ssl=False)
+try:
+    result = select_rows(bad_server_context, schema, table)
+    print(result)
+except ServerNotFoundError:
+    print('Caught context path')
+
+# catch bad folder path error
+bad_server_context = create_server_context(labkey_server, 'bad_project_name', contextPath, use_ssl=False)
+try:
+    result = select_rows(bad_server_context, schema, table)
+    print(result)
+except ServerNotFoundError:
+    print('Caught bad folder name')
+
+
 ###################
 # Test some parameters of select_rows
 ###################
 result = select_rows(server_context, schema, table,
                      max_rows=5, offset=10, include_total_count=True, include_details_column=True,
-                     include_update_column=True, required_version=12.2)
+                     include_update_column=True)  # , required_version=12.2)
 if result is not None:
     print('select_rows: There are ' + str(len(result['rows'])) + ' rows.')
     print('select_rows: There are ' + str(result['rowCount']) + ' total rows.')
@@ -146,7 +200,6 @@
 print('Delete Rows: after row count [ ' + str(all_rows['rowCount']) + ' ]')
 
 
-
 ###################
 # Test execute_sql
 ###################