flaglite 1.0.0__py3-none-any.whl

flaglite/__init__.py

@@ -0,0 +1,44 @@
+"""FlagLite Python SDK.
+
+A lightweight, production-ready Python client for the FlagLite feature flag service.
+
+Example:
+    ```python
+    from flaglite import FlagLite
+
+    flags = FlagLite()  # Auto-init from FLAGLITE_API_KEY env var
+
+    # Async usage
+    if await flags.enabled('new-checkout'):
+        show_new_checkout()
+
+    # With user ID for percentage rollouts
+    if await flags.enabled('new-checkout', user_id='user-123'):
+        show_new_checkout()
+
+    # Sync usage
+    if flags.enabled_sync('new-checkout'):
+        show_new_checkout()
+    ```
+"""
+
+from .client import FlagLite
+from .exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    FlagLiteError,
+    NetworkError,
+    RateLimitError,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "FlagLite",
+    "FlagLiteError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NetworkError",
+    "ConfigurationError",
+    "__version__",
+]

flaglite/cache.py

@@ -0,0 +1,137 @@
+"""TTL cache for flag evaluations."""
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Dict, Optional, Tuple
+
+
+@dataclass
+class CacheEntry:
+    """A cached flag evaluation result."""
+
+    value: bool
+    expires_at: float
+
+
+class TTLCache:
+    """Thread-safe TTL cache for flag evaluations.
+
+    Keys are stored as (flag_key, user_id) tuples to support
+    user-specific flag evaluations.
+    """
+
+    def __init__(self, ttl_seconds: float = 30.0) -> None:
+        """Initialize cache with TTL in seconds.
+
+        Args:
+            ttl_seconds: Time-to-live for cache entries. Default 30 seconds.
+        """
+        self._ttl = ttl_seconds
+        self._cache: Dict[Tuple[str, Optional[str]], CacheEntry] = {}
+        self._lock = asyncio.Lock()
+
+    @property
+    def ttl(self) -> float:
+        """Return the cache TTL in seconds."""
+        return self._ttl
+
+    def _make_key(self, flag_key: str, user_id: Optional[str]) -> Tuple[str, Optional[str]]:
+        """Create a cache key from flag key and user ID."""
+        return (flag_key, user_id)
+
+    async def get(self, flag_key: str, user_id: Optional[str] = None) -> Optional[bool]:
+        """Get a cached value if it exists and hasn't expired.
+
+        Args:
+            flag_key: The feature flag key.
+            user_id: Optional user ID for user-specific evaluations.
+
+        Returns:
+            The cached boolean value, or None if not found/expired.
+        """
+        key = self._make_key(flag_key, user_id)
+        async with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                return None
+            if time.monotonic() > entry.expires_at:
+                # Entry expired, remove it
+                del self._cache[key]
+                return None
+            return entry.value
+
+    async def set(
+        self, flag_key: str, value: bool, user_id: Optional[str] = None
+    ) -> None:
+        """Cache a flag evaluation result.
+
+        Args:
+            flag_key: The feature flag key.
+            value: The evaluation result.
+            user_id: Optional user ID for user-specific evaluations.
+        """
+        key = self._make_key(flag_key, user_id)
+        expires_at = time.monotonic() + self._ttl
+        async with self._lock:
+            self._cache[key] = CacheEntry(value=value, expires_at=expires_at)
+
+    async def invalidate(
+        self, flag_key: str, user_id: Optional[str] = None
+    ) -> None:
+        """Remove a specific entry from the cache.
+
+        Args:
+            flag_key: The feature flag key.
+            user_id: Optional user ID for user-specific evaluations.
+        """
+        key = self._make_key(flag_key, user_id)
+        async with self._lock:
+            self._cache.pop(key, None)
+
+    async def clear(self) -> None:
+        """Clear all entries from the cache."""
+        async with self._lock:
+            self._cache.clear()
+
+    async def cleanup_expired(self) -> int:
+        """Remove all expired entries from the cache.
+
+        Returns:
+            Number of entries removed.
+        """
+        now = time.monotonic()
+        removed = 0
+        async with self._lock:
+            expired_keys = [
+                key for key, entry in self._cache.items() if now > entry.expires_at
+            ]
+            for key in expired_keys:
+                del self._cache[key]
+                removed += 1
+        return removed
+
+    def get_sync(self, flag_key: str, user_id: Optional[str] = None) -> Optional[bool]:
+        """Synchronous version of get() for sync wrapper.
+
+        Note: Not thread-safe with async operations. Only use from sync context.
+        """
+        key = self._make_key(flag_key, user_id)
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+        if time.monotonic() > entry.expires_at:
+            del self._cache[key]
+            return None
+        return entry.value
+
+    def set_sync(
+        self, flag_key: str, value: bool, user_id: Optional[str] = None
+    ) -> None:
+        """Synchronous version of set() for sync wrapper.
+
+        Note: Not thread-safe with async operations. Only use from sync context.
+        """
+        key = self._make_key(flag_key, user_id)
+        expires_at = time.monotonic() + self._ttl
+        self._cache[key] = CacheEntry(value=value, expires_at=expires_at)

flaglite/client.py

@@ -0,0 +1,411 @@
+"""FlagLite SDK client implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from typing import Optional
+from urllib.parse import urlencode, urljoin
+
+import httpx
+
+from .cache import TTLCache
+from .exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    FlagLiteError,
+    NetworkError,
+    RateLimitError,
+)
+
+logger = logging.getLogger("flaglite")
+
+DEFAULT_BASE_URL = "https://api.flaglite.dev/v1"
+DEFAULT_CACHE_TTL = 30.0  # 30 seconds
+DEFAULT_TIMEOUT = 5.0  # 5 seconds
+
+
+class FlagLite:
+    """FlagLite feature flag client.
+
+    A lightweight, production-ready client for the FlagLite feature flag service.
+    Supports both async and sync usage patterns with built-in caching.
+
+    Example:
+        ```python
+        from flaglite import FlagLite
+
+        # Async usage
+        flags = FlagLite()  # Auto-init from FLAGLITE_API_KEY env var
+
+        if await flags.enabled('new-checkout'):
+            show_new_checkout()
+
+        # With user ID for percentage rollouts
+        if await flags.enabled('new-checkout', user_id='user-123'):
+            show_new_checkout()
+
+        # Sync usage
+        if flags.enabled_sync('new-checkout'):
+            show_new_checkout()
+        ```
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        cache_ttl: float = DEFAULT_CACHE_TTL,
+        timeout: float = DEFAULT_TIMEOUT,
+        disable_cache: bool = False,
+    ) -> None:
+        """Initialize the FlagLite client.
+
+        Args:
+            api_key: FlagLite environment API key. If not provided, reads from
+                FLAGLITE_API_KEY environment variable.
+            base_url: API base URL. Defaults to https://api.flaglite.dev/v1.
+                Can also be set via FLAGLITE_BASE_URL env var.
+            cache_ttl: Cache time-to-live in seconds. Default 30 seconds.
+                Set to 0 or use disable_cache=True to disable caching.
+            timeout: HTTP request timeout in seconds. Default 5 seconds.
+            disable_cache: If True, disable caching entirely.
+
+        Raises:
+            ConfigurationError: If no API key is provided or found in environment.
+        """
+        # Resolve API key
+        self._api_key = api_key or os.environ.get("FLAGLITE_API_KEY")
+        if not self._api_key:
+            raise ConfigurationError(
+                "API key required. Pass api_key parameter or set FLAGLITE_API_KEY environment variable."
+            )
+
+        # Resolve base URL
+        self._base_url = (
+            base_url
+            or os.environ.get("FLAGLITE_BASE_URL")
+            or DEFAULT_BASE_URL
+        )
+        if not self._base_url.endswith("/"):
+            self._base_url += "/"
+
+        self._timeout = timeout
+
+        # Initialize cache
+        self._cache_enabled = not disable_cache and cache_ttl > 0
+        self._cache = TTLCache(ttl_seconds=cache_ttl) if self._cache_enabled else None
+
+        # HTTP clients (lazy initialized)
+        self._async_client: Optional[httpx.AsyncClient] = None
+        self._sync_client: Optional[httpx.Client] = None
+
+    @property
+    def cache_ttl(self) -> float:
+        """Return the cache TTL in seconds, or 0 if caching is disabled."""
+        return self._cache.ttl if self._cache else 0.0
+
+    def _get_headers(self) -> dict[str, str]:
+        """Return headers for API requests."""
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "flaglite-python/1.0.0",
+        }
+
+    def _get_async_client(self) -> httpx.AsyncClient:
+        """Get or create the async HTTP client."""
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(
+                base_url=self._base_url,
+                headers=self._get_headers(),
+                timeout=self._timeout,
+            )
+        return self._async_client
+
+    def _get_sync_client(self) -> httpx.Client:
+        """Get or create the sync HTTP client."""
+        if self._sync_client is None:
+            self._sync_client = httpx.Client(
+                base_url=self._base_url,
+                headers=self._get_headers(),
+                timeout=self._timeout,
+            )
+        return self._sync_client
+
+    async def close(self) -> None:
+        """Close the HTTP clients and release resources.
+
+        Should be called when you're done using the client, especially in
+        long-running applications.
+        """
+        if self._async_client:
+            await self._async_client.aclose()
+            self._async_client = None
+        if self._sync_client:
+            self._sync_client.close()
+            self._sync_client = None
+
+    def close_sync(self) -> None:
+        """Synchronous version of close()."""
+        if self._sync_client:
+            self._sync_client.close()
+            self._sync_client = None
+        # Note: Can't close async client from sync context safely
+        # It will be garbage collected
+
+    async def __aenter__(self) -> FlagLite:
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    def __enter__(self) -> FlagLite:
+        """Sync context manager entry."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Sync context manager exit."""
+        self.close_sync()
+
+    async def enabled(
+        self,
+        flag_key: str,
+        user_id: Optional[str] = None,
+        default: bool = False,
+    ) -> bool:
+        """Check if a feature flag is enabled.
+
+        This is the primary method for checking feature flags. Results are cached
+        according to the cache_ttl setting.
+
+        Args:
+            flag_key: The unique flag key (e.g., 'new-checkout').
+            user_id: Optional user ID for consistent percentage rollouts.
+                When provided, the same user always gets the same result
+                for a given flag (sticky bucketing).
+            default: Value to return on error. Defaults to False (fail closed).
+
+        Returns:
+            True if the flag is enabled, False otherwise.
+
+        Note:
+            This method never raises exceptions. On any error (network, auth, etc.),
+            it returns the default value and logs the error.
+        """
+        # Check cache first
+        if self._cache:
+            cached = await self._cache.get(flag_key, user_id)
+            if cached is not None:
+                logger.debug(f"Cache hit for flag '{flag_key}' (user={user_id})")
+                return cached
+
+        # Make API request
+        try:
+            result = await self._evaluate_flag(flag_key, user_id)
+
+            # Cache the result
+            if self._cache:
+                await self._cache.set(flag_key, result, user_id)
+
+            return result
+
+        except FlagLiteError as e:
+            logger.warning(f"FlagLite error evaluating '{flag_key}': {e.message}")
+            return default
+        except Exception as e:
+            logger.warning(f"Unexpected error evaluating flag '{flag_key}': {e}")
+            return default
+
+    async def _evaluate_flag(
+        self, flag_key: str, user_id: Optional[str] = None
+    ) -> bool:
+        """Make the actual API request to evaluate a flag.
+
+        Args:
+            flag_key: The flag key to evaluate.
+            user_id: Optional user ID for percentage rollouts.
+
+        Returns:
+            The flag evaluation result.
+
+        Raises:
+            AuthenticationError: If the API key is invalid.
+            RateLimitError: If rate limit is exceeded.
+            NetworkError: If a network error occurs.
+            FlagLiteError: For other API errors.
+        """
+        client = self._get_async_client()
+
+        # Build URL with query params
+        url = f"flags/{flag_key}"
+        if user_id:
+            url = f"{url}?{urlencode({'user_id': user_id})}"
+
+        try:
+            response = await client.get(url)
+        except httpx.TimeoutException as e:
+            raise NetworkError(f"Request timed out: {e}") from e
+        except httpx.NetworkError as e:
+            raise NetworkError(f"Network error: {e}") from e
+        except httpx.HTTPError as e:
+            raise NetworkError(f"HTTP error: {e}") from e
+
+        # Handle response
+        if response.status_code == 200:
+            data = response.json()
+            return bool(data.get("enabled", False))
+
+        if response.status_code == 401:
+            raise AuthenticationError(
+                "Invalid API key", status_code=response.status_code
+            )
+
+        if response.status_code == 404:
+            # Flag not found - per spec, return enabled: false
+            return False
+
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(
+                "Rate limit exceeded",
+                retry_after=int(retry_after) if retry_after else None,
+                status_code=429,
+            )
+
+        # Other errors
+        try:
+            error_data = response.json()
+            message = error_data.get("message", f"HTTP {response.status_code}")
+        except Exception:
+            message = f"HTTP {response.status_code}"
+
+        raise FlagLiteError(message, status_code=response.status_code)
+
+    def enabled_sync(
+        self,
+        flag_key: str,
+        user_id: Optional[str] = None,
+        default: bool = False,
+    ) -> bool:
+        """Synchronous version of enabled().
+
+        Use this method in synchronous code paths. Internally creates an event
+        loop if needed, or uses httpx sync client for efficiency.
+
+        Args:
+            flag_key: The unique flag key.
+            user_id: Optional user ID for consistent percentage rollouts.
+            default: Value to return on error. Defaults to False.
+
+        Returns:
+            True if the flag is enabled, False otherwise.
+        """
+        # Check cache first (sync version)
+        if self._cache:
+            cached = self._cache.get_sync(flag_key, user_id)
+            if cached is not None:
+                logger.debug(f"Cache hit for flag '{flag_key}' (user={user_id})")
+                return cached
+
+        # Make sync API request
+        try:
+            result = self._evaluate_flag_sync(flag_key, user_id)
+
+            # Cache the result (sync version)
+            if self._cache:
+                self._cache.set_sync(flag_key, result, user_id)
+
+            return result
+
+        except FlagLiteError as e:
+            logger.warning(f"FlagLite error evaluating '{flag_key}': {e.message}")
+            return default
+        except Exception as e:
+            logger.warning(f"Unexpected error evaluating flag '{flag_key}': {e}")
+            return default
+
+    def _evaluate_flag_sync(
+        self, flag_key: str, user_id: Optional[str] = None
+    ) -> bool:
+        """Synchronous version of _evaluate_flag().
+
+        Args:
+            flag_key: The flag key to evaluate.
+            user_id: Optional user ID for percentage rollouts.
+
+        Returns:
+            The flag evaluation result.
+
+        Raises:
+            AuthenticationError: If the API key is invalid.
+            RateLimitError: If rate limit is exceeded.
+            NetworkError: If a network error occurs.
+            FlagLiteError: For other API errors.
+        """
+        client = self._get_sync_client()
+
+        # Build URL with query params
+        url = f"flags/{flag_key}"
+        if user_id:
+            url = f"{url}?{urlencode({'user_id': user_id})}"
+
+        try:
+            response = client.get(url)
+        except httpx.TimeoutException as e:
+            raise NetworkError(f"Request timed out: {e}") from e
+        except httpx.NetworkError as e:
+            raise NetworkError(f"Network error: {e}") from e
+        except httpx.HTTPError as e:
+            raise NetworkError(f"HTTP error: {e}") from e
+
+        # Handle response
+        if response.status_code == 200:
+            data = response.json()
+            return bool(data.get("enabled", False))
+
+        if response.status_code == 401:
+            raise AuthenticationError(
+                "Invalid API key", status_code=response.status_code
+            )
+
+        if response.status_code == 404:
+            # Flag not found - per spec, return enabled: false
+            return False
+
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(
+                "Rate limit exceeded",
+                retry_after=int(retry_after) if retry_after else None,
+                status_code=429,
+            )
+
+        # Other errors
+        try:
+            error_data = response.json()
+            message = error_data.get("message", f"HTTP {response.status_code}")
+        except Exception:
+            message = f"HTTP {response.status_code}"
+
+        raise FlagLiteError(message, status_code=response.status_code)
+
+    async def invalidate_cache(
+        self, flag_key: str, user_id: Optional[str] = None
+    ) -> None:
+        """Invalidate a cached flag value.
+
+        Args:
+            flag_key: The flag key to invalidate.
+            user_id: Optional user ID to invalidate a specific user's cache.
+        """
+        if self._cache:
+            await self._cache.invalidate(flag_key, user_id)
+
+    async def clear_cache(self) -> None:
+        """Clear the entire flag cache."""
+        if self._cache:
+            await self._cache.clear()

flaglite/exceptions.py

@@ -0,0 +1,43 @@
+"""FlagLite SDK exceptions."""
+
+from typing import Optional
+
+
+class FlagLiteError(Exception):
+    """Base exception for FlagLite SDK errors."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+
+class AuthenticationError(FlagLiteError):
+    """Raised when API key is invalid or missing."""
+
+    pass
+
+
+class RateLimitError(FlagLiteError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[int] = None,
+        status_code: int = 429,
+    ) -> None:
+        super().__init__(message, status_code)
+        self.retry_after = retry_after
+
+
+class NetworkError(FlagLiteError):
+    """Raised when a network error occurs."""
+
+    pass
+
+
+class ConfigurationError(FlagLiteError):
+    """Raised when SDK is misconfigured."""
+
+    pass

flaglite-1.0.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: flaglite
+Version: 1.0.0
+Summary: Lightweight Python SDK for FlagLite feature flags
+Project-URL: Homepage, https://flaglite.dev
+Project-URL: Documentation, https://docs.flaglite.dev/sdks/python
+Project-URL: Repository, https://github.com/faiscadev/flaglite-py
+Project-URL: Issues, https://github.com/faiscadev/flaglite-py/issues
+Author-email: FlagLite <support@flaglite.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: feature-flags,feature-toggles,flaglite,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FlagLite Python SDK
+
+A lightweight, production-ready Python client for the [FlagLite](https://flaglite.dev) feature flag service.
+
+[![PyPI version](https://badge.fury.io/py/flaglite.svg)](https://badge.fury.io/py/flaglite)
+[![Python versions](https://img.shields.io/pypi/pyversions/flaglite.svg)](https://pypi.org/project/flaglite/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ✅ **Simple API** - One method to check flags: `enabled()`
+- ✅ **Async/Await** - Native asyncio support
+- ✅ **Sync Support** - Use `enabled_sync()` in synchronous code
+- ✅ **Built-in Caching** - 30-second TTL cache (configurable)
+- ✅ **Fail Closed** - Returns `False` on errors by default
+- ✅ **Type Hints** - Full type annotations for IDE support
+- ✅ **Percentage Rollouts** - Sticky bucketing with user IDs
+- ✅ **Production Ready** - Comprehensive error handling
+
+## Installation
+
+```bash
+pip install flaglite
+```
+
+## Quick Start
+
+### 1. Set your API key
+
+```bash
+export FLAGLITE_API_KEY=ffl_env_your_api_key_here
+```
+
+### 2. Check feature flags
+
+```python
+from flaglite import FlagLite
+
+flags = FlagLite()  # Auto-init from FLAGLITE_API_KEY env var
+
+# Async usage
+if await flags.enabled('new-checkout'):
+    show_new_checkout()
+else:
+    show_old_checkout()
+```
+
+### 3. Percentage rollouts with user IDs
+
+```python
+# User-specific evaluation for consistent rollouts
+if await flags.enabled('new-checkout', user_id='user-123'):
+    # Same user always gets the same result (sticky bucketing)
+    show_new_checkout()
+```
+
+## Usage Examples
+
+### Async/Await (Recommended)
+
+```python
+import asyncio
+from flaglite import FlagLite
+
+async def main():
+    flags = FlagLite()
+
+    # Simple feature check
+    if await flags.enabled('dark-mode'):
+        enable_dark_mode()
+
+    # With user ID for percentage rollouts
+    if await flags.enabled('new-dashboard', user_id=current_user.id):
+        render_new_dashboard()
+
+    # Don't forget to close when done
+    await flags.close()
+
+asyncio.run(main())
+```
+
+### Context Manager
+
+```python
+async def main():
+    async with FlagLite() as flags:
+        if await flags.enabled('feature-x'):
+            do_something()
+    # Client is automatically closed
+```
+
+### Synchronous Usage
+
+```python
+from flaglite import FlagLite
+
+flags = FlagLite()
+
+# Use enabled_sync() in synchronous code
+if flags.enabled_sync('new-checkout'):
+    show_new_checkout()
+
+# Clean up
+flags.close_sync()
+```
+
+### FastAPI Example
+
+```python
+from fastapi import FastAPI, Depends
+from flaglite import FlagLite
+
+app = FastAPI()
+
+# Create a shared client instance
+flags = FlagLite()
+
+@app.on_event("shutdown")
+async def shutdown():
+    await flags.close()
+
+@app.get("/checkout")
+async def checkout(user_id: str):
+    if await flags.enabled('new-checkout', user_id=user_id):
+        return {"version": "new"}
+    return {"version": "legacy"}
+```
+
+### Django Example
+
+```python
+# settings.py
+from flaglite import FlagLite
+FEATURE_FLAGS = FlagLite()
+
+# views.py
+from django.conf import settings
+
+def my_view(request):
+    if settings.FEATURE_FLAGS.enabled_sync('new-feature'):
+        return render(request, 'new_template.html')
+    return render(request, 'old_template.html')
+```
+
+## Configuration
+
+### Constructor Options
+
+```python
+flags = FlagLite(
+    api_key="ffl_env_...",   # Optional: defaults to FLAGLITE_API_KEY env var
+    base_url="https://...",   # Optional: defaults to FLAGLITE_BASE_URL or production
+    cache_ttl=30.0,           # Cache TTL in seconds (default: 30)
+    timeout=5.0,              # HTTP timeout in seconds (default: 5)
+    disable_cache=False,      # Set True to disable caching
+)
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FLAGLITE_API_KEY` | Your environment API key (required if not passed to constructor) |
+| `FLAGLITE_BASE_URL` | API base URL (optional, for self-hosted) |
+
+### Cache Management
+
+```python
+# Invalidate a specific flag
+await flags.invalidate_cache('my-flag')
+
+# Invalidate a specific user's flag
+await flags.invalidate_cache('my-flag', user_id='user-123')
+
+# Clear entire cache
+await flags.clear_cache()
+```
+
+## Error Handling
+
+The SDK is designed to **fail closed** - it returns `False` on any error by default. This ensures your application continues working even if the flag service is unavailable.
+
+```python
+# Errors are logged but don't raise exceptions
+result = await flags.enabled('my-flag')  # Returns False on error
+
+# Override default value
+result = await flags.enabled('my-flag', default=True)  # Returns True on error
+```
+
+### Exceptions (for direct API access)
+
+If you need to handle errors explicitly, you can catch these exceptions:
+
+```python
+from flaglite import (
+    FlagLiteError,
+    AuthenticationError,
+    RateLimitError,
+    NetworkError,
+    ConfigurationError,
+)
+```
+
+## API Reference
+
+### FlagLite
+
+#### `async enabled(flag_key: str, user_id: str | None = None, default: bool = False) -> bool`
+
+Check if a feature flag is enabled.
+
+- **flag_key**: The unique flag key (e.g., 'new-checkout')
+- **user_id**: Optional user ID for consistent percentage rollouts
+- **default**: Value to return on error (default: False)
+- **Returns**: True if enabled, False otherwise
+
+#### `enabled_sync(flag_key: str, user_id: str | None = None, default: bool = False) -> bool`
+
+Synchronous version of `enabled()`.
+
+#### `async close() -> None`
+
+Close HTTP clients and release resources.
+
+#### `close_sync() -> None`
+
+Synchronous version of `close()`.
+
+#### `async invalidate_cache(flag_key: str, user_id: str | None = None) -> None`
+
+Remove a specific entry from the cache.
+
+#### `async clear_cache() -> None`
+
+Clear the entire flag cache.
+
+## Requirements
+
+- Python 3.9+
+- httpx 0.24+
+
+## CI/CD
+
+This package uses automated CI/CD:
+
+- **CI**: Runs on every push/PR - linting (ruff), type checking (mypy), tests across Python 3.9-3.13
+- **Release**: Tag with `v*` (e.g., `git tag v1.0.0 && git push --tags`) to publish to PyPI
+
+Required repository secrets for releases:
+- `PYPI_TOKEN` - PyPI API token with upload access
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Support
+
+- Documentation: https://docs.flaglite.dev/sdks/python
+- Issues: https://github.com/faiscadev/flaglite-py/issues
+- Email: support@flaglite.dev

flaglite-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+flaglite/__init__.py,sha256=kvWPM7PZWkLQljZPGZVof_gcps-8nQk4kCYORTAGdJU,916
+flaglite/cache.py,sha256=y_YNBwocQvtGF1HpX-eOwkLPJiFUP_3ScXnpn8wovlw,4369
+flaglite/client.py,sha256=eBOEYSTLvZRH3--HJDEmGtA0HEIRR2WYfCR_nV7vKcs,13612
+flaglite/exceptions.py,sha256=l1IbBKibNp_mMwbglbqhyMykdD5SvZYVtNxZ2tW8S1w,943
+flaglite/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flaglite-1.0.0.dist-info/METADATA,sha256=3_1BEM4n-uCSSC_vJ_-sehURnDH8Dm16GI8jXwO0SdY,7855
+flaglite-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+flaglite-1.0.0.dist-info/licenses/LICENSE,sha256=pYWPQAzDymlHrEFlHLRR-jFc8vM0SpvHBN0TDnx4BZg,1065
+flaglite-1.0.0.dist-info/RECORD,,

flaglite-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

flaglite-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlagLite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.