analytics-platform 0.3.6__tar.gz → 0.3.7__tar.gz

{analytics_platform-0.3.6 → analytics_platform-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: analytics-platform
-Version: 0.3.6
+Version: 0.3.7
 Summary: Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard.
 Author: steviec87
 License-Expression: MIT
@@ -423,7 +423,7 @@ For what only your server knows for sure. Not pageviews: the tracker counts thos
 session = platform.session_id(request)  # the visit, from the X-Analytics-Session header
 
 platform.track("purchase", {"numeric_value": "49.90", "currency": "EUR", "event_uid": f"order-{order.id}"}, session_id=session)
-platform.identify(user.id, session_id=session)
+platform.identify(user.id, session_id=session, traits={"plan": "pro", "seats": 5, "trial": False})  # traits are optional
 platform.lead({"email": "ana@example.com", "name": "Ana", "status": "qualified"})
 ```
 
@@ -433,6 +433,13 @@ answer (up to 5 seconds). What you pass is taken as JSON when you pass it
 a set a list, `NaN` null and anything else its `str()`, so one odd value can't
 fail the batch it is sent in.
 
+**User traits:** `identify()` takes optional `traits`, a dict of name to
+text, number or `True`/`False`. Lists, dicts and other values are left out
+(and `traits` is left off when nothing is left). The collector does the rest:
+names are lowercased with spaces and dashes as `_` (up to 40 letters, digits
+and `_`), text is cut at 200 characters, values that look like an email
+address are dropped, and at most 20 are kept.
+
 **Link to the visit:** send the tracker's session ID with your site's requests:
 
 ```js

{analytics_platform-0.3.6 → analytics_platform-0.3.7}/README.md

@@ -397,7 +397,7 @@ For what only your server knows for sure. Not pageviews: the tracker counts thos
 session = platform.session_id(request)  # the visit, from the X-Analytics-Session header
 
 platform.track("purchase", {"numeric_value": "49.90", "currency": "EUR", "event_uid": f"order-{order.id}"}, session_id=session)
-platform.identify(user.id, session_id=session)
+platform.identify(user.id, session_id=session, traits={"plan": "pro", "seats": 5, "trial": False})  # traits are optional
 platform.lead({"email": "ana@example.com", "name": "Ana", "status": "qualified"})
 ```
 
@@ -407,6 +407,13 @@ answer (up to 5 seconds). What you pass is taken as JSON when you pass it
 a set a list, `NaN` null and anything else its `str()`, so one odd value can't
 fail the batch it is sent in.
 
+**User traits:** `identify()` takes optional `traits`, a dict of name to
+text, number or `True`/`False`. Lists, dicts and other values are left out
+(and `traits` is left off when nothing is left). The collector does the rest:
+names are lowercased with spaces and dashes as `_` (up to 40 letters, digits
+and `_`), text is cut at 200 characters, values that look like an email
+address are dropped, and at most 20 are kept.
+
 **Link to the visit:** send the tracker's session ID with your site's requests:
 
 ```js

{analytics_platform-0.3.6 → analytics_platform-0.3.7}/analytics_platform/__init__.py

@@ -308,9 +308,9 @@ class Platform:
         analytics = self._modules.get("analytics")
         return analytics.track(name, fields, session_id) if analytics else ""
 
-    def identify(self, user_id, session_id=""):
+    def identify(self, user_id, session_id="", traits=None):
         analytics = self._modules.get("analytics")
-        return analytics.identify(user_id, session_id) if analytics else False
+        return analytics.identify(user_id, session_id, traits) if analytics else False
 
     def lead(self, fields, session_id=""):
         analytics = self._modules.get("analytics")

{analytics_platform-0.3.6 → analytics_platform-0.3.7}/analytics_platform/analytics.py

@@ -4,13 +4,15 @@ tracker counts those, and counting them here too would count them twice.
 
 - track(): events, batched to POST /events/server-events in the background.
   Each gets an event_uid, so a retried batch can be told apart from new events.
-- identify(): links the browser's visit to your user ID (/events/identify).
+- identify(): links the browser's visit to your user ID (/events/identify),
+  with optional traits about the user (plan, seats...).
 - lead(): adds or updates a lead (/events/lead).
 identify() and lead() wait for the answer (up to 5 seconds).
 Pass session_id to link an event to the visit: the page sends
 window.analyticsSession.getId() in the X-Analytics-Session header, and the
 framework integrations give you platform.session_id(request).
 """
+import math
 import threading
 import uuid
 from datetime import datetime, timezone
@@ -23,6 +25,16 @@ FLUSH_EVERY = 2
 RETRY = 15
 
 
+def scalar_traits(traits):
+    """The traits that are text, a finite number or True/False; {} when none is."""
+    if not isinstance(traits, dict):
+        return {}
+    return {
+        str(name): value for name, value in traits.items()
+        if isinstance(value, (str, bool, int)) or (isinstance(value, float) and math.isfinite(value))
+    }
+
+
 class Analytics:
     def __init__(self, core, **_):
         self.core = core
@@ -79,11 +91,18 @@ class Analytics:
     def _flush_job(self):
         return FLUSH_EVERY if self.flush() else RETRY
 
-    def identify(self, user_id, session_id=""):
-        """Links the visit to your user ID. True when stored."""
+    def identify(self, user_id, session_id="", traits=None):
+        """Links the visit to your user ID. True when stored. traits: what you
+        know about the user, name -> text, number or True/False
+        ({"plan": "pro", "seats": 5}); anything else is left out, and the
+        collector cleans the names and values."""
         if not user_id or not session_id or not self.core.is_on("analytics"):
             return False
-        res = self.core.send("analytics", "/events/identify", body={"user_id": str(user_id), "session_id": session_id})
+        body = {"user_id": str(user_id), "session_id": session_id}
+        kept = scalar_traits(traits)
+        if kept:
+            body["traits"] = kept
+        res = self.core.send("analytics", "/events/identify", body=body)
         return bool(res and res.ok)
 
     def lead(self, fields, session_id=""):

{analytics_platform-0.3.6 → analytics_platform-0.3.7}/analytics_platform/core.py

@@ -23,7 +23,7 @@ import urllib.error
 import urllib.parse
 import urllib.request
 
-VERSION = "0.3.6"
+VERSION = "0.3.7"
 TIMEOUT = 5
 MIN_SYNC = 30
 RETRY = 60

{analytics_platform-0.3.6 → analytics_platform-0.3.7}/analytics_platform.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: analytics-platform
-Version: 0.3.6
+Version: 0.3.7
 Summary: Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard.
 Author: steviec87
 License-Expression: MIT
@@ -423,7 +423,7 @@ For what only your server knows for sure. Not pageviews: the tracker counts thos
 session = platform.session_id(request)  # the visit, from the X-Analytics-Session header
 
 platform.track("purchase", {"numeric_value": "49.90", "currency": "EUR", "event_uid": f"order-{order.id}"}, session_id=session)
-platform.identify(user.id, session_id=session)
+platform.identify(user.id, session_id=session, traits={"plan": "pro", "seats": 5, "trial": False})  # traits are optional
 platform.lead({"email": "ana@example.com", "name": "Ana", "status": "qualified"})
 ```
 
@@ -433,6 +433,13 @@ answer (up to 5 seconds). What you pass is taken as JSON when you pass it
 a set a list, `NaN` null and anything else its `str()`, so one odd value can't
 fail the batch it is sent in.
 
+**User traits:** `identify()` takes optional `traits`, a dict of name to
+text, number or `True`/`False`. Lists, dicts and other values are left out
+(and `traits` is left off when nothing is left). The collector does the rest:
+names are lowercased with spaces and dashes as `_` (up to 40 letters, digits
+and `_`), text is cut at 200 characters, values that look like an email
+address are dropped, and at most 20 are kept.
+
 **Link to the visit:** send the tracker's session ID with your site's requests:
 
 ```js

{analytics_platform-0.3.6 → analytics_platform-0.3.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "analytics-platform"
-version = "0.3.6"
+version = "0.3.7"
 description = "Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard."
 readme = "README.md"
 requires-python = ">=3.8"

{analytics_platform-0.3.6 → analytics_platform-0.3.7}/tests/test_hardening.py

@@ -394,6 +394,21 @@ class Payloads(unittest.TestCase):
         self.assertEqual(event["at"], "2026-11-03")
         self.assertIsNone(event["bad"])
 
+    def test_identify_passes_scalar_traits_through(self):
+        core = Quiet()
+        sent = []
+        core.send = lambda module, path, body=None, **_: sent.append(body) or mock.Mock(ok=True)
+        analytics = Analytics(core)
+        self.assertTrue(analytics.identify("u1", "s1"))
+        self.assertTrue(analytics.identify("u1", "s1", traits={"plan": "pro", "Seats": 5, "ratio": 0.5, "trial": False,
+                                                               "tags": ["a"], "meta": {"a": 1}, "gone": None, "bad": float("nan")}))
+        self.assertTrue(analytics.identify("u1", "s1", {"tags": ["a"]}))
+        self.assertEqual(sent, [
+            {"user_id": "u1", "session_id": "s1"},
+            {"user_id": "u1", "session_id": "s1", "traits": {"plan": "pro", "Seats": 5, "ratio": 0.5, "trial": False}},
+            {"user_id": "u1", "session_id": "s1"},
+        ])
+
     def test_plain_handles_deep_and_odd_values(self):
         deep = []
         cur = deep