Add allow_redirects flag to ServerContext (#74)

* ServerContext:
    * Add `allow_redirects` flag to constructor
    * Add `allow_redirects` flag to `make_request`
* APIWrapper Add `allow_redirects` flag
* Add UnexpectedRedirectError
* Update APIWrapper docs to not set `use_ssl=False` in example code

Author: labkey-alan

CHANGE.txt

@@ -2,6 +2,17 @@
 LabKey Python Client API News
 +++++++++++
 
+What's New in the LabKey 3.1.0 package
+==============================
+
+*Release date: 04/03/2024*
+- ServerContext
+    - Add allow_redirects flag (defaults to False) to constructor
+    - Add allow_redirects flag to make_request
+- APIWrapper: Add allow_redirects flag (defaults to False)
+- Add UnexpectedRedirectError
+    - thrown when allow_redirects is False and the server issues a redirect
+
 What's New in the LabKey 3.0.0 package
 ==============================
 

docs/api_wrapper.md

@@ -23,20 +23,23 @@ It includes the following arguments:
 - Example: 'Project/Folder/Subfolder'
 
 **context_path** 
-- The default value is None. Depending on how the LabKey Server instance is implemented, it may be necessary to include a value for the context_path argument. If your LabKey Server instance has text after the base URL, that is the context path. 
+- Defaults to `None`. Depending on how the LabKey Server instance is implemented, it may be necessary to include a value for the context_path argument. If your LabKey Server instance has text after the base URL, that is the context path. 
 - Example: If your home project has a URL such as https://labkey.org/contextpath/home/project-begin.view, then the context path is 'contextpath'.
 
 **use_ssl**
-- The default value is True. This should be set to True if your server is configured to use SSL. If you are not sure if your server uses SSL, refer to any URL for accessing your server. Servers using SSL will have a URL that begins with `https://` instead of `http://`. LabKey Sample Manager-only clients must have this argument set to True.
+- Defaults to `True`. This should be set to True if your server is configured to use SSL. If you are not sure if your server uses SSL, refer to any URL for accessing your server. Servers using SSL will have a URL that begins with `https://` instead of `http://`. LabKey Sample Manager-only clients must have this argument set to True.
 
 **verify_ssl**
-- The default value is True. This argument toggles whether or not the SSL certificate is validated when attempting to connect to a server. This flag is useful when you are connecting to a development server with a self-signed SSL certificate, which would otherwise cause a failure. You should never disable this flag if you are connecting to a production server with a proper SSL certificate.
+- Defaults to `True`. This argument toggles whether or not the SSL certificate is validated when attempting to connect to a server. This flag is useful when you are connecting to a development server with a self-signed SSL certificate, which would otherwise cause a failure. You should never disable this flag if you are connecting to a production server with a proper SSL certificate.
 
 **api_key**
-- The default value is None. Scripts can authenticate their LabKey API calls by using either a netrc file (details on that here, https://www.labkey.org/Documentation/wiki-page.view?name=netrc) or an API key (details about API keys and how to generate and manage them are here, https://www.labkey.org/Documentation/wiki-page.view?name=apikey). 
+- Defaults to `None`. Scripts can authenticate their LabKey API calls by using either a netrc file (details on that here, https://www.labkey.org/Documentation/wiki-page.view?name=netrc) or an API key (details about API keys and how to generate and manage them are here, https://www.labkey.org/Documentation/wiki-page.view?name=apikey). 
 
 **disable_csrf** 
-- The default value is False. In most cases, this argument must be set to False for API calls to work successfully as CSRF tokens are a fundamental security mechanism. For more info about using CSRF with your LabKey Server instance, see here, https://www.labkey.org/Documentation/wiki-page.view?name=csrfProtection.
+- Defaults to `False`. In most cases, this argument must be set to False for API calls to work successfully as CSRF tokens are a fundamental security mechanism. For more info about using CSRF with your LabKey Server instance, see here, https://www.labkey.org/Documentation/wiki-page.view?name=csrfProtection.
+
+**allow_redirects**
+- Defaults to `False`. When the server issues a redirect during an API call the ServerContext will throw an error.
 
 ### Using LabKey Python APIs 
 
@@ -48,13 +51,16 @@ See below for an example of how to properly use the APIWrapper class to create a
 from labkey.api_wrapper import APIWrapper
 
 print("Create an APIWrapper")
-labkey_server = 'localhost:8080'
-project_name = 'ModuleAssayTest'  # Project folder name
+labkey_server = 'www.example.com'
+container_path = 'ModuleAssayTest'  # Project folder name
 contextPath = 'labkey'
 schema = 'core'
 table = 'Users'
-api = APIWrapper(labkey_server, project_name, contextPath, use_ssl=False)
 
+# Note: If developing against localhost with https disabled, set use_ssl=False below
+api = APIWrapper(labkey_server, container_path, contextPath)
+
+# Makes an API request to https://www.example.com/labkey/ModuleAssayTest/query-getQuery.api
 result = api.query.select_rows(schema, table)
 
 if result is not None:

labkey/__init__.py

@@ -14,6 +14,6 @@
 # limitations under the License.
 #
 __title__ = "labkey"
-__version__ = "3.0.0"
+__version__ = "3.1.0"
 __author__ = "LabKey"
 __license__ = "Apache License 2.0"

labkey/api_wrapper.py

@@ -22,6 +22,7 @@ def __init__(
         verify_ssl=True,
         api_key=None,
         disable_csrf=False,
+        allow_redirects=False,
     ):
         self.server_context = ServerContext(
             domain=domain,
@@ -31,6 +32,7 @@ def __init__(
             verify_ssl=verify_ssl,
             api_key=api_key,
             disable_csrf=disable_csrf,
+            allow_redirects=allow_redirects,
         )
         self.container = ContainerWrapper(self.server_context)
         self.domain = DomainWrapper(self.server_context)

labkey/exceptions.py

@@ -47,7 +47,22 @@ def __init__(self, server_response, **kwargs):
             self.message = "No response received"
 
     def __str__(self):
-        return repr(self.message)
+        return str(self.message)
+
+
+class UnexpectedRedirectError(RequestError):
+    default_msg = "Unexpected redirect occurred"
+
+    def __init__(self, server_response, **kwargs):
+        super().__init__(server_response, **kwargs)
+
+        location = server_response.headers.get("Location", "")
+
+        # If the server is redirecting from http to https the user probably has a misconfigured ServerContext with use_ssl=False
+        if server_response.url.startswith("http://") and location.startswith("https://"):
+            self.message = "Redirected from http to https, set use_ssl=True in your APIWrapper or ServerContext"
+        elif location != "":
+            self.message = f"Unexpected redirect to: {location}"
 
 
 class QueryNotFoundError(RequestError):

labkey/query.py

@@ -258,7 +258,7 @@ def execute_sql(
     parameters: dict = None,
     required_version: float = None,
     timeout: int = _default_timeout,
-    waf_encode_sql: bool = True
+    waf_encode_sql: bool = True,
 ):
     """
     Execute sql query against a LabKey server.
@@ -535,7 +535,12 @@ def move_rows(
     """
     url = server_context.build_url("query", "moveRows.api", container_path=container_path)
 
-    payload = {"targetContainerPath": target_container_path, "schemaName": schema_name, "queryName": query_name, "rows": rows}
+    payload = {
+        "targetContainerPath": target_container_path,
+        "schemaName": schema_name,
+        "queryName": query_name,
+        "rows": rows,
+    }
 
     if transacted is False:
         payload["transacted"] = transacted
@@ -582,7 +587,7 @@ def delete_rows(
             transacted,
             audit_behavior,
             audit_user_comment,
-            timeout
+            timeout,
         )
 
     @functools.wraps(truncate_table)
@@ -605,7 +610,7 @@ def execute_sql(
         parameters: dict = None,
         required_version: float = None,
         timeout: int = _default_timeout,
-        waf_encode_sql: bool = True
+        waf_encode_sql: bool = True,
     ):
         return execute_sql(
             self.server_context,
@@ -620,7 +625,7 @@ def execute_sql(
             parameters,
             required_version,
             timeout,
-            waf_encode_sql
+            waf_encode_sql,
         )
 
     @functools.wraps(insert_rows)
@@ -646,7 +651,7 @@ def insert_rows(
             transacted,
             audit_behavior,
             audit_user_comment,
-            timeout
+            timeout,
         )
 
     @functools.wraps(select_rows)
@@ -716,7 +721,7 @@ def update_rows(
             transacted,
             audit_behavior,
             audit_user_comment,
-            timeout
+            timeout,
         )
 
     @functools.wraps(move_rows)
@@ -742,5 +747,5 @@ def move_rows(
             transacted,
             audit_behavior,
             audit_user_comment,
-            timeout
+            timeout,
         )

labkey/security.py

@@ -279,7 +279,7 @@ def stop_impersonating(server_context: ServerContext):
     Stop impersonating a user while keeping the original user logged in.
     """
     url = server_context.build_url(LOGIN_CONTROLLER, "stopImpersonating.api")
-    return server_context.make_request(url)
+    return server_context.make_request(url, allow_redirects=True)
 
 
 @dataclass

labkey/server_context.py

@@ -8,6 +8,7 @@
     QueryNotFoundError,
     ServerContextError,
     ServerNotFoundError,
+    UnexpectedRedirectError,
 )
 
 API_KEY_TOKEN = "apikey"
@@ -29,7 +30,8 @@ def handle_response(response, non_json_response=False):
                 content=response.content,
             )
             return result
-
+    elif sc == 302:
+        raise UnexpectedRedirectError(response)
     elif sc == 401:
         raise RequestAuthorizationError(response)
     elif sc == 404:
@@ -62,6 +64,7 @@ def __init__(
         verify_ssl=True,
         api_key=None,
         disable_csrf=False,
+        allow_redirects=False,
     ):
         self._container_path = container_path
         self._context_path = context_path
@@ -70,6 +73,7 @@ def __init__(
         self._verify_ssl = verify_ssl
         self._api_key = api_key
         self._disable_csrf = disable_csrf
+        self.allow_redirects = allow_redirects
         self._session = requests.Session()
         self._session.headers.update({"User-Agent": f"LabKey Python API/{__version__}"})
 
@@ -174,7 +178,9 @@ def make_request(
         non_json_response: bool = False,
         file_payload: any = None,
         json: dict = None,
+        allow_redirects=False,
     ) -> any:
+        allow_redirects_ = allow_redirects or self.allow_redirects
         if self._api_key is not None:
             if self._session.headers.get(API_KEY_TOKEN) is not self._api_key:
                 self._session.headers.update({API_KEY_TOKEN: self._api_key})
@@ -189,7 +195,13 @@ def make_request(
 
         try:
             if method == "GET":
-                response = self._session.get(url, params=payload, headers=headers, timeout=timeout)
+                response = self._session.get(
+                    url,
+                    params=payload,
+                    headers=headers,
+                    timeout=timeout,
+                    allow_redirects=allow_redirects_,
+                )
             else:
                 if file_payload is not None:
                     response = self._session.post(
@@ -198,6 +210,7 @@ def make_request(
                         files=file_payload,
                         headers=headers,
                         timeout=timeout,
+                        allow_redirects=allow_redirects_,
                     )
                 elif json is not None:
                     if headers is None:
@@ -206,10 +219,20 @@ def make_request(
                     headers_ = {**headers, "Content-Type": "application/json"}
                     # sort_keys is a hack to make unit tests work
                     data = json_dumps(json, sort_keys=True)
-                    response = self._session.post(url, data=data, headers=headers_, timeout=timeout)
+                    response = self._session.post(
+                        url,
+                        data=data,
+                        headers=headers_,
+                        timeout=timeout,
+                        allow_redirects=allow_redirects_,
+                    )
                 else:
                     response = self._session.post(
-                        url, data=payload, headers=headers, timeout=timeout
+                        url,
+                        data=payload,
+                        headers=headers,
+                        timeout=timeout,
+                        allow_redirects=allow_redirects_,
                     )
             return handle_response(response, non_json_response)
         except RequestException as e:

samples/experiment_platemetadata_example.py

@@ -42,9 +42,9 @@
 
 # Assays that are configured for plate support have a required run property for the plate template, this is the plate
 # template lsid
-run_test.properties[
-    "PlateTemplate"
-] = "urn:lsid:labkey.com:PlateTemplate.Folder-6:d8bbec7d-34cd-1038-bd67-b3bd777822f8"
+run_test.properties["PlateTemplate"] = (
+    "urn:lsid:labkey.com:PlateTemplate.Folder-6:d8bbec7d-34cd-1038-bd67-b3bd777822f8"
+)
 
 # The assay plate metadata is a specially formatted JSON object to map properties to the well groups
 run_test.plate_metadata = {

test/integration/test_query.py

@@ -43,10 +43,14 @@ def study(api: APIWrapper):
         "subjectNounSingular": "People",
         "label": "Python Integration Tests Study",
     }
-    created_study = api.server_context.make_request(url, payload, non_json_response=True)
+    created_study = api.server_context.make_request(
+        url, payload, non_json_response=True, allow_redirects=True
+    )
     yield created_study
     url = api.server_context.build_url("study", "deleteStudy.view")
-    api.server_context.make_request(url, {"confirm": "true"}, non_json_response=True)
+    api.server_context.make_request(
+        url, {"confirm": "true"}, non_json_response=True, allow_redirects=True
+    )
 
 
 @pytest.fixture(scope="session")
@@ -91,7 +95,7 @@ def test_create_duplicate_dataset(api: APIWrapper, dataset):
     with pytest.raises(ServerContextError) as e:
         api.domain.create(DATASET_DOMAIN)
 
-    expected = f"'500: A Dataset or Query already exists with the name \"{QUERY_NAME}\".'"
+    expected = f'500: A Dataset or Query already exists with the name "{QUERY_NAME}".'
     assert e.value.message == expected
 
 
@@ -148,7 +152,7 @@ def test_cannot_delete_qc_state_in_use(api: APIWrapper, qc_states, study, datase
 
     assert (
         e.value.message
-        == "\"400: State 'needs verification' cannot be deleted as it is currently in use.\""
+        == "400: State 'needs verification' cannot be deleted as it is currently in use."
     )
     # now clean up/stop using it
     dataset_row_to_remove = [{"lsid": inserted_lsid}]