Add support for reasoning about server semantic version

caveclient/base.py

@@ -1,12 +1,17 @@
 import datetime
 import json
 import logging
+import textwrap
 import urllib
 import webbrowser
+from functools import wraps
+from typing import Callable, Optional
 
 import numpy as np
 import pandas as pd
 import requests
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
 
 from .session_config import patch_session
 
@@ -86,6 +91,7 @@ def _raise_for_status(r, log_warning=True):
 
 def handle_response(response, as_json=True, log_warning=True):
     """Deal with potential errors in endpoint response and return json for default case"""
+    # NOTE: consider adding "None on 404" as an option?
     _raise_for_status(response, log_warning=log_warning)
     _check_authorization_redirect(response)
     if as_json:
@@ -226,6 +232,22 @@ def server_address(self):
     def api_version(self):
         return self._api_version
 
+    def _get_version(self) -> Optional[Version]:
+        endpoint_mapping = self.default_url_mapping
+        url = self._endpoints.get("get_version", None).format_map(endpoint_mapping)
+        response = self.session.get(url)
+        if response.status_code == 404:  # server doesn't have this endpoint yet
+            return None
+        else:
+            version_str = handle_response(response, as_json=True)
+            version = Version(version_str)
+            return version
+
+    @property
+    def server_version(self) -> Optional[Version]:
+        """The version of the remote server."""
+        return self._server_version
+
     @staticmethod
     def raise_for_status(r, log_warning=True):
         """Raises [requests.HTTPError][], if one occurred."""
@@ -299,3 +321,97 @@ def __init__(
     @property
     def datastack_name(self):
         return self._datastack_name
+
+
+def parametrized(dec):
+    """This decorator allows you to easily create decorators that take arguments"""
+    # REF: https://stackoverflow.com/questions/5929107/decorators-with-parameters
+
+    @wraps(dec)
+    def layer(*args, **kwargs):
+        @wraps(dec)
+        def repl(f):
+            return dec(f, *args, **kwargs)
+
+        return repl
+
+    return layer
+
+
+class ServerIncompatibilityError(Exception):
+    def __init__(self, message):
+        # for readability, wrap the message at 80 characters
+        message = textwrap.fill(message, width=80)
+        super().__init__(message)
+
+
+def _version_fails_constraint(version: Version, constraint: str = None):
+    if constraint is None:
+        return False
+    else:
+        specifier = SpecifierSet(constraint)
+        return version not in specifier
+
+
+@parametrized
+def _check_version_compatibility(
+    method: Callable, method_constraint: str = None, kwarg_use_constraints: dict = None
+) -> Callable:
+    """
+    This decorator is used to check the compatibility of features in the client and
+    server versions. If the server version is not compatible with the constraint, an
+    error will be raised.
+
+    Parameters
+    ----------
+    method
+        Method of the client to be decorated.
+    method_constraint
+        Version constraint for the method, described as a comparison operator
+        followed by the version number. For example, "<=1.0.0" would indicate that this
+        method is only compatible with server versions less than or equal to 1.0.0.
+    kwarg_use_constraints
+        Dictionary with some number of the method's keyword arguments as keys and
+        version constraints as values. Version constraints are described as a
+        comparison operator followed by the version number. For example, "<=1.0.0"
+        would indicate that the keyword argument is only compatible with server versions
+        less than or equal to 1.0.0. An error will be raised only if the user both
+        provides the keyword argument (even if passing in the default value!) and the
+        server version is not compatible with the constraint.
+
+    Raises
+    ------
+    ServerIncompatibilityError
+        If the server version is not compatible with the constraints.
+    """
+
+    @wraps(method)
+    def wrapper(*args, **kwargs):
+        self = args[0]
+
+        if method_constraint is not None:
+            if _version_fails_constraint(self.server_version, method_constraint):
+                msg = (
+                    f"Use of method `{method.__name__}` is only permitted "
+                    f"for server version {method_constraint}, your server "
+                    f"version is {self.server_version}. Contact your system "
+                    "administrator to update the server version."
+                )
+
+                raise ServerIncompatibilityError(msg)
+
+        for kwarg, kwarg_constraint in kwarg_use_constraints.items():
+            if _version_fails_constraint(self.server_version, kwarg_constraint):
+                msg = (
+                    f"Use of keyword argument `{kwarg}` in `{method.__name__}` "
+                    "is only permitted "
+                    f"for server version {kwarg_constraint}, your server "
+                    f"version is {self.server_version}. Contact your system "
+                    "administrator to update the server version."
+                )
+                raise ServerIncompatibilityError(msg)
+
+        out = method(*args, **kwargs)
+        return out
+
+    return wrapper

caveclient/chunkedgraph.py

@@ -12,7 +12,13 @@
 import pytz
 
 from .auth import AuthClient
-from .base import BaseEncoder, ClientBase, _api_endpoints, handle_response
+from .base import (
+    BaseEncoder,
+    ClientBase,
+    _api_endpoints,
+    _check_version_compatibility,
+    handle_response,
+)
 from .endpoints import (
     chunkedgraph_api_versions,
     chunkedgraph_endpoints_common,
@@ -183,6 +189,7 @@ def __init__(
         self._default_timestamp = timestamp
         self._table_name = table_name
         self._segmentation_info = None
+        self._server_version = self._get_version()
 
     @property
     def default_url_mapping(self):
@@ -775,6 +782,7 @@ def get_subgraph(
         rd = handle_response(response)
         return np.int64(rd["nodes"]), np.double(rd["affinities"]), np.int32(rd["areas"])
 
+    @_check_version_compatibility(kwarg_use_constraints={"bounds": ">=2.15.0"})
     def level2_chunk_graph(self, root_id, bounds=None) -> list:
         """
         Get graph of level 2 chunks, the smallest agglomeration level above supervoxels.
@@ -811,6 +819,8 @@ def level2_chunk_graph(self, root_id, bounds=None) -> list:
 
         r = handle_response(response)
 
+        # TODO in theory, could remove this check if we are confident in the server
+        # version fix
         used_bounds = response.headers.get("Used-Bounds")
         used_bounds = used_bounds == "true" or used_bounds == "True"
         if bounds is not None and not used_bounds:

caveclient/endpoints.py

@@ -128,6 +128,7 @@
 pcg_common = "{cg_server_address}/segmentation"
 chunkedgraph_endpoints_common = {
     "get_api_versions": pcg_common + "/api/versions",
+    "get_version": pcg_common + "/api/version",
     "info": pcg_common + "/table/{table_id}/info",
 }
 

setup.py

@@ -31,7 +31,7 @@ def find_version(*file_paths):
 setup(
     version=find_version("caveclient", "__init__.py"),
     name="caveclient",
-    description="a service for interacting with the Connectome Annotation Versioning Engine",
+    description="A client for interacting with the Connectome Annotation Versioning Engine",
     long_description=long_description,
     long_description_content_type="text/markdown",
     author="Forrest Collman, Casey Schneider-Mizell, Sven Dorkenwald",

tests/conftest.py

@@ -27,18 +27,46 @@
     "viewer_resolution_y": 4.0,
     "viewer_resolution_z": 40,
 }
+url_template = endpoints.infoservice_endpoints_v2["datastack_info"]
+mapping = {"i_server_address": TEST_GLOBAL_SERVER, "datastack_name": TEST_DATASTACK}
+url = url_template.format_map(mapping)
 
 
 @pytest.fixture()
 @responses.activate
 def myclient():
-    url_template = endpoints.infoservice_endpoints_v2["datastack_info"]
-    mapping = {"i_server_address": TEST_GLOBAL_SERVER, "datastack_name": TEST_DATASTACK}
-    url = url_template.format_map(mapping)
+    responses.add(responses.GET, url, json=test_info, status=200)
+
+    client = CAVEclient(
+        TEST_DATASTACK, server_address=TEST_GLOBAL_SERVER, write_server_cache=False
+    )
+
+    # need to mock the response of the version checking code for each sub-client which
+    # wants that information, and then create the sub-client here since the mock is
+    # narrowly scoped to this function
+    version_url = f"{TEST_LOCAL_SERVER}/segmentation/api/version"
+    responses.add(responses.GET, version_url, json="2.15.0", status=200)
 
+    client.chunkedgraph  # this will trigger the version check
+
+    return client
+
+
+@pytest.fixture()
+@responses.activate
+def old_chunkedgraph_client():
     responses.add(responses.GET, url, json=test_info, status=200)
 
     client = CAVEclient(
         TEST_DATASTACK, server_address=TEST_GLOBAL_SERVER, write_server_cache=False
     )
+
+    # need to mock the response of the version checking code for each sub-client which
+    # wants that information, and then create the sub-client here since the mock is
+    # narrowly scoped to this function
+    version_url = f"{TEST_LOCAL_SERVER}/segmentation/api/version"
+    responses.add(responses.GET, version_url, json="1.0.0", status=200)
+
+    client.chunkedgraph  # this will trigger the version check
+
     return client

tests/test_chunkedgraph.py

@@ -8,6 +8,7 @@
 import responses
 from responses.matchers import json_params_matcher
 
+from caveclient.base import ServerIncompatibilityError
 from caveclient.endpoints import (
     chunkedgraph_endpoints_common,
     chunkedgraph_endpoints_v1,
@@ -420,6 +421,15 @@ def test_get_lvl2subgraph_bounds(self, myclient):
                 root_id, bounds=bounds
             )
 
+    @responses.activate
+    def test_lvl2subgraph_old_server_fails_bounds(self, old_chunkedgraph_client):
+        bounds = np.array([[83875, 85125], [82429, 83679], [20634, 20884]])
+        root_id = 864691136812623475
+        with pytest.raises(ServerIncompatibilityError):
+            old_chunkedgraph_client.chunkedgraph.level2_chunk_graph(
+                root_id, bounds=bounds
+            )
+
     @responses.activate
     def test_get_remeshing(self, myclient):
         endpoint_mapping = self._default_endpoint_map