redis-feature-flags 0.1.0__tar.gz

redis_feature_flags-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+develop-eggs/
+.installed.cfg
+lib/
+lib64/
+wheels/
+
+# Virtual environment
+.venv/
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+*.cover
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Environment variables
+.env
+.env.local
+
+# Redis
+dump.rdb
+appendonly.aof
+
+# Distribution
+*.tar.gz
+*.whl

redis_feature_flags-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: redis-feature-flags
+Version: 0.1.0
+Summary: Feature flags backed by Redis. No new server. No monthly bill.
+License: MIT
+Keywords: feature-flags,feature-toggles,redis,rollout
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: redis>=4.0.0
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: fakeredis>=2.0; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# redis-feature-flags
+
+Feature flags backed by Redis.
+No new server. No new database. No monthly bill.
+
+## Install
+
+# Python
+pip install redis-feature-flags

redis_feature_flags-0.1.0/README.md

@@ -0,0 +1,9 @@
+# redis-feature-flags
+
+Feature flags backed by Redis.
+No new server. No new database. No monthly bill.
+
+## Install
+
+# Python
+pip install redis-feature-flags

redis_feature_flags-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "redis-feature-flags"
+version = "0.1.0"
+description = "Feature flags backed by Redis. No new server. No monthly bill."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["redis", "feature-flags", "feature-toggles", "rollout"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "redis>=4.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "fakeredis>=2.0",
+    "black",
+    "mypy",
+    "ruff",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=redis_feature_flags --cov-report=term-missing --cov-fail-under=90"
+
+[tool.coverage.run]
+source = ["redis_feature_flags"]
+omit = ["tests/*"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.hatch.build.targets.wheel]
+packages = ["redis_feature_flags"]

redis_feature_flags-0.1.0/redis_feature_flags/__init__.py

@@ -0,0 +1,20 @@
+from .client import FeatureFlags
+from .exceptions import (
+    RedisFlagError,
+    FlagNotFoundError,
+    CohortNotFoundError,
+    InvalidRolloutError,
+    RedisConnectionError,
+    SchemaVersionError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "FeatureFlags",
+    "RedisFlagError",
+    "FlagNotFoundError",
+    "CohortNotFoundError",
+    "InvalidRolloutError",
+    "RedisConnectionError",
+    "SchemaVersionError",
+]

redis_feature_flags-0.1.0/redis_feature_flags/cache.py

@@ -0,0 +1,121 @@
+# redis_feature_flags/cache.py
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class CacheEntry:
+    """
+    A single cached flag object.
+    Stores the raw flag data and when it was cached.
+    """
+    data: Dict[str, Any]
+    cached_at: float = field(default_factory=time.monotonic)
+
+    def is_expired(self, ttl_seconds: int) -> bool:
+        """Check if this entry is older than the TTL."""
+        age = time.monotonic() - self.cached_at
+        return age > ttl_seconds
+
+
+class LocalCache:
+    """
+    In-process cache for feature flag data.
+
+    Serves flag data from memory to avoid a Redis call
+    on every is_enabled() evaluation. Falls back to
+    serving stale data if Redis becomes unreachable.
+
+    Thread-safe — safe to use across multiple threads.
+    """
+
+    def __init__(self, ttl_seconds: int = 30):
+        """
+        Args:
+            ttl_seconds: How long a cached flag is considered
+                         fresh. Default 30 seconds.
+                         After TTL expires, next read fetches
+                         from Redis and refreshes the cache.
+        """
+        self._ttl = ttl_seconds
+        self._store: Dict[str, CacheEntry] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Optional[Dict[str, Any]]:
+        """
+        Get a cached flag if it exists and is not expired.
+
+        Returns:
+            Flag data dict if cached and fresh.
+            None if not cached or expired.
+        """
+        with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            if entry.is_expired(self._ttl):
+                return None
+            return entry.data
+
+    def get_stale(self, key: str) -> Optional[Dict[str, Any]]:
+        """
+        Get a cached flag even if expired.
+        Used as fallback when Redis is unreachable.
+
+        Returns:
+            Flag data dict if it exists in cache at all.
+            None if never cached.
+        """
+        with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            return entry.data
+
+    def set(self, key: str, data: Dict[str, Any]) -> None:
+        """
+        Store flag data in cache.
+
+        Args:
+            key: Cache key — typically the Redis flag key
+            data: Flag data dict from Redis HGETALL
+        """
+        with self._lock:
+            self._store[key] = CacheEntry(data=data)
+
+    def delete(self, key: str) -> None:
+        """
+        Remove a flag from cache.
+        Called when a flag is updated or deleted
+        so the next read fetches fresh data from Redis.
+        """
+        with self._lock:
+            self._store.pop(key, None)
+
+    def clear(self) -> None:
+        """
+        Remove all entries from cache.
+        Useful for testing and for forcing a full refresh.
+        """
+        with self._lock:
+            self._store.clear()
+
+    def size(self) -> int:
+        """Number of entries currently in cache."""
+        with self._lock:
+            return len(self._store)
+
+    def preload(self, flags: Dict[str, Dict[str, Any]]) -> None:
+        """
+        Load multiple flags into cache at once.
+        Called on SDK startup to pre-warm the cache.
+
+        Args:
+            flags: Dict of {cache_key: flag_data}
+        """
+        with self._lock:
+            for key, data in flags.items():
+                self._store[key] = CacheEntry(data=data)

redis_feature_flags-0.1.0/redis_feature_flags/client.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Any
+
+import redis
+
+from .cache import LocalCache
+from .cohorts import CohortManager
+from .evaluator import Evaluator
+from .exceptions import FlagNotFoundError, InvalidRolloutError
+from .schema import SchemaKeys
+from .utils import now_unix
+
+
+class FeatureFlags:
+    """
+    Main entry point for redis-feature-flags.
+
+    Usage:
+        import redis
+        from redis_feature_flags import FeatureFlags
+
+        r = redis.Redis()
+        flags = FeatureFlags(r)
+
+        flags.create("dark_mode", rollout=10)
+        flags.is_enabled("dark_mode", user_id="alice")
+    """
+
+    SCHEMA_VERSION = "1"
+
+    def __init__(
+        self,
+        redis_client: redis.Redis,
+        env: str = "prod",
+        cache_ttl: int = 30,
+    ):
+        self._redis = redis_client
+        self._schema = SchemaKeys(env=env)
+        self._cache = LocalCache(ttl_seconds=cache_ttl)
+        self._evaluator = Evaluator(redis_client, self._schema, self._cache)
+        self._cohorts = CohortManager(redis_client, self._schema)
+
+    # ── Core evaluation ────────────────────────────────────────
+
+    def is_enabled(
+        self,
+        flag_name: str,
+        user_id: str,
+        default: bool = False,
+    ) -> bool:
+        return self._evaluator.is_enabled(flag_name, user_id, default)
+
+    # ── Flag management ────────────────────────────────────────
+
+    def create(
+        self,
+        flag_name: str,
+        rollout: int = 0,
+        created_by: str = "unknown",
+    ) -> None:
+        if not 0 <= rollout <= 100:
+            raise InvalidRolloutError(rollout)
+        ts = str(now_unix())
+        self._redis.hset(
+            self._schema.flag(flag_name),
+            mapping={
+                "enabled":      "0",
+                "rollout":      str(rollout),
+                "expires_at":   "0",
+                "created_at":   ts,
+                "updated_at":   ts,
+                "created_by":   created_by,
+                "updated_by":   created_by,
+                "flag_version": "1",
+            },
+        )
+        self._redis.sadd(self._schema.flags_index(), flag_name)
+
+    def enable(self, flag_name: str, updated_by: str = "unknown") -> None:
+        self._assert_exists(flag_name)
+        self._redis.hset(
+            self._schema.flag(flag_name),
+            mapping={
+                "enabled":    "1",
+                "updated_at": str(now_unix()),
+                "updated_by": updated_by,
+            },
+        )
+        self._cache.delete(self._schema.flag(flag_name))
+
+    def disable(self, flag_name: str, updated_by: str = "unknown") -> None:
+        self._assert_exists(flag_name)
+        self._redis.hset(
+            self._schema.flag(flag_name),
+            mapping={
+                "enabled":    "0",
+                "updated_at": str(now_unix()),
+                "updated_by": updated_by,
+            },
+        )
+        self._cache.delete(self._schema.flag(flag_name))
+
+    def set_rollout(
+        self,
+        flag_name: str,
+        percent: int,
+        updated_by: str = "unknown",
+    ) -> None:
+        if not 0 <= percent <= 100:
+            raise InvalidRolloutError(percent)
+        self._assert_exists(flag_name)
+        self._redis.hset(
+            self._schema.flag(flag_name),
+            mapping={
+                "rollout":    str(percent),
+                "updated_at": str(now_unix()),
+                "updated_by": updated_by,
+            },
+        )
+        self._cache.delete(self._schema.flag(flag_name))
+
+    def delete(self, flag_name: str) -> None:
+        self._redis.delete(self._schema.flag(flag_name))
+        self._redis.delete(self._schema.flag_users(flag_name))
+        self._redis.delete(self._schema.flag_cohorts(flag_name))
+        self._redis.delete(self._schema.flag_history(flag_name))
+        self._redis.srem(self._schema.flags_index(), flag_name)
+        self._cache.delete(self._schema.flag(flag_name))
+
+    def list_flags(self) -> List[str]:
+        flags = self._redis.smembers(self._schema.flags_index())
+        return sorted([f.decode() for f in flags])
+
+    def get(self, flag_name: str) -> Dict[str, Any]:
+        self._assert_exists(flag_name)
+        data = self._redis.hgetall(self._schema.flag(flag_name))
+        return {k.decode(): v.decode() for k, v in data.items()}
+
+    # ── User targeting ─────────────────────────────────────────
+
+    def add_user(self, flag_name: str, user_id: str) -> None:
+        self._assert_exists(flag_name)
+        self._redis.sadd(self._schema.flag_users(flag_name), user_id)
+
+    def remove_user(self, flag_name: str, user_id: str) -> None:
+        self._redis.srem(self._schema.flag_users(flag_name), user_id)
+
+    # ── Cohort targeting ───────────────────────────────────────
+
+    def create_cohort(self, cohort_name: str) -> None:
+        self._cohorts.create(cohort_name)
+
+    def add_to_cohort(self, cohort_name: str, user_id: str) -> None:
+        self._cohorts.add_user(cohort_name, user_id)
+
+    def remove_from_cohort(self, cohort_name: str, user_id: str) -> None:
+        self._cohorts.remove_user(cohort_name, user_id)
+
+    def add_cohort_to_flag(self, flag_name: str, cohort_name: str) -> None:
+        self._assert_exists(flag_name)
+        self._redis.sadd(self._schema.flag_cohorts(flag_name), cohort_name)
+
+    def remove_cohort_from_flag(
+        self, flag_name: str, cohort_name: str
+    ) -> None:
+        self._redis.srem(self._schema.flag_cohorts(flag_name), cohort_name)
+
+    # ── Private helpers ────────────────────────────────────────
+
+    def _assert_exists(self, flag_name: str) -> None:
+        if not self._redis.exists(self._schema.flag(flag_name)):
+            raise FlagNotFoundError(flag_name)

redis_feature_flags-0.1.0/redis_feature_flags/cohorts.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import redis
+
+from .exceptions import CohortNotFoundError
+from .schema import SchemaKeys
+
+
+class CohortManager:
+    """
+    Manages cohorts in Redis.
+
+    A cohort is a named group of users — e.g. beta-testers, premium-users.
+    Flags can target entire cohorts instead of individual users.
+
+    Uses a bidirectional index:
+      Direction 1 — ff:{env}:cohort:{name}        → Set of user_ids
+      Direction 2 — ff:{env}:user:{id}:cohorts    → Set of cohort names
+
+    Direction 1 answers: "who is in this cohort?" (management)
+    Direction 2 answers: "which cohorts does this user belong to?" (evaluation)
+    Both directions must always stay in sync.
+    """
+
+    def __init__(
+        self,
+        redis_client: redis.Redis,
+        schema: SchemaKeys,
+    ):
+        self._redis = redis_client
+        self._schema = schema
+
+    def create(self, cohort_name: str) -> None:
+        """
+        Register a cohort name in the cohorts index.
+
+        Adds cohort_name to ff:{env}:cohorts:__index__ so it
+        appears in list_cohorts() without needing a KEYS * scan.
+        Does not add any members — cohort starts empty.
+        """
+        self._redis.sadd(self._schema.cohorts_index(), cohort_name)
+
+    def delete(self, cohort_name: str) -> None:
+        """
+        Fully remove a cohort from Redis — cleans up all three locations.
+
+        Step 1 — get all members before deleting
+                so we can clean their reverse index keys.
+
+        Step 2 — pipeline all removals atomically:
+            a. Remove cohort name from every member's reverse index
+            ff:{env}:user:{user_id}:cohorts
+            b. Delete the cohort members Set
+            ff:{env}:cohort:{name}
+            c. Remove cohort name from the cohorts index
+            ff:{env}:cohorts:__index__
+
+        Note: does NOT clean up flag cohort Sets that reference this cohort.
+            ff:{env}:flag:{name}:cohorts may still contain this cohort name.
+            Evaluation is unaffected — SINTER finds no match once the cohort
+            is gone from the user reverse index.
+            Full flag cleanup is planned for v2.
+        """
+        members = self._redis.smembers(self._schema.cohort(cohort_name))
+
+        pipe = self._redis.pipeline()
+        for member in members:
+            pipe.srem(self._schema.user_cohorts(member.decode()), cohort_name)
+        pipe.delete(self._schema.cohort(cohort_name))
+        pipe.srem(self._schema.cohorts_index(), cohort_name)
+        pipe.execute()
+
+    def add_user(self, cohort_name: str, user_id: str) -> None:
+        """
+        Add a user to a cohort — writes both directions atomically.
+
+        Uses a Redis pipeline to send both commands in one round trip
+        and execute them together — either both succeed or both fail.
+
+        Line 1 — direction 1 (cohort → members):
+            SADD ff:{env}:cohort:{name} {user_id}
+
+        Line 2 — direction 2 (user → cohorts) reverse index:
+            SADD ff:{env}:user:{user_id}:cohorts {cohort_name}
+
+        Direction 2 is what makes evaluation fast — SINTER can find
+        cohort matches in one Redis call instead of checking each cohort.
+        """
+        pipe = self._redis.pipeline()
+        pipe.sadd(self._schema.cohort(cohort_name), user_id)
+        pipe.sadd(self._schema.user_cohorts(user_id), cohort_name)
+        pipe.execute()
+
+    def remove_user(self, cohort_name: str, user_id: str) -> None:
+        """
+        Remove a user from a cohort — removes both directions atomically.
+
+        Uses a Redis pipeline — both removals happen together.
+
+        Line 1 — removes user from cohort members Set:
+            SREM ff:{env}:cohort:{name} {user_id}
+
+        Line 2 — removes cohort from user's reverse index:
+            SREM ff:{env}:user:{user_id}:cohorts {cohort_name}
+
+        Both directions must be removed to keep the index consistent.
+        """
+        pipe = self._redis.pipeline()
+        pipe.srem(self._schema.cohort(cohort_name), user_id)
+        pipe.srem(self._schema.user_cohorts(user_id), cohort_name)
+        pipe.execute()
+
+    def get_members(self, cohort_name: str) -> set:
+        """
+        Return all user_ids in a cohort as a Python set of strings.
+
+        Reads from direction 1 — ff:{env}:cohort:{name}.
+        Redis returns bytes — decoded to strings before returning.
+        Returns empty set if cohort does not exist.
+
+        Used for management — e.g. CLI command "show me who is in beta-testers".
+        Not used during flag evaluation — direction 2 is used there instead.
+        """
+        members = self._redis.smembers(self._schema.cohort(cohort_name))
+        return {m.decode() for m in members}
+
+    def list_cohorts(self) -> list:
+        """
+        Return all cohort names as a Python list of strings.
+
+        Reads from ff:{env}:cohorts:__index__ — the cohort name registry.
+        Redis returns bytes — decoded to strings before returning.
+
+        Safe to call in production — reads one Set key, no KEYS * scan.
+        """
+        cohorts = self._redis.smembers(self._schema.cohorts_index())
+        return [c.decode() for c in cohorts]
+
+    def exists(self, cohort_name: str) -> bool:
+        """
+        Check if a cohort name is registered in the index.
+
+        Uses SISMEMBER on ff:{env}:cohorts:__index__ — O(1) lookup.
+        Returns True if cohort exists, False otherwise.
+
+        Note: a cohort can exist in the index but have zero members.
+        exists() only checks registration — not whether it has members.
+        """
+        return bool(
+            self._redis.sismember(
+                self._schema.cohorts_index(), cohort_name
+            )
+        )