Split.io Python Client

Common errors

• TypeError: type() argument 1 must be string, not unicode

  cause This error typically occurs in older Python 2.7 environments due to issues with the `enum34` dependency being an outdated version.
  fix While `splitio-client` primarily supports Python 3.7+, if encountered in a constrained Python 2.7 environment, ensure `enum34` is version 1.1.5 or above: `pip install 'enum34>=1.1.5'`.

• pip install 'splitio-client[cpphash]' fails with 'command 'g++' failed with exit status 1' on macOS

  cause This is often due to an outdated or incompatible C++ compiler (g++) or issues with `libstdc++` on older macOS versions (e.g., Mojave) when building the `splitmmh3` dependency.
  fix Try `pip install splitio-client` without the `[cpphash]` extra, as the pure Python hashing implementation might work. Alternatively, update your Xcode Command Line Tools or try a different Python environment manager (like Conda) that provides its own compiler toolchain.

• factory instantiation: you passed an empty api_key, api_key must be a non-empty string.

  cause The SDK was initialized with an empty or `None` API key string.
  fix Provide a valid, non-empty SDK API key from your Split.io account. Ensure environment variables or configuration files are correctly populated.

Warnings

• gotcha The SDK might return 'control' for treatments if it's not fully initialized or if a feature flag is not found. Always use `factory.block_until_ready()` with a timeout to ensure data is loaded before evaluation.
  Fix: Call `factory.block_until_ready(timeout_seconds)` after `get_factory()` and handle `TimeoutException`.
• breaking Asynchronous (asyncio) support was introduced in v10.0.0 and requires Python 3.7.16 or later. Previous Python 3.x versions might experience issues with asyncio-specific functionalities.
  Fix: Upgrade Python to 3.7.16 or later if using `asyncio` features. Ensure `get_factory_async` is used for async initialization.
• deprecated The configuration parameter `redisErrors` was deprecated in v10.5.0 as it was removed from the underlying `redis-py` library since v6.0.0.
  Fix: Remove `redisErrors` from your SDK configuration if present. Refer to `redis-py` documentation for equivalent error handling if needed.
• gotcha Using the client after calling `factory.destroy()` will result in 'Client has already been destroyed' errors, and all `getTreatment` calls will return 'control' or map of controls.
  Fix: Ensure `factory.destroy()` is called only during application shutdown. Do not use the client object after the factory has been destroyed.
• gotcha Rule-based segments are only fully supported from SDK versions 10.4.0 and above. Older SDK versions will return the 'control' treatment for flags configured with rule-based segments and log a specific impression label.
  Fix: Upgrade to `splitio-client` v10.4.0 or later to correctly evaluate rule-based segments.

Install

• pip install splitio-client Standard installation
• pip install 'splitio-client[cpphash,asyncio]' With C++ hashing and asyncio support

Imports

• get_factory

  from splitio import get_factory

• TimeoutException

  from splitio.exceptions import TimeoutException

• get_factory_async

  from splitio import get_factory_async

  For asynchronous (asyncio) factory initialization.

Quickstart

This quickstart demonstrates how to initialize the Split.io Python SDK, wait for it to be ready, and retrieve a treatment for a specific feature flag and user key. It also includes basic error handling for timeouts and ensures proper shutdown of the SDK factory.

import os
from splitio import get_factory
from splitio.exceptions import TimeoutException

# Get your SDK API key from environment variables for security
SPLIT_API_KEY = os.environ.get('SPLIT_SDK_API_KEY', 'YOUR_SDK_TYPE_API_KEY')
CUSTOMER_ID = 'test_user_123'
FEATURE_FLAG_NAME = 'my_new_feature'

# Initialize the Split factory
# For production, ensure config is properly set up, e.g., for logging, storage, etc.
factory = get_factory(SPLIT_API_KEY)

try:
    # Wait up to 5 seconds for the SDK to be ready and download definitions
    factory.block_until_ready(5)
    split_client = factory.client()

    # Get treatment for the customer
    treatment = split_client.get_treatment(CUSTOMER_ID, FEATURE_FLAG_NAME)

    if treatment == 'on':
        print(f"Feature '{FEATURE_FLAG_NAME}' is ON for user '{CUSTOMER_ID}'.")
        # Code to show 'on' treatment
    elif treatment == 'off':
        print(f"Feature '{FEATURE_FLAG_NAME}' is OFF for user '{CUSTOMER_ID}'.")
        # Code to show 'off' treatment
    else:
        # 'control' or any other undefined treatment
        print(f"Feature '{FEATURE_FLAG_NAME}' is in CONTROL for user '{CUSTOMER_ID}'.")
        # Code for default/control treatment

except TimeoutException:
    print("Split SDK timed out while initializing. Falling back to control.")
    # Handle timeout gracefully, e.g., log and proceed with default experience
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # It's important to destroy the factory when the application shuts down
    # to ensure all queued impressions/events are sent and resources are released.
    factory.destroy()