This repository houses the Python SDK for use with Optimizely Feature Experimentation and Optimizely Full Stack (legacy).

Optimizely Feature Experimentation is an A/B testing and feature management tool for product development teams that enables you to experiment at every step. Using Optimizely Feature Experimentation allows for every feature on your roadmap to be an opportunity to discover hidden insights. Learn more at Optimizely.com, or see the developer documentation.

Optimizely Rollouts is free feature flags for development teams. You can easily roll out and roll back features in any application without code deploys, mitigating risk for every feature on your roadmap.

Refer to the Python SDK's developer documentation for detailed instructions on getting started with using the SDK.

Version 5.0+: Python 3.8+, PyPy 3.8+

Version 4.0+: Python 3.7+, PyPy 3.7+

Version 3.0+: Python 2.7+, PyPy 3.4+

The SDK is available through PyPi.

To install:

pip install optimizely-sdk

To access the Feature Management configuration in the Optimizely dashboard, please contact your Optimizely customer success manager.

You can initialize the Optimizely instance in three ways: with a datafile, by providing an sdk_key, or by providing an implementation of BaseConfigManager. Each method is described below.

1. Initialize Optimizely with a datafile. This datafile will be used as the source of ProjectConfig throughout the life of Optimizely instance:

   optimizely.Optimizely(
     datafile
   )
   

2. Initialize Optimizely by providing an 'sdk_key'. This will initialize a PollingConfigManager that makes an HTTP GET request to the URL (formed using your provided sdk key and the default datafile CDN URL template) to asynchronously download the project datafile at regular intervals and update ProjectConfig when a new datafile is received. A hard-coded datafile can also be provided along with the sdk_key that will be used initially before any update:

   optimizely.Optimizely(
     sdk_key='put_your_sdk_key_here'
   )
   

   If providing a datafile, the initialization will look like:

   optimizely.Optimizely(
     datafile=datafile,
     sdk_key='put_your_sdk_key_here'
   )
   

3. Initialize Optimizely by providing a ConfigManager that implements BaseConfigManager. You may use our PollingConfigManager or AuthDatafilePollingConfigManager as needed:

   optimizely.Optimizely(
     config_manager=custom_config_manager
   )
   

The PollingConfigManager asynchronously polls for datafiles from a specified URL at regular intervals by making HTTP requests.

polling_config_manager = PollingConfigManager(
    sdk_key=None,
    datafile=None,
    update_interval=None,
    url=None,
    url_template=None,
    logger=None,
    error_handler=None,
    notification_center=None,
    skip_json_validation=False
)

Note: You must provide either the sdk_key or URL. If you provide both, the URL takes precedence.

sdk_key The sdk_key is used to compose the outbound HTTP request to the default datafile location on the Optimizely CDN.

datafile You can provide an initial datafile to bootstrap the ProjectConfigManager so that it can be used immediately. The initial datafile also serves as a fallback datafile if HTTP connection cannot be established. The initial datafile will be discarded after the first successful datafile poll.

update_interval The update_interval is used to specify a fixed delay in seconds between consecutive HTTP requests for the datafile.

url The target URL from which to request the datafile.

url_template A string with placeholder {sdk_key} can be provided so that this template along with the provided sdk key is used to form the target URL.

You may also provide your own logger, error_handler, or notification_center.

The AuthDatafilePollingConfigManager implements PollingConfigManager and asynchronously polls for authenticated datafiles from a specified URL at regular intervals by making HTTP requests.

auth_datafile_polling_config_manager = AuthDatafilePollingConfigManager(
    datafile_access_token,
    *args,
    **kwargs
)

Note: To use AuthDatafilePollingConfigManager, you must create a secure environment for your project and generate an access token for your datafile.

datafile_access_token The datafile_access_token is attached to the outbound HTTP request header to authorize the request and fetch the datafile.

The following properties can be set to override the default configurations for PollingConfigManager and AuthDatafilePollingConfigManager.

A notification signal will be triggered whenever a new datafile is fetched and Project Config is updated. To subscribe to these notifications, use:

notification_center.add_notification_listener(NotificationTypes.OPTIMIZELY_CONFIG_UPDATE, update_callback)

For Further details see the Optimizely Feature Experimentation documentation to learn how to set up your first Python project and use the SDK.

Build and install the SDK with pip, using the following command:

pip install -e .

To get test dependencies installed, use a modified version of the install command:

pip install -e '.[test]'

You can run all unit tests with:

pytest

To run all tests under a particular test file you can use the following command:

pytest tests.<file_name_without_extension>

For example, to run all tests under test_event_builder, the command would be:

pytest tests/test_event_builder.py

To run all tests under a particular class of tests you can use the following command:

pytest tests/<file_name_with_extension>::ClassName

For example, to run all tests under test_event_builder.EventTest, the command would be:

pytest tests/test_event_builder.py::EventTest

To run a single test you can use the following command:

pytest tests/<file_name_with_extension>::ClassName::test_name

For example, to run test_event_builder.EventTest.test_init, the command would be:

pytest tests/test_event_builder.py::EventTest::test_init

Please see CONTRIBUTING.

This software incorporates code from the following open source projects:

requests (Apache-2.0 License: https://github.com/psf/requests/blob/master/LICENSE)

idna (BSD 3-Clause License https://github.com/kjd/idna/blob/master/LICENSE.md)

• Agent - https://github.com/optimizely/agent

• Android - https://github.com/optimizely/android-sdk

• C# - https://github.com/optimizely/csharp-sdk

• Flutter - https://github.com/optimizely/optimizely-flutter-sdk

• Go - https://github.com/optimizely/go-sdk

• Java - https://github.com/optimizely/java-sdk

• JavaScript - https://github.com/optimizely/javascript-sdk

• PHP - https://github.com/optimizely/php-sdk

• Python - https://github.com/optimizely/python-sdk

• React - https://github.com/optimizely/react-sdk

• Ruby - https://github.com/optimizely/ruby-sdk

• Swift - https://github.com/optimizely/swift-sdk