chore: add examples

Author: tilyupo

examples/README.md

@@ -0,0 +1,119 @@
+# Replane Python SDK Examples
+
+This directory contains example projects demonstrating how to use the Replane Python SDK for feature flags and remote configuration.
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| [basic-sync](./basic-sync) | Basic usage with the synchronous client |
+| [basic-async](./basic-async) | Basic usage with the asynchronous client |
+| [flask-integration](./flask-integration) | Integration with Flask web framework |
+| [fastapi-integration](./fastapi-integration) | Integration with FastAPI framework |
+| [django-integration](./django-integration) | Integration with Django framework |
+| [testing](./testing) | How to test code that uses Replane |
+| [feature-flags](./feature-flags) | Various feature flag patterns and use cases |
+
+## Quick Start
+
+Each example is a standalone project that can be copied and used as a starting point. To run any example:
+
+1. Navigate to the example directory:
+   ```bash
+   cd examples/basic-sync
+   ```
+
+2. Create and activate a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. Update the configuration (BASE_URL and SDK_KEY) in the main file
+
+5. Run the example:
+   ```bash
+   python main.py  # or app.py for web examples
+   ```
+
+## Example Descriptions
+
+### basic-sync
+
+Demonstrates the fundamental usage of `SyncReplaneClient`:
+- Context manager usage
+- Reading feature flags and configs
+- Passing context for override evaluation
+- Default values
+- Manual lifecycle management
+
+### basic-async
+
+Demonstrates the asynchronous `AsyncReplaneClient`:
+- Async context manager usage
+- Real-time update subscriptions
+- Async callbacks
+- Integration with asyncio applications
+
+### flask-integration
+
+Shows how to integrate Replane with a Flask application:
+- Application startup/shutdown lifecycle
+- Building context from request headers
+- Feature flags in route handlers
+- Dynamic rate limits and upload sizes
+
+### fastapi-integration
+
+Shows how to integrate Replane with FastAPI:
+- Lifespan handler for async client
+- Dependency injection
+- Pydantic response models
+- Middleware for maintenance mode
+- Health check endpoints
+
+### django-integration
+
+Shows how to integrate Replane with Django:
+- App initialization in `AppConfig.ready()`
+- Singleton client pattern
+- Custom middleware for maintenance mode
+- Class-based views with feature flags
+- Health check endpoints
+
+### testing
+
+Demonstrates testing patterns using `InMemoryReplaneClient`:
+- Simple test configurations
+- Override rules in tests
+- Pytest fixtures
+- Testing services with dependency injection
+- Subscription testing
+
+### feature-flags
+
+Comprehensive examples of feature flag patterns:
+- Basic on/off toggles
+- User targeting
+- Plan-based limits
+- Regional features
+- Gradual rollouts
+- Environment configs
+- Complex conditions
+- Real-time updates
+
+## Requirements
+
+- Python 3.10 or higher
+- A Replane server (for non-testing examples)
+- An SDK key from your Replane dashboard
+
+## Getting Help
+
+- [Replane Python SDK Documentation](https://github.com/replane-dev/replane-python)
+- [Report Issues](https://github.com/replane-dev/replane-python/issues)

examples/basic-async/README.md

@@ -0,0 +1,51 @@
+# Basic Asynchronous Example
+
+This example demonstrates the basic usage of the Replane Python SDK with the asynchronous client.
+
+## Prerequisites
+
+- Python 3.10 or higher
+- A running Replane server
+- An SDK key from your Replane dashboard
+
+## Setup
+
+1. Create a virtual environment:
+
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+2. Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+3. Update configuration in `main.py`:
+
+```python
+BASE_URL = "https://your-replane-server.com"
+SDK_KEY = "sk_your_sdk_key_here"
+```
+
+## Run
+
+```bash
+python main.py
+```
+
+## What This Example Shows
+
+- Using the `AsyncReplaneClient` with async context manager
+- Reading feature flags and configs (sync read from local cache)
+- Passing context for override evaluation
+- Using default values for missing configs
+- Manual async client lifecycle
+- Subscribing to config changes (sync and async callbacks)
+- Real-time config updates
+
+## Note on `client.get()`
+
+The `get()` method is intentionally synchronous even in the async client because it only reads from the local in-memory cache. There's no I/O involved, so there's no benefit to making it async. The SSE connection that keeps the cache updated runs in a background task.

examples/basic-async/main.py

@@ -0,0 +1,128 @@
+"""Basic asynchronous Replane client example.
+
+This example demonstrates how to use the AsyncReplaneClient
+for async/await applications.
+"""
+
+import asyncio
+
+from replane import AsyncReplaneClient
+
+# Configuration - replace with your actual values
+BASE_URL = "https://your-replane-server.com"
+SDK_KEY = "sk_your_sdk_key_here"
+
+
+async def main():
+    # Using async context manager (recommended)
+    async with AsyncReplaneClient(
+        base_url=BASE_URL,
+        sdk_key=SDK_KEY,
+        # Optional: set default context for all evaluations
+        context={"environment": "production"},
+        # Optional: fallback values if server is unavailable
+        fallbacks={
+            "feature-enabled": False,
+            "max-items": 10,
+        },
+        # Optional: enable debug logging
+        debug=True,
+    ) as client:
+        # Read a boolean feature flag (sync - reads from local cache)
+        is_feature_enabled = client.get("feature-enabled")
+        print(f"Feature enabled: {is_feature_enabled}")
+
+        # Read a numeric config
+        max_items = client.get("max-items")
+        print(f"Max items: {max_items}")
+
+        # Read with context for override evaluation
+        rate_limit = client.get(
+            "rate-limit",
+            context={"plan": "premium", "user_id": "user-123"},
+        )
+        print(f"Rate limit: {rate_limit}")
+
+        # Read with default value if config doesn't exist
+        timeout = client.get("request-timeout", default=30)
+        print(f"Timeout: {timeout}")
+
+        # Keep running to receive real-time updates
+        print("\nListening for config updates (Ctrl+C to stop)...")
+        try:
+            while True:
+                await asyncio.sleep(5)
+                # Re-read to see any updates
+                current_value = client.get("feature-enabled")
+                print(f"Current feature-enabled value: {current_value}")
+        except KeyboardInterrupt:
+            print("\nStopping...")
+
+
+async def example_manual_lifecycle():
+    """Example showing manual connect/close lifecycle."""
+    client = AsyncReplaneClient(
+        base_url=BASE_URL,
+        sdk_key=SDK_KEY,
+    )
+
+    try:
+        # Connect and wait for initial configs
+        await client.connect(wait=True)
+
+        # Now you can read configs
+        value = client.get("my-config")
+        print(f"Config value: {value}")
+
+    finally:
+        # Always close the client when done
+        await client.close()
+
+
+async def example_with_subscriptions():
+    """Example showing how to subscribe to config changes."""
+    async with AsyncReplaneClient(
+        base_url=BASE_URL,
+        sdk_key=SDK_KEY,
+    ) as client:
+        # Subscribe to all config changes
+        def on_any_change(name, config):
+            print(f"Config '{name}' changed to: {config.value}")
+
+        unsubscribe_all = client.subscribe(on_any_change)
+
+        # Subscribe to a specific config
+        def on_feature_change(config):
+            print(f"Feature flag updated: {config.value}")
+
+        unsubscribe_feature = client.subscribe_config("feature-enabled", on_feature_change)
+
+        # Keep running to receive updates
+        print("Listening for changes...")
+        await asyncio.sleep(60)
+
+        # Unsubscribe when done
+        unsubscribe_all()
+        unsubscribe_feature()
+
+
+async def example_async_callback():
+    """Example showing async callbacks for config changes."""
+    async with AsyncReplaneClient(
+        base_url=BASE_URL,
+        sdk_key=SDK_KEY,
+    ) as client:
+        # Async callbacks are supported
+        async def on_change(name, config):
+            print(f"Config '{name}' changed")
+            # Can do async operations here
+            await asyncio.sleep(0.1)
+            print(f"Processed change for '{name}'")
+
+        client.subscribe(on_change)
+
+        await asyncio.sleep(60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/basic-async/requirements.txt

@@ -0,0 +1 @@
+replane[async]

examples/basic-sync/README.md

@@ -0,0 +1,47 @@
+# Basic Synchronous Example
+
+This example demonstrates the basic usage of the Replane Python SDK with the synchronous client.
+
+## Prerequisites
+
+- Python 3.10 or higher
+- A running Replane server
+- An SDK key from your Replane dashboard
+
+## Setup
+
+1. Create a virtual environment:
+
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+2. Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+3. Update configuration in `main.py`:
+
+```python
+BASE_URL = "https://your-replane-server.com"
+SDK_KEY = "sk_your_sdk_key_here"
+```
+
+## Run
+
+```bash
+python main.py
+```
+
+## What This Example Shows
+
+- Using the `SyncReplaneClient` with context manager
+- Reading boolean feature flags
+- Reading numeric configuration values
+- Passing context for override evaluation
+- Using default values for missing configs
+- Manual client lifecycle management
+- Non-blocking connection pattern