cohorly 0.1.0__py3-none-any.whl

cohorly/__init__.py

@@ -0,0 +1,462 @@
+"""Cohorly server-side Python SDK.
+
+Mirrors the mixpanel-python API surface, targeting a self-hosted Cohorly
+server (`/track`, `/engage`, `/alias`).
+
+Basic usage::
+
+    from cohorly import Cohorly
+
+    ch = Cohorly("YOUR_PROJECT_TOKEN", api_host="http://localhost:4000")
+    ch.track("user-1", "Signed Up", {"plan": "pro"})
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import random
+import time as _time_module
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, List, Optional, Type
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Cohorly",
+    "Consumer",
+    "BufferedConsumer",
+    "CohorlyException",
+    "DatetimeSerializer",
+    "__version__",
+]
+
+DEFAULT_API_HOST = "http://localhost:4000"
+
+# Retry contract shared by all Cohorly SDKs.
+BASE_RETRY_DELAY_SECONDS = 2.0
+MAX_RETRY_DELAY_SECONDS = 600.0
+RETRY_JITTER = 0.2
+MAX_QUEUE_SIZE = 1000
+# Server rejects batches larger than 500 events.
+MAX_BATCH_SIZE = 500
+
+
+class CohorlyException(Exception):
+    """Raised when a message cannot be delivered to the Cohorly server."""
+
+
+class DatetimeSerializer(json.JSONEncoder):
+    """JSON encoder that serializes datetime/date values as ISO-8601 strings."""
+
+    def default(self, o: Any) -> Any:
+        if isinstance(o, (datetime.datetime, datetime.date)):
+            return o.isoformat()
+        return super().default(o)
+
+
+def json_dumps(data: Any, cls: Optional[Type[json.JSONEncoder]] = None) -> str:
+    # Separators are specified to eliminate whitespace.
+    return json.dumps(data, separators=(",", ":"), cls=cls)
+
+
+def _now_ms() -> int:
+    return int(_time_module.time() * 1000)
+
+
+class _Response:
+    """Outcome of a single HTTP POST (no exception escapes the transport)."""
+
+    __slots__ = ("status", "body", "retry_after")
+
+    def __init__(
+        self,
+        status: Optional[int],
+        body: str = "",
+        retry_after: Optional[float] = None,
+    ) -> None:
+        self.status = status  # None means network error / timeout
+        self.body = body
+        self.retry_after = retry_after
+
+    @property
+    def ok(self) -> bool:
+        return self.status is not None and 200 <= self.status < 300
+
+    @property
+    def retryable(self) -> bool:
+        """429, any 5xx, or a network error."""
+        return self.status is None or self.status == 429 or self.status >= 500
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        return max(float(value), 0.0)
+    except ValueError:
+        return None
+
+
+def _backoff_delay(
+    consecutive_failures: int,
+    retry_after: Optional[float],
+    jitter_fn: Callable[[], float],
+) -> float:
+    """Delay before the next attempt, honoring Retry-After when present.
+
+    Exponential: base 2s, doubling per consecutive failure, capped at 10 min,
+    with +/-20% jitter. Retry-After (when given) wins, capped at 10 min.
+    """
+    if retry_after is not None:
+        return min(retry_after, MAX_RETRY_DELAY_SECONDS)
+    exponent = max(consecutive_failures - 1, 0)
+    delay = min(BASE_RETRY_DELAY_SECONDS * (2**exponent), MAX_RETRY_DELAY_SECONDS)
+    return min(delay * (1.0 + jitter_fn()), MAX_RETRY_DELAY_SECONDS)
+
+
+class Consumer:
+    """Synchronous consumer: sends every message immediately.
+
+    On 429/5xx/network errors it retries inline with the Cohorly backoff
+    schedule (base 2s doubling, +/-20% jitter, Retry-After honored) up to
+    ``retry_limit`` times, then raises :class:`CohorlyException`. Any other
+    HTTP error raises immediately.
+    """
+
+    _ENDPOINTS = {
+        "events": "/track",
+        "people": "/engage",
+        "alias": "/alias",
+    }
+
+    def __init__(
+        self,
+        api_host: str = DEFAULT_API_HOST,
+        request_timeout: float = 10.0,
+        retry_limit: int = 4,
+    ) -> None:
+        self._api_host = api_host.rstrip("/")
+        self._request_timeout = request_timeout
+        self._retry_limit = retry_limit
+        # Injection points for tests.
+        self._sleep: Callable[[float], None] = _time_module.sleep
+        self._jitter: Callable[[], float] = lambda: random.uniform(
+            -RETRY_JITTER, RETRY_JITTER
+        )
+
+    def _request_url(self, endpoint: str) -> str:
+        return self._api_host + self._ENDPOINTS[endpoint]
+
+    def _check_endpoint(self, endpoint: str) -> None:
+        if endpoint not in self._ENDPOINTS:
+            raise CohorlyException(
+                "unknown endpoint {!r} (valid: {})".format(
+                    endpoint, ", ".join(sorted(self._ENDPOINTS))
+                )
+            )
+
+    def send(self, endpoint: str, json_message: str) -> None:
+        """Immediately deliver one JSON message to the given endpoint."""
+        self._check_endpoint(endpoint)
+        url = self._request_url(endpoint)
+        failures = 0
+        while True:
+            response = self._post(url, json_message)
+            if response.ok:
+                return
+            if response.retryable and failures < self._retry_limit:
+                failures += 1
+                self._sleep(_backoff_delay(failures, response.retry_after, self._jitter))
+                continue
+            raise CohorlyException(
+                "POST {} failed (status={}): {}".format(
+                    url, response.status, response.body
+                )
+            )
+
+    def flush(self) -> bool:
+        """No-op for the synchronous consumer (messages are never buffered)."""
+        return True
+
+    def _post(self, url: str, payload: str) -> _Response:
+        data = payload.encode("utf-8")
+        request = urllib.request.Request(
+            url,
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self._request_timeout) as raw:
+                return _Response(raw.status, raw.read().decode("utf-8", "replace"))
+        except urllib.error.HTTPError as exc:
+            try:
+                body = exc.read().decode("utf-8", "replace")
+            except Exception:
+                body = ""
+            return _Response(
+                exc.code, body, _parse_retry_after(exc.headers.get("Retry-After"))
+            )
+        except (urllib.error.URLError, OSError, ValueError) as exc:
+            return _Response(None, str(exc))
+
+
+class BufferedConsumer(Consumer):
+    """Batching consumer with the full Cohorly retry contract.
+
+    Messages accumulate in per-endpoint buffers and are sent in batches of up
+    to ``max_size`` (default 50, hard cap 500 - the server batch limit). A
+    buffer auto-flushes when it reaches ``max_size``; call :meth:`flush` to
+    drain everything (e.g. before process exit).
+
+    Retry contract:
+
+    - 429 / 5xx / network error: queue kept; exponential backoff (base 2s,
+      doubling, cap 10 min, +/-20% jitter), Retry-After honored when present.
+      Flush attempts before the backoff deadline are no-ops.
+    - 413: flush batch size halved (floor 1), queue kept, retried immediately.
+      A single message over the server body cap is dropped (raises).
+    - 400: that batch is dropped permanently (raises CohorlyException).
+    - 401: queue kept, backoff forced to the maximum delay.
+    - Buffers capped at ``max_queue_size`` (default 1000) messages each; the
+      OLDEST message is dropped on overflow.
+    """
+
+    def __init__(
+        self,
+        max_size: int = 50,
+        api_host: str = DEFAULT_API_HOST,
+        request_timeout: float = 10.0,
+        max_queue_size: int = MAX_QUEUE_SIZE,
+    ) -> None:
+        super().__init__(
+            api_host=api_host, request_timeout=request_timeout, retry_limit=0
+        )
+        self._max_size = min(max(max_size, 1), MAX_BATCH_SIZE)
+        self._max_queue_size = max(max_queue_size, 1)
+        self._buffers: Dict[str, List[str]] = {name: [] for name in self._ENDPOINTS}
+        self._flush_batch_size = self._max_size
+        self._consecutive_failures = 0
+        self._next_attempt_at = 0.0
+        # Injection point for tests.
+        self._clock: Callable[[], float] = _time_module.time
+
+    def send(self, endpoint: str, json_message: str) -> None:
+        """Buffer one JSON message; auto-flushes when the buffer is full."""
+        self._check_endpoint(endpoint)
+        buf = self._buffers[endpoint]
+        buf.append(json_message)
+        if len(buf) > self._max_queue_size:
+            del buf[0 : len(buf) - self._max_queue_size]  # drop oldest
+        if len(buf) >= self._max_size:
+            self._flush_endpoint(endpoint)
+
+    def flush(self) -> bool:
+        """Attempt to drain all buffers.
+
+        Returns True when every buffer is empty afterwards; False when
+        messages remain queued (backoff window active or delivery failing).
+        Raises CohorlyException when the server permanently rejects a batch
+        (the rejected batch is dropped, the rest of the queue is kept).
+        """
+        drained = True
+        for endpoint in self._ENDPOINTS:
+            drained = self._flush_endpoint(endpoint) and drained
+        return drained
+
+    # -- internals ---------------------------------------------------------
+
+    def _flush_endpoint(self, endpoint: str) -> bool:
+        buf = self._buffers[endpoint]
+        url = self._request_url(endpoint)
+        while buf:
+            if self._clock() < self._next_attempt_at:
+                return False  # inside a backoff window; keep the queue
+            if endpoint == "alias":
+                batch_len = 1  # /alias takes a single object, not an array
+                payload = buf[0]
+            else:
+                batch_len = min(len(buf), max(self._flush_batch_size, 1))
+                payload = "[" + ",".join(buf[:batch_len]) + "]"
+            response = self._post(url, payload)
+            if response.ok:
+                del buf[:batch_len]
+                self._consecutive_failures = 0
+                self._next_attempt_at = 0.0
+                continue
+            if response.retryable:
+                self._register_failure(retry_after=response.retry_after)
+                return False
+            if response.status == 401:
+                # Invalid token: keep the queue, back off at the max delay.
+                self._register_failure(delay=MAX_RETRY_DELAY_SECONDS)
+                return False
+            if response.status == 413:
+                if batch_len > 1:
+                    # Halve the batch size (floor 1) and retry immediately.
+                    self._flush_batch_size = max(batch_len // 2, 1)
+                    continue
+                # A single message is over the server body cap; it can never
+                # succeed, so drop it rather than wedging the queue.
+                del buf[:1]
+                raise CohorlyException(
+                    "message exceeds the server payload limit and was dropped"
+                )
+            # 400 (or another non-retryable client error): drop the batch.
+            del buf[:batch_len]
+            raise CohorlyException(
+                "POST {} rejected batch (status={}): {}".format(
+                    url, response.status, response.body
+                )
+            )
+        return True
+
+    def _register_failure(
+        self,
+        retry_after: Optional[float] = None,
+        delay: Optional[float] = None,
+    ) -> None:
+        self._consecutive_failures += 1
+        if delay is None:
+            delay = _backoff_delay(
+                self._consecutive_failures, retry_after, self._jitter
+            )
+        self._next_attempt_at = self._clock() + delay
+
+
+class Cohorly:
+    """Cohorly tracking client (mirrors the ``Mixpanel`` class).
+
+    :param token: project token (from the Cohorly dashboard).
+    :param api_host: base URL of the Cohorly server.
+    :param consumer: message consumer; defaults to a synchronous
+        :class:`Consumer` pointed at ``api_host``. Pass a
+        :class:`BufferedConsumer` for batching.
+    :param serializer: JSON encoder class used to serialize messages.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        api_host: str = DEFAULT_API_HOST,
+        consumer: Optional[Consumer] = None,
+        serializer: Type[json.JSONEncoder] = DatetimeSerializer,
+    ) -> None:
+        self._token = token
+        self._consumer = consumer if consumer is not None else Consumer(api_host)
+        self._serializer = serializer
+
+    # -- events ------------------------------------------------------------
+
+    def track(
+        self,
+        distinct_id: str,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Record an event.
+
+        Default properties (``token``, ``distinct_id``, ``time`` in unix ms,
+        ``$insert_id``, ``$lib``, ``$lib_version``) are stamped first; user
+        ``properties`` merge over them, so a custom ``time`` or ``$insert_id``
+        (for deduplication) may be supplied.
+        """
+        all_properties: Dict[str, Any] = {
+            "token": self._token,
+            "distinct_id": distinct_id,
+            "time": _now_ms(),
+            "$insert_id": uuid.uuid4().hex,
+            "$lib": "python",
+            "$lib_version": __version__,
+        }
+        if properties:
+            all_properties.update(properties)
+        event: Dict[str, Any] = {"event": event_name, "properties": all_properties}
+        if meta:
+            event.update(meta)
+        self._consumer.send("events", json_dumps(event, cls=self._serializer))
+
+    def import_data(
+        self,
+        distinct_id: str,
+        event_name: str,
+        timestamp: int,
+        properties: Optional[Dict[str, Any]] = None,
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Record a historical event with an explicit timestamp.
+
+        ``timestamp`` is unix **milliseconds** (Cohorly convention - note this
+        differs from mixpanel-python's seconds). Uses the same ``/track``
+        endpoint; Cohorly has no separate import endpoint or api_key.
+        """
+        props = dict(properties) if properties else {}
+        props["time"] = int(timestamp)
+        self.track(distinct_id, event_name, props, meta)
+
+    def alias(self, alias_id: str, original: str) -> None:
+        """Link ``alias_id`` to the ``original`` distinct_id."""
+        record = {
+            "alias": alias_id,
+            "distinct_id": original,
+            "token": self._token,
+        }
+        self._consumer.send("alias", json_dumps(record, cls=self._serializer))
+
+    # -- people ------------------------------------------------------------
+
+    def people_set(
+        self,
+        distinct_id: str,
+        properties: Dict[str, Any],
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Set profile properties (overwrites existing values)."""
+        self.people_update({"distinct_id": distinct_id, "$set": properties}, meta)
+
+    def people_set_once(
+        self,
+        distinct_id: str,
+        properties: Dict[str, Any],
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Set profile properties only if they are not already set."""
+        self.people_update({"distinct_id": distinct_id, "$set_once": properties}, meta)
+
+    def people_increment(
+        self,
+        distinct_id: str,
+        properties: Dict[str, float],
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Increment numeric profile properties by the given amounts."""
+        self.people_update({"distinct_id": distinct_id, "$add": properties}, meta)
+
+    def people_unset(
+        self,
+        distinct_id: str,
+        properties: List[str],
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Remove the named properties from a profile."""
+        self.people_update({"distinct_id": distinct_id, "$unset": properties}, meta)
+
+    def people_delete(
+        self, distinct_id: str, meta: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Delete a profile entirely."""
+        self.people_update({"distinct_id": distinct_id, "$delete": True}, meta)
+
+    def people_update(
+        self, message: Dict[str, Any], meta: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Send a raw engage operation (must include ``distinct_id``)."""
+        record: Dict[str, Any] = {"token": self._token}
+        record.update(message)
+        if meta:
+            record.update(meta)
+        self._consumer.send("people", json_dumps(record, cls=self._serializer))

cohorly-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: cohorly
+Version: 0.1.0
+Summary: Official Cohorly server-side Python SDK (Mixpanel-style product analytics, self-hosted)
+Author: Cohorly
+License: Apache-2.0
+Keywords: analytics,cohorly,mixpanel,tracking,events
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# Cohorly Python SDK
+
+The official server-side Python SDK for [Cohorly](../../README.md), a
+self-hosted Mixpanel-style product analytics platform. The API mirrors
+`mixpanel-python`, so migrating existing code is mostly a matter of swapping
+the import and pointing at your Cohorly server.
+
+- Zero runtime dependencies (stdlib `urllib` only)
+- Python 3.8+, fully typed (`py.typed`)
+- Synchronous `Consumer` and batching `BufferedConsumer` with the Cohorly
+  retry contract (exponential backoff, `Retry-After`, bounded queue)
+
+## Installation
+
+```bash
+pip install cohorly
+```
+
+Or from this repo:
+
+```bash
+pip install ./sdks/python
+```
+
+## Quickstart
+
+```python
+from cohorly import Cohorly
+
+ch = Cohorly("YOUR_PROJECT_TOKEN", api_host="http://localhost:4000")
+
+# Track an event
+ch.track("user-1", "Signed Up", {"plan": "pro", "source": "landing"})
+
+# Link an alias to an existing distinct_id
+ch.alias("user-1", "anon-7f3a")
+
+# Update a user profile
+ch.people_set("user-1", {"$first_name": "Ada", "plan": "pro"})
+```
+
+The project token comes from your Cohorly dashboard (Settings -> Projects).
+`api_host` is the base URL of your Cohorly server (default
+`http://localhost:4000`).
+
+## Tracking events
+
+`track(distinct_id, event_name, properties=None, meta=None)` stamps these
+default properties before sending:
+
+| Property       | Value                                   |
+| -------------- | --------------------------------------- |
+| `distinct_id`  | the id you pass                         |
+| `time`         | current unix time in **milliseconds**   |
+| `$insert_id`   | random uuid4 hex (server-side dedup)    |
+| `$lib`         | `"python"`                              |
+| `$lib_version` | SDK version                             |
+| `token`        | your project token (stripped by server) |
+
+Your `properties` merge over the defaults, so you may supply a custom `time`
+or `$insert_id` (e.g. for idempotent re-sends):
+
+```python
+ch.track("user-1", "Order Completed", {
+    "amount": 42.5,
+    "$insert_id": f"order-{order.id}",  # dedup key
+})
+```
+
+### Historical imports
+
+Use `import_data` to record events with an explicit timestamp (unix
+milliseconds - Cohorly's convention throughout):
+
+```python
+ch.import_data("user-1", "Legacy Signup", 1600000000000, {"source": "csv"})
+```
+
+Unlike Mixpanel there is no separate import endpoint, API secret, or 5-day
+cutoff - it is the same `/track` pipeline.
+
+## User profiles (people)
+
+```python
+ch.people_set("user-1", {"plan": "pro"})          # set/overwrite
+ch.people_set_once("user-1", {"created": "..."})  # only if unset
+ch.people_increment("user-1", {"logins": 1})      # numeric add
+ch.people_unset("user-1", ["plan"])               # remove properties
+ch.people_delete("user-1")                        # delete the profile
+ch.people_update({"distinct_id": "user-1", "$set": {"x": 1}})  # raw op
+```
+
+These map to the Cohorly `/engage` operations `$set`, `$set_once`, `$add`,
+`$unset`, `$delete`.
+
+## Consumers
+
+By default every call sends immediately via a synchronous `Consumer`. For
+higher throughput use `BufferedConsumer`, which batches messages (default 50
+per request, server max 500) and implements the Cohorly retry contract:
+
+```python
+from cohorly import Cohorly, BufferedConsumer
+
+consumer = BufferedConsumer(max_size=50, api_host="http://localhost:4000")
+ch = Cohorly("YOUR_PROJECT_TOKEN", consumer=consumer)
+
+for user in users:
+    ch.track(user.id, "Backfill Event", {"batch": True})
+
+consumer.flush()  # IMPORTANT: drain remaining messages before exit
+```
+
+Retry behavior (BufferedConsumer):
+
+- **429 / 5xx / network error** - the queue is kept and retried with
+  exponential backoff: base 2s, doubling per consecutive failure, capped at
+  10 minutes, +/-20% jitter. A `Retry-After` header is honored when present.
+- **413** - the flush batch size is halved (floor 1) and retried.
+- **400** - the rejected batch is dropped and `CohorlyException` is raised.
+- **401** (invalid token) - the queue is kept; backoff at the maximum delay.
+- The in-memory queue is capped at 1000 messages per endpoint; the oldest
+  message is dropped on overflow.
+
+Cohorly batch rejections are atomic (nothing partially inserted), so retrying
+the same payload is always safe.
+
+The synchronous `Consumer(api_host, request_timeout=10, retry_limit=4)`
+retries 429/5xx/network errors inline with the same backoff schedule up to
+`retry_limit` times, then raises `CohorlyException`.
+
+Because the token travels with each message, several `Cohorly` instances with
+different project tokens can share one consumer.
+
+## Error handling
+
+Delivery failures raise `cohorly.CohorlyException`:
+
+```python
+from cohorly import Cohorly, CohorlyException
+
+try:
+    ch.track("user-1", "event")
+except CohorlyException as exc:
+    log.warning("cohorly delivery failed: %s", exc)
+```
+
+## Serialization
+
+Messages are JSON. `datetime`/`date` values are serialized to ISO-8601 by the
+default `DatetimeSerializer`; pass your own `json.JSONEncoder` subclass via
+`Cohorly(..., serializer=MyEncoder)` for custom types.
+
+## Development
+
+```bash
+cd sdks/python
+python3 -m venv .venv
+.venv/bin/pip install pytest
+.venv/bin/pytest
+```
+
+Tests run against the source tree (no install needed) and use a mocked
+transport - no network required.

cohorly-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+cohorly/__init__.py,sha256=7n0CshKraW3uetT0q4Dk96gtSo3skzR5sQYNR7z-aGA,16527
+cohorly/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cohorly-0.1.0.dist-info/METADATA,sha256=PxNbH0LLOihrEqCtLcTMpt3ZoEV31fvCX9kCmAZ27FE,6015
+cohorly-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+cohorly-0.1.0.dist-info/top_level.txt,sha256=tcBbDP05wFRN4DPIvKLX-pdAW-3HJ_9HINVujBruodE,8
+cohorly-0.1.0.dist-info/RECORD,,

cohorly-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cohorly-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cohorly