azfive-capture 0.1.0__py3-none-any.whl

azfive_capture/__init__.py

@@ -0,0 +1,11 @@
+"""azfive-capture — AzFive product analytics for Python servers.
+
+Events, identity, super properties and feature flags/experiments against a
+AzFive deployment.  See ``sdk-spec/SPEC.md`` in the AzFive repo for the
+cross-SDK behavioral contract.
+"""
+
+from .client import LIB_NAME, LIB_VERSION, Client, create_client
+from .flags import FlagValue
+
+__all__ = ["Client", "create_client", "FlagValue", "LIB_NAME", "LIB_VERSION"]

azfive_capture/client.py

@@ -0,0 +1,324 @@
+"""AzFive capture client for Python servers.
+
+Port of ``@azfive/capture`` (see ``sdk-spec/SPEC.md``): same event envelope,
+merge order, batching semantics and flag exposure rules, adapted to a server
+runtime — in-memory identity, no session, background flush thread, and flag
+evaluation per ``distinct_id`` through ``/v1/decide`` with a secret key.
+
+    from azfive_capture import Client
+
+    azfive = Client("azfive_…", host="https://analytics.example.com")
+    azfive.capture("invoice_paid", {"amount": 99}, distinct_id="user-42")
+    variant = azfive.get_flag("user-42", "exp-checkout")
+    azfive.flush()
+"""
+
+from __future__ import annotations
+
+import atexit
+import platform
+import threading
+from datetime import datetime, timezone
+from typing import Any
+
+from . import transport
+from .flags import FlagsManager, FlagValue
+
+LIB_VERSION = "0.1.0"
+LIB_NAME = "azfive-python"
+
+DEFAULT_BATCH_SIZE = 10
+DEFAULT_FLUSH_INTERVAL_S = 5.0
+DEFAULT_MAX_QUEUE_SIZE = 1000
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _static_props() -> dict:
+    return {
+        "$os": platform.system() or "Unknown",
+        "$os_version": platform.release() or "",
+        "$device_type": "Server",
+    }
+
+
+def merge_properties(
+    static: dict, session: dict, super_props: dict, event: dict, reserved: dict
+) -> dict:
+    """The spec'd merge order: static < session < super < event < reserved.
+    (Server SDKs have no dynamic layer; session is empty for them.)"""
+    return {**static, **session, **super_props, **event, **reserved}
+
+
+class People:
+    """``people.set`` / ``people.set_once`` — person-property events."""
+
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    def set(self, properties: dict, distinct_id: str | None = None) -> None:
+        self._client._track("az.set", {}, set_props=properties, distinct_id=distinct_id)
+
+    def set_once(self, properties: dict, distinct_id: str | None = None) -> None:
+        self._client._track("az.set_once", {}, set_once_props=properties, distinct_id=distinct_id)
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        host: str,
+        project: str = "default",
+        batch_size: int = DEFAULT_BATCH_SIZE,
+        flush_interval_s: float = DEFAULT_FLUSH_INTERVAL_S,
+        max_queue_size: int = DEFAULT_MAX_QUEUE_SIZE,
+        gzip: bool = False,
+        opt_out: bool = False,
+        disable_decide: bool = False,
+        extra_static_props: dict | None = None,
+        start_flush_thread: bool = True,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        if not host:
+            raise ValueError("host is required")
+        self._api_key = api_key
+        self._host = host.rstrip("/")
+        self._project = project
+        self._batch_size = batch_size
+        self._flush_interval_s = flush_interval_s
+        self._max_queue_size = max_queue_size
+        self._gzip = gzip
+        self._opted_out = opt_out
+
+        self._distinct_id = transport.uuid4()
+        self._device_id = transport.uuid4()
+        self._identified = False
+        self._super_props: dict = {}
+        self._static = {**_static_props(), **(extra_static_props or {})}
+
+        self._queue: list[dict] = []
+        self._lock = threading.Lock()
+        self._closed = False
+
+        self.people = People(self)
+        self._flags: FlagsManager | None = None
+        if not disable_decide:
+            self._flags = FlagsManager(
+                host=self._host,
+                api_key=api_key,
+                project=project,
+                capture=self._capture_for_flags,
+            )
+
+        self._flush_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        if start_flush_thread:
+            self._thread = threading.Thread(
+                target=self._flush_loop, name="azfive-capture-flush", daemon=True
+            )
+            self._thread.start()
+        atexit.register(self.close)
+
+    # ── Identity ──────────────────────────────────────────────────────────────
+
+    def get_distinct_id(self) -> str:
+        return self._distinct_id
+
+    def get_session_id(self) -> str:
+        return ""  # servers have no session
+
+    def identify(
+        self, distinct_id: str, set: dict | None = None, set_once: dict | None = None
+    ) -> None:
+        did = str(distinct_id)
+        if self._identified and self._distinct_id == did:
+            if set or set_once:
+                self._track("az.set", {}, set_props=set, set_once_props=set_once)
+            return
+        prev = self._distinct_id
+        self._distinct_id = did
+        self._identified = True
+        self._track(
+            "az.identify",
+            {"$anon_distinct_id": prev},
+            set_props=set,
+            set_once_props=set_once,
+            distinct_id=did,
+        )
+        if self._flags:
+            self._flags.reload_flags(did)
+
+    def alias(self, alias: str) -> None:
+        self._track("az.alias", {"alias": str(alias)})
+
+    def reset(self, reset_device_id: bool = False) -> None:
+        self._identified = False
+        self._distinct_id = transport.uuid4()
+        self._super_props = {}
+        if reset_device_id:
+            self._device_id = transport.uuid4()
+        # opt-out is intentionally preserved across reset()
+
+    # ── Super properties ──────────────────────────────────────────────────────
+
+    def register(self, props: dict) -> None:
+        self._super_props = {**self._super_props, **props}
+
+    def register_once(self, props: dict) -> None:
+        self._super_props = {**props, **self._super_props}  # existing values win
+
+    def unregister(self, key: str) -> None:
+        self._super_props.pop(key, None)
+
+    # ── Opt-out ───────────────────────────────────────────────────────────────
+
+    def opt_in_capturing(self) -> None:
+        self._opted_out = False
+
+    def opt_out_capturing(self) -> None:
+        self._opted_out = True
+
+    def has_opted_out_capturing(self) -> bool:
+        return self._opted_out
+
+    # ── Capture ───────────────────────────────────────────────────────────────
+
+    def capture(
+        self, event: str, properties: dict | None = None, *, distinct_id: str | None = None
+    ) -> None:
+        self._track(event, properties or {}, distinct_id=distinct_id)
+
+    def _capture_for_flags(
+        self, event: str, properties: dict, *, distinct_id: str
+    ) -> None:
+        self._track(event, properties, distinct_id=distinct_id)
+
+    def _track(
+        self,
+        event: str,
+        properties: dict,
+        *,
+        set_props: dict | None = None,
+        set_once_props: dict | None = None,
+        distinct_id: str | None = None,
+    ) -> None:
+        if self._opted_out:
+            return
+        props = dict(properties)
+        did = distinct_id or self._distinct_id
+        if props.get("distinct_id") is not None:
+            did = str(props.pop("distinct_id"))
+        evt: dict = {
+            "event": event,
+            "distinct_id": did,
+            "timestamp": _now_iso(),
+            "uuid": transport.uuid4(),
+            "properties": merge_properties(
+                self._static,
+                {},
+                self._super_props,
+                props,
+                {"$lib": LIB_NAME, "$lib_version": LIB_VERSION, "$device_id": self._device_id},
+            ),
+        }
+        if set_props:
+            evt["$set"] = set_props
+        if set_once_props:
+            evt["$set_once"] = set_once_props
+        self._enqueue(evt)
+
+    def _enqueue(self, evt: dict) -> None:
+        with self._lock:
+            self._queue.append(evt)
+            if len(self._queue) > self._max_queue_size:
+                del self._queue[: len(self._queue) - self._max_queue_size]
+            trigger = len(self._queue) >= self._batch_size
+        if trigger:
+            self._request_flush()
+
+    def _request_flush(self) -> None:
+        # With the background thread running, hand off (capture() never blocks
+        # on network I/O); without it (tests, single-shot scripts) flush inline.
+        if self._thread is not None:
+            self._flush_event.set()
+        else:
+            self.flush()
+
+    # ── Feature flags ─────────────────────────────────────────────────────────
+
+    def get_flag(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> FlagValue | None:
+        if self._flags is None:
+            return None
+        return self._flags.get_flag(distinct_id, key, person_properties)
+
+    def is_flag_enabled(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> bool:
+        if self._flags is None:
+            return False
+        return self._flags.is_flag_enabled(distinct_id, key, person_properties)
+
+    def get_flag_payload(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> Any:
+        if self._flags is None:
+            return None
+        return self._flags.get_flag_payload(distinct_id, key, person_properties)
+
+    def reload_flags(self, distinct_id: str) -> None:
+        if self._flags is not None:
+            self._flags.reload_flags(distinct_id)
+
+    # ── Delivery ──────────────────────────────────────────────────────────────
+
+    def _send(self, batch: list[dict]) -> bool:
+        return transport.send_batch(
+            batch,
+            host=self._host,
+            api_key=self._api_key,
+            project=self._project,
+            gzip=self._gzip,
+        )
+
+    def flush(self) -> None:
+        with self._lock:
+            if not self._queue:
+                return
+            batch = self._queue
+            self._queue = []
+        if not self._send(batch):
+            with self._lock:
+                # Re-queue at the FRONT, bounded keeping the newest events.
+                self._queue = (batch + self._queue)[-self._max_queue_size:]
+
+    def _flush_loop(self) -> None:
+        while not self._closed:
+            self._flush_event.wait(timeout=self._flush_interval_s)
+            self._flush_event.clear()
+            if self._closed:
+                return
+            try:
+                self.flush()
+            except Exception:  # never kill the flush thread
+                pass
+
+    def close(self) -> None:
+        """Flush pending events and stop the background thread. Idempotent."""
+        if self._closed:
+            return
+        self._closed = True
+        self._flush_event.set()
+        try:
+            self.flush()
+        except Exception:
+            pass
+
+
+def create_client(api_key: str, **config: Any) -> Client:
+    return Client(api_key, **config)

azfive_capture/flags.py

@@ -0,0 +1,132 @@
+"""Server-side feature flags: /v1/decide per distinct_id with a TTL cache and
+automatic, deduped ``az.flag_called`` exposure events.
+
+Servers have no session, so exposures dedup on ``(distinct_id, flag, value)``
+in a bounded LRU — the experiment pipeline only counts a person's FIRST
+exposure anyway, so the LRU merely caps event noise, not correctness.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Callable
+
+from . import transport
+
+FlagValue = bool | str
+
+DECIDE_CACHE_TTL_S = 60.0
+DECIDE_CACHE_MAX = 10_000
+EXPOSURE_LRU_MAX = 50_000
+
+
+class _LRU:
+    """Tiny thread-safe bounded LRU used for decide caching + exposure dedup."""
+
+    def __init__(self, max_entries: int) -> None:
+        self._data: OrderedDict[str, Any] = OrderedDict()
+        self._max = max_entries
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Any | None:
+        with self._lock:
+            if key not in self._data:
+                return None
+            self._data.move_to_end(key)
+            return self._data[key]
+
+    def put(self, key: str, value: Any) -> None:
+        with self._lock:
+            self._data[key] = value
+            self._data.move_to_end(key)
+            while len(self._data) > self._max:
+                self._data.popitem(last=False)
+
+    def contains(self, key: str) -> bool:
+        return self.get(key) is not None
+
+    def remove(self, key: str) -> None:
+        with self._lock:
+            self._data.pop(key, None)
+
+
+class FlagsManager:
+    def __init__(
+        self,
+        *,
+        host: str,
+        api_key: str,
+        project: str,
+        capture: Callable[..., None],
+        cache_ttl_s: float = DECIDE_CACHE_TTL_S,
+        now: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._host = host
+        self._api_key = api_key
+        self._project = project
+        self._capture = capture
+        self._ttl = cache_ttl_s
+        self._now = now
+        self._decide_cache = _LRU(DECIDE_CACHE_MAX)
+        self._exposures = _LRU(EXPOSURE_LRU_MAX)
+
+    # ── decide ────────────────────────────────────────────────────────────────
+
+    def _decide(self, distinct_id: str, person_properties: dict | None) -> dict:
+        # person_properties bypass the cache only when they change the request —
+        # cache key folds them in so overlays don't leak between calls.
+        cache_key = distinct_id if not person_properties else (
+            distinct_id + "|" + repr(sorted(person_properties.items()))
+        )
+        cached = self._decide_cache.get(cache_key)
+        if cached is not None and self._now() - cached["at"] < self._ttl:
+            return cached["doc"]
+        payload: dict = {"distinct_id": distinct_id, "project": self._project}
+        if person_properties:
+            payload["person_properties"] = person_properties
+        doc = transport.post_json(f"{self._host}/api/v1/decide", self._api_key, payload)
+        if doc is None:
+            # Network failure: serve stale if we have it, else empty. Never raise.
+            return cached["doc"] if cached is not None else {"flags": {}, "flagPayloads": {}}
+        self._decide_cache.put(cache_key, {"at": self._now(), "doc": doc})
+        return doc
+
+    def reload_flags(self, distinct_id: str) -> None:
+        """Bust one distinct_id's cached decide response."""
+        self._decide_cache.remove(distinct_id)
+
+    # ── getters ───────────────────────────────────────────────────────────────
+
+    def get_flag(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> FlagValue | None:
+        doc = self._decide(distinct_id, person_properties)
+        value = (doc.get("flags") or {}).get(key)
+        self._report_exposure(distinct_id, key, value)
+        return value
+
+    def is_flag_enabled(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> bool:
+        return bool(self.get_flag(distinct_id, key, person_properties))
+
+    def get_flag_payload(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> Any:
+        # No exposure — payload reads follow a get_flag/is_flag_enabled call.
+        doc = self._decide(distinct_id, person_properties)
+        return (doc.get("flagPayloads") or {}).get(key)
+
+    def _report_exposure(self, distinct_id: str, key: str, value: FlagValue | None) -> None:
+        reported = False if value is None else value
+        dedupe = f"{distinct_id}:{key}:{reported!r}"
+        if self._exposures.contains(dedupe):
+            return
+        self._exposures.put(dedupe, True)
+        self._capture(
+            "az.flag_called",
+            {"$feature_flag": key, "$feature_flag_response": reported},
+            distinct_id=distinct_id,
+        )

azfive_capture/transport.py

@@ -0,0 +1,78 @@
+"""HTTP transport: batch POST with optional gzip, stdlib-only.
+
+Endpoint selection mirrors the reference SDK: public tokens (``azfive_pub_…``)
+use the browser-safe ingest path, anything else the server path.  Delivery is
+best-effort — the client re-queues failed batches; this module never raises.
+"""
+
+from __future__ import annotations
+
+import gzip as _gzip
+import json
+import logging
+import urllib.error
+import urllib.request
+import uuid
+
+logger = logging.getLogger("azfive_capture")
+
+_TIMEOUT_S = 10.0
+
+
+def uuid4() -> str:
+    return str(uuid.uuid4())
+
+
+def ingest_path(api_key: str) -> str:
+    return "/api/v1/events/ingest" if api_key.startswith("azfive_pub_") else "/api/v1/events"
+
+
+def send_batch(
+    events: list[dict],
+    *,
+    host: str,
+    api_key: str,
+    project: str,
+    gzip: bool = False,
+) -> bool:
+    """POST one batch. Returns True when the server accepted the request."""
+    body = json.dumps({"events": events, "project": project}).encode()
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    if gzip:
+        body = _gzip.compress(body)
+        headers["Content-Encoding"] = "gzip"
+    req = urllib.request.Request(
+        f"{host}{ingest_path(api_key)}", data=body, headers=headers, method="POST"
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_TIMEOUT_S) as res:
+            return 200 <= res.status < 300
+    except urllib.error.HTTPError as exc:
+        logger.debug("azfive batch rejected: %s", exc.code)
+        return False
+    except Exception as exc:  # network errors — silent, caller re-queues
+        logger.debug("azfive batch failed: %s", exc)
+        return False
+
+
+def post_json(url: str, api_key: str, payload: dict) -> dict | None:
+    """POST JSON, return the decoded JSON response or None on any failure."""
+    body = json.dumps(payload).encode()
+    req = urllib.request.Request(
+        url,
+        data=body,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_TIMEOUT_S) as res:
+            return json.loads(res.read().decode())
+    except Exception as exc:
+        logger.debug("azfive decide failed: %s", exc)
+        return None

azfive_capture-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: azfive-capture
+Version: 0.1.0
+Summary: Capture product-analytics events into AzFive from Python servers — events, identity, feature flags & experiments.
+Author: AzFive
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# azfive-capture (Python)
+
+AzFive product analytics for Python servers — events, identity, super
+properties, and feature flags/experiments. Zero dependencies (stdlib only).
+See `sdk-spec/SPEC.md` in the AzFive repo for the cross-SDK contract.
+
+## Install
+
+```bash
+pip install azfive-capture
+```
+
+Use a **secret** API key with the `events:write` scope (AzFive → Settings → API
+Keys). Secret keys are also valid on `/v1/decide`, so server-side flag
+evaluation needs no extra setup.
+
+## Quickstart
+
+```python
+from azfive_capture import Client
+
+azfive = Client("azfive_…", host="https://analytics.example.com", project="backend")
+
+azfive.capture("invoice_paid", {"amount": 99}, distinct_id="user-42")
+azfive.people.set({"plan": "pro"}, distinct_id="user-42")
+
+# experiments / feature flags — get_flag() reports the exposure automatically,
+# deduped per (distinct_id, flag, value)
+variant = azfive.get_flag("user-42", "exp-checkout")   # 'control' | 'test' | False | None
+if azfive.is_flag_enabled("user-42", "new-onboarding"):
+    ...
+
+azfive.flush()   # also flushed by the background thread and at exit
+```
+
+Batching: events queue in memory (batch 10 / 5 s / max 1000, oldest dropped)
+and are delivered by a daemon thread; failed batches retry on the next tick.
+`close()` (also registered via `atexit`) drains the queue.
+
+## Tests
+
+```bash
+pip install -e '.[dev]' && pytest   # golden vectors from ../sdk-spec/vectors
+```

azfive_capture-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+azfive_capture/__init__.py,sha256=D2LMN2ycIoLJAkngrLfaOKQUd43wyk6ZVe0u3j7kRmk,424
+azfive_capture/client.py,sha256=3Iw7aPNg4cPb2YLRpoSay1foSBPJvVcXK7-Edu7Qy34,11426
+azfive_capture/flags.py,sha256=m8R_tESn-dRNz9cWSeX6_UhRbYxnukOKyUVjQzslqUM,5082
+azfive_capture/transport.py,sha256=mYDNnW8rb4bm6N3C9z39V9e2zJP7hosSUKWWktCUq6E,2344
+azfive_capture-0.1.0.dist-info/METADATA,sha256=cal-c_mItZiI9i3KLbm0Q43D1e_vrYtzQZdMrdug5p0,2077
+azfive_capture-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+azfive_capture-0.1.0.dist-info/licenses/LICENSE,sha256=kOC_1jG3gKfLRJ7Qj404daeUxdeartrPlkwb8NsDU0Q,1063
+azfive_capture-0.1.0.dist-info/RECORD,,

azfive_capture-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

azfive_capture-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AzFive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.