[RFC] Propose a minimal specialization for extract

zyte_api/aio/client.py

@@ -4,8 +4,10 @@
 
 import asyncio
 import time
+from base64 import b64decode
+from collections.abc import Mapping
 from functools import partial
-from typing import Optional, Iterator, List
+from typing import Awaitable, Iterator, List, Optional
 
 import aiohttp
 from aiohttp import TCPConnector
@@ -16,7 +18,7 @@
 from ..apikey import get_apikey
 from ..constants import API_URL, API_TIMEOUT
 from ..stats import AggStats, ResponseStats
-from ..utils import user_agent
+from ..utils import _to_lower_camel_case, user_agent
 
 
 # 120 seconds is probably too long, but we are concerned about the case with
@@ -43,6 +45,38 @@ def _post_func(session):
         return session.post
 
 
+class ExtractResult(Mapping):
+    """Result of a call to AsyncClient.extract.
+
+    It can be used as a dictionary to access the raw API response.
+
+    It also provides some helper properties for easier access to some of its
+    underlying data.
+    """
+
+    def __init__(self, api_response: dict):
+        self._api_response = api_response
+
+    def __getitem__(self, key):
+        return self._api_response[key]
+
+    def __iter__(self):
+        yield from self._api_response
+
+    def __len__(self):
+        return len(self._api_response)
+
+    @property
+    def http_response_body(self): -> bytes:
+        if hasattr(self, "_http_response_body"):
+            return self._http_response_body
+        base64_body = self._api_response.get("httpResponseBody", None)
+        if base64_body is None:
+            raise ValueError("API response has no httpResponseBody key.")
+        self._http_response_body = b64decode(base64_body)
+        return self._http_response_body
+
+
 class AsyncClient:
     def __init__(self, *,
                  api_key=None,
@@ -148,3 +182,44 @@ async def _request(query):
                     session=session)
 
         return asyncio.as_completed([_request(query) for query in queries])
+
+    @staticmethod
+    def _build_extract_query(raw_query):
+        return {
+            _to_lower_camel_case(k): v
+            for k, v in raw_query.items()
+        }
+
+    async def extract(
+        self,
+        url: str,
+        *,
+        session: Optional[aiohttp.ClientSession] = None,
+        handle_retries: bool = True,
+        retrying: Optional[AsyncRetrying] = None,
+        **kwargs,
+    ) -> Awaitable[ExtractResult]:
+        """…"""
+        query = self._build_extract_query({**kwargs, 'url'=url})
+        response = await self.request_raw(
+            query=query,
+            endpoint='extract',
+            session=session,
+            handle_retries=handle_retries,
+            retrying=retrying,
+        )
+        return ExtractResult(response)
+
+    def extract_in_parallel(
+        self,
+        queries: List[dict],
+        *,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> Iterator[asyncio.Future]:
+        """…"""
+        queries = [self._build_extract_query(query) for query in queries]
+        return self.request_parallel_as_completed(
+            queries,
+            endpoint='extract',
+            session=session,
+        )

zyte_api/utils.py

@@ -1,7 +1,13 @@
-# -*- coding: utf-8 -*-
 from .__version__ import __version__
 
 
+def _to_lower_camel_case(snake_case_string):
+    """Convert from snake case (foo_bar) to lower-case-initial camel case
+    (fooBar)."""
+    prefix, *rest = snake_case_string.split('_')
+    return prefix + ''.join(part.title() for part in rest)
+
+
 def user_agent(library):
     return 'python-zyte-api/{} {}/{}'.format(
         __version__,