Amplitude Experiment Python SDK

1.10.1 · active · verified Thu Apr 16

The `amplitude-experiment` library is the official Amplitude Experiment Python SDK for server-side instrumentation, enabling feature flagging and A/B testing. It supports both remote and local evaluation of feature flags. The current version is 1.10.1 and the library maintains an active development cycle with frequent updates and bug fixes.

Common errors

```
NameError: name 'Experiment' is not defined
```
cause The `Experiment` class (or other Amplitude Experiment symbols) was not correctly imported.

fix Ensure you have the correct import statement: `from amplitude_experiment import Experiment, User, RemoteEvaluationConfig, RemoteEvaluationClient`.
```
KeyError: 'YOUR-FLAG-KEY' or AttributeError: 'NoneType' object has no attribute 'value'
```
cause Attempting to access a feature flag variant that does not exist in the fetched variants, or the fetch operation failed to return a variant for the specified key. This could be due to an incorrect flag key, the flag not being enabled for the deployment, or the user not qualifying for any variants.

fix Always check if the variant exists before accessing its properties using `variants.get('YOUR-FLAG-KEY')` or by checking `if variant:` before proceeding. Verify the flag key in your Amplitude Experiment dashboard and ensure the flag is enabled for the correct deployment and user.
```
Failed to connect to host 'api.amplitude.com'
```
cause Network issues preventing the SDK from reaching Amplitude's servers, or an incorrect `server_url` or `server_zone` configuration.

fix Verify your network connectivity. If using an EU data center, ensure `server_zone='EU'` is correctly configured. For custom endpoints, check the `server_url` in your `RemoteEvaluationConfig`.

Warnings

breaking Major version upgrades (e.g., v1.x.x to v2.x.x) typically introduce breaking changes in public interfaces, behaviors, or semantics. Always consult the official upgrade guidelines before updating to a new major version.
Fix: Review the release notes and migration guides for the specific major version you are upgrading to. Test your application thoroughly after any major version update.
gotcha Inconsistent bucketing or 'variant jumping' can occur if the `device_id` or `user_id` used for fetching variants differs from the IDs used to track subsequent exposure events in Amplitude Analytics. This often points to an identity mismatch in implementation.
Fix: Ensure that the `device_id` and `user_id` provided to the `User` object for fetching variants are identical to those used by your Amplitude Analytics instrumentation for tracking events. Implement a consistent identity resolution strategy across your client and server-side SDKs.
gotcha If you are using Amplitude's EU data center, you must explicitly configure the `server_zone` option during client initialization to `'EU'`, otherwise, data will be routed to the US data center by default.
Fix: When initializing your client, pass a `RemoteEvaluationConfig` or `LocalEvaluationConfig` object with `server_zone='EU'`: `Experiment.initialize_remote(API_KEY, config=RemoteEvaluationConfig(server_zone='EU'))`.
gotcha Do not assign a variant a name or value of 'off'. This value is explicitly reserved by Amplitude Experiment for users in the 'OFF/FALLBACK' bucket, which is used when Experiment cannot assign a user to a treatment group.
Fix: Choose alternative names or values for your feature flag variants. Avoid 'off' to prevent unexpected behavior with fallback assignments.

Install

pip install amplitude-experiment Install latest version

Imports

Experiment
wrong:
```
from amplitude_experiment.experiment import Experiment
```
correct:
```
from amplitude_experiment import Experiment
```
The primary `Experiment` class is available directly under the top-level package.
RemoteEvaluationClient
```
from amplitude_experiment import RemoteEvaluationClient
```
Used for remote evaluation, initialized via `Experiment.initialize_remote()`.
LocalEvaluationClient
```
from amplitude_experiment import LocalEvaluationClient
```
Used for local evaluation, initialized via `Experiment.initialize_local()`.
User
```
from amplitude_experiment import User
```
Essential for defining the user context for flag evaluation.
RemoteEvaluationConfig
```
from amplitude_experiment import RemoteEvaluationConfig
```
Configuration options for remote evaluation.
LocalEvaluationConfig
```
from amplitude_experiment import LocalEvaluationConfig
```
Configuration options for local evaluation.

Quickstart

This quickstart demonstrates how to initialize the Amplitude Experiment client for remote evaluation, define a user, fetch feature flag variants, and access a specific flag's value. The API key should be a server-side deployment key. For local evaluation, use `Experiment.initialize_local()` and `experiment.start()` followed by `experiment.evaluate()`.

import os
from amplitude_experiment import Experiment, User

# Get your deployment's API key from environment variables
API_KEY = os.environ.get('AMPLITUDE_EXPERIMENT_API_KEY', 'YOUR_DEPLOYMENT_KEY')

# Initialize the experiment remote evaluation client
# It's recommended to initialize the client once on application startup.
experiment = Experiment.initialize_remote(API_KEY)

# Define a user for whom variants should be fetched
user = User(
    device_id="abcdefg",
    user_id="user@company.com",
    user_properties={'premium': True, 'country': 'USA'}
)

async def get_variants_and_evaluate():
    try:
        # Fetch variants for the user asynchronously
        variants = await experiment.fetch_v2(user)

        # Access a flag's variant
        feature_flag_key = 'your-feature-flag-key'
        variant = variants.get(feature_flag_key)

        if variant:
            print(f"Variant for '{feature_flag_key}': {variant.value}")
            if variant.value == 'on':
                # Implement 'on' behavior
                print("Feature is ON for this user.")
            elif variant.value == 'control':
                # Implement 'control' behavior
                print("User is in control group.")
            else:
                # Implement other variant behavior
                print(f"User is in variant: {variant.value}")
        else:
            print(f"Flag '{feature_flag_key}' not found or variant is None.")

    except Exception as e:
        print(f"An error occurred: {e}")

# In a real application, you would call get_variants_and_evaluate() 
# within an async context, e.g., using asyncio.run()
# import asyncio
# asyncio.run(get_variants_and_evaluate())

view raw JSON →