[REFACTOR] introduces ApiRequest and dynamic dispatch across implemen…

…tations (#19)

pokedex/api/__init__.py

@@ -1,4 +0,0 @@
-from typing import Any, Dict
-
-PokeApiEndpoints = Dict[str, str]
-Pokemon = Dict[str, Any]

pokedex/api/client.py

@@ -5,12 +5,15 @@
 from actionpack.actions import Call
 from actionpack.utils import Closure
 
-from pokedex.api import PokeApiEndpoints, Pokemon
-from pokedex.api.constants import BASE_URL
-from pokedex.api.models import PokeApiRequest, PokeApiResource, PokeApiResourceRef, PokemonRef
+from pokedex.api.models import PokeApiEndpoints, PokeApiResource, PokeApiResourceRef, Pokemon, PokemonRef
+from pokedex.api.request import ApiRequest
+from pokedex.api.request.protocol import DeferredRequest
+from pokedex.constants import BASE_URL
 
+ApiRequestType = ApiRequest.type()
 
-def get_endpoints(endpoints_request: PokeApiRequest) -> PokeApiEndpoints:
+
+def get_endpoints(endpoints_request: DeferredRequest) -> PokeApiEndpoints:
     response: requests.Response = endpoints_request()
     response.raise_for_status()
     endpoints: PokeApiEndpoints = response.json()
@@ -19,17 +22,19 @@ def get_endpoints(endpoints_request: PokeApiRequest) -> PokeApiEndpoints:
     return endpoints
 
 
-def select_endpoint(name: str, endpoints: PokeApiEndpoints) -> PokeApiRequest:
-    return PokeApiRequest(endpoints[name])
+def select_endpoint(name: str, endpoints: PokeApiEndpoints) -> DeferredRequest:
+    return ApiRequestType(endpoints[name])
 
 
-def get_resource(request: PokeApiRequest) -> PokeApiResource:
+def get_resource(request: DeferredRequest) -> PokeApiResource:
     response: requests.Response = request()
     response.raise_for_status()  # TODO: handle error states
     return PokeApiResource(**response.json())
 
 
-def generate_pokemon_requests(api_request: PokeApiRequest, response_key: str) -> Generator[PokeApiRequest, None, None]:
+def generate_pokemon_requests(
+    api_request: DeferredRequest, response_key: str
+) -> Generator[DeferredRequest, None, None]:
     response: requests.Response = api_request()
     response.raise_for_status()  # TODO: handle error states
     resource_refs = response.json()[response_key]
@@ -41,7 +46,7 @@ def generate_pokemon_requests(api_request: PokeApiRequest, response_key: str) ->
         yield model.as_request()
 
 
-def get_pokemon(pokemon_requests: Iterable[PokeApiRequest]) -> Generator[Pokemon, None, None]:
+def get_pokemon(pokemon_requests: Iterable[DeferredRequest]) -> Generator[Pokemon, None, None]:
     calls = (Call(Closure(pokemon_request)) for pokemon_request in pokemon_requests)
     for result in Procedure(calls).execute(synchronously=False, should_raise=True):
         # TODO: consider how to proceed if `result.successful => False`
@@ -52,7 +57,7 @@ def get_pokemon(pokemon_requests: Iterable[PokeApiRequest]) -> Generator[Pokemon
 
 def search_endpoint(
     endpoint_name: str, resource_ref_name: str, api_resource: Optional[PokeApiResource] = None
-) -> Optional[PokeApiRequest]:
+) -> Optional[DeferredRequest]:
     if not api_resource:
         api_resource = fetch(endpoint_name)
 
@@ -68,19 +73,21 @@ def search_endpoint(
         return search_endpoint(endpoint_name, resource_ref_name, new_api_resource)
 
 
+# TODO -- consider passing an `api_request_type: type[DeferredRequest]` param.
+# Doing so would give entrypoints explicit control over implementation selection at runtime.
 def fetch(endpoint_name: str) -> PokeApiResource:
-    endpoints = get_endpoints(PokeApiRequest(BASE_URL))
+    endpoints = get_endpoints(ApiRequestType(BASE_URL))
     endpoint = select_endpoint(endpoint_name, endpoints)
     return get_resource(endpoint)
 
 
-def get_pokemon_by_move(pokemon_move: str) -> Generator[PokeApiRequest, None, None]:
+def get_pokemon_by_move(pokemon_move: str) -> Generator[DeferredRequest, None, None]:
     endpoint_request = search_endpoint("move", pokemon_move)
     if endpoint_request:
         yield from generate_pokemon_requests(endpoint_request, "learned_by_pokemon")
 
 
-def get_pokemon_by_type(pokemon_type: str) -> Generator[PokeApiRequest, None, None]:
+def get_pokemon_by_type(pokemon_type: str) -> Generator[DeferredRequest, None, None]:
     endpoint_request = search_endpoint("type", pokemon_type)
     if endpoint_request:
         yield from generate_pokemon_requests(endpoint_request, "pokemon")

pokedex/api/models.py

@@ -1,30 +1,20 @@
-from dataclasses import dataclass
-from typing import List, Optional
+from typing import Any, Dict, List, Optional
 
-import requests
 from pydantic import BaseModel
 
-from pokedex.db.client import cached_get
+from pokedex.api.request import ApiRequest
+from pokedex.api.request.protocol import DeferredRequest
 
-
-@dataclass(frozen=True)
-class PokeApiRequest:
-    url: str
-
-    def __call__(self) -> requests.Response:
-        return cached_get(self.url)
-
-    @property
-    def __name__(self):
-        return f"{self.__class__.__name__}:{self.url}"
+Pokemon = Dict[str, Any]
+PokeApiEndpoints = Dict[str, str]
 
 
 class PokeApiResourceRef(BaseModel):
     name: str
     url: str
 
-    def as_request(self) -> PokeApiRequest:
-        return PokeApiRequest(self.url)
+    def as_request(self) -> DeferredRequest:
+        return ApiRequest.type()(self.url)
 
 
 class PokemonRef(BaseModel):
@@ -34,7 +24,7 @@ class PokemonRef(BaseModel):
     def as_api_resource_ref(self) -> PokeApiResourceRef:
         return self.pokemon
 
-    def as_request(self) -> PokeApiRequest:
+    def as_request(self) -> DeferredRequest:
         return self.pokemon.as_request()
 
 
@@ -45,6 +35,6 @@ class PokeApiResource(BaseModel):
     results: List[PokeApiResourceRef]
 
     @property
-    def next_request(self) -> Optional[PokeApiRequest]:
+    def next_request(self) -> Optional[DeferredRequest]:
         if self.next:
-            return PokeApiRequest(self.next)
+            return ApiRequest.type()(self.next)

pokedex/api/request/__init__.py

@@ -0,0 +1,16 @@
+from enum import Enum
+from typing import Type
+
+from pokedex.api.request.implementations.cached import CachedPokeApiRequest
+from pokedex.api.request.implementations.default import PokeApiRequest
+from pokedex.api.request.protocol import DeferredRequest
+from pokedex.constants import API_REQUEST_IMPL
+
+
+class ApiRequest(Enum):
+    DEFAULT: DeferredRequest = PokeApiRequest
+    CACHED: DeferredRequest = CachedPokeApiRequest
+
+    @staticmethod
+    def type() -> Type[DeferredRequest]:
+        return ApiRequest[API_REQUEST_IMPL].value

pokedex/api/request/implementations/cached.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+
+from requests import Response
+
+from pokedex.db.client import cached_get
+
+
+@dataclass(frozen=True)
+class CachedPokeApiRequest:
+    url: str
+
+    def __call__(self) -> Response:
+        return cached_get(self.url)
+
+    @property
+    def __name__(self):
+        return f"{self.__class__.__name__}:{self.url}"

pokedex/api/request/implementations/default.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+
+import requests
+
+
+@dataclass(frozen=True)
+class PokeApiRequest:
+    url: str
+
+    def __call__(self) -> requests.Response:
+        response = requests.get(self.url)
+        response.raise_for_status()
+        return response
+
+    @property
+    def __name__(self):
+        return f"{self.__class__.__name__}:{self.url}"

pokedex/api/request/protocol.py

@@ -0,0 +1,12 @@
+from typing import Protocol, runtime_checkable
+
+from requests import Response
+
+
+@runtime_checkable
+class DeferredRequest(Protocol):
+    url: str
+
+    def __call__(self) -> Response:
+        classname = self.__class__.__name__
+        raise NotImplementedError(f"Followers of the {classname} Protocol must return a {Response.__name__}")

pokedex/constants.py

@@ -1,5 +1,10 @@
+from os import environ
 from pathlib import Path
 
 PROJECTROOT = Path(__file__).parent.parent.absolute()
 DBROOT = PROJECTROOT / "pokedex" / "db"
 CACHEPATH = DBROOT / "cache"
+
+BASE_URL = "https://pokeapi.co/api/v2/"
+
+API_REQUEST_IMPL = environ.get("API_REQUEST_IMPL") or "DEFAULT"

pokedex/db/actions.py

@@ -5,8 +5,8 @@
 
 from actionpack import Action
 
+from pokedex.api.request.protocol import DeferredRequest
 from pokedex.constants import CACHEPATH
-from pokedex.db.models import DeferredRequest
 
 
 @dataclass

pokedex/db/client.py

@@ -4,8 +4,8 @@
 import requests
 from actionpack import KeyedProcedure
 
+from pokedex.api.request.protocol import DeferredRequest
 from pokedex.db.actions import DbInsert, DbInsertRequestResult, DbRead
-from pokedex.db.models import DeferredRequest
 
 
 def persist_requests(requests: Iterable[DeferredRequest]):

pokedex/db/models.py

@@ -2,17 +2,6 @@
 from dataclasses import asdict, dataclass
 from typing import Any, Dict, List, Type, Union
 
-from requests import Response
-from typing_extensions import Protocol
-
-
-class DeferredRequest(Protocol):
-    url: str
-
-    def __call__(self) -> Response:
-        pass
-
-
 JSON = Union[Dict[str, Any], List[Any], int, str, float, bool, Type[None]]
 
 

scripts/__init__.py

@@ -18,7 +18,7 @@ def coverage():
         # black ignore formatting:
         # fmt: off
         "python", "-m",
-        "coverage", "report", "-m", "--skip-empty", "--fail-under=90"
+        "coverage", "report", "-m", "--skip-empty", "--fail-under=80"
         # fmt: on
     ]
     completed_proc = subprocess.run(compile_coverage_report)

tests/pokedex/api/test_client.py

@@ -5,7 +5,7 @@
 from requests.exceptions import HTTPError
 
 from pokedex.api.client import get_pokemon, get_pokemon_by_move, get_pokemon_by_type
-from pokedex.api.models import PokeApiRequest
+from pokedex.api.request.implementations.default import PokeApiRequest
 from tests.fixtures import craft_response, resource
 
 

tests/pokedex/db/test_actions.py

@@ -8,7 +8,7 @@
 class TestActions(TestCase):
     @patch("dbm.open")
     def test_can_read_cache(self, mock_kv_open):
-        key = "https://pokeapi.co/api/v2/pokemon/39/"
+        key = "https://pokeapi.co/api/v2/pokemon/18/"
         pokemon_data = resource("jigglypuff.response")
         mock_kv_open.return_value.__enter__.return_value.__getitem__.return_value = pokemon_data
         mock_kv_open.assert_not_called()

tests/pokedex/db/test_client.py

@@ -4,7 +4,7 @@
 import requests
 from requests.exceptions import HTTPError
 
-from pokedex.api.models import PokeApiRequest
+from pokedex.api.request.implementations.cached import CachedPokeApiRequest
 from pokedex.db.actions import DbRead
 from pokedex.db.client import cached_get, persist_requests
 from tests.fixtures import craft_response, craft_result, resource
@@ -13,14 +13,14 @@
 class TestClientCanCache(TestCase):
     @patch("pokedex.db.actions.DbInsertRequestResult")
     @patch.object(
-        target=PokeApiRequest,
+        target=CachedPokeApiRequest,
         attribute="__call__",
         side_effect=[
             craft_response(resource("jigglypuff.response"), status_code=200),
         ],
     )
     def test_can_persist_request(self, mock_request, mock_db_insert):
-        request_url = "https://pokeapi.co/api/v2/pokemon/39/"
+        request_url = "https://pokeapi.co/api/v2/pokemon/18/"
         mock_request.url = request_url
         key, response_data = next(persist_requests((mock_request,)))
         assert key is request_url
@@ -36,7 +36,7 @@ class TestClientCanRetrieveFromCache(TestCase):
         ],
     )
     def test_cache_hit(self, mock_db_reads):
-        pokemon_response = cached_get("https://pokeapi.co/api/v2/pokemon/39/")
+        pokemon_response = cached_get("https://pokeapi.co/api/v2/pokemon/18/")
         assert pokemon_response.json()["name"] == "jigglypuff"
 
     @patch.object(
@@ -53,20 +53,20 @@ def test_cache_hit(self, mock_db_reads):
     )
     def test_cache_miss_request_fail(self, mock_requests, mock_db_reads):
         with self.assertRaises(HTTPError):
-            cached_get("https://pokeapi.co/api/v2/pokemon/39/")
+            cached_get("https://pokeapi.co/api/v2/pokemon/18/")
 
     @patch.object(
         target=DbRead,
         attribute="perform",
         side_effect=[craft_result(value=Exception("missing key."), successful=False)],
     )
     @patch.object(
-        target=PokeApiRequest,
-        attribute="__call__",
+        target=requests,
+        attribute="get",
         side_effect=[
             craft_response(resource("jigglypuff.response"), status_code=200),
         ],
     )
     def test_cache_miss_request_success(self, mock_requests, mock_db_reads):
-        pokemon_response = cached_get("https://pokeapi.co/api/v2/pokemon/39/")
+        pokemon_response = cached_get("https://pokeapi.co/api/v2/pokemon/18/")
         assert pokemon_response.json()["name"] == "jigglypuff"

tests/pokedex/db/test_models.py

@@ -0,0 +1,21 @@
+import json
+from unittest import TestCase
+
+from pokedex.db.models import Report
+
+
+class TestReport(TestCase):
+
+    def test_report_representation(self):
+        results = {
+            "https://pokeapi.co/api/v2/pokemon/1/": True,
+            "https://pokeapi.co/api/v2/pokemon/2/": True,
+            "https://pokeapi.co/api/v2/pokemon/3/": False,
+        }
+        report = Report(persisted=results)
+        expected_report = json.dumps(
+            {"persisted": results, "count": len(results)},
+            indent=4
+        )
+
+        assert str(report) == expected_report