Initialize Python SDK

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-beta

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.

Returns

Instantiates an instance of the Optimizely Feature Experimentation class.

Examples

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

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 = 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 versions of the datafile. 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 = 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 = optimizely.Optimizely(datafile,
                                          skip_json_validation=True)

OdpManager

📘

Note

You must have the Advanced Audience Targeting integration between Optimizely Data Platform (ODP) and Optimizely Feature Experimentation enabled and set up before being able to use OdpManager.

Advanced Audience Targeting and OdpManager are currently beta. Contact your Customer Success Manager for more information or register now on Optimizely.com.

OdpManager contains all the logic supporting Optimizely Data Platform (ODP)-related features, including audience segments.

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. --comment "when you reboot the device or terminate the app"?

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

📘

Note

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 = Optimizely(settings=sdk_settings)

Customize OdpSegmentApiManager

An OdpSegmentApiManager can be provided allowing for customization. --comment passive voice

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)

client = optimizely.Optimizely(settings=sdk_settings)

Customize OdpEventApiManager

An OdpEventApiManager can be provided allowing for customization. --comment passive voice

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)

client = optimizely.Optimizely(settings=sdk_settings)

Customize OdpEventManager

You can provide custom request_timeout and flush_interval in the initializer. If set to zero, the batch_size is 1; otherwise, batch_size is set to the default of 10. --comment check my wording on this, removed parentheses for clarity.

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)

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)

client = optimizely.Optimizely(settings=sdk_settings)

Providing 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: ...

Here 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)
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. --comment passive voice

Use authenticated datafiles in secure environments

📘

Note

Authenticated datafiles is in beta. Contact your Customer Success Manager if you are interested in becoming an early user of authenticated datafiles as part of the beta secure environment feature.

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 = 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/platform source files containing the implementation for Python are at optimizely.py.