Dev guideAPI Reference
Dev guideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

Initialize the Python SDK

How to initialize the Optimizely Feature Experimentation Python SDK in your application.

Instantiate Optimizely class to initialize the Python SDK and create an instance of the Optimizely client that exposes API methods like the Decide methods. Each client corresponds to the datafile representing the state of a project for a certain environment.

Version

SDK v3.2.0 and higher

Description

The SDK provides a default implementation, but you may want to override optional parameters for your production environments. For example, you can override the parameters to set up an error handler and logger to catch issues, an event dispatcher to manage network calls, and a User Profile Service to ensure sticky bucketing.

Parameters

The table below lists the required and optional parameters in Python.

ParameterTypeDescription
datafile
optional
stringThe JSON string representing the project.
Must provide either datafile or sdk_key.
sdk_key
optional
stringOptional string that uniquely identifies the datafile corresponding to project and environment combination.
Must provide either datafile or sdk_key.
event_dispatcher
optional
EventDispatcherAn event handler to manage network calls.
logger
optional
logging.LoggerA logger implementation to log issues.
error_handler
optional
BaseErrorHandlerAn error handler object to handle errors.
user_profile_service
optional
UserProfileServiceA user profile service.
skip_json_validation
optional
BooleanSpecifies whether the JSON should be validated. Set to true to skip JSON validation on the schema, or false to perform validation.
config_manager
optional
BaseConfigManagerImplements optimizely.config_manager.BaseConfigManager.
Responsible for providing get_config method which returns an instance of optimizely.project_config.ProjectConfig.
notification_center
optional
NotificationCenterInstance of optimizely.notification_center.NotificationCenter.
This option is useful when providing your own optimizely.config_manager.BaseConfigManager implementation, which can use the same NotificationCenter instance.
access_token
optional
string(Server-side only) An access token for Optimizely Feature Experimentation SDKs (in combination with an SDK key) to fetch the datafile from an authenticated endpoint. Find your datafile access token in the Optimizely app at Settings>Environments. Select your secure environment, and copy the Datafile access token.
default_decide_optionsarrayAn array of OptimizelyDecideOption enums. When the Optimizely client is constructed with this parameter, it sets default decide options which are applied to all the Decide calls made during the lifetime of the Optimizely client. Additionally, you can pass options to individual Decide methods (does not overrides defaults).
For details on decide options, see OptimizelyDecideOption

Returns

Instantiates an instance of the Optimizely Feature Experimentation class.

Examples

In the Python SDK, you can provide either a sdkKey or datafile or both.

  • When initializing with the SDK key, the SDK polls for datafile changes in the background at regular intervals.
  • When initializing with the datafile, the SDK does not poll for datafile changes in the background.
  • When initializing with both the SDK key and datafile, the SDK uses the given datafile and starts polling for datafile changes in the background.

Instantiate using SDK Key (recommended)

In the Python SDK, you only need to pass the SDK key value to instantiate a client. Whenever the experiment configuration changes, the SDK handles the change for you.

Include sdk_key as a string when you instantiate the Optimizely class.

When you provide the sdk_key, the SDK instance downloads the datafile associated with that sdk_key. When the download completes, the SDK instance updates itself to use the downloaded datafile.

from optimizely import optimizely
optimizely_client = optimizely.Optimizely(sdk_key='123456')

Instantiate using datafile

To instantiate a client for simple applications, provide a datafile specifying the project configuration for a given environment. For most advanced implementations, you should customize the logger or error handler for your specific requirements.

For simple applications, all you need to provide to instantiate a client is a datafile specifying the project configuration for a given environment. For most advanced implementations, you'll want to customize the logger or error handler for your specific requirements.

from optimizely import optimizely

# Instantiate an Optimizely client
optimizely_client = optimizely.Optimizely(datafile)

Notes

Enable JSON schema validation

Skipping the JSON schema validation enhances performance during instantiation. In the Python SDK, you can control whether to validate the JSON schema of the datafile when instantiating the client. This example shows how to skip JSON schema validation:

# Skip JSON schema validation (SDK versions 0.1.1 and above)
optimizely_client = optimizely.Optimizely(datafile, skip_json_validation=True)

Use authenticated datafiles in secure environments.

You can fetch the Optimizely Feature Experimentation datafile from an authenticated endpoint using a server-side (only) Optimizely Feature Experimentation SDK.

To use an authenticated datafile, download your Optimizely Feature Experimentation environment's access token from the Optimizely app at Settings>Environments. Select your secure environment, and copy the Datafile access token. The example below shows how to initialize the Optimizely client using an access token and sdk_key, enabling the client to fetch the authenticated datafile and complete initialization.

# fetch the datafile from an authenticated endpoint
access_tkn = '<YOUR_DATAFILE_ACCESS_TOKEN>'
sdk_key = '<YOUR_SDK_KEY>'
optimizely_client = optimizely.Optimizely(sdk_key = sdk_key, datafile_access_token = access_tkn)

For more information on the custom use of the Optimizely Feature Experimentation datafile, see Manage config (datafile).

Source files

The language and platform source files containing the implementation for Python are available on GitHub.