---

Switcher Client SDK
A Python SDK for Switcher API

---

---

Table of Contents

• 🚀 Quick Start
• 📦 Installation
• 🔧 Configuration
• 📖 Usage Examples
• 🎛️ Advanced Features
• 🔄 Snapshot Management
• 🧪 Testing & Development
• 🤝 Contributing

---

🌟 About

The Switcher Client SDK for Python provides seamless integration with Switcher-API, enabling powerful feature flag management in your Python applications.

✨ Key Features

• 🎯 Clean & Maintainable: Flexible and robust functions that keep your code organized
• 🏠 Local Mode: Work offline using snapshot files from your Switcher-API Domain
• 🔄 Silent Mode: Hybrid configuration with automatic fallback for connectivity issues
• 🧪 Built-in Mocking: Easy implementation of automated testing with mock support
• ⚡ Zero Latency: Local snapshot execution for high-performance scenarios
• 🛡️ Secure: Built-in protection against ReDoS attacks with regex safety features
• 📊 Monitoring: Comprehensive logging and error handling capabilities

🚀 Quick Start

Get up and running in just a few lines of code:

from switcher_client import Client

# Initialize the client
Client.build_context(
    domain='My Domain',
    url='https://api.switcherapi.com',
    api_key='[YOUR_API_KEY]',
    component='MyApp',
    environment='default'
)

# Use feature flags
switcher = Client.get_switcher()
if switcher.is_on('FEATURE_TOGGLE'):
    print("Feature is enabled!")

📦 Installation

Install the Switcher Client SDK using pip:

pip install switcher-client

System Requirements

• Python: 3.9+ (supports 3.9, 3.10, 3.11, 3.12, 3.13)
• Operating System: Cross-platform (Windows, macOS, Linux)

🔧 Configuration

Basic Setup

Initialize the Switcher Client with your domain configuration:

from switcher_client import Client

Client.build_context(
    domain='My Domain',                 # Your Switcher domain name
    url='https://api.switcherapi.com',  # Switcher-API endpoint (optional)
    api_key='[YOUR_API_KEY]',           # Your component's API key (optional)
    component='MyApp',                  # Your application name (optional)
    environment='default'               # Environment ('default' for production)
)

switcher = Client.get_switcher()

Configuration Parameters

Parameter	Required	Description	Default
domain	✅	Your Switcher domain name	-
url		Switcher-API endpoint	https://api.switcherapi.com
api_key		API key for your component	-
component		Your application identifier	-
environment		Target environment	default

Advanced Configuration

Enable additional features like local mode, silent mode, and security options:

from switcher_client import Client, ContextOptions

Client.build_context(
    domain='My Domain',
    url='https://api.switcherapi.com',
    api_key='[YOUR_API_KEY]',
    component='MyApp',
    environment='default',
    options=ContextOptions(
        local=True,                              # Enable local mode
        logger=True,                             # 🚧 TODO: Enable logging
        snapshot_location='./snapshot/',         # Snapshot files location
        snapshot_auto_update_interval=3,         # Auto-update interval (seconds)
        silent_mode='5m',                        # 🚧 TODO: Silent mode retry time
        cert_path='./certs/ca.pem'               # 🚧 TODO: Certificate path
    )
)

switcher = Client.get_switcher()

Advanced Options Reference

Option	Type	Description	Default
local	bool	Use local snapshot files only (zero latency)	False
snapshot_location	str	Directory for snapshot files	'./snapshot/'
snapshot_auto_update_interval	int	Auto-update interval in seconds (0 = disabled)	0
regex_safe	bool	Enable ReDoS attack protection	True
regex_max_black_list	int	Max cached entries for failed regex	50
regex_max_time_limit	int	Regex execution time limit (ms)	3000

🔒 Security Features

• ReDoS Protection: The regex_safe feature prevents Regular Expression Denial of Service attacks
• Certificate Support: Use custom certificates for secure API connections
• Time Limits: Configurable timeouts prevent long-running regex operations

⚠️ Security Note: Keep regex_safe enabled to protect against ReDoS attacks

📖 Usage Examples

Basic Feature Flag Checking

The simplest way to check if a feature is enabled:

switcher = Client.get_switcher()

# Simple boolean check
if switcher.is_on('FEATURE_LOGIN_V2'):
    # Use new login system
    new_login()
else:
    # Use legacy login
    legacy_login()

Detailed Response Information

Get comprehensive information about the feature flag evaluation:

response = switcher.is_on_with_details('FEATURE_LOGIN_V2')

print(f"Feature enabled: {response.result}")     # True or False
print(f"Reason: {response.reason}")              # Evaluation reason
print(f"Metadata: {response.metadata}")          # Additional context

Strategy-Based Feature Flags

Method 1: Prepare and Execute

Load validation data separately, useful for complex applications:

# Prepare the validation context
switcher.check_value('USER_123').prepare('USER_FEATURE')

# Execute when ready
if switcher.is_on():
    enable_user_feature()

Method 2: All-in-One Execution

Chain multiple validation strategies for comprehensive feature control:

# Validate user, network, and other criteria in one call
is_enabled = switcher.check_value('premium_user') \
                    .check_network('192.168.1.0/24') \
                    .is_on('PREMIUM_FEATURES')

if is_enabled:
    show_premium_dashboard()

Error Handling

Subscribe to error notifications for robust error management:

# Set up error handling
Client.subscribe_notify_error(lambda error: print(f"Switcher Error: {error}"))

🎛️ Advanced Features

🚧 Planned Features

The following features are currently in development:

Throttling (Coming Soon)

# 🚧 TODO: Zero-latency async execution
switcher.throttle(1000).is_on('FEATURE01')

Hybrid Mode (Coming Soon)

# 🚧 TODO: Force remote resolution for specific features
switcher.remote().is_on('FEATURE01')

🔄 Snapshot Management

Loading Snapshots

Load configuration snapshots from the API for local/offline usage:

# Download and save snapshot from API
Client.load_snapshot()

Version Management

Check your current snapshot version:

# Verify snapshot version
version_info = Client.check_snapshot()
print(f"Current snapshot version: {Client.snapshot_version()}")

Automated Updates

Schedule automatic snapshot updates for zero-latency local mode:

Client.schedule_snapshot_auto_update(
    interval=60,
    callback=lambda error, updated: (
        print(f"Snapshot updated to version: {Client.snapshot_version()}") if updated else None
    )
)

🚧 Snapshot Monitoring (Coming Soon)

# 🚧 TODO: Watch for snapshot file changes
Client.watch_snapshot({
    'success': lambda: print('In-memory snapshot updated'),
    'reject': lambda err: print(f'Update failed: {err}')
})

🧪 Testing & Development

Built-in Mocking (Coming Soon)

🚧 Note: The mocking features are currently under development

The SDK will include powerful mocking capabilities for testing:

# 🚧 TODO: Mock feature states for testing
Client.assume('FEATURE01').true()
assert switcher.is_on('FEATURE01') == True

Client.forget('FEATURE01')  # Reset to normal behavior

# 🚧 TODO: Mock with metadata
Client.assume('FEATURE01').false().with_metadata({
    'message': 'Feature is disabled'
})
response = switcher.is_on_with_details('FEATURE01')
assert response.result == False
assert response.metadata['message'] == 'Feature is disabled'

Test Mode Configuration

# 🚧 TODO: Enable test mode to prevent file locking
Client.enable_test_mode()

Configuration Validation

Validate your feature flag configuration before deployment:

# Verify that all required switchers are configured
try:
    Client.check_switchers(['FEATURE_LOGIN', 'FEATURE_DASHBOARD', 'FEATURE_PAYMENTS'])
    print("✅ All switchers are properly configured")
except Exception as e:
    print(f"❌ Configuration error: {e}")

This validation helps prevent deployment issues by ensuring all required feature flags are properly set up in your Switcher domain.

🤝 Contributing

We welcome contributions to the Switcher Client SDK for Python! If you have suggestions, improvements, or bug fixes, please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and commit them with clear messages.
4. Submit a pull request detailing your changes and the problem they solve.

Thank you for helping us improve the Switcher Client SDK!

Requirements

• Python 3.9 or higher
• Virtualenv - pip install virtualenv
• Create a virtual environment - python3 -m venv .venv
• Install Pipenv - pip install pipenv
• Check Makefile for all available commands