Start of subscriptions client tests (#590)

* Start of subscriptions client tests

More or less the same inputs as the CLI tests.

Resolves #518

* Drop filter/lambda for generator expression

A little test tweaking too,

* Hoist placeholder implementation of create_subscription up and out

It's now at the module root. Something more like the production
code remains.

* Finish hoisting

* Raise APIError on simulated server errors

* Rename PlaceholderSubscriptionsClient to SubscriptionsClient

Still not connected to the API servers, saving that for next.

Author: sgillies

planet/cli/subscriptions.py

@@ -7,8 +7,7 @@
 from planet import Session
 from planet.cli.cmds import coro, translate_exceptions
 from planet.cli.io import echo_json
-from planet.clients.subscriptions import (PlaceholderSubscriptionsClient as
-                                          SubscriptionsClient)
+from planet.clients.subscriptions import SubscriptionsClient
 
 
 @click.group()

planet/clients/subscriptions.py

@@ -4,64 +4,111 @@
 from typing import AsyncIterator, Dict, Optional, Set
 import uuid
 
-from planet.exceptions import ClientError
+from planet.exceptions import APIError
 
 # Collections of fake subscriptions and results for testing. Tests will
 # monkeypatch these attributes.
-_fake_subs: Optional[Dict[str, dict]] = None
-_fake_sub_results: Optional[Dict[str, list]] = None
+_fake_subs: Dict[str, dict] = {}
+_fake_sub_results: Dict[str, list] = {}
 
 
-class PlaceholderSubscriptionsClient:
-    """A placeholder client.
+async def _server_subscriptions_post(request):
+    missing_keys = {'name', 'delivery', 'source'} - request.keys()
+    if missing_keys:
+        raise RuntimeError(f"Request lacks required members: {missing_keys!r}")
 
-    This class and its methods are derived from tests of a skeleton
-    Subscriptions CLI. It is evolving into the real API client.
+    id = str(uuid.uuid4())
+    _fake_subs[id] = request
+    sub = _fake_subs[id].copy()
+    sub.update(id=id)
+    return sub
+
+
+async def _server_subscriptions_get(status=None, limit=None):
+    select_subs = (dict(**sub, id=sub_id) for sub_id,
+                   sub in _fake_subs.items()
+                   if not status or sub['status'] in status)
+    filtered_subs = itertools.islice(select_subs, limit)
+    for sub in filtered_subs:
+        yield sub
+
+
+async def _server_subscriptions_id_cancel_post(subscription_id):
+    sub = _fake_subs.pop(subscription_id)
+    sub.update(id=subscription_id)
+    return sub
+
+
+async def _server_subscriptions_id_put(subscription_id, request):
+    _fake_subs[subscription_id].update(**request)
+    sub = _fake_subs[subscription_id].copy()
+    sub.update(id=subscription_id)
+    return sub
+
+
+async def _server_subscriptions_id_get(subscription_id):
+    sub = _fake_subs[subscription_id].copy()
+    sub.update(id=subscription_id)
+    return sub
+
+
+async def _server_subscriptions_id_results_get(subscription_id,
+                                               status=None,
+                                               limit=None):
+    select_results = (result for result in _fake_sub_results[subscription_id]
+                      if not status or result['status'] in status)
+    filtered_results = itertools.islice(select_results, limit)
+    for result in filtered_results:
+        yield result
+
+
+class SubscriptionsClient:
+    """The Planet Subscriptions API client.
+
+    TODO: make requests to the production API. Currently, the backend
+    is fake and exists at the top of this class's module.
 
     """
 
     def __init__(self, session=None) -> None:
         self._session = session
 
     async def list_subscriptions(self,
-                                 status: Set[str] = None,
+                                 status: Optional[Set[str]] = None,
                                  limit: int = 100) -> AsyncIterator[dict]:
         """Get account subscriptions with optional filtering.
 
-        The name of this method is based on the API's method name. This
-        method provides iteration over subcriptions, it does not return
-        a list.
+        Note:
+            The name of this method is based on the API's method name. This
+            method provides iteration over subcriptions, it does not return
+            a list.
 
         Args:
             status (Set[str]): pass subscriptions with status in this
                 set, filter out subscriptions with status not in this
                 set.
             limit (int): limit the number of subscriptions in the
                 results.
+            TODO: user_id
 
         Yields:
             dict: a description of a subscription.
 
         Raises:
-            ClientError
+            APIError: on an API server error.
+            ClientError: on a client error.
 
         """
-        # Temporary marker for behavior of module with unpatched state.
-        if _fake_subs is None:
-            raise NotImplementedError
-
-        if status:
-            select_subs = (dict(**sub, id=sub_id) for sub_id,
-                           sub in _fake_subs.items()
-                           if sub['status'] in status)
-        else:
-            select_subs = (
-                dict(**sub, id=sub_id) for sub_id, sub in _fake_subs.items())
-
-        filtered_subs = itertools.islice(select_subs, limit)
-
-        for sub in filtered_subs:
-            yield sub
+        try:
+            # TODO: replace with httpx request.
+            async for sub in _server_subscriptions_get(status=status,
+                                                       limit=limit):
+                yield sub
+        except Exception as server_error:
+            # TODO: remove "from server_error" clause. It's useful
+            # during development but may invite users to depend on the
+            # value of server_error.
+            raise APIError("Subscription failure") from server_error
 
     async def create_subscription(self, request: dict) -> dict:
         """Create a Subscription.
@@ -73,23 +120,20 @@ async def create_subscription(self, request: dict) -> dict:
             dict: description of created subscription.
 
         Raises:
-            ClientError
+            APIError: on an API server error.
+            ClientError: on a client error.
 
         """
-        # Temporary marker for behavior of module with unpatched state.
-        if _fake_subs is None:
-            raise NotImplementedError
-
-        missing_keys = {'name', 'delivery', 'source'} - request.keys()
-        if missing_keys:
-            raise ClientError(
-                f"Request lacks required members: {missing_keys!r}")
-
-        id = str(uuid.uuid4())
-        _fake_subs[id] = request
-        sub = _fake_subs[id].copy()
-        sub.update(id=id)
-        return sub
+        try:
+            # TODO: replace with httpx request.
+            sub = await _server_subscriptions_post(request)
+        except Exception as server_error:
+            # TODO: remove "from server_error" clause. It's useful
+            # during development but may invite users to depend on the
+            # value of server_error.
+            raise APIError("Subscription failure") from server_error
+        else:
+            return sub
 
     async def cancel_subscription(self, subscription_id: str) -> dict:
         """Cancel a Subscription.
@@ -101,20 +145,20 @@ async def cancel_subscription(self, subscription_id: str) -> dict:
             dict: description of cancelled subscription.
 
         Raises:
-            ClientError
+            APIError: on an API server error.
+            ClientError: on a client error.
 
         """
-        # Temporary marker for behavior of module with unpatched state.
-        if _fake_subs is None:
-            raise NotImplementedError
-
         try:
-            sub = _fake_subs.pop(subscription_id)
-        except KeyError:
-            raise ClientError(f"No such subscription: {subscription_id!r}")
-
-        sub.update(id=subscription_id)
-        return sub
+            # TODO: replace with httpx request.
+            sub = await _server_subscriptions_id_cancel_post(subscription_id)
+        except Exception as server_error:
+            # TODO: remove "from server_error" clause. It's useful
+            # during development but may invite users to depend on the
+            # value of server_error.
+            raise APIError("Subscription failure.") from server_error
+        else:
+            return sub
 
     async def update_subscription(self, subscription_id: str,
                                   request: dict) -> dict:
@@ -128,21 +172,20 @@ async def update_subscription(self, subscription_id: str,
             dict: description of the updated subscription.
 
         Raises:
-            ClientError
+            APIError: on an API server error.
+            ClientError: on a client error.
 
         """
-        # Temporary marker for behavior of module with unpatched state.
-        if _fake_subs is None:
-            raise NotImplementedError
-
         try:
-            _fake_subs[subscription_id].update(**request)
-            sub = _fake_subs[subscription_id].copy()
-        except KeyError:
-            raise ClientError(f"No such subscription: {subscription_id!r}")
-
-        sub.update(id=subscription_id)
-        return sub
+            # TODO: replace with httpx request.
+            sub = await _server_subscriptions_id_put(subscription_id, request)
+        except Exception as server_error:
+            # TODO: remove "from server_error" clause. It's useful
+            # during development but may invite users to depend on the
+            # value of server_error.
+            raise APIError("Subscription failure.") from server_error
+        else:
+            return sub
 
     async def get_subscription(self, subscription_id: str) -> dict:
         """Get a description of a Subscription.
@@ -154,61 +197,55 @@ async def get_subscription(self, subscription_id: str) -> dict:
             dict: description of the subscription.
 
         Raises:
-            ClientError
+            APIError: on an API server error.
+            ClientError: on a client error.
 
         """
-        # Temporary marker for behavior of module with unpatched state.
-        if _fake_subs is None:
-            raise NotImplementedError
-
         try:
-            sub = _fake_subs[subscription_id].copy()
-        except KeyError:
-            raise ClientError(f"No such subscription: {subscription_id!r}")
-
-        sub.update(id=subscription_id)
-        return sub
+            # TODO: replace with httpx request.
+            sub = await _server_subscriptions_id_get(subscription_id)
+        except Exception as server_error:
+            # TODO: remove "from server_error" clause. It's useful
+            # during development but may invite users to depend on the
+            # value of server_error.
+            raise APIError("Subscription failure.") from server_error
+        else:
+            return sub
 
     async def get_results(self,
                           subscription_id: str,
-                          status: Set[str] = None,
+                          status: Optional[Set[str]] = None,
                           limit: int = 100) -> AsyncIterator[dict]:
         """Get Results of a Subscription.
 
-        The name of this method is based on the API's method name. This
-        method provides iteration over results, it does not get a
-        single result description or return a list of descriptions.
+        Note:
+            The name of this method is based on the API's method name. This
+            method provides iteration over results, it does not get a
+            single result description or return a list of descriptions.
 
         Args:
             subscription_id (str): id of a subscription.
             status (Set[str]): pass result with status in this set,
                 filter out results with status not in this set.
             limit (int): limit the number of subscriptions in the
                 results.
+            TODO: created, updated, completed, user_id
 
         Yields:
             dict: description of a subscription results.
 
         Raises:
-            ClientError
+            APIError: on an API server error.
+            ClientError: on a client error.
 
         """
-        # Temporary marker for behavior of module with unpatched state.
-        if _fake_sub_results is None:
-            raise NotImplementedError
-
         try:
-            if status:
-                select_results = (
-                    result for result in _fake_sub_results[subscription_id]
-                    if result['status'] in status)
-            else:
-                select_results = (
-                    result for result in _fake_sub_results[subscription_id])
-
-            filtered_results = itertools.islice(select_results, limit)
-        except KeyError:
-            raise ClientError(f"No such subscription: {subscription_id!r}")
-
-        for result in filtered_results:
-            yield result
+            # TODO: replace with httpx request.
+            async for result in _server_subscriptions_id_results_get(
+                    subscription_id, status=status, limit=limit):
+                yield result
+        except Exception as server_error:
+            # TODO: remove "from server_error" clause. It's useful
+            # during development but may invite users to depend on the
+            # value of server_error.
+            raise APIError("Subscription failure.") from server_error