trodo-python 1.0.0__tar.gz

trodo_python-1.0.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: trodo-python
+Version: 1.0.0
+Summary: Trodo Analytics SDK for Python — server-side event tracking
+License: ISC
+Keywords: analytics,tracking,trodo,server-side
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: async
+Requires-Dist: httpx>=0.27.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: responses>=0.25.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+
+# trodo-python
+
+Server-side Python SDK for [Trodo Analytics](https://trodo.ai). Track backend events, identify users, and manage people/groups — all merging seamlessly with your frontend Trodo data under the same `site_id`.
+
+## Installation
+
+```bash
+pip install trodo-python
+```
+
+For async support (optional):
+
+```bash
+pip install trodo-python[async]
+```
+
+Requires Python 3.8+.
+
+## Quick Start
+
+```python
+import trodo
+
+# Initialize once at app startup
+trodo.init(
+    site_id='your-site-id',
+    debug=False,        # optional: log API calls
+    auto_events=True,   # optional: hook sys.excepthook
+)
+
+# Get a user context
+user = trodo.for_user('user-123')
+
+# Track a custom event
+user.track('purchase_completed', {'amount': 99.99, 'plan': 'pro'})
+
+# Identify the user (merges with frontend events under the same identity)
+user.identify('user@example.com')   # distinct_id becomes id_user@example.com
+
+# Update people profile
+user.people.set({'plan': 'pro', 'company': 'Acme'})
+
+# Track a server-side error
+user.capture_error(Exception('payment failed'))
+
+# Flush queued events before process exit
+trodo.shutdown()
+```
+
+## Flask / FastAPI Example
+
+```python
+# Flask
+from flask import Flask, request
+import trodo
+
+app = Flask(__name__)
+trodo.init(site_id='your-site-id')
+
+@app.route('/purchase', methods=['POST'])
+def purchase():
+    user_id = request.json['user_id']
+    user = trodo.for_user(user_id)
+    user.track('purchase_completed', {'amount': request.json['amount']})
+    return {'ok': True}
+```
+
+## Cross-SDK Identity Merging
+
+Frontend and backend events merge when both sides call `identify()` with the same value:
+
+```python
+# Python SDK
+user.identify('user@example.com')    # → id_user@example.com
+
+# Browser SDK (same value)
+# Trodo.identify('user@example.com') → id_user@example.com
+
+# Both event streams now appear together in the Trodo dashboard
+```
+
+## API Reference
+
+### `trodo.init(config)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `site_id` | `str` | required | Your Trodo site ID |
+| `api_base` | `str` | `https://sdkapi.trodo.ai` | API base URL |
+| `debug` | `bool` | `False` | Log API requests/responses |
+| `auto_events` | `bool` | `False` | Hook `sys.excepthook` + `threading.excepthook` |
+| `retries` | `int` | `3` | HTTP retry attempts on 5xx errors |
+| `timeout` | `int` | `10` | HTTP timeout in seconds |
+| `batch_enabled` | `bool` | `False` | Queue events and flush in bulk |
+| `batch_size` | `int` | `50` | Max events per batch flush |
+| `batch_flush_interval` | `float` | `5.0` | Flush interval in seconds |
+| `on_error` | `callable` | `None` | Callback for SDK errors |
+
+### `trodo.for_user(distinct_id, session_id=None)`
+
+Returns a user-bound context. All subsequent calls use this user's session.
+
+```python
+user = trodo.for_user(
+    'user-123',
+    session_id=request.cookies.get('trodo_session'),  # optional: correlate with browser session
+)
+```
+
+### User Context Methods
+
+```python
+user.track(event_name, properties=None)          # Track custom event
+user.track_event(event_name, properties=None)    # Alias for track()
+user.identify(identify_id)                       # Merge identity
+user.wallet_address(address)                     # Set crypto wallet address
+user.reset()                                     # Clear session context
+user.capture_error(exception)                    # Track server_error event
+
+# People profile
+user.people.set(properties)
+user.people.set_once(properties)
+user.people.unset(keys)
+user.people.increment(properties)
+user.people.append(properties)
+user.people.union(properties)
+user.people.remove(properties)
+user.people.track_charge(amount, properties=None)
+user.people.clear_charges()
+user.people.delete_user()
+
+# Groups
+user.set_group(group_key, group_id)
+user.add_group(group_key, group_id)
+user.remove_group(group_key, group_id)
+group = user.get_group(group_key, group_id)
+group.set(properties)
+group.set_once(properties)
+group.union(properties)
+group.remove(properties)
+group.unset(keys)
+group.increment(properties)
+group.append(properties)
+group.delete()
+```
+
+### Direct Call Pattern (for pipelines/scripts)
+
+```python
+trodo.track('user-123', 'event_name', {'key': 'value'})
+trodo.identify('user-123', 'identify_id')
+trodo.people_set('user-123', {'plan': 'pro'})
+trodo.set_group('user-123', 'company', 'acme')
+```
+
+### Global Methods
+
+```python
+trodo.enable_auto_events()    # Enable sys.excepthook hooks
+trodo.disable_auto_events()   # Disable hooks
+trodo.flush()                 # Flush pending batch queue
+trodo.shutdown()              # Flush + stop background timers
+```
+
+## Auto Events
+
+When `auto_events=True`, the SDK wraps Python's exception hooks and sends `server_error` events to Trodo:
+
+- `sys.excepthook` — unhandled exceptions in the main thread
+- `threading.excepthook` — unhandled exceptions in threads
+
+These events use `distinct_id: 'server_global'` in the dashboard.
+
+Per-user error capture: `user.capture_error(e)` uses the user's own `distinct_id`.
+
+## Batching
+
+```python
+trodo.init(
+    site_id='your-site-id',
+    batch_enabled=True,
+    batch_size=100,
+    batch_flush_interval=3.0,
+)
+
+# Events are queued and flushed every 3s or when 100 events accumulate
+user.track('page_view')
+
+# Always flush before process exit
+import atexit
+atexit.register(trodo.shutdown)
+```
+
+## Thread Safety
+
+The SDK is thread-safe. `SessionManager`, `EventQueue`, and `BatchFlusher` all use `threading.Lock` internally. Safe to use in multi-threaded Flask/Django/FastAPI applications.
+
+## License
+
+ISC

trodo_python-1.0.0/README.md

@@ -0,0 +1,200 @@
+# trodo-python
+
+Server-side Python SDK for [Trodo Analytics](https://trodo.ai). Track backend events, identify users, and manage people/groups — all merging seamlessly with your frontend Trodo data under the same `site_id`.
+
+## Installation
+
+```bash
+pip install trodo-python
+```
+
+For async support (optional):
+
+```bash
+pip install trodo-python[async]
+```
+
+Requires Python 3.8+.
+
+## Quick Start
+
+```python
+import trodo
+
+# Initialize once at app startup
+trodo.init(
+    site_id='your-site-id',
+    debug=False,        # optional: log API calls
+    auto_events=True,   # optional: hook sys.excepthook
+)
+
+# Get a user context
+user = trodo.for_user('user-123')
+
+# Track a custom event
+user.track('purchase_completed', {'amount': 99.99, 'plan': 'pro'})
+
+# Identify the user (merges with frontend events under the same identity)
+user.identify('user@example.com')   # distinct_id becomes id_user@example.com
+
+# Update people profile
+user.people.set({'plan': 'pro', 'company': 'Acme'})
+
+# Track a server-side error
+user.capture_error(Exception('payment failed'))
+
+# Flush queued events before process exit
+trodo.shutdown()
+```
+
+## Flask / FastAPI Example
+
+```python
+# Flask
+from flask import Flask, request
+import trodo
+
+app = Flask(__name__)
+trodo.init(site_id='your-site-id')
+
+@app.route('/purchase', methods=['POST'])
+def purchase():
+    user_id = request.json['user_id']
+    user = trodo.for_user(user_id)
+    user.track('purchase_completed', {'amount': request.json['amount']})
+    return {'ok': True}
+```
+
+## Cross-SDK Identity Merging
+
+Frontend and backend events merge when both sides call `identify()` with the same value:
+
+```python
+# Python SDK
+user.identify('user@example.com')    # → id_user@example.com
+
+# Browser SDK (same value)
+# Trodo.identify('user@example.com') → id_user@example.com
+
+# Both event streams now appear together in the Trodo dashboard
+```
+
+## API Reference
+
+### `trodo.init(config)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `site_id` | `str` | required | Your Trodo site ID |
+| `api_base` | `str` | `https://sdkapi.trodo.ai` | API base URL |
+| `debug` | `bool` | `False` | Log API requests/responses |
+| `auto_events` | `bool` | `False` | Hook `sys.excepthook` + `threading.excepthook` |
+| `retries` | `int` | `3` | HTTP retry attempts on 5xx errors |
+| `timeout` | `int` | `10` | HTTP timeout in seconds |
+| `batch_enabled` | `bool` | `False` | Queue events and flush in bulk |
+| `batch_size` | `int` | `50` | Max events per batch flush |
+| `batch_flush_interval` | `float` | `5.0` | Flush interval in seconds |
+| `on_error` | `callable` | `None` | Callback for SDK errors |
+
+### `trodo.for_user(distinct_id, session_id=None)`
+
+Returns a user-bound context. All subsequent calls use this user's session.
+
+```python
+user = trodo.for_user(
+    'user-123',
+    session_id=request.cookies.get('trodo_session'),  # optional: correlate with browser session
+)
+```
+
+### User Context Methods
+
+```python
+user.track(event_name, properties=None)          # Track custom event
+user.track_event(event_name, properties=None)    # Alias for track()
+user.identify(identify_id)                       # Merge identity
+user.wallet_address(address)                     # Set crypto wallet address
+user.reset()                                     # Clear session context
+user.capture_error(exception)                    # Track server_error event
+
+# People profile
+user.people.set(properties)
+user.people.set_once(properties)
+user.people.unset(keys)
+user.people.increment(properties)
+user.people.append(properties)
+user.people.union(properties)
+user.people.remove(properties)
+user.people.track_charge(amount, properties=None)
+user.people.clear_charges()
+user.people.delete_user()
+
+# Groups
+user.set_group(group_key, group_id)
+user.add_group(group_key, group_id)
+user.remove_group(group_key, group_id)
+group = user.get_group(group_key, group_id)
+group.set(properties)
+group.set_once(properties)
+group.union(properties)
+group.remove(properties)
+group.unset(keys)
+group.increment(properties)
+group.append(properties)
+group.delete()
+```
+
+### Direct Call Pattern (for pipelines/scripts)
+
+```python
+trodo.track('user-123', 'event_name', {'key': 'value'})
+trodo.identify('user-123', 'identify_id')
+trodo.people_set('user-123', {'plan': 'pro'})
+trodo.set_group('user-123', 'company', 'acme')
+```
+
+### Global Methods
+
+```python
+trodo.enable_auto_events()    # Enable sys.excepthook hooks
+trodo.disable_auto_events()   # Disable hooks
+trodo.flush()                 # Flush pending batch queue
+trodo.shutdown()              # Flush + stop background timers
+```
+
+## Auto Events
+
+When `auto_events=True`, the SDK wraps Python's exception hooks and sends `server_error` events to Trodo:
+
+- `sys.excepthook` — unhandled exceptions in the main thread
+- `threading.excepthook` — unhandled exceptions in threads
+
+These events use `distinct_id: 'server_global'` in the dashboard.
+
+Per-user error capture: `user.capture_error(e)` uses the user's own `distinct_id`.
+
+## Batching
+
+```python
+trodo.init(
+    site_id='your-site-id',
+    batch_enabled=True,
+    batch_size=100,
+    batch_flush_interval=3.0,
+)
+
+# Events are queued and flushed every 3s or when 100 events accumulate
+user.track('page_view')
+
+# Always flush before process exit
+import atexit
+atexit.register(trodo.shutdown)
+```
+
+## Thread Safety
+
+The SDK is thread-safe. `SessionManager`, `EventQueue`, and `BatchFlusher` all use `threading.Lock` internally. Safe to use in multi-threaded Flask/Django/FastAPI applications.
+
+## License
+
+ISC

trodo_python-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trodo-python"
+version = "1.0.0"
+description = "Trodo Analytics SDK for Python — server-side event tracking"
+readme = "README.md"
+license = { text = "ISC" }
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.28.0",
+]
+keywords = ["analytics", "tracking", "trodo", "server-side"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: ISC License (ISCL)",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.optional-dependencies]
+async = ["httpx>=0.27.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "responses>=0.25.0",
+    "httpx>=0.27.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["trodo*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

trodo_python-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trodo_python-1.0.0/trodo/__init__.py

@@ -0,0 +1,134 @@
+"""
+trodo-python — Trodo Analytics SDK for Python
+
+Usage (module-level singleton):
+    import trodo
+    trodo.init(site_id='your-site-id')
+    user = trodo.for_user('user-123')
+    user.track('purchase_completed', {'amount': 99.99})
+
+Usage (class):
+    from trodo import TrodoClient
+    client = TrodoClient(site_id='your-site-id')
+    user = client.for_user('user-123')
+    user.track('purchase_completed', {'amount': 99.99})
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from .client import TrodoClient
+from .user_context import UserContext
+from .managers.group_manager import GroupProfile
+from .types import ApiResult, IdentifyResult, ResetResult, WalletAddressResult
+
+__all__ = [
+    "TrodoClient",
+    "UserContext",
+    "GroupProfile",
+    "init",
+    "for_user",
+    "track",
+    "identify",
+    "wallet_address",
+    "reset",
+    "enable_auto_events",
+    "disable_auto_events",
+    "flush",
+    "shutdown",
+]
+
+# ============================================================================
+# Singleton convenience API
+# ============================================================================
+
+_client: Optional[TrodoClient] = None
+
+
+def _get_client() -> TrodoClient:
+    if _client is None:
+        raise RuntimeError(
+            "trodo-python: Call trodo.init(site_id=...) before using the SDK."
+        )
+    return _client
+
+
+def init(
+    site_id: str,
+    api_base: str = "https://sdkapi.trodo.ai",
+    timeout: int = 10,
+    retries: int = 2,
+    batch_enabled: bool = False,
+    batch_size: int = 50,
+    batch_flush_interval: float = 5.0,
+    auto_events: bool = False,
+    on_error: Optional[Any] = None,
+    debug: bool = False,
+) -> TrodoClient:
+    """Initialise the singleton SDK instance."""
+    global _client
+    _client = TrodoClient(
+        site_id=site_id,
+        api_base=api_base,
+        timeout=timeout,
+        retries=retries,
+        batch_enabled=batch_enabled,
+        batch_size=batch_size,
+        batch_flush_interval=batch_flush_interval,
+        auto_events=auto_events,
+        on_error=on_error,
+        debug=debug,
+    )
+    return _client
+
+
+def for_user(
+    distinct_id: str,
+    session_id: Optional[str] = None,
+) -> UserContext:
+    """Return a UserContext bound to the given distinctId."""
+    return _get_client().for_user(distinct_id, session_id)
+
+
+def track(
+    distinct_id: str,
+    event_name: str,
+    properties: Optional[Dict[str, Any]] = None,
+    category: str = "custom",
+) -> None:
+    """Track an event for a user (direct-call pattern)."""
+    _get_client().track(distinct_id, event_name, properties, category)
+
+
+def identify(distinct_id: str, identify_id: str) -> IdentifyResult:
+    """Alias a user's distinctId to an external identifier."""
+    return _get_client().identify(distinct_id, identify_id)
+
+
+def wallet_address(distinct_id: str, wallet_addr: str) -> WalletAddressResult:
+    """Associate a wallet address with a user."""
+    return _get_client().wallet_address(distinct_id, wallet_addr)
+
+
+def reset(distinct_id: str) -> ResetResult:
+    """Reset a user's session."""
+    return _get_client().reset(distinct_id)
+
+
+def enable_auto_events() -> None:
+    _get_client().enable_auto_events()
+
+
+def disable_auto_events() -> None:
+    _get_client().disable_auto_events()
+
+
+def flush() -> None:
+    """Flush any queued batch events."""
+    _get_client().flush()
+
+
+def shutdown() -> None:
+    """Flush, stop timers, and disable auto events."""
+    _get_client().shutdown()

trodo_python-1.0.0/trodo/api/async_client.py

@@ -0,0 +1,96 @@
+"""Async HTTP client using httpx (optional dependency)."""
+
+from __future__ import annotations
+
+import sys
+import asyncio
+from typing import Any, Callable, Dict, Optional
+
+from ..types import ApiResult, EventPayload
+
+
+class AsyncHttpClient:
+    def __init__(
+        self,
+        api_base: str,
+        site_id: str,
+        timeout: int = 10,
+        retries: int = 2,
+        on_error: Optional[Callable[[Exception], None]] = None,
+        debug: bool = False,
+    ) -> None:
+        try:
+            import httpx  # noqa: F401
+        except ImportError:
+            raise ImportError(
+                "trodo-python async support requires httpx: pip install trodo-python[async]"
+            )
+
+        self.api_base = api_base.rstrip("/")
+        self.site_id = site_id
+        self.timeout = timeout
+        self.retries = retries
+        self.on_error = on_error
+        self.debug = debug
+
+    def _log(self, *args: Any) -> None:
+        if self.debug:
+            sys.stderr.write(f"[trodo-python-async] {' '.join(str(a) for a in args)}\n")
+
+    async def _request(
+        self, path: str, body: Dict[str, Any], attempt: int = 0
+    ) -> ApiResult:
+        import httpx
+
+        url = f"{self.api_base}{path}"
+        self._log(f"POST {url}")
+        headers = {
+            "Content-Type": "application/json",
+            "X-Trodo-Site-Id": self.site_id,
+        }
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                resp = await client.post(url, json=body, headers=headers)
+            if resp.status_code >= 500 and attempt < self.retries:
+                delay = 2 ** attempt
+                self._log(f"Retry {attempt + 1} after {delay}s")
+                await asyncio.sleep(delay)
+                return await self._request(path, body, attempt + 1)
+            try:
+                return resp.json()
+            except Exception:
+                return {}
+        except Exception as exc:
+            if attempt < self.retries:
+                await asyncio.sleep(2 ** attempt)
+                return await self._request(path, body, attempt + 1)
+            self._log(f"Error: {exc}")
+            if self.on_error:
+                self.on_error(exc)
+            return {}
+
+    async def post_track(self, session_data: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/track", {"sessionData": session_data})
+
+    async def post_event(self, event: EventPayload) -> ApiResult:
+        return await self._request("/api/events", event.to_dict())
+
+    async def post_bulk_events(self, events: list) -> ApiResult:
+        return await self._request(
+            "/api/events/bulk", {"events": [e.to_dict() for e in events]}
+        )
+
+    async def post_identify(self, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/identify", payload)
+
+    async def post_wallet_address(self, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/wallet-address", payload)
+
+    async def post_reset(self, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request("/api/sdk/reset", payload)
+
+    async def post_people(self, path: str, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request(path, payload)
+
+    async def post_group(self, path: str, payload: Dict[str, Any]) -> ApiResult:
+        return await self._request(path, payload)