---

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, 3.14)
• 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,                             # 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