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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: analytics-platform
-Version: 0.3.6
+Version: 0.3.8
 Summary: Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard.
 Author: steviec87
 License-Expression: MIT
@@ -35,7 +35,42 @@ dependencies; Python 3.8 or later.
 pip install analytics-platform
 ```
 
-## Django
+Put your keys in `.env` (site settings has all three, ready to copy), or in
+your host's environment:
+
+```bash
+ANALYTICS_SITE_ID=YOUR_SITE_ID
+ANALYTICS_SITE_SECRET=YOUR_SITE_SECRET
+ANALYTICS_ENDPOINT=https://YOUR_COLLECTOR_URL
+```
+
+The package reads only the `ANALYTICS_*` lines of the `.env` in the folder the
+server starts in (Django: beside `manage.py`), and never writes them into
+`os.environ`, so your own `.env` loading is unaffected. Behind Cloudflare, add
+`ANALYTICS_TRUST_PROXY=cloudflare`; behind Nginx or a load balancer,
+`ANALYTICS_TRUST_PROXY=1`. Several services on one site? Give each
+`ANALYTICS_SERVER_NAME=api` (or `worker`, and so on).
+
+## Flask and FastAPI: one line
+
+```python
+from analytics_platform.start import platform
+```
+
+Put it near the top of the module that makes your app. On the app's first
+request, the package puts itself in front of it: Flask through
+`init_flask(app)`, and FastAPI or any Starlette app through its middleware, as
+the outermost of yours. It works whether the import is above or below
+`app = Flask(...)`. An app that already has the platform by hand gets nothing
+added a second time, and a FastAPI app mounted inside another isn't counted
+twice.
+
+Use the same import wherever you call `platform.track()` and the rest: it's
+one platform for the whole process. It's made on first use, not on import, so
+under Gunicorn or uWSGI with `--preload` its background threads start in each
+worker, not in the master.
+
+## Django: one line in settings
 
 ```python
 # settings.py
@@ -43,36 +78,31 @@ MIDDLEWARE = [
     "analytics_platform.django.PlatformMiddleware",  # first
     # ...
 ]
+```
 
-ANALYTICS_PLATFORM = {
-    "site_id": "YOUR_SITE_ID",
-    "secret": os.environ["ANALYTICS_SITE_SECRET"],  # site settings; keep it on the server
-    "endpoint": "https://YOUR_COLLECTOR_URL",
-    # "trust_proxy": 1,             # behind Nginx or a load balancer
-    # "trust_proxy": "cloudflare",  # every request through Cloudflare
-}
+That's all with the keys in `.env` or the environment. Options in code go in
+`ANALYTICS_PLATFORM`, and win over the environment:
+
+```python
+ANALYTICS_PLATFORM = {"trust_proxy": 1, "errors": {"capture_logging": True}}
 ```
 
 In your code: `from analytics_platform.django import get_platform`. The
 package tells the collector it is a Django site (`analytics-platform-django/…`),
 so attack patterns written for Django reach it.
 
-## FastAPI / Starlette
+## Setting it up in code instead
+
+For options in code with Flask, FastAPI or another app (use this or the line
+above, not both). Any key left out is read from `ANALYTICS_*`:
 
 ```python
 from analytics_platform import create_platform, PlatformMiddleware
 
-platform = create_platform(site_id="YOUR_SITE_ID", secret=os.environ["ANALYTICS_SITE_SECRET"],
-                           endpoint="https://YOUR_COLLECTOR_URL")
-app.add_middleware(PlatformMiddleware, platform=platform)
-```
-
-## Flask
+platform = create_platform(errors={"capture_logging": True})
 
-```python
-platform = create_platform(site_id="YOUR_SITE_ID", secret=os.environ["ANALYTICS_SITE_SECRET"],
-                           endpoint="https://YOUR_COLLECTOR_URL")
-platform.init_flask(app)
+app.add_middleware(PlatformMiddleware, platform=platform)   # FastAPI / Starlette
+platform.init_flask(app)                                    # Flask
 ```
 
 Other WSGI apps: `app = platform.wsgi(app)`; other ASGI apps: `app = platform.asgi(app)`.
@@ -423,7 +453,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 +463,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.8}/README.md

@@ -9,7 +9,42 @@ dependencies; Python 3.8 or later.
 pip install analytics-platform
 ```
 
-## Django
+Put your keys in `.env` (site settings has all three, ready to copy), or in
+your host's environment:
+
+```bash
+ANALYTICS_SITE_ID=YOUR_SITE_ID
+ANALYTICS_SITE_SECRET=YOUR_SITE_SECRET
+ANALYTICS_ENDPOINT=https://YOUR_COLLECTOR_URL
+```
+
+The package reads only the `ANALYTICS_*` lines of the `.env` in the folder the
+server starts in (Django: beside `manage.py`), and never writes them into
+`os.environ`, so your own `.env` loading is unaffected. Behind Cloudflare, add
+`ANALYTICS_TRUST_PROXY=cloudflare`; behind Nginx or a load balancer,
+`ANALYTICS_TRUST_PROXY=1`. Several services on one site? Give each
+`ANALYTICS_SERVER_NAME=api` (or `worker`, and so on).
+
+## Flask and FastAPI: one line
+
+```python
+from analytics_platform.start import platform
+```
+
+Put it near the top of the module that makes your app. On the app's first
+request, the package puts itself in front of it: Flask through
+`init_flask(app)`, and FastAPI or any Starlette app through its middleware, as
+the outermost of yours. It works whether the import is above or below
+`app = Flask(...)`. An app that already has the platform by hand gets nothing
+added a second time, and a FastAPI app mounted inside another isn't counted
+twice.
+
+Use the same import wherever you call `platform.track()` and the rest: it's
+one platform for the whole process. It's made on first use, not on import, so
+under Gunicorn or uWSGI with `--preload` its background threads start in each
+worker, not in the master.
+
+## Django: one line in settings
 
 ```python
 # settings.py
@@ -17,36 +52,31 @@ MIDDLEWARE = [
     "analytics_platform.django.PlatformMiddleware",  # first
     # ...
 ]
+```
 
-ANALYTICS_PLATFORM = {
-    "site_id": "YOUR_SITE_ID",
-    "secret": os.environ["ANALYTICS_SITE_SECRET"],  # site settings; keep it on the server
-    "endpoint": "https://YOUR_COLLECTOR_URL",
-    # "trust_proxy": 1,             # behind Nginx or a load balancer
-    # "trust_proxy": "cloudflare",  # every request through Cloudflare
-}
+That's all with the keys in `.env` or the environment. Options in code go in
+`ANALYTICS_PLATFORM`, and win over the environment:
+
+```python
+ANALYTICS_PLATFORM = {"trust_proxy": 1, "errors": {"capture_logging": True}}
 ```
 
 In your code: `from analytics_platform.django import get_platform`. The
 package tells the collector it is a Django site (`analytics-platform-django/…`),
 so attack patterns written for Django reach it.
 
-## FastAPI / Starlette
+## Setting it up in code instead
+
+For options in code with Flask, FastAPI or another app (use this or the line
+above, not both). Any key left out is read from `ANALYTICS_*`:
 
 ```python
 from analytics_platform import create_platform, PlatformMiddleware
 
-platform = create_platform(site_id="YOUR_SITE_ID", secret=os.environ["ANALYTICS_SITE_SECRET"],
-                           endpoint="https://YOUR_COLLECTOR_URL")
-app.add_middleware(PlatformMiddleware, platform=platform)
-```
-
-## Flask
+platform = create_platform(errors={"capture_logging": True})
 
-```python
-platform = create_platform(site_id="YOUR_SITE_ID", secret=os.environ["ANALYTICS_SITE_SECRET"],
-                           endpoint="https://YOUR_COLLECTOR_URL")
-platform.init_flask(app)
+app.add_middleware(PlatformMiddleware, platform=platform)   # FastAPI / Starlette
+platform.init_flask(app)                                    # Flask
 ```
 
 Other WSGI apps: `app = platform.wsgi(app)`; other ASGI apps: `app = platform.asgi(app)`.
@@ -397,7 +427,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 +437,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.8}/analytics_platform/__init__.py

@@ -20,6 +20,7 @@ import http
 import time
 import weakref
 
+from . import _env
 from .core import Core, EXIT_DEADLINE, SESSION_HEADER, VERSION, begin_exit, header, request_target, within
 from .errors import add_breadcrumb, current_request, current_trail
 from .queries import current_queries
@@ -77,7 +78,8 @@ MODULES = ("proxy", "firewall", "errors", "analytics", "performance", "crawlers"
 
 class Platform:
     """site_id, secret (site settings; keep it on the server), endpoint (the
-    collector's URL); trust_proxy (how to find the visitor's address: None
+    collector's URL), each read from ANALYTICS_SITE_ID, ANALYTICS_SITE_SECRET and
+    ANALYTICS_ENDPOINT when left out; trust_proxy (ANALYTICS_TRUST_PROXY) (how to find the visitor's address: None
     uses the connection's, a number of proxies in X-Forwarded-For,
     "cloudflare"); debug (print send problems); per module True / False / {options}.
     client: the name this package goes by to the collector ("python", or
@@ -86,14 +88,20 @@ class Platform:
     keep Server speed and leave database queries, outgoing calls or job
     queues out of it."""
 
-    def __init__(self, site_id, secret, endpoint, trust_proxy=None, debug=False, firewall=True, errors=True, analytics=True,
+    def __init__(self, site_id=None, secret=None, endpoint=None, trust_proxy=None, debug=False, firewall=True, errors=True, analytics=True,
                  performance=True, crawlers=True, forms=True, headers=True, audit=True, flags=True, maintenance=True,
                  inventory=True,
                  posture=True, resources=True, proxy=True, server_name=None, client="python", queries=True,
                  calls=True, queues=True):
+        # Each of these left out is read from ANALYTICS_* in the environment (_env.py).
+        given = _env.from_environment({"site_id": site_id, "secret": secret, "endpoint": endpoint,
+                                       "trust_proxy": trust_proxy, "server_name": server_name})
+        site_id, secret, endpoint = given["site_id"], given["secret"], given["endpoint"]
+        trust_proxy, server_name = given["trust_proxy"], given["server_name"]
         self.core = Core(site_id, secret, endpoint, debug, server_name=server_name, client=client)
         if not self.core.valid:
-            print("[analytics-platform] site_id, secret and endpoint are required; nothing is sent and every request passes")
+            print("[analytics-platform] site_id, secret and endpoint are required (or ANALYTICS_SITE_ID, ANALYTICS_SITE_SECRET "
+                  "and ANALYTICS_ENDPOINT in the environment); nothing is sent and every request passes")
         settings = {"firewall": firewall, "errors": errors, "analytics": analytics, "performance": performance,
                     "crawlers": crawlers, "forms": forms,
                     "headers": headers, "audit": audit, "flags": flags, "maintenance": maintenance, "inventory": inventory,
@@ -308,9 +316,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")
@@ -577,6 +585,12 @@ class Platform:
 
     def init_flask(self, app):
         """Flask: the firewall in front of the app, and its request errors."""
+        # Once per app, by hand or by analytics_platform.start.
+        extensions = getattr(app, "extensions", None)
+        if isinstance(extensions, dict):
+            if "analytics_platform" in extensions:
+                return app
+            extensions["analytics_platform"] = self
         app.wsgi_app = self.wsgi(app.wsgi_app, timing=False)
         from flask import g, got_request_exception, request
 

analytics_platform-0.3.8/analytics_platform/_env.py

@@ -0,0 +1,71 @@
+"""The options read from ANALYTICS_* when they aren't passed, as the Node and
+Go packages do: ANALYTICS_SITE_ID, ANALYTICS_SITE_SECRET, ANALYTICS_ENDPOINT,
+and optionally ANALYTICS_TRUST_PROXY ("cloudflare" or a number of proxies)
+and ANALYTICS_SERVER_NAME. And the ANALYTICS_* lines of a .env file, for
+analytics_platform.start and Django: read, never written to os.environ, so
+whatever loads the app's own .env files still sets them as it would."""
+import os
+import re
+
+_LINE = re.compile(r"^\s*(?:export\s+)?(ANALYTICS_[A-Z0-9_]+)\s*=\s*(.*)$")
+
+
+def options_from(env):
+    """{site_id, secret, endpoint, trust_proxy, server_name} found in env."""
+    def read(name):
+        value = env.get(name)
+        return value.strip() if isinstance(value, str) and value.strip() else None
+
+    found = {}
+    for option, name in (("site_id", "ANALYTICS_SITE_ID"), ("secret", "ANALYTICS_SITE_SECRET"),
+                         ("endpoint", "ANALYTICS_ENDPOINT"), ("server_name", "ANALYTICS_SERVER_NAME")):
+        if read(name):
+            found[option] = read(name)
+    if "endpoint" not in found and read("ANALYTICS_FIREWALL_ENDPOINT"):
+        found["endpoint"] = read("ANALYTICS_FIREWALL_ENDPOINT")
+    trust = read("ANALYTICS_TRUST_PROXY")
+    if trust:
+        if trust.lower() == "cloudflare":
+            found["trust_proxy"] = "cloudflare"
+        elif trust.lower() == "true":
+            found["trust_proxy"] = 1
+        elif trust.isdigit() and int(trust) > 0:
+            found["trust_proxy"] = int(trust)
+    return found
+
+
+def read_dotenv(path):
+    """The ANALYTICS_* lines of a .env file as {name: value}; {} without one.
+    Not a dotenv: no expansion, and every other line is ignored."""
+    try:
+        with open(path, encoding="utf-8") as handle:
+            text = handle.read()
+    except (OSError, UnicodeDecodeError):
+        return {}
+    found = {}
+    for line in text.splitlines():
+        match = _LINE.match(line)
+        if not match:
+            continue
+        value = match.group(2).strip()
+        quote = value[:1]
+        if quote in ("'", '"') and value.find(quote, 1) > 0:
+            value = value[1:value.find(quote, 1)]
+        else:
+            value = re.sub(r"\s+#.*$", "", value)
+        found[match.group(1)] = value
+    return found
+
+
+def from_environment(options, dotenv=None):
+    """options with what's missing filled from os.environ, then (when given)
+    from a .env file's ANALYTICS_* lines."""
+    filled = dict(options)
+    sources = [options_from(os.environ)]
+    if dotenv:
+        sources.append(options_from(read_dotenv(dotenv)))
+    for source in sources:
+        for key, value in source.items():
+            if filled.get(key) is None:
+                filled[key] = value
+    return filled

{analytics_platform-0.3.6 → analytics_platform-0.3.8}/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.8}/analytics_platform/core.py

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

{analytics_platform-0.3.6 → analytics_platform-0.3.8}/analytics_platform/django.py

@@ -1,11 +1,12 @@
-"""Django: add the middleware first in MIDDLEWARE and the options to settings.
+"""Django: add the middleware first in MIDDLEWARE. That's all when the keys
+are in the environment or in the project's .env (beside manage.py):
+ANALYTICS_SITE_ID, ANALYTICS_SITE_SECRET and ANALYTICS_ENDPOINT.
 
     MIDDLEWARE = ["analytics_platform.django.PlatformMiddleware", ...]
-    ANALYTICS_PLATFORM = {
-        "site_id": "...",
-        "secret": os.environ["ANALYTICS_SITE_SECRET"],
-        "endpoint": "https://...",
-    }
+
+Options in code go in settings, and win over the environment:
+
+    ANALYTICS_PLATFORM = {"trust_proxy": 1, "errors": {"capture_logging": True}}
 
 In your code, get_platform() is the same platform: get_platform().track(...).
 The visitor's address is REMOTE_ADDR unless you set trust_proxy. The package
@@ -13,11 +14,13 @@ says it is Django (analytics-platform-django/<version>), so request rules
 aimed at Django sites reach it. Every connection's queries are timed for
 Server speed, under the request that ran them ("queries": False leaves them out).
 """
+import os
 import time
 
 from django.conf import settings
 from django.http import HttpResponse
 
+from . import _env
 from . import SESSION_HEADER, Platform, _inflight_end, _inflight_start, _queries_end, _queries_start
 from .errors import current_request, current_trail
 
@@ -27,8 +30,13 @@ _platform = None
 def get_platform():
     global _platform
     if _platform is None:
+        # Settings first, then ANALYTICS_* in the environment, then the
+        # ANALYTICS_* lines of the project's .env (beside manage.py), which is
+        # read, never loaded into the environment.
         options = dict(getattr(settings, "ANALYTICS_PLATFORM", {}))
         options.setdefault("client", "django")
+        base = getattr(settings, "BASE_DIR", None) or os.getcwd()
+        options = _env.from_environment(options, os.path.join(str(base), ".env"))
         _platform = Platform(**options)
         _connect_login_failed()
         _watch_queries(_platform)

analytics_platform-0.3.8/analytics_platform/start.py

@@ -0,0 +1,118 @@
+"""The one-line setup. Near the top of the module that makes your app:
+
+    from analytics_platform.start import platform
+
+It reads ANALYTICS_SITE_ID, ANALYTICS_SITE_SECRET and ANALYTICS_ENDPOINT from
+the environment, or else from the ANALYTICS_* lines of the .env in the folder
+the server starts in (read, never written to os.environ).
+
+Flask and FastAPI (any Starlette app): that's all. On an app's first request
+it puts itself in front, as platform.init_flask(app) and
+app.add_middleware(PlatformMiddleware, platform=platform) do by hand, so it
+doesn't matter whether this import comes before or after the app is made. An
+app that already has either by hand gets nothing added a second time, and a
+Starlette app mounted inside another isn't counted twice.
+
+Django: add "analytics_platform.django.PlatformMiddleware" first in
+MIDDLEWARE instead, and use get_platform() from there.
+
+The platform is made on first use (the first request, or the first
+platform.track()), not on import: under Gunicorn or uWSGI with the app loaded
+before the workers fork, its background threads then start in each worker,
+not in the master. Use the same import wherever you call platform.track() and
+the rest: it's one platform for the process.
+"""
+import os
+import threading
+
+from . import Platform, PlatformMiddleware, _env
+
+_lock = threading.Lock()
+_made = None
+
+
+def _platform():
+    global _made
+    if _made is None:
+        with _lock:
+            if _made is None:
+                _made = Platform(**_env.from_environment({}, os.path.join(os.getcwd(), ".env")))
+    return _made
+
+
+class _Platform:
+    """Stands for the platform until its first use, then hands every
+    attribute to it."""
+
+    def __getattr__(self, name):
+        return getattr(_platform(), name)
+
+    def __repr__(self):
+        return "<analytics_platform.start platform%s>" % ("" if _made is not None else " (not made yet)")
+
+
+platform = _Platform()
+
+_MARK = "_analytics_platform_started"
+
+
+def _hook_flask():
+    try:
+        from flask import Flask
+    except Exception:
+        return
+    if getattr(Flask.__call__, _MARK, False):
+        return
+    original = Flask.__call__
+    hook_lock = threading.Lock()
+
+    # The first request's own thread hooks the app in before Flask marks it
+    # as started (after that it refuses new before_request functions); other
+    # threads wait for it, so none gets past without it.
+    def __call__(self, environ, start_response):
+        if not self.__dict__.get(_MARK):
+            with hook_lock:
+                if not self.__dict__.get(_MARK):
+                    try:
+                        _platform().init_flask(self)
+                    except Exception as error:
+                        print("[analytics-platform] couldn't add itself to this Flask app; call platform.init_flask(app) by hand: %s" % error)
+                    self.__dict__[_MARK] = True
+        return original(self, environ, start_response)
+
+    setattr(__call__, _MARK, True)
+    Flask.__call__ = __call__
+
+
+def _hook_starlette():
+    try:
+        from starlette.applications import Starlette
+        from starlette.middleware import Middleware
+    except Exception:
+        return
+    if getattr(Starlette.__call__, _MARK, False):
+        return
+    original = Starlette.__call__
+
+    # Before the app builds its middleware stack, on its first call. Only the
+    # outermost app: a mounted one is called with scope["app"] already set by
+    # the app it's mounted in. Outermost of your own middleware, as
+    # add_middleware() called last puts it.
+    async def __call__(self, scope, receive, send):
+        if not self.__dict__.get(_MARK):
+            self.__dict__[_MARK] = True
+            outermost = "app" not in scope
+            by_hand = any(getattr(m, "cls", None) is PlatformMiddleware for m in getattr(self, "user_middleware", []))
+            if outermost and not by_hand and getattr(self, "middleware_stack", None) is None:
+                self.user_middleware.insert(0, Middleware(PlatformMiddleware, platform=platform))
+        await original(self, scope, receive, send)
+
+    setattr(__call__, _MARK, True)
+    Starlette.__call__ = __call__
+
+
+# Each only when its framework is installed.
+_hook_flask()
+_hook_starlette()
+
+__all__ = ["platform"]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: analytics-platform
-Version: 0.3.6
+Version: 0.3.8
 Summary: Firewall, error monitoring and server analytics for your Python server, run from your analytics dashboard.
 Author: steviec87
 License-Expression: MIT
@@ -35,7 +35,42 @@ dependencies; Python 3.8 or later.
 pip install analytics-platform
 ```
 
-## Django
+Put your keys in `.env` (site settings has all three, ready to copy), or in
+your host's environment:
+
+```bash
+ANALYTICS_SITE_ID=YOUR_SITE_ID
+ANALYTICS_SITE_SECRET=YOUR_SITE_SECRET
+ANALYTICS_ENDPOINT=https://YOUR_COLLECTOR_URL
+```
+
+The package reads only the `ANALYTICS_*` lines of the `.env` in the folder the
+server starts in (Django: beside `manage.py`), and never writes them into
+`os.environ`, so your own `.env` loading is unaffected. Behind Cloudflare, add
+`ANALYTICS_TRUST_PROXY=cloudflare`; behind Nginx or a load balancer,
+`ANALYTICS_TRUST_PROXY=1`. Several services on one site? Give each
+`ANALYTICS_SERVER_NAME=api` (or `worker`, and so on).
+
+## Flask and FastAPI: one line
+
+```python
+from analytics_platform.start import platform
+```
+
+Put it near the top of the module that makes your app. On the app's first
+request, the package puts itself in front of it: Flask through
+`init_flask(app)`, and FastAPI or any Starlette app through its middleware, as
+the outermost of yours. It works whether the import is above or below
+`app = Flask(...)`. An app that already has the platform by hand gets nothing
+added a second time, and a FastAPI app mounted inside another isn't counted
+twice.
+
+Use the same import wherever you call `platform.track()` and the rest: it's
+one platform for the whole process. It's made on first use, not on import, so
+under Gunicorn or uWSGI with `--preload` its background threads start in each
+worker, not in the master.
+
+## Django: one line in settings
 
 ```python
 # settings.py
@@ -43,36 +78,31 @@ MIDDLEWARE = [
     "analytics_platform.django.PlatformMiddleware",  # first
     # ...
 ]
+```
 
-ANALYTICS_PLATFORM = {
-    "site_id": "YOUR_SITE_ID",
-    "secret": os.environ["ANALYTICS_SITE_SECRET"],  # site settings; keep it on the server
-    "endpoint": "https://YOUR_COLLECTOR_URL",
-    # "trust_proxy": 1,             # behind Nginx or a load balancer
-    # "trust_proxy": "cloudflare",  # every request through Cloudflare
-}
+That's all with the keys in `.env` or the environment. Options in code go in
+`ANALYTICS_PLATFORM`, and win over the environment:
+
+```python
+ANALYTICS_PLATFORM = {"trust_proxy": 1, "errors": {"capture_logging": True}}
 ```
 
 In your code: `from analytics_platform.django import get_platform`. The
 package tells the collector it is a Django site (`analytics-platform-django/…`),
 so attack patterns written for Django reach it.
 
-## FastAPI / Starlette
+## Setting it up in code instead
+
+For options in code with Flask, FastAPI or another app (use this or the line
+above, not both). Any key left out is read from `ANALYTICS_*`:
 
 ```python
 from analytics_platform import create_platform, PlatformMiddleware
 
-platform = create_platform(site_id="YOUR_SITE_ID", secret=os.environ["ANALYTICS_SITE_SECRET"],
-                           endpoint="https://YOUR_COLLECTOR_URL")
-app.add_middleware(PlatformMiddleware, platform=platform)
-```
-
-## Flask
+platform = create_platform(errors={"capture_logging": True})
 
-```python
-platform = create_platform(site_id="YOUR_SITE_ID", secret=os.environ["ANALYTICS_SITE_SECRET"],
-                           endpoint="https://YOUR_COLLECTOR_URL")
-platform.init_flask(app)
+app.add_middleware(PlatformMiddleware, platform=platform)   # FastAPI / Starlette
+platform.init_flask(app)                                    # Flask
 ```
 
 Other WSGI apps: `app = platform.wsgi(app)`; other ASGI apps: `app = platform.asgi(app)`.
@@ -423,7 +453,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 +463,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.8}/analytics_platform.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 analytics_platform/__init__.py
+analytics_platform/_env.py
 analytics_platform/analytics.py
 analytics_platform/audit.py
 analytics_platform/calls.py
@@ -25,6 +26,7 @@ analytics_platform/queues.py
 analytics_platform/request_rules.py
 analytics_platform/resources.py
 analytics_platform/rq.py
+analytics_platform/start.py
 analytics_platform.egg-info/PKG-INFO
 analytics_platform.egg-info/SOURCES.txt
 analytics_platform.egg-info/dependency_links.txt
@@ -45,4 +47,5 @@ tests/test_redis.py
 tests/test_request_rules.py
 tests/test_resources.py
 tests/test_rq_dramatiq.py
+tests/test_start.py
 tests/test_static_late.py

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "analytics-platform"
-version = "0.3.6"
+version = "0.3.8"
 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.8}/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

analytics_platform-0.3.8/tests/test_start.py

@@ -0,0 +1,156 @@
+"""The one-line setup: keys from ANALYTICS_* or a .env file (never written to
+os.environ), and analytics_platform.start putting itself in front of Flask
+and FastAPI/Starlette apps on their first request, and Django's settings
+block becoming optional. The framework tests skip where the framework isn't
+installed; run them where Flask, FastAPI (with httpx) and Django are."""
+import os
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from analytics_platform import Platform, PlatformMiddleware, _env  # noqa: E402
+
+SITE = "a" * 24
+KEYS = {"ANALYTICS_SITE_ID": SITE, "ANALYTICS_SITE_SECRET": "s3cret", "ANALYTICS_ENDPOINT": "http://127.0.0.1:9"}
+OFF = {name: False for name in ("firewall", "errors", "analytics", "performance", "crawlers", "forms", "headers", "audit",
+                                "flags", "maintenance", "inventory", "posture", "resources", "proxy")}
+
+
+def installed(name):
+    try:
+        __import__(name)
+        return True
+    except Exception:
+        return False
+
+
+class EnvTest(unittest.TestCase):
+    def test_options_from_the_environment(self):
+        found = _env.options_from({**KEYS, "ANALYTICS_TRUST_PROXY": "2", "ANALYTICS_SERVER_NAME": "api"})
+        self.assertEqual(found, {"site_id": SITE, "secret": "s3cret", "endpoint": "http://127.0.0.1:9",
+                                 "server_name": "api", "trust_proxy": 2})
+        self.assertEqual(_env.options_from({"ANALYTICS_TRUST_PROXY": "Cloudflare"})["trust_proxy"], "cloudflare")
+        self.assertEqual(_env.options_from({"ANALYTICS_FIREWALL_ENDPOINT": "https://x"})["endpoint"], "https://x")
+        self.assertEqual(_env.options_from({"ANALYTICS_TRUST_PROXY": "nonsense", "ANALYTICS_SITE_ID": "  "}), {})
+
+    def test_dotenv_lines_are_read_and_never_loaded(self):
+        with tempfile.TemporaryDirectory() as folder:
+            path = os.path.join(folder, ".env")
+            with open(path, "w") as handle:
+                handle.write('DATABASE_URL=x\nANALYTICS_SITE_ID="%s"\nexport ANALYTICS_SITE_SECRET=from-file # note\n' % SITE)
+            with mock.patch.dict(os.environ, {"ANALYTICS_ENDPOINT": "http://127.0.0.1:9"}, clear=True):
+                filled = _env.from_environment({"secret": None}, path)
+                self.assertNotIn("ANALYTICS_SITE_SECRET", os.environ)
+                self.assertNotIn("DATABASE_URL", os.environ)
+        self.assertEqual((filled["site_id"], filled["secret"], filled["endpoint"]), (SITE, "from-file", "http://127.0.0.1:9"))
+
+    def test_the_environment_wins_over_the_file_and_given_options_over_both(self):
+        with tempfile.TemporaryDirectory() as folder:
+            path = os.path.join(folder, ".env")
+            with open(path, "w") as handle:
+                handle.write("ANALYTICS_SITE_SECRET=file\nANALYTICS_SERVER_NAME=file\n")
+            with mock.patch.dict(os.environ, {"ANALYTICS_SITE_SECRET": "env"}, clear=True):
+                filled = _env.from_environment({"server_name": "given"}, path)
+        self.assertEqual((filled["secret"], filled["server_name"]), ("env", "given"))
+
+    def test_platform_with_no_keys_reads_them_from_the_environment(self):
+        with mock.patch.dict(os.environ, KEYS, clear=True):
+            platform = Platform(**OFF)
+        self.assertTrue(platform.core.valid)
+        with mock.patch.dict(os.environ, {}, clear=True), mock.patch("builtins.print") as printed:
+            self.assertFalse(Platform(**OFF).core.valid)
+        self.assertIn("ANALYTICS_SITE_SECRET", printed.call_args[0][0])
+
+
+def started():
+    """analytics_platform.start, with a fresh platform made from KEYS."""
+    from analytics_platform import start
+    start._made = None
+    return start
+
+
+@unittest.skipUnless(installed("flask"), "Flask isn't installed")
+class FlaskTest(unittest.TestCase):
+    def test_hooks_itself_in_on_the_first_request_wherever_the_import_is(self):
+        from flask import Flask
+        app = Flask("before")  # made before the import
+        app.get("/")(lambda: "ok")
+        with mock.patch.dict(os.environ, KEYS):
+            start = started()
+            response = app.test_client().get("/")
+        self.assertEqual(response.status_code, 200)
+        self.assertIs(app.extensions["analytics_platform"], start._made)
+        wrapped = app.wsgi_app
+        app.test_client().get("/")
+        self.assertIs(app.wsgi_app, wrapped, "wrapped once, not on every request")
+
+    def test_an_app_set_up_by_hand_is_left_alone(self):
+        from flask import Flask
+        with mock.patch.dict(os.environ, KEYS):
+            started()
+            own = Platform(**OFF)
+            app = Flask("by_hand")
+            app.get("/")(lambda: "ok")
+            own.init_flask(app)
+            wrapped = app.wsgi_app
+            self.assertEqual(app.test_client().get("/").status_code, 200)
+        self.assertIs(app.extensions["analytics_platform"], own)
+        self.assertIs(app.wsgi_app, wrapped)
+
+
+@unittest.skipUnless(installed("fastapi") and installed("httpx"), "FastAPI or httpx isn't installed")
+class FastAPITest(unittest.TestCase):
+    def test_outermost_of_your_middleware_and_not_in_a_mounted_app(self):
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+        from starlette.middleware.gzip import GZipMiddleware
+        with mock.patch.dict(os.environ, KEYS):
+            started()
+            app = FastAPI()
+            app.add_middleware(GZipMiddleware)
+            sub = FastAPI()
+            sub.get("/x")(lambda: {"ok": True})
+            app.mount("/sub", sub)
+            app.get("/")(lambda: {"ok": True})
+            client = TestClient(app)
+            self.assertEqual(client.get("/").status_code, 200)
+            self.assertEqual(client.get("/sub/x").status_code, 200)
+        self.assertEqual([m.cls for m in app.user_middleware], [PlatformMiddleware, GZipMiddleware])
+        self.assertEqual([m.cls for m in sub.user_middleware], [], "a mounted app isn't counted twice")
+
+    def test_an_app_with_it_by_hand_gets_no_second_one(self):
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+        with mock.patch.dict(os.environ, KEYS):
+            started()
+            app = FastAPI()
+            app.add_middleware(PlatformMiddleware, platform=Platform(**OFF))
+            app.get("/")(lambda: {"ok": True})
+            self.assertEqual(TestClient(app).get("/").status_code, 200)
+        self.assertEqual([m.cls for m in app.user_middleware], [PlatformMiddleware])
+
+
+@unittest.skipUnless(installed("django"), "Django isn't installed")
+class DjangoTest(unittest.TestCase):
+    def test_no_settings_block_the_keys_from_the_projects_dotenv(self):
+        from django.conf import settings
+        with tempfile.TemporaryDirectory() as folder:
+            with open(os.path.join(folder, ".env"), "w") as handle:
+                handle.write("\n".join("%s=%s" % item for item in KEYS.items()))
+            if not settings.configured:
+                settings.configure(BASE_DIR=folder)
+            else:
+                settings.BASE_DIR = folder
+            from analytics_platform import django as integration
+            integration._platform = None
+            with mock.patch.dict(os.environ, {}, clear=True):
+                platform = integration.get_platform()
+                self.assertNotIn("ANALYTICS_SITE_SECRET", os.environ)
+        self.assertTrue(platform.core.valid)
+
+
+if __name__ == "__main__":
+    unittest.main()