From 7dd2921b229a9a4b626255ed66eee28c5d61dfb0 Mon Sep 17 00:00:00 2001 From: Owais Date: Thu, 11 Jul 2019 17:41:59 +0500 Subject: [PATCH 1/5] add dfm readme --- polling-config-manager.md | 71 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 polling-config-manager.md diff --git a/polling-config-manager.md b/polling-config-manager.md new file mode 100644 index 000000000..f1683f916 --- /dev/null +++ b/polling-config-manager.md @@ -0,0 +1,71 @@ + +## Using the SDK + +To use the SDK, the Optimizely instance can be initialized in three different ways as per your requirement. + + 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( + datafile=None, + sdk_key='put_your_sdk_key_here' + ) + + 3. Initialize Optimizely by providing a Config Manager that implements a 'get_config' method.You may use our Polling Config Manager and customize it to your need. + ~~~~~~~~~~~~ + optimizely.Optimizely( + config_manager=custom_config_manager + ) + +##### PollingConfigManager + +The PollingConfigManager asynchronously polls for datafiles from a specified URL at regular intervals by making HTTP request. + + 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**: One of the sdk_key or url must be provided. When both are provided, url takes the preference. + +**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 you can use the `notification_center.add_notification_listener(NotificationTypes.OPTIMIZELY_CONFIG_UPDATE, update_callback)` + + From 1a865538cc8c114c5d2ad7b8105ec5167e84070c Mon Sep 17 00:00:00 2001 From: Owais Date: Thu, 11 Jul 2019 17:53:37 +0500 Subject: [PATCH 2/5] convert md to rst --- README.rst | 92 ++++++++++++++++++++++++++++++++++++++- polling-config-manager.md | 71 ------------------------------ 2 files changed, 91 insertions(+), 72 deletions(-) delete mode 100644 polling-config-manager.md diff --git a/README.rst b/README.rst index f47e7e30c..4d9a75049 100644 --- a/README.rst +++ b/README.rst @@ -30,7 +30,97 @@ dashboard, please contact your Optimizely account executive. Using the SDK ~~~~~~~~~~~~~ -See the Optimizely `Full Stack documentation`_ to learn how to +Optimizely instance can be initialized in three +different ways as per your requirement. + +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( + datafile=None, + sdk_key='put_your_sdk_key_here' + ) + +3. Initialize Optimizely by providing a Config Manager that implements a + 'get_config' method.You may use our Polling Config Manager and + customize it to your need. + :: + + optimizely.Optimizely( + config_manager=custom_config_manager + ) + +PollingConfigManager +'''''''''''''''''''' + +The PollingConfigManager asynchronously polls for datafiles from a +specified URL at regular intervals by making HTTP request. + +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**: One of the sdk_key or url must be provided. When both are +provided, url takes the preference. + +**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. + +================ ======================================================== ===================================================================================== +**Property Name** **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 you can use the + +``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 diff --git a/polling-config-manager.md b/polling-config-manager.md deleted file mode 100644 index f1683f916..000000000 --- a/polling-config-manager.md +++ /dev/null @@ -1,71 +0,0 @@ - -## Using the SDK - -To use the SDK, the Optimizely instance can be initialized in three different ways as per your requirement. - - 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( - datafile=None, - sdk_key='put_your_sdk_key_here' - ) - - 3. Initialize Optimizely by providing a Config Manager that implements a 'get_config' method.You may use our Polling Config Manager and customize it to your need. - ~~~~~~~~~~~~ - optimizely.Optimizely( - config_manager=custom_config_manager - ) - -##### PollingConfigManager - -The PollingConfigManager asynchronously polls for datafiles from a specified URL at regular intervals by making HTTP request. - - 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**: One of the sdk_key or url must be provided. When both are provided, url takes the preference. - -**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 you can use the `notification_center.add_notification_listener(NotificationTypes.OPTIMIZELY_CONFIG_UPDATE, update_callback)` - - From 6cf4443cfa6fce55ddfbabd2fecd1419d9485bd5 Mon Sep 17 00:00:00 2001 From: Owais Date: Thu, 11 Jul 2019 17:56:15 +0500 Subject: [PATCH 3/5] rst is problematic --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 4d9a75049..606548d47 100644 --- a/README.rst +++ b/README.rst @@ -104,7 +104,7 @@ The following properties can be set to override the default configurations for PollingConfigManager. ================ ======================================================== ===================================================================================== -**Property Name** **Default Value** **Description** +**PropertyName** **Default Value** **Description** ================ ======================================================== ===================================================================================== update_interval 5 minutes Fixed delay between fetches for the datafile sdk_key None Optimizely project SDK key From 07f449d25141397580c7a51c709ca75e199a647e Mon Sep 17 00:00:00 2001 From: Owais Date: Mon, 15 Jul 2019 17:17:32 +0500 Subject: [PATCH 4/5] update readme --- README.rst | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/README.rst b/README.rst index 606548d47..c19190f03 100644 --- a/README.rst +++ b/README.rst @@ -30,8 +30,7 @@ dashboard, please contact your Optimizely account executive. Using the SDK ~~~~~~~~~~~~~ -Optimizely instance can be initialized in three -different ways as per your requirement. +You can initialize the Optimizely instance in three ways: with a datafile, by providing an `sdk_key`, or by providing a Config Manager. Each method is described below. 1. Initialize Optimizely with a datafile. This datafile will be used as ProjectConfig throughout the life of Optimizely instance. @@ -42,11 +41,11 @@ different ways as per your requirement. ) 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 + 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 + hard-coded datafile can also be provided along with the `sdk_key` that will be used initially before any update. :: @@ -56,8 +55,7 @@ different ways as per your requirement. ) 3. Initialize Optimizely by providing a Config Manager that implements a - 'get_config' method.You may use our Polling Config Manager and - customize it to your need. + 'get_config' method. You may use our `PollingConfigManager` as needed. :: optimizely.Optimizely( @@ -67,18 +65,17 @@ different ways as per your requirement. PollingConfigManager '''''''''''''''''''' -The PollingConfigManager asynchronously polls for datafiles from a -specified URL at regular intervals by making HTTP request. +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**: One of the sdk_key or url must be provided. When both are -provided, url takes the preference. +**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 +**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 @@ -91,31 +88,31 @@ successful datafile poll. 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 +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 +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. +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. +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 you can use the +notifications, use the ``notification_center.add_notification_listener(NotificationTypes.OPTIMIZELY_CONFIG_UPDATE, update_callback)`` From 611dc54bbc2b229e3eacc2bff1bb63a5821a2742 Mon Sep 17 00:00:00 2001 From: Owais Date: Tue, 16 Jul 2019 18:12:33 +0500 Subject: [PATCH 5/5] Address readme feedback --- README.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index c19190f03..0b45db8b2 100644 --- a/README.rst +++ b/README.rst @@ -30,7 +30,7 @@ dashboard, please contact your Optimizely account executive. Using the SDK ~~~~~~~~~~~~~ -You can initialize the Optimizely instance in three ways: with a datafile, by providing an `sdk_key`, or by providing a Config Manager. Each method is described below. +You can initialize the Optimizely instance in three ways: with a datafile, by providing an `sdk_key`, or by providing a `ConfigManager`_. Each method is described below. 1. Initialize Optimizely with a datafile. This datafile will be used as ProjectConfig throughout the life of Optimizely instance. @@ -42,7 +42,7 @@ You can initialize the Optimizely instance in three ways: with a datafile, by pr 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 + 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 @@ -50,12 +50,10 @@ You can initialize the Optimizely instance in three ways: with a datafile, by pr :: optimizely.Optimizely( - datafile=None, sdk_key='put_your_sdk_key_here' ) -3. Initialize Optimizely by providing a Config Manager that implements a - 'get_config' method. You may use our `PollingConfigManager` as needed. +3. Initialize Optimizely by providing a ConfigManager that implements `BaseConfigManager`_. You may use our `PollingConfigManager` as needed. :: optimizely.Optimizely( @@ -112,7 +110,7 @@ datafile None Initia A notification signal will be triggered whenever a *new* datafile is fetched and Project Config is updated. To subscribe to these -notifications, use the +notifications, use: ``notification_center.add_notification_listener(NotificationTypes.OPTIMIZELY_CONFIG_UPDATE, update_callback)`` @@ -210,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 +.. _ConfigManager: https://github.com/optimizely/python-sdk/tree/master/optimizely/config_manager.py +.. _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