Spec 24062: Support Python 3

 - Adding additional parameter support for query.py
 - Added query_examples.py

Author: labkey-ians

README.md

@@ -9,26 +9,37 @@ $ pip install labkey
 ```
 
 # Credentials
-In order to the use the Python client API for LabKey Server, you will need to specify your login credentials in a credential file. The package assumes that this file will be located either:
+The api no longer supports using a ``.labkeycredentials.txt`` file, and now uses the .netrc files similar to the other labkey apis. Additional .netrc [setup instructions](https://www.labkey.org/wiki/Staff/steveh/DocsSandbox/page.view?name=netrc&_docid=wiki%3Ae780ab5b-241e-1033-93dd-22a830bccfbb) can be found at the link.
 
-1. ``$HOME/.labkeycredentials.txt``
-2. The location will be specified in the ``LABKEY_CREDENTIALS`` environment variable.
+## Set Up a netrc File
 
-The ``labkeycredentials`` file must be in the following format. (3 separate lines):
+On a Mac, UNIX, or Linux system the netrc file should be named ``.netrc`` (dot netrc) and on Windows it should be named ``_netrc`` (underscore netrc). The file should be located in your home directory and the permissions on the file must be set so that you are the only user who can read it, i.e. it is unreadable to everyone else.
+
+To create the netrc on a Windows machine, first create an environment variable called ’HOME’ that is set to your home directory (c:/Users/<User-Name> on Vista or Windows 7) or any directory you want to use.
+
+In that directory, create a text file with the prefix appropriate to your system, either an underscore or dot.
+
+The following three lines must be included in the file. The lines must be separated by either white space (spaces, tabs, or newlines) or commas:
 ```
-machine https://hosted.labkey.com
-login labkeypython@gmail.com
-password python
+machine <remote-instance-of-labkey-server>
+login <user-email>
+password <user-password>
 ```
-where:
-- machine: URL of your LabKey Server
-- login: email address to be used to login to the LabKey Server
-- password: password associated with the login
 
-A sample ``labkeycredentials`` file has been shipped with the source and named ``.labkeycredentials.sample``.
+One example would be:
+```
+machine mymachine.labkey.org
+login user@labkey.org
+password mypassword
+```
+Another example would be:
+```
+machine mymachine.labkey.org login user@labkey.org password mypassword
+```
 
 # Supported Versions
-Python 2.6 or 2.7 are fully supported.
+Python 2.6 or 2.7 and 3.4 are fully supported.
+
 LabKey Server v11.1 and later.
 
 # Contributing

labkey/__init__.py

@@ -13,9 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+from labkey import query, experiment  # wiki, messageboard
+
 __title__ = 'labkey'
 __version__ = '0.3.0'
 __author__ = 'LabKey Software'
 __license__ = 'Apache 2.0'
-
-from labkey import query  # wiki, messageboard

labkey/query.py

@@ -45,20 +45,28 @@
 ############################################################################
 """
 from __future__ import unicode_literals
-from enum import Enum
+import json
 
 from requests.exceptions import SSLError
 from labkey.utils import build_url, handle_response
 
 
-class Pagination(Enum):
-    paginated = 0
-    selected = 1
-    unselected = 2
-    all = 3
-    none = 4
+_query_headers = {
+    'Content-Type': 'application/json'
+}
 
-def delete_rows(server_context, schema_name, query_name, rows, container_path=None):
+_default_timeout = 30  # in seconds
+
+
+class Pagination:
+    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):
     url = build_url(server_context, 'query', 'deleteRows.api', container_path=container_path)
 
     payload = {
@@ -67,12 +75,20 @@ def delete_rows(server_context, schema_name, query_name, rows, container_path=No
         'rows': rows
     }
 
-    delete_rows_response = _make_request(server_context, url, payload)
+    # 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)
     return delete_rows_response
 
 
 def execute_sql(server_context, schema_name, sql, container_path=None,
-                max_rows=None, sort=None, offset=None, container_filter=None):
+                max_rows=None,
+                sort=None,
+                offset=None,
+                container_filter=None,
+                save_in_session=None,
+                parameters=None,
+                required_version=None,
+                timeout=_default_timeout):
     url = build_url(server_context, 'query', 'executeSql.api', container_path=container_path)
 
     payload = {
@@ -81,22 +97,31 @@ def execute_sql(server_context, schema_name, sql, container_path=None,
     }
 
     if container_filter is not None:
-        payload['query.containerFilter'] = container_filter
+        payload['containerFilter'] = container_filter
 
     if max_rows is not None:
-        payload['query.max_rows'] = max_rows
+        payload['maxRows'] = max_rows
 
     if offset is not None:
-        payload['query.offset'] = offset
+        payload['offset'] = offset
 
     if sort is not None:
         payload['query.sort'] = sort
 
-    execute_sql_response = _make_request(server_context, url, payload)
+    if save_in_session is not None:
+        payload['saveInSession'] = save_in_session
+
+    if parameters is not None:
+        payload['query.parameters'] = parameters
+
+    if required_version is not None:
+        payload['apiVersion'] = required_version
+
+    execute_sql_response = _make_request(server_context, url, payload, timeout=timeout)
     return execute_sql_response
 
 
-def insert_rows(server_context, schema_name, query_name, rows, container_path=None):
+def insert_rows(server_context, schema_name, query_name, rows, container_path=None, timeout=_default_timeout):
     url = build_url(server_context, 'query', 'insertRows.api', container_path=container_path)
 
     payload = {
@@ -105,11 +130,11 @@ def insert_rows(server_context, schema_name, query_name, rows, container_path=No
         'rows': rows
     }
 
-    insert_rows_response = _make_request(server_context, url, payload)
+    # 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)
     return insert_rows_response
 
 
-# TODO: Support all the properties
 def select_rows(server_context, schema_name, query_name, view_name=None,
                 filter_array=None,
                 container_path=None,
@@ -123,9 +148,9 @@ def select_rows(server_context, schema_name, query_name, view_name=None,
                 include_total_count=None,
                 include_details_column=None,
                 include_update_column=None,
-                # selection_key=None,
-                timeout=None,
-                required_version=None
+                selection_key=None,
+                required_version=None,
+                timeout=_default_timeout
                 ):
     # TODO: Support data_region_name
     url = build_url(server_context, 'query', 'getQuery.api', container_path=container_path)
@@ -140,9 +165,9 @@ def select_rows(server_context, schema_name, query_name, view_name=None,
         payload['query.viewName'] = view_name
 
     if filter_array is not None:
-        for filter in filter_array:
-            prefix = 'query.' + filter[0] + '~' + filter[1]
-            payload[prefix] = filter[2]
+        for query_filter in filter_array:
+            prefix = query_filter.get_url_parameter_name()
+            payload[prefix] = query_filter.get_url_parameter_value()
 
     if columns is not None:
         payload['query.columns'] = columns
@@ -157,7 +182,7 @@ def select_rows(server_context, schema_name, query_name, view_name=None,
         payload['query.offset'] = offset
 
     if container_filter is not None:
-        payload['query.containerFilter'] = container_filter
+        payload['containerFilter'] = container_filter
 
     if parameters is not None:
         payload['query.parameters'] = parameters
@@ -166,25 +191,25 @@ def select_rows(server_context, schema_name, query_name, view_name=None,
         payload['query.showRows'] = show_rows
 
     if include_total_count is not None:
-        payload['query.includeTotalCount'] = include_total_count
+        payload['includeTotalCount'] = include_total_count
 
     if include_details_column is not None:
-        payload['query.includeDetailsColumn'] = include_details_column
+        payload['includeDetailsColumn'] = include_details_column
 
     if include_update_column is not None:
-        payload['query.includeUpdateColumn'] = include_update_column
+        payload['includeUpdateColumn'] = include_update_column
 
-    if timeout is not None:
-        payload['query.timeout'] = timeout
+    if selection_key is not None:
+        payload['query.selectionKey'] = selection_key
 
     if required_version is not None:
-        payload['query.requiredVersion'] = required_version
+        payload['apiVersion'] = required_version
 
-    select_rows_response = _make_request(server_context, url, payload)
+    select_rows_response = _make_request(server_context, url, payload, timeout=timeout)
     return select_rows_response
 
 
-def update_rows(server_context, schema_name, query_name, rows, container_path=None):
+def update_rows(server_context, schema_name, query_name, rows, container_path=None, timeout=_default_timeout):
     url = build_url(server_context, 'query', 'updateRows.api', container_path=container_path)
 
     payload = {
@@ -193,14 +218,90 @@ def update_rows(server_context, schema_name, query_name, rows, container_path=No
         'rows': rows
     }
 
-    update_rows_response = _make_request(server_context, url, payload)
+    # 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)
     return update_rows_response
 
 
-def _make_request(server_context, url, payload):
+def _make_request(server_context, url, payload, headers=None, timeout=_default_timeout):
     try:
         session = server_context['session']
-        raw_response = session.post(url, data=payload)
+        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.')
+
+
+# TODO: Provide filter generators.
+#
+# There are some inconsistencies between the different filter types with multiple values,
+# some use ';' and others use ',' to delimit values within string list; and still others use an array of value objects.
+# This is a historical artifact of the api and isn't clearly documented.
+#
+# https://www.labkey.org/download/clientapi_docs/javascript-api/symbols/LABKEY.Filter.html
+class QueryFilter:
+
+    class Types:
+        HAS_ANY_VALUE = '',
+
+        EQUAL = 'eq',
+        DATE_EQUAL = 'dateeq',
+
+        NEQ = 'neq',
+        NOT_EQUAL = 'neq',
+        DATE_NOT_EQUAL = 'dateneq',
+
+        NEQ_OR_NULL = 'neqornull',
+        NOT_EQUAL_OR_MISSING = 'neqornull',
+
+        GT = 'gt',
+        GREATER_THAN = 'gt',
+        DATE_GREATER_THAN = 'dategt',
+
+        LT = 'lt',
+        LESS_THAN = 'lt',
+        DATE_LESS_THAN = 'datelt',
+
+        GTE = 'gte',
+        GREATER_THAN_OR_EQUAL = 'gte',
+        DATE_GREATER_THAN_OR_EQUAL = 'dategte',
+
+        LTE = 'lte',
+        LESS_THAN_OR_EQUAL = 'lte',
+        DATE_LESS_THAN_OR_EQUAL = 'datelte',
+
+        STARTS_WITH = 'startswith',
+        DOES_NOT_START_WITH = 'doesnotstartwith',
+
+        CONTAINS = 'contains',
+        DOES_NOT_CONTAIN = 'doesnotcontain',
+
+        CONTAINS_ONE_OF = 'containsoneof',
+        CONTAINS_NONE_OF = 'containsnoneof',
+
+        IN = 'in',
+
+        EQUALS_ONE_OF = 'in',
+
+        NOT_IN = 'notin',
+        EQUALS_NONE_OF = 'notin',
+
+        BETWEEN = 'between',
+        NOT_BETWEEN = 'notbetween',
+
+        MEMBER_OF = 'memberof'
+
+    def __init__(self, column, value, filter_type = Types.EQUAL):
+        self.column_name = column
+        self.value = value
+        self.filter_type = filter_type
+
+    def get_url_parameter_name(self):
+        return 'query.' + self.column_name + '~' + self.filter_type[0]
+
+    def get_url_parameter_value(self):
+        return self.value
+
+    def get_column_name(self):
+        return self.column_name
+