recapi 0.4.1__py3-none-any.whl

recapi/__init__.py

@@ -0,0 +1,38 @@
+"""recapi: recommendations for any site or app with a catalog.
+
+Quick start::
+
+    import recapi
+
+    client = recapi.Client("rk_sec_...", "https://api.example.com")
+    client.track("item-42", "view", user_id="user-1")
+    recs = client.recommend(user_id="user-1", count=4)
+
+In asyncio apps (FastAPI), ``recapi.AsyncClient`` has the same methods as
+coroutines. See ``sdk/python/README.md``.
+"""
+
+from typing import Any
+
+from .client import Client, Item, MemoryStore, RecapiError, Recommendations, Store, __version__
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "Item",
+    "MemoryStore",
+    "RecapiError",
+    "Recommendations",
+    "Store",
+    "__version__",
+]
+
+
+def __getattr__(name: str) -> Any:
+    # asyncio takes longer to import than the rest of the library: only the
+    # apps that use AsyncClient pay for it.
+    if name == "AsyncClient":
+        from .async_client import AsyncClient  # noqa: PLC0415
+
+        return AsyncClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

recapi/async_client.py

@@ -0,0 +1,95 @@
+"""The recapi client for asyncio apps (FastAPI, async Django), standard library only.
+
+Every method of :class:`Client` runs on a small thread pool of the client's
+own, so a slow recapi never blocks the event loop, and the client's
+connections to recapi stay open between calls.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import os
+import time
+import weakref
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+from .client import Client, Item, Recommendations, _call
+
+# Calls in flight per process. A call takes a few milliseconds of a thread,
+# so 8 serve hundreds of recommendations a second; past that they queue, and
+# recommend() falls back by its deadline.
+THREADS = 8
+
+
+class AsyncClient:
+    """A :class:`Client` whose methods are coroutines; same arguments, same behaviour.
+
+    Create one per process. recommend()'s 1.5 s count from the ``await``: a
+    call still waiting for a free thread then goes straight to popular items.
+    """
+
+    def __init__(self, api_key: str, base_url: str, **options: Any) -> None:
+        self._client = Client(api_key, base_url, **options)
+        self._init_pool()
+        if hasattr(os, "register_at_fork"):
+            ref = weakref.ref(self)
+            os.register_at_fork(after_in_child=lambda: _call(ref, "_init_pool"))
+
+    def _init_pool(self) -> None:
+        # Also in a forked child, which has none of the parent's threads.
+        self._pool = ThreadPoolExecutor(THREADS, thread_name_prefix="recapi-async")
+
+    async def _run(self, fn: Any, *args: Any, **kwargs: Any) -> Any:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(self._pool, functools.partial(fn, *args, **kwargs))
+
+    async def recommend(self, **params: Any) -> Recommendations:
+        """Personalised recommendations: :meth:`Client.recommend`, same keywords."""
+        client = self._client
+        deadline = time.monotonic() + client._recommend_timeout
+        job = self._pool.submit(client._recommend, deadline, **params)
+        result = asyncio.wrap_future(job)
+        try:
+            return await asyncio.wait_for(asyncio.shield(result), client._recommend_timeout)
+        except TimeoutError:
+            if not job.cancel():
+                return await result  # running: its own deadline has passed too
+        except asyncio.CancelledError:
+            job.cancel()
+            raise
+        # Every thread was still busy at the deadline: don't wait for one to
+        # serve the fallback. Past its deadline, the call asks only for popular items.
+        return await asyncio.to_thread(client._recommend, deadline, **params)
+
+    async def track(self, item_id: str, level: int | str, **ids: str | None) -> None:
+        """Record an interaction: :meth:`Client.track`."""
+        await self._run(self._client.track, item_id, level, **ids)
+
+    async def identify(self, anon_id: str, user_id: str) -> None:
+        """At login, the visitor's history becomes the user's: :meth:`Client.identify`."""
+        await self._run(self._client.identify, anon_id, user_id)
+
+    async def popular(self, **params: Any) -> list[Item]:
+        """Popular items: :meth:`Client.popular`."""
+        return await self._run(self._client.popular, **params)
+
+    async def upsert_items(self, items: Any) -> int:
+        """Create or replace items: :meth:`Client.upsert_items`."""
+        return await self._run(self._client.upsert_items, items)
+
+    async def delete_user(self, user_id: str) -> None:
+        """Erase a user (GDPR): :meth:`Client.delete_user`."""
+        await self._run(self._client.delete_user, user_id)
+
+    async def flush(self) -> None:
+        """Send every queued event now: :meth:`Client.flush`."""
+        await self._run(self._client.flush)
+
+    async def close(self) -> None:
+        """Send what is queued and stop the sender: :meth:`Client.close` (also runs at exit).
+
+        As with Client, later calls still work (their events are sent at once).
+        """
+        await self._run(self._client.close)