Initialize the Python SDK

22 min

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

5.0.0

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 configure 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 following are the required and optional parameters in Python:

Parameter	Type	Description
`datafile` _optional_	string	The JSON string representing the project. You can provide either `datafile` or `sdk_key` or both. See the [Examples](#examples) section.
`sdk_key` _optional_	string	Optional string that uniquely identifies the datafile corresponding to project and environment combination. You can provide either `datafile` or `sdk_key` or both. See the [Examples](#examples) section.
`event_dispatcher` _optional_	EventDispatcher	An event handler to manage network calls.
`logger` _optional_	logging.Logger	A logger implementation to log issues.
`error_handler` _optional_	BaseErrorHandler	An object to handle errors.
`user_profile_service` _optional_	UserProfileService	A user profile service.
`skip_json_validation` _optional_	Boolean	Specifies whether the JSON should be validated. Set to `true` to skip JSON validation on the schema, or `false` to perform validation.
`config_manager` _optional_	BaseConfigManager	Implements `optimizely.config_manager.BaseConfigManager`. Responsible for providing `get_config` method which returns an instance of `optimizely.project_config.ProjectConfig`.
`notification_center` _optional_	NotificationCenter	Instance 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_tkn` _optional_	string	Use an access token (with an `sdkKey`) 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. See the [Use authenticated datafile in a secure environment](#use-authenticated-datafile-in-a-secure-environment) section.
`default_decide_options` _optional_	array	An 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 override defaults). For details on decide options, see [OptimizelyDecideOption](https://docs.developers.optimizely.com/feature-experimentation/docs/decide-methods-python#optimizely-decide-option).
`event_processor_options` _optional_	dictionary	A dictionary of options to pass to the default batch event processor. See [BatchEventProcessor](https://docs.developers.optimizely.com/feature-experimentation/docs/event-batching-python#configure-event-batching) for more details.
`settings`	`OptimizelySdkSettings`	Instance of `optimizely.helpers.sdk_settings.OptimizelySdkSettings` used to configure [Real-Time Audiences for Feature Experimentation](https://docs.developers.optimizely.com/feature-experimentation/docs/real-time-audiences-for-feature-experimentation). You must configure this parameter to use Real-Time Audiences for Feature Experimentation. The Python SDK enables the Real-Time Audiences for Feature Experimentation by default. But, the methods do nothing unless you have enabled and configured [Real-Time Audiences for Feature Experimentation](https://docs.developers.optimizely.com/feature-experimentation/docs/real-time-audiences-for-feature-experimentation). To optionally disable Real-Time Audiences for Feature Experimentation, set `odp_disabled=True`. See [OdpManager](https://docs.developers.optimizely.com/feature-experimentation/docs/initialize-sdk-python#odpmanager).

Returns

Instantiates an instance of the Optimizely class.

Examples

In the Python SDK, you can provide sdkKey, 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)

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

Include sdk_key as a string when instantiating 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

You can also instantiate with a hard-coded datafile. If you do not pass in an SDK key, the Optimizely Client will not automatically sync newer datafile versions. Any time you retrieve an updated datafile, just re-instantiate the same client.

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.

from optimizely import optimizely

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

Notes

Enable JSON schema validation

Skipping 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)

Dispose of the client

For effective resource management with the Optimizely Python SDK, you must properly close the Optimizely client instance when it is no longer needed. This is done by calling optimizelyClient.close().

The .close() method ensures that the processes and queues associated with the instance are properly released. This is essential for preventing memory leaks and ensuring that the application runs efficiently, especially in environments where resources are limited or in applications that create and dispose of many instances over their lifecycle.

Use authenticated datafiles in secure environments

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

To use an authenticated datafile, download your environment's access token from the Optimizely app by going to Settings > Environments. Select your secure environment, and copy the Datafile access token. The following example 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 information on the custom use of the datafile, see Manage config (datafile).

OdpManager

The OdpManager contains all the logic supporting Real-Time Audiences for Feature Experimentation-related features, including audience segments. You must configure this parameter to use Real-Time Audiences for Feature Experimentation.

The Python SDK enables the Real-Time Audiences for Feature Experimentation methods by default. But, the methods do nothing unless you have enabled and configured Real-Time Audiences for Feature Experimentation.

If necessary, to disable Real-Time Audiences for Feature Experimentation altogether, set odp_disabled: True. See the following sample code for information.

OdpSegmentManager

This module provides an interface to the remote ODP server for audience segment mappings.

It fetches all qualified segments for the given user context and returns true if the qualified segments array in the user context was updated.

It also manages a segment's cache shared for all user contexts. The cache is in memory (not persistent) and is reset when the device is rebooted or the app is terminated.

The following settings are optionally configurable when the Python SDK is initialized:

ODP SegmentsCache size – segments_cache_size

Default – 10,000

Set to 0 to disable caching.

ODP SegmentsCache timeout (in seconds) – segments_cache_timeout_in_secs

Default – 600 secs (10 minutes)

Set to 0 to disable timeout (never expires).

ODP enable – odp_disabled

Default – False (enabled)

The Python SDK returns or logs an odpNotEnabled error when ODP is disabled and its features are requested.

See the code example in OdpEventManager.

OdpEventManager

This module provides an interface to the remote ODP server for events.

It queues all pending events (persistent) and sends them (in batches of up to 10) to the ODP server when all resources are available, including network connection and ODP public key (in the SDK's datafile).

Although the Python SDK tries to dispatch all events (stored in a persistent queue and retried on recoverable errors), completion is not guaranteed.

from optimizely import optimizely
from optimizely.odp.odp_segment_manager import OdpSegmentManager
from optimizely.odp.odp_event_manager import OdpEventManager
from optimizely.helpers.sdk_settings import OptimizelySdkSettings

segments_cache = CustomCache()
event_manager = OdpEventManager()
segments_manager = OdpSegmentManager()

sdk_settings = OptimizelySdkSettings(
    odp_disabled=False,
    segments_cache_size=10_000,
    segments_cache_timeout_in_secs=600,
    odp_segments_cache=segments_cache,
    odp_segment_manager=segments_manager,
    odp_event_manager=event_manager,
    odp_segment_request_timeout=10,
    odp_event_request_timeout=10,
    odp_event_flush_interval=1
)
optimizely_client = Optimizely(settings=sdk_settings)

Customize OdpSegmentApiManager

You can provide an OdpSegmentApiManager for customization.

from optimizely import optimizely
from optimizely.odp.odp_segment_manager import OdpSegmentManager
from optimizely.odp.odp_segment_api_manager import OdpSegmentApiManager
from optimizely.odp.lru_cache import LRUCache
from optimizely.helpers.sdk_settings import OptimizelySdkSettings

segment_api_manager = OdpSegmentApiManager(timeout=10)
cache = LRUCache(cache_size=10_000, cache_timeout=600)
odp_segment_manager = OdpSegmentManager(segments_cache=cache, api_manager=segment_api_manager)
sdk_settings = OptimizelySdkSettings(odp_segment_manager=odp_segment_manager)

optimizely_client = optimizely.Optimizely(settings=sdk_settings)

Customize OdpEventApiManager

You can provide an OdpEventApiManager for customization.

from optimizely import optimizely
from optimizely.odp.odp_event_api_manager import OdpEventApiManager
from optimizely.odp.odp_event_manager import OdpEventManager
from optimizely.helpers.sdk_settings import OptimizelySdkSettings

event_api_manager = OdpEventApiManager(timeout=10)
odp_event_manager = OdpEventManager(api_manager=event_api_manager, flush_interval=1)
sdk_settings = OptimizelySdkSettings(odp_event_manager=odp_event_manager)

optimizely_client = optimizely.Optimizely(settings=sdk_settings)

Customize OdpEventManager

You can provide a custom request_timeout and flush_interval in the initializer. If set to 0, the batch_size is 1. Otherwise, batch_size is set to the default of 10.

from optimizely import optimizely
from optimizely.odp.odp_event_manager import OdpEventManager
from optimizely.helpers.sdk_settings import OptimizelySdkSettings

event_manager = OdpEventManager(request_timeout=10, flush_interval=1)
sdk_settings = OptimizelySdkSettings(odp_event_manager=event_manager)

optimizely_client = optimizely.Optimizely(settings=sdk_settings)

OdpSegmentManager

from optimizely import optimizely
from optimizely.odp.odp_segment_manager import OdpSegmentManager
from optimizely.odp.lru_cache import LRUCache
from optimizely.helpers.sdk_settings import OptimizelySdkSettings

cache = LRUCache(cache_size=10_000, cache_timeout=600)

odp_segment_manager = OdpSegmentManager(segments_cache=cache, timeout=10)
sdk_settings = OptimizelySdkSettings(odp_segment_manager=odp_segment_manager)

optimizely_client = optimizely.Optimizely(settings=sdk_settings)

Provide a custom cache

You can provide a custom cache to store the fetch_qualified_segments results by implementing the OptimizelySegmentsCache Protocol.

class OptimizelySegmentsCache(Protocol):
    def save(self, key: str, value: list[str]) -> None: ...
    def lookup(self, key: str) -> Optional[list[str]]: ...
    def reset(self) -> None: ...

The following is an example of custom cache implementation:

class CustomCache:
    def __init__(self):
        self.lock = threading.Lock()
        self.map = {}

    def save(self, key, value):
        with self.lock:
           self.map[key] = value

    def lookup(self, key):
        with self.lock:
            return self.map.get(key)

    def reset(self):
        with self.lock:
            self.map.clear()

Pass this CustomCache within OptimizelySdkSettings when instantiating the Optimizely client.

from optimizely import optimizely
from optimizely.helpers.sdk_settings import OptimizelySdkSettings

segments_cache = CustomCache()
sdk_settings = OptimizelySdkSettings(odp_segments_cache=segments_cache)
optimizely_client = optimizely.Optimizely(settings=sdk_settings)

If odp_segments_cache is provided, segments_cache_size and segments_cache_timeout_in_secs parameters from OptimizelySdkSettings are ignored.

CMAB configuration

Configure the caching behavior for Contextual Multi-Armed Bandit (CMAB) decisions at initialization time.

Use OptimizelyFactory class methods to configure CMAB caching before initializing your client.

Parameters

Parameter	Method	Type	Default	Description
Cache Size	`cmab_cache_size`	Integer	10000	Maximum number of cached decisions
Custom Cache	`cmab_custom_cache`	Cache	None	Optional custom cache implementation. If not provided, uses built-in thread-safe LRU cache
Cache TTL	`cmab_cache_ttl`	Integer	1800 seconds (30 minutes)	Time-to-live for cache entries
Prediction Endpoint	`cmab_prediction_endpoint`	str	`"https://prediction.cmab.optimizely.com/predict/{}"`	URL template for CMAB prediction API. The `{}` placeholder is replaced with the rule ID. Useful for proxying.

For configuration examples, cache behavior details, and runtime control options, see Configure the CMAB cache for the Python SDK.

Source files

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