diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..edfa7028 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,217 @@ +# Optimizely Python SDK Changelog + +## 3.2.0b1 +July 26th, 2019 + +### New Features: +* Added support for automatic datafile management via [PollingConfigManager](https://github.com/optimizely/python-sdk/blob/3.2.x/optimizely/config_manager.py#L151): + * The [PollingConfigManager](https://github.com/optimizely/python-sdk/blob/3.2.x/optimizely/config_manager.py#L151) is an implementation of the [BaseConfigManager](https://github.com/optimizely/python-sdk/blob/3.2.x/optimizely/config_manager.py#L32). + * 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](https://github.com/optimizely/python-sdk/blob/3.2.x/optimizely/config_manager.py#L73) or the [PollingConfigManager](https://github.com/optimizely/python-sdk/blob/3.2.x/optimizely/config_manager.py#L151). Refer to the [README](README.md) 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 the OPTIMIZELY_CONFIG_UPDATE notification listener. +* Introduced `Optimizely.get_feature_variable` API. ([#191](https://github.com/optimizely/python-sdk/pull/191)) + +### Deprecated: + +* `NotificationCenter.clear_notifications` is deprecated as of this release. Please use `NotificationCenter.clear_notification_listeners`. ([#182](https://github.com/optimizely/python-sdk/pull/182)) +* `NotificationCenter.clear_all_notifications` is deprecated as of this release. Please use `NotificationCenter.clear_all_notification_listeners`. ([#182](https://github.com/optimizely/python-sdk/pull/182)) + +## 3.1.0 +May 3rd, 2019 + +### New Features: +* Introduced Decision notification listener to be able to record: + * Variation assignments for users activated in an experiment. + * Feature access for users. + * Feature variable value for users. + +### Bug Fixes: +* Feature variable APIs now return default variable value when featureEnabled property is false. ([#171](https://github.com/optimizely/python-sdk/pull/171)) + +### Deprecated: +* Activate notification listener is deprecated as of this release. Recommendation is to use the new Decision notification listener. Activate notification listener will be removed in the next major release. + +## 3.0.0 +March 1st, 2019 + +The 3.0 release improves event tracking and supports additional audience +targeting functionality. + +### New Features: +* Event tracking: + * The `track` method now dispatches its conversion event *unconditionally*, without first determining whether the user is targeted by a known experiment that uses the event. This may increase outbound network traffic. + * In Optimizely results, conversion events sent by 3.0 SDKs don\'t explicitly name the experiments and variations that are currently targeted to the user. Instead, conversions are automatically attributed to variations that the user has previously seen, as long as those variations were served via 3.0 SDKs or by other clients capable of automatic attribution, and as long as our backend actually received the impression events for those variations. + * Altogether, this allows you to track conversion events and attribute them to variations even when you don't know all of a user's attribute values, and even if the user's attribute values or the experiment's configuration have changed such that the user is no longer affected by the experiment. As a result, **you may observe an increase in the conversion rate for previously-instrumented events.** If that is undesirable, you can reset the results of previously-running experiments after upgrading to the 3.0 SDK. - This will also allow you to attribute events to variations from other Optimizely projects in your account, even though those experiments don't appear in the same datafile. + * Note that for results segmentation in Optimizely results, the user attribute values from one event are automatically applied to all other events in the same session, as long as the events in question were actually received by our backend. This behavior was already in place and is not affected by the 3.0 release. +* Support for all types of attribute values, not just strings. + * All values are passed through to notification listeners. + * Strings, booleans, and valid numbers are passed to the event dispatcher and can be used for Optimizely results segmentation. A valid number is a finite float or numbers.Integral in the inclusive range \[-2⁵³, 2⁵³\]. + * Strings, booleans, and valid numbers are relevant for audience conditions. +* Support for additional matchers in audience conditions: + * An `exists` matcher that passes if the user has a non-null value for the targeted user attribute and fails otherwise. + * A `substring` matcher that resolves if the user has a string value for the targeted attribute. + * `gt` (greater than) and `lt` (less than) matchers that resolve if the user has a valid number value for the targeted attribute. A valid number is a finite float or numbers.Integral in the inclusive range \[-2⁵³, 2⁵³\]. + * The original (`exact`) matcher can now be used to target booleans and valid numbers, not just strings. +* Support for A/B tests, feature tests, and feature rollouts whose audiences are combined using `"and"` and `"not"` operators, not just the `"or"` operator. +* Datafile-version compatibility check: The SDK will remain uninitialized (i.e., will gracefully fail to activate experiments and features) if given a datafile version greater than 4. +* Updated Pull Request template and commit message guidelines. + +### Breaking Changes: +* Conversion events sent by 3.0 SDKs don\'t explicitly name the experiments and variations that are currently targeted to the user, so these events are unattributed in raw events data export. You must use the new *results* export to determine the variations to which events have been attributed. +* Previously, notification listeners were only given string-valued user attributes because only strings could be passed into various method calls. That is no longer the case. You may pass non-string attribute values, and if you do, you must update your notification listeners to be able to receive whatever values you pass in. + +### Bug Fixes: +* Experiments and features can no longer activate when a negatively targeted attribute has a missing, null, or malformed value. + * Audience conditions (except for the new `exists` matcher) no longer resolve to `false` when they fail to find an legitimate value for the targeted user attribute. The result remains `null` (unknown). Therefore, an audience that negates such a condition (using the `"not"` operator) can no longer resolve to `true` unless there is an unrelated branch in the condition tree that itself resolves to `true`. +* Updated the default event dispatcher to log an error if the request resolves to HTTP 4xx or 5xx. ([#140](https://github.com/optimizely/python-sdk/pull/140)) +* All methods now validate that user IDs are strings and that experiment keys, feature keys, feature variable keys, and event keys are non-empty strings. + +## 2.1.1 +August 21st, 2018 + +* Fix: record conversions for all experiments using an event when using track([#136](https://github.com/optimizely/python-sdk/pull/136)). + +## 2.1.0 +July 2nd, 2018 + +* Introduced support for bot filtering ([#121](https://github.com/optimizely/python-sdk/pull/121)). +* Overhauled logging to use standard Python logging ([#123](https://github.com/optimizely/python-sdk/pull/123)). + +## 2.0.1 +June 19th, 2018 + +* Fix: send impression event for Feature Test when Feature is disabled ([#128](https://github.com/optimizely/python-sdk/pull/128)). + +## 2.0.0 +April 12th, 2018 + +This major release introduces APIs for Feature Management. It also +introduces some breaking changes listed below. + +### New Features +* Introduced the `is_feature_enabled` API to determine whether to show a feature to a user or not. + +``` + is_enabled = optimizel_client.is_feature_enabled('my_feature_key', 'my_user', user_attributes) +``` + +* All enabled features for the user can be retrieved by calling: + +``` + enabled_features = optimizely_client.get_enabled_features('my_user', user_attributes) +``` +* Introduced Feature Variables to configure or parameterize a feature. There are four variable types: `String`, `Integer`, `Double`, `Boolean`. + +``` + string_variable = optimizely_client.get_feature_variable_string('my_feature_key', 'string_variable_key', 'my_user') + integer_variable = optimizely_client.get_feature_variable_integer('my_feature_key', 'integer_variable_key', 'my_user') + double_variable = optimizely_client.get_feature_variable_double('my_feature_key', 'double_variable_key', 'my_user') + boolean_variable = optimizely_client.get_feature_variable_boolean('my_feature_key', 'boolean_variable_key', 'my_user') +``` + +### Breaking changes +* The `track` API with revenue value as a stand-alone parameter has been removed. The revenue value should be passed in as an entry in the event tags dict. The key for the revenue tag is `revenue` and the passed in value will be treated by Optimizely as the value for computing results. + +``` + event_tags = { + 'revenue': 1200 + } + + optimizely_client.track('event_key', 'my_user', user_attributes, event_tags) +``` + +## 2.0.0b1 +March 29th, 2018 + +This beta release introduces APIs for Feature Management. It also +introduces some breaking changes listed below. + +### New Features +* Introduced the `is_feature_enabled` API to determine whether to show a feature to a user or not. +``` + is_enabled = optimizel_client.is_feature_enabled('my_feature_key', 'my_user', user_attributes) +``` + +* All enabled features for the user can be retrieved by calling: + +``` + enabled_features = optimizely_client.get_enabled_features('my_user', user_attributes) +``` + +* Introduced Feature Variables to configure or parameterize a feature. There are four variable types: `String`, `Integer`, `Double`, `Boolean`. + +``` + string_variable = optimizely_client.get_feature_variable_string('my_feature_key', 'string_variable_key', 'my_user') + integer_variable = optimizely_client.get_feature_variable_integer('my_feature_key', 'integer_variable_key', 'my_user') + double_variable = optimizely_client.get_feature_variable_double('my_feature_key', 'double_variable_key', 'my_user') + boolean_variable = optimizely_client.get_feature_variable_boolean('my_feature_key', 'boolean_variable_key', 'my_user') +``` + +### Breaking changes +* The `track` API with revenue value as a stand-alone parameter has been removed. The revenue value should be passed in as an entry in the event tags dict. The key for the revenue tag is `revenue` and the passed in value will be treated by Optimizely as the value for computing results. + +``` + event_tags = { + 'revenue': 1200 + } + + optimizely_client.track('event_key', 'my_user', user_attributes, event_tags) +``` + +## 1.4.0 + +* Added support for IP anonymization. +* Added support for notification listeners. +* Added support for bucketing ID. +* Updated mmh3 to handle installation failures on Windows 10. + +## 1.3.0 + +* Introduced support for forced bucketing. +* Introduced support for numeric metrics. +* Updated event builder to support new endpoint. + +## 1.2.1 + +* Removed older feature flag parsing. + +## 1.2.0 + +* Added user profile service. + +## 1.1.1 + +* Updated datafile parsing to be able to handle additional fields. +* Deprecated Classic project support. + +## 1.1.0 + +* Included datafile revision information in log events. +* Added event tags to track API to allow users to pass in event metadata. +* Deprecated the `event_value` parameter from the track method. Should use `event_tags` to pass in event value instead. +* Updated event logging endpoint to logx.optimizely.com. + +## 1.0.0 + +* Introduced support for Full Stack projects in Optimizely X. No breaking changes from previous version. +* Introduced more graceful exception handling in instantiation and core methods. +* Updated whitelisting to precede audience matching. + +## 0.1.3 + +* Added support for v2 endpoint and datafile. +* Updated dispatch_event to consume an Event object instead of url and params. The Event object comprises of four properties: url (string representing URL to dispatch event to), params (dict representing the params to be set for the event), http_verb (one of 'GET' or 'POST') and headers (header values to be sent along). +* Fixed issue with tracking events for experiments in groups. + +## 0.1.2 + +* Updated requirements file. + +## 0.1.1 + +* Introduced option to skip JSON schema validation. + +## 0.1.0 + +* Beta release of the Python SDK for server-side testing. diff --git a/CHANGELOG.rst b/CHANGELOG.rst deleted file mode 100644 index 1ad87b7f..00000000 --- a/CHANGELOG.rst +++ /dev/null @@ -1,400 +0,0 @@ -=============================== -Optimizely Python SDK Changelog -=============================== - -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 ------ - -May 3rd, 2019 - -New Features: -~~~~~~~~~~~~~ - -- Introduced Decision notification listener to be able to record: - - - Variation assignments for users activated in an experiment. - - Feature access for users. - - Feature variable value for users. - -Bug Fixes: -~~~~~~~~~~ - -- Feature variable APIs now return default variable value when featureEnabled property is false. (`#171`_) - -.. _#171: https://github.com/optimizely/python-sdk/pull/171 - -Deprecated: -~~~~~~~~~~~ - -- Activate notification listener is deprecated as of this release. - Recommendation is to use the new Decision notification listener. - Activate notification listener will be removed in the next major release. - -3.0.0 ------ - -March 1st, 2019 - -The 3.0 release improves event tracking and supports additional audience targeting functionality. - -New Features: -~~~~~~~~~~~~~ - -- Event tracking: - - - The ``track`` method now dispatches its conversion event - *unconditionally*, without first determining whether the user is - targeted by a known experiment that uses the event. This may - increase outbound network traffic. - - In Optimizely results, conversion events sent by 3.0 SDKs don't - explicitly name the experiments and variations that are currently - targeted to the user. Instead, conversions are automatically - attributed to variations that the user has previously seen, as long - as those variations were served via 3.0 SDKs or by other clients - capable of automatic attribution, and as long as our backend - actually received the impression events for those variations. - - Altogether, this allows you to track conversion events and - attribute them to variations even when you don’t know all of a - user’s attribute values, and even if the user’s attribute values - or the experiment’s configuration have changed such that the user - is no longer affected by the experiment. As a result, **you may - observe an increase in the conversion rate for - previously-instrumented events.** If that is undesirable, you can - reset the results of previously-running experiments after - upgrading to the 3.0 SDK. - - This will also allow you to attribute events to variations from - other Optimizely projects in your account, even though those - experiments don’t appear in the same datafile. - - Note that for results segmentation in Optimizely results, the user - attribute values from one event are automatically applied to all - other events in the same session, as long as the events in - question were actually received by our backend. This behavior was - already in place and is not affected by the 3.0 release. - -- Support for all types of attribute values, not just strings. - - - All values are passed through to notification listeners. - - Strings, booleans, and valid numbers are passed to the event - dispatcher and can be used for Optimizely results segmentation. A - valid number is a finite float or numbers.Integral in the inclusive range [-2⁵³, - 2⁵³]. - - Strings, booleans, and valid numbers are relevant for audience - conditions. - -- Support for additional matchers in audience conditions: - - - An ``exists`` matcher that passes if the user has a non-null value - for the targeted user attribute and fails otherwise. - - A ``substring`` matcher that resolves if the user has a string - value for the targeted attribute. - - ``gt`` (greater than) and ``lt`` (less than) matchers that resolve - if the user has a valid number value for the targeted attribute. A - valid number is a finite float or numbers.Integral in the inclusive range [-2⁵³, - 2⁵³]. - - The original (``exact``) matcher can now be used to target - booleans and valid numbers, not just strings. - -- Support for A/B tests, feature tests, and feature rollouts whose - audiences are combined using ``"and"`` and ``"not"`` operators, not - just the ``"or"`` operator. -- Datafile-version compatibility check: The SDK will remain - uninitialized (i.e., will gracefully fail to activate experiments and - features) if given a datafile version greater than 4. -- Updated Pull Request template and commit message guidelines. - -Breaking Changes: -~~~~~~~~~~~~~~~~~ - -- Conversion events sent by 3.0 SDKs don't explicitly name the experiments - and variations that are currently targeted to the user, so these events - are unattributed in raw events data export. You must use the new *results* - export to determine the variations to which events have been attributed. -- Previously, notification listeners were only given string-valued user - attributes because only strings could be passed into various method - calls. That is no longer the case. You may pass non-string attribute - values, and if you do, you must update your notification listeners to - be able to receive whatever values you pass in. - -Bug Fixes: -~~~~~~~~~~ - -- Experiments and features can no longer activate when a negatively - targeted attribute has a missing, null, or malformed value. - - - Audience conditions (except for the new ``exists`` matcher) no - longer resolve to ``false`` when they fail to find an legitimate - value for the targeted user attribute. The result remains ``null`` - (unknown). Therefore, an audience that negates such a condition - (using the ``"not"`` operator) can no longer resolve to ``true`` - unless there is an unrelated branch in the condition tree that - itself resolves to ``true``. - -- Updated the default event dispatcher to log an error if the request - resolves to HTTP 4xx or 5xx. (`#140`_) -- All methods now validate that user IDs are strings and that - experiment keys, feature keys, feature variable keys, and event keys - are non-empty strings. - -.. _#140: https://github.com/optimizely/python-sdk/pull/140 - -2.1.1 ------ - -August 21st, 2018 - -- Fix: record conversions for all experiments using an event when using - track(\ `#136`_). - -.. _section-1: - -2.1.0 ------ - -July 2nd, 2018 - -- Introduced support for bot filtering (`#121`_). -- Overhauled logging to use standard Python logging (`#123`_). - -.. _section-2: - -2.0.1 ------ - -June 19th, 2018 - -- Fix: send impression event for Feature Test when Feature is disabled - (`#128`_). - -2.0.0 ------ - -April 12th, 2018 - -This major release introduces APIs for Feature Management. It also -introduces some breaking changes listed below. - -New Features -~~~~~~~~~~~~ - -- Introduced the ``is_feature_enabled`` API to determine whether to - show a feature to a user or not. - -:: - - is_enabled = optimizel_client.is_feature_enabled('my_feature_key', 'my_user', user_attributes) - -- All enabled features for the user can be retrieved by calling: - -:: - - enabled_features = optimizely_client.get_enabled_features('my_user', user_attributes) - -- Introduced Feature Variables to configure or parameterize a feature. - There are four variable types: ``String``, ``Integer``, ``Double``, - ``Boolean``. - -:: - - string_variable = optimizely_client.get_feature_variable_string('my_feature_key', 'string_variable_key', 'my_user') - integer_variable = optimizely_client.get_feature_variable_integer('my_feature_key', 'integer_variable_key', 'my_user') - double_variable = optimizely_client.get_feature_variable_double('my_feature_key', 'double_variable_key', 'my_user') - boolean_variable = optimizely_client.get_feature_variable_boolean('my_feature_key', 'boolean_variable_key', 'my_user') - -Breaking changes -~~~~~~~~~~~~~~~~ - -- The ``track`` API with revenue value as a stand-alone parameter has - been removed. The revenue value should be passed in as an entry in - the event tags dict. The key for the revenue tag is ``revenue`` and - the passed in value will be treated by Optimizely as the value for - computing results. - -:: - - event_tags = { - 'revenue': 1200 - } - - optimizely_client.track('event_key', 'my_user', user_attributes, event_tags) - -2.0.0b1 -------- - -March 29th, 2018 - -This beta release introduces APIs for Feature Management. It also -introduces some breaking changes listed below. - -New Features -~~~~~~~~~~~~ - -- Introduced the ``is_feature_enabled`` API to determine whether to - show a feature to a user or not. - -:: - - is_enabled = optimizel_client.is_feature_enabled('my_feature_key', 'my_user', user_attributes) - -- All enabled features for the user can be retrieved by calling: - -:: - - enabled_features = optimizely_client.get_enabled_features('my_user', user_attributes) - -- Introduced Feature Variables to configure or parameterize a feature. - There are four variable types: ``String``, ``Integer``, ``Double``, - ``Boolean``. - -:: - - string_variable = optimizely_client.get_feature_variable_string('my_feature_key', 'string_variable_key', 'my_user') - integer_variable = optimizely_client.get_feature_variable_integer('my_feature_key', 'integer_variable_key', 'my_user') - double_variable = optimizely_client.get_feature_variable_double('my_feature_key', 'double_variable_key', 'my_user') - boolean_variable = optimizely_client.get_feature_variable_boolean('my_feature_key', 'boolean_variable_key', 'my_user') - -Breaking changes -~~~~~~~~~~~~~~~~ - -- The ``track`` API with revenue value as a stand-alone parameter has - been removed. The revenue value should be passed in as an entry in - the event tags dict. The key for the revenue tag is ``revenue`` and - the passed in value will be treated by Optimizely as the value for - computing results. - -:: - - event_tags = { - 'revenue': 1200 - } - - optimizely_client.track('event_key', 'my_user', user_attributes, event_tags) - -1.4.0 ------ - -- Added support for IP anonymization. -- Added support for notification listeners. -- Added support for bucketing ID. -- Updated mmh3 to handle installation failures on Windows 10. - -.. _section-3: - -1.3.0 ------ - -- Introduced support for forced bucketing. -- Introduced support for numeric metrics. -- Updated event builder to support new endpoint. - -.. _section-4: - -1.2.1 ------ - -- Removed older feature flag parsing. - -.. _section-5: - -1.2.0 ------ - -- Added user profile service. - -.. _section-6: - -1.1.1 ------ - -- Updated datafile parsing to be able to handle additional fields. -- Deprecated Classic project support. - -.. _section-7: - -1.1.0 ------ - -- Included datafile revision information in log events. -- Added event tags to track API to allow users to pass in event - metadata. -- Deprecated the ``event_value`` parameter from the track method. - Should use ``event_tags`` to pass in event value instead. -- Updated event logging endpoint to logx.optimizely.com. - -.. _section-8: - -1.0.0 ------ - -- Introduced support for Full Stack projects in Optimizely X. No - breaking changes from previous version. -- Introduced more graceful exception handling in instantiation and core - methods. -- Updated whitelisting to precede audience matching. - -.. _section-9: - -0.1.3 ------ - -- Added support for v2 endpoint and datafile. -- Updated dispatch_event to consume an Event object instead of url and - params. The Event object comprises of four properties: url (string - representing URL to dispatch event to), params (dict representing the - params to be set for the event), http_verb (one of ‘GET’ or ‘POST’) - and headers (header values to be sent along). -- Fixed issue with tracking events for experiments in groups. - -0.1.2 ------ - -- Updated requirements file. - -.. _section-10: - -0.1.1 ------ - -- Introduced option to skip JSON schema validation. - -.. _section-11: - -0.1.0 ------ - -- Beta release of the Python SDK for server-side testing. - -.. _#136: https://github.com/optimizely/python-sdk/pull/136 -.. _#121: https://github.com/optimizely/python-sdk/pull/121 -.. _#123: https://github.com/optimizely/python-sdk/pull/123 -.. _#128: https://github.com/optimizely/python-sdk/pull/128 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..3ed58d21 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,77 @@ +Contributing to the Optimizely Python SDK +========================================= + +We welcome contributions and feedback! All contributors must sign our +[Contributor License Agreement +(CLA)](https://docs.google.com/a/optimizely.com/forms/d/e/1FAIpQLSf9cbouWptIpMgukAKZZOIAhafvjFCV8hS00XJLWQnWDFtwtA/viewform) +to be eligible to contribute. Please read the [README](README.md) to +set up your development environment, then read the guidelines below for +information on submitting your code. + +Development process +------------------- + +1. Fork the repository and create your branch from master. +2. Please follow the [commit message guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines) + for each commit message. +3. Make sure to add tests! +4. Run `pep8` to ensure there are no lint errors. +5. `git push` your changes to GitHub. +6. Open a PR from your fork into the master branch of the original + repo. +7. Make sure that all unit tests are passing and that there are no + merge conflicts between your branch and `master`. +8. Open a pull request from `YOUR_NAME/branch_name` to `master`. +9. A repository maintainer will review your pull request and, if all + goes well, squash and merge it! + +Pull request acceptance criteria +-------------------------------- + +- **All code must have test coverage.** We use unittest. Changes in + functionality should have accompanying unit tests. Bug fixes should + have accompanying regression tests. + - Tests are located in `/tests` with one file per class. +- Please don't change the `__version__`. We'll take care of bumping + the version when we next release. +- Lint your code with PEP-8 before submitting. + +Style +----- + +We enforce Flake8 rules with a few minor +[deviations](https://github.com/optimizely/python-sdk/blob/master/tox.ini). + +License +------- + +All contributions are under the CLA mentioned above. For this project, +Optimizely uses the Apache 2.0 license, and so asks that by contributing +your code, you agree to license your contribution under the terms of the +[Apache License v2.0](http://www.apache.org/licenses/LICENSE-2.0). Your +contributions should also include the following header: + + # Copyright YEAR, Optimizely, Inc. and contributors + # + # Licensed under the Apache License, Version 2.0 (the "License"); + # you may not use this file except in compliance with the License. + # You may obtain a copy of the License at + # + # http://www.apache.org/licenses/LICENSE-2.0 + # + # Unless required by applicable law or agreed to in writing, software + # distributed under the License is distributed on an "AS IS" BASIS, + # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + # See the License for the specific language governing permissions and + # limitations under the License. + +The YEAR above should be the year of the contribution. If work on the +file has been done over multiple years, list each year in the section +above. Example: Optimizely writes the file and releases it in 2014. No +changes are made in 2015. Change made in 2016. YEAR should be "2014, +2016". + +Contact +------- + +If you have questions, please contact . diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 00024232..00000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,82 +0,0 @@ -Contributing to the Optimizely Python SDK -========================================= - -We welcome contributions and feedback! All contributors must sign our -`Contributor License Agreement (CLA)`_ to be eligible to contribute. -Please read the `README`_ to set up your development environment, then -read the guidelines below for information on submitting your code. - -Development process -------------------- - -1. Fork the repository and create your branch from master. -2. Please follow the `commit message guidelines`_ for each commit message. -3. Make sure to add tests! -4. Run ``pep8`` to ensure there are no lint errors. -5. ``git push`` your changes to GitHub. -6. Open a PR from your fork into the master branch of the original repo. -7. Make sure that all unit tests are passing and that there are no merge - conflicts between your branch and ``master``. -8. Open a pull request from ``YOUR_NAME/branch_name`` to ``master``. -9. A repository maintainer will review your pull request and, if all - goes well, squash and merge it! - -Pull request acceptance criteria --------------------------------- - -- **All code must have test coverage.** We use unittest. Changes in - functionality should have accompanying unit tests. Bug fixes should - have accompanying regression tests. - - - Tests are located in ``/tests`` with one file per class. - -- Please don’t change the ``__version__``. We’ll take care of bumping - the version when we next release. -- Lint your code with PEP-8 before submitting. - -Style ------ - -We enforce Flake8 rules with a few minor `deviations`_. - -License -------- - -All contributions are under the CLA mentioned above. For this project, -Optimizely uses the Apache 2.0 license, and so asks that by contributing -your code, you agree to license your contribution under the terms of the -`Apache License v2.0`_. Your contributions should also include the -following header: - -:: - - # Copyright YEAR, Optimizely, Inc. and contributors - # - # Licensed under the Apache License, Version 2.0 (the "License"); - # you may not use this file except in compliance with the License. - # You may obtain a copy of the License at - # - # http://www.apache.org/licenses/LICENSE-2.0 - # - # Unless required by applicable law or agreed to in writing, software - # distributed under the License is distributed on an "AS IS" BASIS, - # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - # See the License for the specific language governing permissions and - # limitations under the License. - -The YEAR above should be the year of the contribution. If work on the -file has been done over multiple years, list each year in the section -above. Example: Optimizely writes the file and releases it in 2014. No -changes are made in 2015. Change made in 2016. YEAR should be “2014, -2016”. - -Contact -------- - -If you have questions, please contact developers@optimizely.com. - -.. _Contributor License Agreement (CLA): https://docs.google.com/a/optimizely.com/forms/d/e/1FAIpQLSf9cbouWptIpMgukAKZZOIAhafvjFCV8hS00XJLWQnWDFtwtA/viewform -.. _README: README.rst -.. _commit message guidelines: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines -.. _deviations: https://github.com/optimizely/python-sdk/blob/master/tox.ini -.. _Apache License v2.0: http://www.apache.org/licenses/LICENSE-2.0 diff --git a/MANIFEST.in b/MANIFEST.in index 74f53fcf..109cdcd0 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,5 +1,5 @@ include LICENSE -include CHANGELOG.rst -include README.rst +include CHANGELOG.md +include README.md include requirements/* recursive-exclude tests * diff --git a/README.md b/README.md new file mode 100644 index 00000000..76203272 --- /dev/null +++ b/README.md @@ -0,0 +1,205 @@ +Optimizely Python SDK +===================== + +[![PyPI +version](https://badge.fury.io/py/optimizely-sdk.svg)](https://pypi.org/project/optimizely-sdk) +[![Build +Status](https://travis-ci.org/optimizely/python-sdk.svg?branch=master)](https://travis-ci.org/optimizely/python-sdk) +[![Coverage +Status](https://coveralls.io/repos/github/optimizely/python-sdk/badge.svg)](https://coveralls.io/github/optimizely/python-sdk) +[![Apache +2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0) + +This repository houses the official Python SDK for use with Optimizely +Full Stack and Optimizely Rollouts. + +Optimizely Full Stack is A/B testing and feature flag management for +product development teams. Experiment in any application. Make every +feature on your roadmap an opportunity to learn. Learn more at +, or see the [Full +Stack +documentation](https://docs.developers.optimizely.com/full-stack/docs). + +Optimizely Rollouts is free feature flags for development teams. Easily +roll out and roll back features in any application without code deploys. +Mitigate risk for every feature on your roadmap. Learn more at +, or see the [Rollouts +documentation](https://docs.developers.optimizely.com/rollouts/docs). + +Getting Started +--------------- + +### Installing the SDK + +The SDK is available through [PyPi](https://pypi.python.org/pypi?name=optimizely-sdk&:action=display). + +To install: + + pip install optimizely-sdk + +### Feature Management Access + +To access the Feature Management configuration in the Optimizely +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 an implementation of +[BaseConfigManager](https://github.com/optimizely/python-sdk/tree/master/optimizely/config_manager.py#L32). +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](https://github.com/optimizely/python-sdk/tree/master/optimizely/config_manager.py#L32). + You may use our [PollingConfigManager](https://github.com/optimizely/python-sdk/blob/master/optimizely/config_manager.py#L151) as needed. : + + optimizely.Optimizely( + config_manager=custom_config_manager + ) + +#### PollingConfigManager + +The [PollingConfigManager](https://github.com/optimizely/python-sdk/blob/master/optimizely/config_manager.py#L151) 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]{.title-ref}. + + **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](https://docs.developers.optimizely.com/full-stack/docs) to learn how to set up your first Python project and use the SDK. + +Development +----------- + +### Building the SDK + +Build and install the SDK with pip, using the following command: + + pip install -e . + +### Unit tests + +#### Running all tests + +To get test dependencies installed, use a modified version of the +install command: + + pip install -e .[test] + +You can run all unit tests with: + + nosetests + +#### Running all tests in a file + +To run all tests under a particular test file you can use the following +command: + + nosetests tests. + +For example, to run all tests under `test_event`, the command would be: + + nosetests tests.test_event + +#### Running all tests under a class + +To run all tests under a particular class of tests you can use the +following command: + + nosetests tests.:ClassName + +For example, to run all tests under `test_event.EventTest`, the command +would be: + + nosetests tests.test_event:EventTest + +#### Running a single test + +To run a single test you can use the following command: + + nosetests tests.:ClassName.test_name + +For example, to run `test_event.EventTest.test_dispatch`, the command +would be: + + nosetests tests.test_event:EventTest.test_dispatch + +### Contributing + +Please see [CONTRIBUTING](CONTRIBUTING.md). diff --git a/README.rst b/README.rst deleted file mode 100644 index e7bd6ec2..00000000 --- a/README.rst +++ /dev/null @@ -1,229 +0,0 @@ -===================== -Optimizely Python SDK -===================== - -|PyPI version| |Build Status| |Coverage Status| |Apache 2.0| - -This repository houses the official Python SDK for use with Optimizely Full Stack and Optimizely Rollouts. - -Optimizely Full Stack is A/B testing and feature flag management for product development teams. Experiment in any application. Make every feature on your roadmap an opportunity to learn. Learn more at https://www.optimizely.com/platform/full-stack/, or see the `Full Stack documentation`_. - -Optimizely Rollouts is free feature flags for development teams. Easily roll out and roll back features in any application without code deploys. Mitigate risk for every feature on your roadmap. Learn more at https://www.optimizely.com/rollouts/, or see the `Rollouts documentation`_. - -Getting Started ---------------- - -Installing the SDK -~~~~~~~~~~~~~~~~~~ - -The SDK is available through `PyPi`_. To install: - -:: - - pip install optimizely-sdk - -Feature Management Access -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To access the Feature Management configuration in the Optimizely -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 an implementation of `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 ------------ - -Building the SDK -~~~~~~~~~~~~~~~~ - -Build and install the SDK with pip, using the following command: - -:: - - pip install -e . - -Unit tests -~~~~~~~~~~ - -Running all tests -''''''''''''''''' - -To get test dependencies installed, use a modified version of the -install command: - -:: - - pip install -e .[test] - -You can run all unit tests with: - -:: - - nosetests - -Running all tests in a file -''''''''''''''''''''''''''' - -To run all tests under a particular test file you can use the following -command: - -:: - - nosetests tests. - -For example, to run all tests under ``test_event``, the command would -be: - -:: - - nosetests tests.test_event - -Running all tests under a class -''''''''''''''''''''''''''''''' - -To run all tests under a particular class of tests you can use the -following command: - -:: - - nosetests tests.:ClassName - -For example, to run all tests under ``test_event.EventTest``, the -command would be: - -:: - - nosetests tests.test_event:EventTest - -Running a single test -''''''''''''''''''''' - -To run a single test you can use the following command: - -:: - - nosetests tests.:ClassName.test_name - -For example, to run ``test_event.EventTest.test_dispatch``, the command -would be: - -:: - - nosetests tests.test_event:EventTest.test_dispatch - -Contributing -~~~~~~~~~~~~ - -Please see `CONTRIBUTING`_. - -.. _PyPi: https://pypi.python.org/pypi?name=optimizely-sdk&:action=display -.. _Full Stack documentation: https://docs.developers.optimizely.com/full-stack/docs -.. _Rollouts documentation: https://docs.developers.optimizely.com/rollouts/docs -.. _CONTRIBUTING: CONTRIBUTING.rst -.. _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 -.. |Build Status| image:: https://travis-ci.org/optimizely/python-sdk.svg?branch=master - :target: https://travis-ci.org/optimizely/python-sdk -.. |Coverage Status| image:: https://coveralls.io/repos/github/optimizely/python-sdk/badge.svg - :target: https://coveralls.io/github/optimizely/python-sdk -.. |Apache 2.0| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg - :target: http://www.apache.org/licenses/LICENSE-2.0 diff --git a/setup.py b/setup.py index 0b69d8c9..f6ac5362 100644 --- a/setup.py +++ b/setup.py @@ -17,10 +17,10 @@ TEST_REQUIREMENTS = _file.read().splitlines() TEST_REQUIREMENTS = list(set(REQUIREMENTS + TEST_REQUIREMENTS)) -with open(os.path.join(here, 'README.rst')) as _file: +with open(os.path.join(here, 'README.md')) as _file: README = _file.read() -with open(os.path.join(here, 'CHANGELOG.rst')) as _file: +with open(os.path.join(here, 'CHANGELOG.md')) as _file: CHANGELOG = _file.read() about_text = 'Optimizely X Full Stack is A/B testing and feature management for product development teams. ' \ @@ -32,15 +32,16 @@ name='optimizely-sdk', version=__version__, description='Python SDK for Optimizely X Full Stack.', - long_description=about_text, + long_description=about_text + README + CHANGELOG, + long_description_content_type='text/markdown', author='Optimizely', author_email='developers@optimizely.com', url='https://github.com/optimizely/python-sdk', - license=open('LICENSE').read(), classifiers=[ 'Development Status :: 5 - Production/Stable', 'Environment :: Web Environment', 'Intended Audience :: Developers', + 'License :: OSI Approved :: Apache Software License', 'Operating System :: OS Independent', 'Programming Language :: Python', 'Programming Language :: Python :: 2.7', diff --git a/tests/testapp/README.rst b/tests/testapp/README.md similarity index 100% rename from tests/testapp/README.rst rename to tests/testapp/README.md