Merge 921284e into 08f314e

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

README.rst

@@ -30,7 +30,92 @@ 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 recieved. 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'
+      )
+
+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 +208,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

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)