toggletest 0.1.0__tar.gz

toggletest-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: toggletest
+Version: 0.1.0
+Summary: ToggleTest SDK for feature flags and A/B testing
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: httpx>=0.25
+Requires-Dist: wasmtime>=27.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'

toggletest-0.1.0/README.md

@@ -0,0 +1,289 @@
+# ToggleTest Python SDK
+
+Python SDK for feature flags and A/B testing with local WASM-based evaluation. After initialization, all flag evaluations happen locally with zero network latency.
+
+## Installation
+
+```bash
+pip install toggletest
+```
+
+## Quick Start
+
+```python
+from toggletest import ToggleTestClient
+
+# Initialize the client
+client = ToggleTestClient(
+    api_key="tt_your_api_key",
+    base_url="https://api.toggletest.com",
+    environment="production"  # optional
+)
+
+# Start the SDK (fetches WASM evaluator and rules)
+client.start()
+
+# Evaluate a feature flag
+if client.is_enabled("dark-mode", user_id="user-123"):
+    print("Dark mode is enabled")
+
+# Get A/B test variant
+result = client.get_variant("pricing-test", user_id="user-123")
+print(f"User assigned to variant: {result.variant}")
+
+# Track an event
+client.track(
+    "conversion",
+    end_user_id="user-123",
+    test_key="pricing-test",
+    variant_name=result.variant
+)
+
+# Shutdown gracefully
+client.close()
+```
+
+## API Reference
+
+### Client Initialization
+
+```python
+client = ToggleTestClient(
+    api_key="tt_your_api_key",
+    base_url="https://api.toggletest.com",
+    environment="production",  # optional
+    on_ready=lambda: print("SDK ready"),  # optional callback
+    on_error=lambda e: print(f"Error: {e}")  # optional error handler
+)
+```
+
+### Lifecycle Methods
+
+#### `start()`
+Initialize the SDK. Fetches the WASM evaluator binary and rules, then starts the SSE connection for real-time updates.
+
+```python
+client.start()
+```
+
+Raises `RuntimeError` if WASM loading fails or `httpx.HTTPError` if rules fetch fails.
+
+#### `close()`
+Gracefully shut down the SDK. Disconnects SSE, flushes buffered events, and releases resources.
+
+```python
+client.close()
+```
+
+#### `ready` (property)
+Check if the SDK has completed initialization.
+
+```python
+if client.ready:
+    # SDK is ready for evaluations
+```
+
+### Feature Flag Evaluation
+
+#### `is_enabled(flag_key, *, user_id, attributes=None)`
+Returns a boolean indicating if a flag is enabled. Returns `False` if the flag is not found.
+
+```python
+enabled = client.is_enabled(
+    "dark-mode",
+    user_id="user-123",
+    attributes={"plan": "pro", "country": "US"}
+)
+```
+
+#### `evaluate_flag(flag_key, *, user_id, attributes=None)`
+Returns the full flag evaluation result including value, reason, and rule ID.
+
+```python
+from toggletest import FlagResult
+
+result = client.evaluate_flag(
+    "feature-x",
+    user_id="user-123",
+    attributes={"beta": True}
+)
+
+print(f"Value: {result.value}")
+print(f"Reason: {result.reason}")
+print(f"Rule ID: {result.rule_id}")
+```
+
+**Returns:** `FlagResult` with:
+- `value`: The flag value (bool, str, number, or dict)
+- `reason`: Evaluation reason (e.g., "rule_match", "default", "disabled", "not_found")
+- `rule_id`: ID of the matched rule, if any
+
+#### `evaluate_all(*, user_id, attributes=None)`
+Evaluate all flags and tests for the given user. Useful for bootstrapping client-side SDKs.
+
+```python
+from toggletest import EvalResults
+
+results = client.evaluate_all(
+    user_id="user-123",
+    attributes={"plan": "enterprise"}
+)
+
+# Access all flags
+for flag_key, flag_result in results.flags.items():
+    print(f"{flag_key}: {flag_result.value}")
+
+# Access all tests
+for test_key, test_result in results.tests.items():
+    print(f"{test_key}: {test_result.variant}")
+```
+
+**Returns:** `EvalResults` with:
+- `flags`: Dict[str, FlagResult] - All flag evaluations
+- `tests`: Dict[str, TestResult] - All test assignments
+
+### A/B Testing
+
+#### `get_variant(test_key, *, user_id, attributes=None)`
+Get the variant assignment for an A/B test. Users are deterministically assigned based on a hash of user_id + test_key.
+
+```python
+from toggletest import TestResult
+
+result = client.get_variant(
+    "pricing-test",
+    user_id="user-123",
+    attributes={"plan": "pro"}
+)
+
+print(f"Variant: {result.variant}")  # e.g., "control", "variant_a"
+print(f"Bucket: {result.bucket}")    # 0-9999
+```
+
+**Returns:** `TestResult` with:
+- `variant`: Variant name (e.g., "control", "variant_a")
+- `bucket`: Deterministic bucket value (0-9999)
+
+### Event Tracking
+
+#### `track(event_type, *, end_user_id, test_key=None, flag_key=None, variant_name=None, evaluation_reason=None, metadata=None)`
+Track an analytics event. Events are buffered and sent in batches.
+
+```python
+# Track a conversion
+client.track(
+    "conversion",
+    end_user_id="user-123",
+    test_key="pricing-test",
+    variant_name="variant_a",
+    metadata={"revenue": 99.99}
+)
+
+# Track a flag evaluation
+client.track(
+    "flag_evaluation",
+    end_user_id="user-123",
+    flag_key="dark-mode",
+    evaluation_reason="rule_match"
+)
+
+# Track a variant assignment
+client.track(
+    "variant_assignment",
+    end_user_id="user-123",
+    test_key="homepage-redesign",
+    variant_name="control"
+)
+```
+
+Common event types:
+- `"conversion"` - User completed a goal
+- `"flag_evaluation"` - A flag was evaluated
+- `"variant_assignment"` - User was assigned to a variant
+
+### Listeners
+
+#### `on_rules_update(listener)`
+Register a callback for rules updates. The listener receives the new rules version hash.
+
+```python
+def on_update(version_hash):
+    print(f"Rules updated to version: {version_hash}")
+
+unsubscribe = client.on_rules_update(on_update)
+
+# Later, to unsubscribe:
+unsubscribe()
+```
+
+## Configuration Options
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `api_key` | str | Yes | SDK API key (typically prefixed with "tt_") |
+| `base_url` | str | Yes | Base URL of the ToggleTest API |
+| `environment` | str | No | Environment identifier (e.g., "production", "staging") |
+| `on_ready` | Callable | No | Callback invoked when SDK initialization completes |
+| `on_error` | Callable | No | Callback invoked on non-fatal errors (SSE disconnect, etc.) |
+
+## User Context and Attributes
+
+The `attributes` parameter accepts a dictionary of user/request attributes for targeting rules:
+
+```python
+client.is_enabled(
+    "premium-feature",
+    user_id="user-123",
+    attributes={
+        "plan": "enterprise",
+        "country": "US",
+        "beta_tester": True,
+        "account_age_days": 45
+    }
+)
+```
+
+## Architecture
+
+The SDK uses WASM-based local evaluation for zero-latency flag checks:
+
+1. **Initialization** - Downloads WASM evaluator binary and rules JSON
+2. **Local Evaluation** - All flag/test evaluations run in-process via WASM
+3. **Real-time Updates** - SSE connection for instant rules change notifications
+4. **Event Batching** - Analytics events are buffered and sent periodically
+
+After `start()` completes, all evaluation methods are synchronous with no network calls in the hot path.
+
+## Error Handling
+
+```python
+from toggletest import ToggleTestClient
+
+client = ToggleTestClient(
+    api_key="tt_key",
+    base_url="https://api.toggletest.com",
+    on_error=lambda e: print(f"SDK Error: {e}")
+)
+
+try:
+    client.start()
+except RuntimeError as e:
+    print(f"Failed to start SDK: {e}")
+
+# Evaluation methods raise RuntimeError if SDK is not ready
+if not client.ready:
+    print("SDK not ready")
+else:
+    result = client.evaluate_flag("feature", user_id="user-123")
+```
+
+## Requirements
+
+- Python 3.9+
+- httpx >= 0.25
+- httpx-sse >= 0.4
+- wasmtime >= 27.0
+
+## License
+
+MIT

toggletest-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "toggletest"
+version = "0.1.0"
+description = "ToggleTest SDK for feature flags and A/B testing"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = [
+    "httpx>=0.25",
+    "httpx-sse>=0.4",
+    "wasmtime>=27.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio"]

toggletest-0.1.0/toggletest/__init__.py

@@ -0,0 +1,54 @@
+"""
+toggletest - ToggleTest Python SDK with WASM-based local evaluation
+
+This is the package entry point. It re-exports only the types and classes
+that SDK consumers need. Internal implementation details (WasmEngine,
+RulesStore, SseConnection, EventBuffer) are NOT exported.
+
+Usage:
+    from toggletest import ToggleTestClient
+    from toggletest import EvalContext, EvalResults, FlagResult, TestResult
+
+    client = ToggleTestClient(
+        api_key="tt_...",
+        base_url="http://localhost:3001",
+        environment="production",
+    )
+    client.start()
+
+    if client.is_enabled("dark-mode", user_id="user-123"):
+        ...
+
+    client.close()
+"""
+
+# -- Main client class --
+from .client import ToggleTestClient
+
+# -- Configuration and context types --
+from .types import ToggleTestConfig, EvalContext
+
+# -- Evaluation result types --
+from .types import FlagResult, TestResult, EvalResults
+
+# -- Event tracking types --
+from .types import SdkEvent
+
+# -- Listener types --
+from .types import RulesUpdateListener
+
+__all__ = [
+    # Client
+    "ToggleTestClient",
+    # Config / context
+    "ToggleTestConfig",
+    "EvalContext",
+    # Evaluation results
+    "FlagResult",
+    "TestResult",
+    "EvalResults",
+    # Events
+    "SdkEvent",
+    # Listeners
+    "RulesUpdateListener",
+]