diff --git a/CHANGELOG.rst b/CHANGELOG.rst index a424bef1..d38aa55e 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,3 +1,34 @@ +3.2.0b1 +------- + +July 26th, 2019 + +New Features: +~~~~~~~~~~~~~ + +- Added support for automatic datafile management via `PollingConfigManager`_: + + - The `PollingConfigManager`_ is an implementation of the `BaseConfigManager`_. + - Users may provide one of datafile or SDK key (sdk_key) or both to `optimizely.Optimizely`. Based on that the SDK will use the `StaticConfigManager`_ or the `PollingConfigManager`_. Refer to the README_ for more instructions. + - An initial datafile can be provided to the `PollingConfigManager` to bootstrap before making HTTP requests for the hosted datafile. + - Requests for the datafile are made in a separate thread and are scheduled with fixed delay. + - Configuration updates can be subscribed to by adding . + +- Introduced `Optimizely.get_feature_variable` API. (`#191`_) + +Deprecated: +~~~~~~~~~~~ + +- `NotificationCenter.clear_notifications` is deprecated as of this release. Please use `NotificationCenter.clear_notification_listeners`. (`#182`_) +- `NotificationCenter.clear_all_notifications` is deprecated as of this release. Please use `NotificationCenter.clear_all_notification_listeners`. (`#182`_) + +.. _#182: https://github.com/optimizely/python-sdk/pull/182 +.. _#191: https://github.com/optimizely/python-sdk/pull/191 +.. _BaseConfigManager: https://github.com/optimizely/python-sdk/blob/3.2.x/optimizely/config_manager.py#L32 +.. _PollingConfigManager: https://github.com/optimizely/python-sdk/blob/3.2.x/optimizely/config_manager.py#L151 +.. _README: https://github.com/optimizely/python-sdk/blob/3.2.x/README.rst +.. _StaticConfigManager: https://github.com/optimizely/python-sdk/blob/3.2.x/optimizely/config_manager.py#L73 + 3.1.0 ----- diff --git a/README.rst b/README.rst index f47e7e30..3649753f 100644 --- a/README.rst +++ b/README.rst @@ -30,7 +30,100 @@ dashboard, please contact your Optimizely account executive. Using the SDK ~~~~~~~~~~~~~ -See the Optimizely `Full Stack documentation`_ to learn how to +You can initialize the Optimizely instance in three ways: with a datafile, by providing an `sdk_key`, or by providing an implementation of `config_manager.BaseConfigManager`_. Each method is described below. + +1. Initialize Optimizely with a datafile. This datafile will be used as + 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` as needed. + :: + + optimizely.Optimizely( + config_manager=custom_config_manager + ) + +PollingConfigManager +'''''''''''''''''''' + +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_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. + +Advanced configuration +'''''''''''''''''''''' + +The following properties can be set to override the default +configurations for `PollingConfigManager`. + +================ ======================================================== ===================================================================================== +**PropertyName** **Default Value** **Description** +================ ======================================================== ===================================================================================== +update_interval 5 minutes Fixed delay between fetches for the datafile +sdk_key None Optimizely project SDK key +url None URL override location used to specify custom HTTP source for the Optimizely datafile +url_template https://cdn.optimizely.com/datafiles/{sdk_key}.json Parameterized datafile URL by SDK key +datafile None Initial datafile, typically sourced from a local cached source +================ ======================================================== ===================================================================================== + +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 `Full Stack documentation`_ to learn how to set up your first Python project and use the SDK. Development @@ -123,6 +216,8 @@ Please see `CONTRIBUTING`_. .. _Full Stack documentation: https://docs.developers.optimizely.com/full-stack/docs .. _Rollouts documentation: https://docs.developers.optimizely.com/rollouts/docs .. _CONTRIBUTING: CONTRIBUTING.rst +.. _config_manager.BaseConfigManager:: https://github.com/optimizely/python-sdk/tree/master/optimizely/config_manager.py#L32 +.. _BaseConfigManager: https://github.com/optimizely/python-sdk/tree/master/optimizely/config_manager.py#L32 .. |PyPI version| image:: https://badge.fury.io/py/optimizely-sdk.svg :target: https://pypi.org/project/optimizely-sdk diff --git a/optimizely/version.py b/optimizely/version.py index 39ea486e..27041c60 100644 --- a/optimizely/version.py +++ b/optimizely/version.py @@ -11,5 +11,5 @@ # See the License for the specific language governing permissions and # limitations under the License. -version_info = (3, 1, 0) +version_info = (3, 2, '0-beta1') __version__ = '.'.join(str(v) for v in version_info)