recapi 0.4.1__tar.gz → 0.4.2__tar.gz

{recapi-0.4.1/recapi.egg-info → recapi-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: recapi
-Version: 0.4.1
+Version: 0.4.2
 Summary: Python client for the recapi recommendation API: per-user history, event batching, retries, popular fallback.
 License: MIT
 Requires-Python: >=3.11
@@ -28,7 +28,7 @@ Your recapi API serves the library: install it with pip, or put the same URL
 in your `requirements.txt`. No package index, no build step, no dependencies:
 
 ```sh
-pip install https://api.<your-domain>/sdk/python/recapi-0.4.1-py3-none-any.whl
+pip install https://api.<your-domain>/sdk/python/recapi-0.4.2-py3-none-any.whl
 ```
 
 The dashboard's quick start shows this line with your API's address. To work
@@ -110,8 +110,9 @@ recapi uses the history it keeps from that user's events, and returns it with
 the recommendations; the client stores it for the next calls. If the store's
 first call for that user was a `track()` or an `identify()`, the first
 `recommend()` fetches that history (`GET /v1/users/{id}/history`, unbilled)
-with half of its 1.5 s and merges it with what was tracked here; a failed
-fetch is tried again on the next call. This works for `user_id` only, and
+with half of its 1.5 s and merges it with what was tracked here (after an
+`identify()`, without the visitor's browsing, which is already merged here); a
+failed fetch is tried again on the next call. This works for `user_id` only, and
 only with a secret key. A store that fails
 (Redis down) is logged and skipped: tracking and recommendations go on.
 Updates to one user are serialised within a process only: two processes
@@ -184,7 +185,7 @@ one recommendation id collects the events of many users ("Page caches").
 | `recommend(*, user_id=None, anon_id=None, count=0, placement=None, tags_any=None, tags_all=None, exclude=None, context_item_id=None, discovery=None)` | Returns `Recommendations(recommendation_id, fallback, items)`, each item `Item(item_id, score, slot, metadata, why)`. `metadata` is the dict stored with the item ([Item metadata](../../docs/api.md#item-metadata)), None when it has none; `why` its [reason code](../../docs/api.md#reason-codes). The user's rejected items are added to `exclude` |
 | `popular(*, count=10, tags_any=None, tags_all=None)` | Popular items (`Item`, metadata and `why` included), for pages without a user |
 | `upsert_items(items)` | Creates or replaces items (dicts with the [item fields](../../docs/api.md#put-v1itemsitem_id--secret-key)), 1,000 per request, with retries. Returns how many were stored |
-| `identify(anon_id, user_id)` | At login: merges the visitor's history and shown items into the user's, then deletes the visitor's entry |
+| `identify(anon_id, user_id)` | At login: merges the visitor's history and shown items into the user's, then deletes the visitor's entry. The user's first restore from recapi then leaves that visitor's browsing out, so it doesn't count twice |
 | `delete_user(user_id)` | Erases the user's events in recapi (GDPR) and their state in the store |
 | `flush()` / `close()` | Send queued events now; `close()` also stops the background sender |
 

{recapi-0.4.1 → recapi-0.4.2}/README.md

@@ -18,7 +18,7 @@ Your recapi API serves the library: install it with pip, or put the same URL
 in your `requirements.txt`. No package index, no build step, no dependencies:
 
 ```sh
-pip install https://api.<your-domain>/sdk/python/recapi-0.4.1-py3-none-any.whl
+pip install https://api.<your-domain>/sdk/python/recapi-0.4.2-py3-none-any.whl
 ```
 
 The dashboard's quick start shows this line with your API's address. To work
@@ -100,8 +100,9 @@ recapi uses the history it keeps from that user's events, and returns it with
 the recommendations; the client stores it for the next calls. If the store's
 first call for that user was a `track()` or an `identify()`, the first
 `recommend()` fetches that history (`GET /v1/users/{id}/history`, unbilled)
-with half of its 1.5 s and merges it with what was tracked here; a failed
-fetch is tried again on the next call. This works for `user_id` only, and
+with half of its 1.5 s and merges it with what was tracked here (after an
+`identify()`, without the visitor's browsing, which is already merged here); a
+failed fetch is tried again on the next call. This works for `user_id` only, and
 only with a secret key. A store that fails
 (Redis down) is logged and skipped: tracking and recommendations go on.
 Updates to one user are serialised within a process only: two processes
@@ -174,7 +175,7 @@ one recommendation id collects the events of many users ("Page caches").
 | `recommend(*, user_id=None, anon_id=None, count=0, placement=None, tags_any=None, tags_all=None, exclude=None, context_item_id=None, discovery=None)` | Returns `Recommendations(recommendation_id, fallback, items)`, each item `Item(item_id, score, slot, metadata, why)`. `metadata` is the dict stored with the item ([Item metadata](../../docs/api.md#item-metadata)), None when it has none; `why` its [reason code](../../docs/api.md#reason-codes). The user's rejected items are added to `exclude` |
 | `popular(*, count=10, tags_any=None, tags_all=None)` | Popular items (`Item`, metadata and `why` included), for pages without a user |
 | `upsert_items(items)` | Creates or replaces items (dicts with the [item fields](../../docs/api.md#put-v1itemsitem_id--secret-key)), 1,000 per request, with retries. Returns how many were stored |
-| `identify(anon_id, user_id)` | At login: merges the visitor's history and shown items into the user's, then deletes the visitor's entry |
+| `identify(anon_id, user_id)` | At login: merges the visitor's history and shown items into the user's, then deletes the visitor's entry. The user's first restore from recapi then leaves that visitor's browsing out, so it doesn't count twice |
 | `delete_user(user_id)` | Erases the user's events in recapi (GDPR) and their state in the store |
 | `flush()` / `close()` | Send queued events now; `close()` also stops the background sender |
 

{recapi-0.4.1 → recapi-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "recapi"
-version = "0.4.1"
+version = "0.4.2"
 description = "Python client for the recapi recommendation API: per-user history, event batching, retries, popular fallback."
 readme = "README.md"
 requires-python = ">=3.11"

{recapi-0.4.1 → recapi-0.4.2}/recapi/client.py

@@ -29,7 +29,7 @@ from typing import Any, Protocol
 
 from .history import History, is_id
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 log = logging.getLogger("recapi")
 Tags = Sequence[str] | None
@@ -196,22 +196,32 @@ class _UserState:
 
     ``shown`` maps item -> [recommendation id, shown at, clicked at?], oldest
     first. ``restored`` is set once the history holds recapi's stored one.
+    ``anon_id`` is the visitor identify() merged in before that: recapi's
+    snapshot also holds that visitor's browsing, so the restore asks it to
+    leave it out.
     """
 
-    __slots__ = ("history", "restored", "shown")
+    __slots__ = ("anon_id", "history", "restored", "shown")
 
     def __init__(
-        self, history: History | None = None, shown: dict | None = None, restored: bool = False
+        self,
+        history: History | None = None,
+        shown: dict | None = None,
+        restored: bool = False,
+        anon_id: str | None = None,
     ) -> None:
         self.history = history or History()
         self.shown: dict[str, list[Any]] = shown or {}
         self.restored = restored
+        self.anon_id = anon_id
 
     def dumps(self, now: int) -> str:
         shown = [[item, *entry] for item, entry in self.shown.items() if _attributable(entry, now)]
         state = {"history": self.history.encode(), "shown": shown[-MAX_SHOWN_ITEMS:]}
         if self.restored:
             state["restored"] = True
+        if self.anon_id:
+            state["anon_id"] = self.anon_id
         return json.dumps(state, separators=(",", ":"))
 
     @classmethod
@@ -231,7 +241,10 @@ class _UserState:
         if history is None:
             log.warning("recapi: discarding a malformed stored user state")
             return cls()
-        return cls(history, shown, data.get("restored") is True)
+        anon_id = data.get("anon_id")
+        return cls(
+            history, shown, data.get("restored") is True, anon_id if is_id(anon_id) else None
+        )
 
 
 def _attributable(entry: Sequence[Any], t: int) -> bool:
@@ -628,9 +641,11 @@ class Client:
         a failure leaves the state as it was, to be tried on the next call.
         """
         path = "/v1/users/" + urllib.parse.quote(user_id, safe="") + "/history"
+        query = {"anon_id": state.anon_id} if state.anon_id else None
         try:
             # Half the time left, so the recommendation itself still fits.
-            snapshot = self._request("GET", path, timeout=(deadline - time.monotonic()) / 2)
+            timeout = (deadline - time.monotonic()) / 2
+            snapshot = self._request("GET", path, timeout=timeout, query=query)
             if not isinstance(snapshot, dict):
                 raise RecapiError("invalid_response", "malformed history response")
         except RecapiError as error:
@@ -642,6 +657,7 @@ class Client:
             if not state.restored:
                 state.history = state.history.merge_snapshot(History.from_snapshot(snapshot), t)
                 state.restored = True
+                state.anon_id = None
                 self._save(key, state, t)
         return state
 
@@ -664,6 +680,9 @@ class Client:
                 return
             state = self._load(user)
             state.history = state.history.merge(guest.history, t)
+            if not state.restored:
+                # recapi's snapshot, fetched later, holds this visitor's browsing too.
+                state.anon_id = anon_id
             # Oldest display first, as recommend() keeps them; an item's later display wins.
             shown = sorted([*state.shown.items(), *guest.shown.items()], key=lambda e: e[1][1])
             state.shown = {}

{recapi-0.4.1 → recapi-0.4.2/recapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: recapi
-Version: 0.4.1
+Version: 0.4.2
 Summary: Python client for the recapi recommendation API: per-user history, event batching, retries, popular fallback.
 License: MIT
 Requires-Python: >=3.11
@@ -28,7 +28,7 @@ Your recapi API serves the library: install it with pip, or put the same URL
 in your `requirements.txt`. No package index, no build step, no dependencies:
 
 ```sh
-pip install https://api.<your-domain>/sdk/python/recapi-0.4.1-py3-none-any.whl
+pip install https://api.<your-domain>/sdk/python/recapi-0.4.2-py3-none-any.whl
 ```
 
 The dashboard's quick start shows this line with your API's address. To work
@@ -110,8 +110,9 @@ recapi uses the history it keeps from that user's events, and returns it with
 the recommendations; the client stores it for the next calls. If the store's
 first call for that user was a `track()` or an `identify()`, the first
 `recommend()` fetches that history (`GET /v1/users/{id}/history`, unbilled)
-with half of its 1.5 s and merges it with what was tracked here; a failed
-fetch is tried again on the next call. This works for `user_id` only, and
+with half of its 1.5 s and merges it with what was tracked here (after an
+`identify()`, without the visitor's browsing, which is already merged here); a
+failed fetch is tried again on the next call. This works for `user_id` only, and
 only with a secret key. A store that fails
 (Redis down) is logged and skipped: tracking and recommendations go on.
 Updates to one user are serialised within a process only: two processes
@@ -184,7 +185,7 @@ one recommendation id collects the events of many users ("Page caches").
 | `recommend(*, user_id=None, anon_id=None, count=0, placement=None, tags_any=None, tags_all=None, exclude=None, context_item_id=None, discovery=None)` | Returns `Recommendations(recommendation_id, fallback, items)`, each item `Item(item_id, score, slot, metadata, why)`. `metadata` is the dict stored with the item ([Item metadata](../../docs/api.md#item-metadata)), None when it has none; `why` its [reason code](../../docs/api.md#reason-codes). The user's rejected items are added to `exclude` |
 | `popular(*, count=10, tags_any=None, tags_all=None)` | Popular items (`Item`, metadata and `why` included), for pages without a user |
 | `upsert_items(items)` | Creates or replaces items (dicts with the [item fields](../../docs/api.md#put-v1itemsitem_id--secret-key)), 1,000 per request, with retries. Returns how many were stored |
-| `identify(anon_id, user_id)` | At login: merges the visitor's history and shown items into the user's, then deletes the visitor's entry |
+| `identify(anon_id, user_id)` | At login: merges the visitor's history and shown items into the user's, then deletes the visitor's entry. The user's first restore from recapi then leaves that visitor's browsing out, so it doesn't count twice |
 | `delete_user(user_id)` | Erases the user's events in recapi (GDPR) and their state in the store |
 | `flush()` / `close()` | Send queued events now; `close()` also stops the background sender |
 

{recapi-0.4.1 → recapi-0.4.2}/tests/test_client.py

@@ -971,6 +971,63 @@ class Restore(APITest):
         client.recommend(user_id="u/1 é")
         self.assertEqual(self.api.calls[0].raw_path, "/v1/users/u%2F1%20%C3%A9/history")
 
+    def test_the_visitor_of_a_login_is_left_out_of_the_restore_until_it_succeeds(self) -> None:
+        self.api.on(self.HISTORY, Reply(503, {"error": {"code": "unavailable", "message": "x"}}))
+        store = recapi.MemoryStore()
+        client = self.client(store=store)
+        client.track("a", "view", anon_id="v")
+        client.identify("v", "u")
+        with self.assertLogs("recapi", "WARNING"):
+            client.recommend(user_id="u")
+        # The failed restore keeps the visitor, also for another process.
+        self.assertIn('"anon_id":"v"', store.get(client._key("u", None)))
+        self.api.on(self.HISTORY, Reply(200, {"top": [], "recent": [], "as_of": T0}))
+        other = self.client(store=store)
+        other.recommend(user_id="u")
+        other.recommend(user_id="u")
+        history = f"GET {self.HISTORY}?anon_id=v"
+        recommend = "POST /v1/recommendations"
+        self.assertEqual(self.api.lines(), [history, recommend, history, recommend, recommend])
+        self.assertNotIn("anon_id", store.get(client._key("u", None)))
+
+    def test_a_login_after_the_restore_or_an_invalid_stored_visitor_asks_for_no_visitor(
+        self,
+    ) -> None:
+        store = recapi.MemoryStore()
+        client = self.client(store=store)
+        restored = {
+            "history": {
+                "top": [["s", 3.0, T0]],
+                "recent": [["s", T0]],
+                "rejected": [],
+                "lastT": T0,
+            },
+            "shown": [],
+            "restored": True,
+        }
+        store.set(client._key("u", None), json.dumps(restored))
+        client.track("a", "view", anon_id="v")
+        client.identify("v", "u")
+        self.assertNotIn("anon_id", store.get(client._key("u", None)))
+        # Written by a newer version, or by hand: an id the API would refuse is dropped.
+        invalid = {
+            "history": {
+                "top": [["a", 3.0, T0]],
+                "recent": [["a", T0]],
+                "rejected": [],
+                "lastT": T0,
+            },
+            "shown": [],
+            "anon_id": "v\n",
+        }
+        store.set(client._key("w", None), json.dumps(invalid))
+        client.recommend(user_id="u")
+        client.recommend(user_id="w")
+        self.assertEqual(
+            self.api.lines(),
+            ["POST /v1/recommendations", "GET /v1/users/w/history", "POST /v1/recommendations"],
+        )
+
 
 class Identify(APITest):
     def test_a_visitors_history_and_clicks_count_after_login(self) -> None:

{recapi-0.4.1 → recapi-0.4.2}/tests/test_client_vectors.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from unittest import mock
 
 import recapi
-from fakeapi import KEY, T0, APITest, Reply, dead_url, popular, recs
+from fakeapi import KEY, T0, APITest, Reply, dead_url, popular, recs, request_line
 from recapi import client as rc
 
 VECTORS = json.loads(
@@ -226,7 +226,7 @@ class ClientVectors(APITest):
                 with self.assertNoLogs("recapi") if "stored" in case else self.assertLogs("recapi"):
                     client.recommend(user_id="u")
                 client.recommend(user_id="u")
-                self.assertEqual([f"{c.method} {c.path}" for c in self.api.calls], case["requests"])
+                self.assertEqual(self.api.lines(), case["requests"])
                 body = next(c.body for c in self.api.calls if c.path == "/v1/recommendations")
                 sent = {k: body.get(k) for k in ("history", "recent", "exclude")}
                 self.assertEqual(sent, case["sent"])
@@ -257,7 +257,7 @@ class ClientVectors(APITest):
                 start = len(self.api.calls)
                 client.recommend(user_id="u")
                 calls = self.api.calls[start:]
-                self.assertEqual([f"{c.method} {c.path}" for c in calls], case["requests"])
+                self.assertEqual([request_line(c) for c in calls], case["requests"])
                 body = calls[-1].body
                 self.assertEqual(
                     {k: body.get(k) for k in ("history", "recent", "exclude")}, case["sent"]