featureflip 0.1.0__tar.gz

featureflip-0.1.0/.gitignore

@@ -0,0 +1,77 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# uv lock file (optional, use pip with pyproject.toml)
+uv.lock

featureflip-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: featureflip
+Version: 0.1.0
+Summary: Python SDK for Featureflip - a feature flag SaaS platform
+Project-URL: Homepage, https://featureflip.io
+Project-URL: Documentation, https://featureflip.io/docs/sdks/python/
+Author: Featureflip Team
+License-Expression: MIT
+Keywords: feature-flags,feature-toggles,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: structlog>=24.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Featureflip Python SDK
+
+Python SDK for [Featureflip](https://github.com/featureflip/featureflip) - evaluate feature flags locally with near-zero latency.
+
+## Installation
+
+```bash
+pip install featureflip
+```
+
+## Quick Start
+
+```python
+from featureflip import FeatureflipClient
+
+# Initialize the client (blocks until flags are loaded)
+client = FeatureflipClient(sdk_key="your-sdk-key")
+
+# Evaluate a feature flag
+enabled = client.variation("my-feature", {"user_id": "user-123"}, default=False)
+
+if enabled:
+    print("Feature is enabled!")
+else:
+    print("Feature is disabled")
+
+# Clean shutdown
+client.close()
+```
+
+## Configuration
+
+```python
+from featureflip import FeatureflipClient, Config
+
+client = FeatureflipClient(
+    sdk_key="your-sdk-key",
+    config=Config(
+        base_url="https://eval.featureflip.io",  # Evaluation API URL
+        streaming=True,           # Use SSE for real-time updates (default)
+        poll_interval=30.0,       # Polling interval if streaming=False
+        send_events=True,         # Enable analytics event tracking
+        flush_interval=30.0,      # Event flush interval in seconds
+        init_timeout=10.0,        # Max seconds to wait for initialization
+    )
+)
+```
+
+The SDK key can also be set via the `FEATUREFLIP_SDK_KEY` environment variable.
+
+## Context Manager
+
+```python
+with FeatureflipClient(sdk_key="your-sdk-key") as client:
+    enabled = client.variation("my-feature", {"user_id": "123"}, default=False)
+# Automatically closes and flushes events on exit
+```
+
+## Evaluation
+
+```python
+# Boolean flag
+enabled = client.variation("feature-key", {"user_id": "123"}, default=False)
+
+# String flag
+tier = client.variation("pricing-tier", {"user_id": "123"}, default="free")
+
+# Number flag
+limit = client.variation("rate-limit", {"user_id": "123"}, default=100)
+
+# JSON flag
+config = client.variation("ui-config", {"user_id": "123"}, default={"theme": "light"})
+```
+
+### Detailed Evaluation
+
+```python
+detail = client.variation_detail("feature-key", {"user_id": "123"}, default=False)
+
+print(detail.value)    # The evaluated value
+print(detail.reason)   # "RULE_MATCH", "FALLTHROUGH", "FLAG_DISABLED", etc.
+print(detail.rule_id)  # Rule ID if reason is RULE_MATCH
+```
+
+## Event Tracking
+
+```python
+# Track custom events
+client.track("checkout-completed", {"user_id": "123"}, metadata={"total": 99.99})
+
+# Identify users for segment building
+client.identify({"user_id": "123", "email": "user@example.com", "plan": "pro"})
+
+# Force flush pending events
+client.flush()
+```
+
+## Testing
+
+Use the test client for deterministic unit tests:
+
+```python
+from featureflip import FeatureflipClient
+
+# Create a test client with fixed values (no network calls)
+client = FeatureflipClient.for_testing({
+    "my-feature": True,
+    "pricing-tier": "pro",
+})
+
+# Evaluations return the configured values
+assert client.variation("my-feature", {}, default=False) is True
+assert client.variation("pricing-tier", {}, default="free") == "pro"
+
+# Unknown flags return the default
+assert client.variation("unknown", {}, default="fallback") == "fallback"
+
+# Update values at runtime
+client.set_test_value("my-feature", False)
+```
+
+## Features
+
+- **Client-side evaluation** - Near-zero latency after initialization
+- **Real-time updates** - SSE streaming with polling fallback
+- **Event tracking** - Automatic batching and flushing of analytics events
+- **Test support** - `for_testing()` factory for deterministic unit tests
+- **Type-safe** - Full type hints with mypy strict mode compliance
+
+## Requirements
+
+- Python 3.10+
+
+## Development
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run linting
+ruff check src/featureflip tests
+
+# Run type checking
+mypy src/featureflip --strict
+```
+
+## License
+
+MIT

featureflip-0.1.0/README.md

@@ -0,0 +1,152 @@
+# Featureflip Python SDK
+
+Python SDK for [Featureflip](https://github.com/featureflip/featureflip) - evaluate feature flags locally with near-zero latency.
+
+## Installation
+
+```bash
+pip install featureflip
+```
+
+## Quick Start
+
+```python
+from featureflip import FeatureflipClient
+
+# Initialize the client (blocks until flags are loaded)
+client = FeatureflipClient(sdk_key="your-sdk-key")
+
+# Evaluate a feature flag
+enabled = client.variation("my-feature", {"user_id": "user-123"}, default=False)
+
+if enabled:
+    print("Feature is enabled!")
+else:
+    print("Feature is disabled")
+
+# Clean shutdown
+client.close()
+```
+
+## Configuration
+
+```python
+from featureflip import FeatureflipClient, Config
+
+client = FeatureflipClient(
+    sdk_key="your-sdk-key",
+    config=Config(
+        base_url="https://eval.featureflip.io",  # Evaluation API URL
+        streaming=True,           # Use SSE for real-time updates (default)
+        poll_interval=30.0,       # Polling interval if streaming=False
+        send_events=True,         # Enable analytics event tracking
+        flush_interval=30.0,      # Event flush interval in seconds
+        init_timeout=10.0,        # Max seconds to wait for initialization
+    )
+)
+```
+
+The SDK key can also be set via the `FEATUREFLIP_SDK_KEY` environment variable.
+
+## Context Manager
+
+```python
+with FeatureflipClient(sdk_key="your-sdk-key") as client:
+    enabled = client.variation("my-feature", {"user_id": "123"}, default=False)
+# Automatically closes and flushes events on exit
+```
+
+## Evaluation
+
+```python
+# Boolean flag
+enabled = client.variation("feature-key", {"user_id": "123"}, default=False)
+
+# String flag
+tier = client.variation("pricing-tier", {"user_id": "123"}, default="free")
+
+# Number flag
+limit = client.variation("rate-limit", {"user_id": "123"}, default=100)
+
+# JSON flag
+config = client.variation("ui-config", {"user_id": "123"}, default={"theme": "light"})
+```
+
+### Detailed Evaluation
+
+```python
+detail = client.variation_detail("feature-key", {"user_id": "123"}, default=False)
+
+print(detail.value)    # The evaluated value
+print(detail.reason)   # "RULE_MATCH", "FALLTHROUGH", "FLAG_DISABLED", etc.
+print(detail.rule_id)  # Rule ID if reason is RULE_MATCH
+```
+
+## Event Tracking
+
+```python
+# Track custom events
+client.track("checkout-completed", {"user_id": "123"}, metadata={"total": 99.99})
+
+# Identify users for segment building
+client.identify({"user_id": "123", "email": "user@example.com", "plan": "pro"})
+
+# Force flush pending events
+client.flush()
+```
+
+## Testing
+
+Use the test client for deterministic unit tests:
+
+```python
+from featureflip import FeatureflipClient
+
+# Create a test client with fixed values (no network calls)
+client = FeatureflipClient.for_testing({
+    "my-feature": True,
+    "pricing-tier": "pro",
+})
+
+# Evaluations return the configured values
+assert client.variation("my-feature", {}, default=False) is True
+assert client.variation("pricing-tier", {}, default="free") == "pro"
+
+# Unknown flags return the default
+assert client.variation("unknown", {}, default="fallback") == "fallback"
+
+# Update values at runtime
+client.set_test_value("my-feature", False)
+```
+
+## Features
+
+- **Client-side evaluation** - Near-zero latency after initialization
+- **Real-time updates** - SSE streaming with polling fallback
+- **Event tracking** - Automatic batching and flushing of analytics events
+- **Test support** - `for_testing()` factory for deterministic unit tests
+- **Type-safe** - Full type hints with mypy strict mode compliance
+
+## Requirements
+
+- Python 3.10+
+
+## Development
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run linting
+ruff check src/featureflip tests
+
+# Run type checking
+mypy src/featureflip --strict
+```
+
+## License
+
+MIT

featureflip-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "featureflip"
+version = "0.1.0"
+description = "Python SDK for Featureflip - a feature flag SaaS platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Featureflip Team" }
+]
+keywords = ["feature-flags", "feature-toggles", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "httpx-sse>=0.4.0",
+    "structlog>=24.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-asyncio>=0.23.0",
+    "respx>=0.21.0",
+    "ruff>=0.3.0",
+    "mypy>=1.8.0",
+]
+
+[project.urls]
+Homepage = "https://featureflip.io"
+Documentation = "https://featureflip.io/docs/sdks/python/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/featureflip"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = [
+    "-ra",
+    "-q",
+    "--strict-markers",
+]
+markers = [
+    "unit: Unit tests",
+    "integration: Integration tests",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+    "TCH",    # flake8-type-checking
+    "PTH",    # flake8-use-pathlib
+    "ERA",    # eradicate
+    "RUF",    # Ruff-specific rules
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["featureflip"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_configs = true
+show_error_codes = true
+files = ["src/featureflip"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false

featureflip-0.1.0/src/featureflip/__init__.py

@@ -0,0 +1,51 @@
+"""Featureflip Python SDK."""
+
+__version__ = "0.1.0"
+
+from featureflip.client import FeatureflipClient
+from featureflip.config import Config
+from featureflip.context import EvaluationContext
+from featureflip.detail import EvaluationDetail, EvaluationReason
+from featureflip.exceptions import (
+    ConfigurationError,
+    FeatureflipError,
+    InitializationError,
+)
+from featureflip.models import (
+    Condition,
+    ConditionGroup,
+    ConditionLogic,
+    ConditionOperator,
+    FlagConfiguration,
+    FlagType,
+    Segment,
+    ServeConfig,
+    ServeType,
+    TargetingRule,
+    Variation,
+    WeightedVariation,
+)
+
+__all__: list[str] = [
+    "Condition",
+    "ConditionGroup",
+    "ConditionLogic",
+    "ConditionOperator",
+    "Config",
+    "ConfigurationError",
+    "EvaluationContext",
+    "EvaluationDetail",
+    "EvaluationReason",
+    "FeatureflipClient",
+    "FeatureflipError",
+    "FlagConfiguration",
+    "FlagType",
+    "InitializationError",
+    "Segment",
+    "ServeConfig",
+    "ServeType",
+    "TargetingRule",
+    "Variation",
+    "WeightedVariation",
+    "__version__",
+]

featureflip-0.1.0/src/featureflip/_events.py

@@ -0,0 +1,123 @@
+"""Event processor for batching and flushing analytics events."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Protocol
+
+import structlog
+
+logger = structlog.get_logger()
+
+
+class HttpClientProtocol(Protocol):
+    """Protocol for HTTP client to allow loose coupling."""
+
+    def post_events(self, events: list[dict[str, Any]]) -> None:
+        """Send events to the API."""
+        ...
+
+
+class EventProcessor:
+    """Batches and flushes analytics events.
+
+    This processor collects events in an internal queue and sends them to the API
+    either when the batch reaches a threshold size or after a time interval.
+    Events are also flushed when the processor is stopped.
+
+    Thread-safe: multiple threads can safely queue events concurrently.
+    """
+
+    def __init__(
+        self,
+        http_client: HttpClientProtocol,
+        flush_interval: float = 30.0,
+        flush_batch_size: int = 100,
+    ) -> None:
+        """Initialize the event processor.
+
+        Args:
+            http_client: HTTP client for sending events to the API.
+            flush_interval: Seconds between automatic flushes (default 30).
+            flush_batch_size: Number of events that triggers an immediate flush (default 100).
+        """
+        self._http = http_client
+        self._flush_interval = flush_interval
+        self._flush_batch_size = flush_batch_size
+        self._queue: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def queue_event(self, event: dict[str, Any]) -> None:
+        """Add an event to the queue.
+
+        Thread-safe. If the queue reaches the flush_batch_size threshold,
+        an immediate flush is triggered.
+
+        Args:
+            event: Event dictionary to queue. Should contain at minimum a 'type' field.
+        """
+        should_flush = False
+        with self._lock:
+            self._queue.append(event)
+            if len(self._queue) >= self._flush_batch_size:
+                should_flush = True
+
+        if should_flush:
+            self.flush()
+
+    def flush(self) -> None:
+        """Flush all queued events immediately.
+
+        Blocks until the flush is complete. If the queue is empty, no API call is made.
+        HTTP errors are logged but not raised.
+        """
+        events_to_send: list[dict[str, Any]] = []
+        with self._lock:
+            if not self._queue:
+                return
+            events_to_send = self._queue.copy()
+            self._queue.clear()
+
+        if not events_to_send:
+            return
+
+        try:
+            logger.debug("flushing_events", count=len(events_to_send))
+            self._http.post_events(events_to_send)
+            logger.debug("events_flushed_successfully", count=len(events_to_send))
+        except Exception as e:
+            logger.warning("event_flush_error", error=str(e), count=len(events_to_send))
+            # Events are lost on error - this is intentional to prevent memory growth
+            # In a production system, you might want to implement retry logic
+
+    def start(self) -> None:
+        """Start the background flush thread.
+
+        The background thread will periodically flush events at the configured interval.
+        """
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        logger.info("event_processor_started", flush_interval=self._flush_interval)
+
+    def stop(self) -> None:
+        """Stop the background thread and flush remaining events.
+
+        Blocks until the thread has stopped and all remaining events are flushed.
+        """
+        self._stop_event.set()
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=5.0)
+        # Flush any remaining events
+        self.flush()
+        logger.info("event_processor_stopped")
+
+    def _run(self) -> None:
+        """Main loop for the background flush thread."""
+        while not self._stop_event.is_set():
+            # Wait for either the interval or stop signal
+            self._stop_event.wait(self._flush_interval)
+            if not self._stop_event.is_set():
+                self.flush()