| Name | ABSmartly JSON |
| Version |
0.2.3
JSON |
| download |
| home_page | None |
| Summary | ABSmartly Python SDK lib |
| upload_time | 2024-04-18 10:34:02 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | The MIT License (MIT) Copyright © 2022 <copyright holders> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
absmartly
sdk
testing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# A/B Smartly SDK
A/B Smartly - Python SDK
## Compatibility
The A/B Smartly Python SDK is compatible with Python 3.
It provides both a blocking and an asynchronous interfaces.
## Getting Started
### Install the SDK
```bash
pip install absmartly==0.2.3
```
### Dependencies
```
setuptools~=60.2.0
requests~=2.28.1
urllib3~=1.26.12
jsons~=1.6.3
```
## Import and Initialize the SDK
Once the SDK is installed, it can be initialized in your project.
```python
def main():
client_config = ClientConfig()
client_config.endpoint = "https://sandbox.test.io/v1"
client_config.api_key = "test"
client_config.application = "www"
client_config.environment = "prod"
default_client_config = DefaultHTTPClientConfig()
default_client = DefaultHTTPClient(default_client_config)
sdk_config = ABSmartlyConfig()
sdk_config.client = Client(client_config, default_client)
sdk = ABSmartly(sdk_config)
context_config = ContextConfig()
ctx = sdk.create_context(context_config)
```
**SDK Options**
| Config | Type | Required? | Default | Description |
| :---------- |:----------------------------------------------| :-------: |:---------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| endpoint | `string` | ✅ | `undefined` | The URL to your API endpoint. Most commonly `"your-company.absmartly.io"` |
| apiKey | `string` | ✅ | `undefined` | Your API key which can be found on the Web Console. |
| environment | `"production"` or `"development"` | ✅ | `undefined` | The environment of the platform where the SDK is installed. Environments are created on the Web Console and should match the available environments in your infrastructure. |
| application | `string` | ✅ | `undefined` | The name of the application where the SDK is installed. Applications are created on the Web Console and should match the applications where your experiments will be running. |
| max_retries | `number` | ❌ | `5` | The number of retries before the SDK stops trying to connect. |
| connection_timeout | `number` | ❌ | `3` | An amount of time, in seconds, before the SDK will stop trying to connect. |
| context_event_logger | `(self, event_type: EventType, data: object)` | ❌ | See "Using a Custom Event Logger" below | A callback function which runs after SDK events.
#### Using a custom Event Logger
The A/B Smartly SDK can be instantiated with an event logger used for all contexts.
In addition, an event logger can be specified when creating a particular context, in the `ContextConfig`.
```python
class EventType(Enum):
ERROR = "error"
READY = "ready"
REFRESH = "refresh"
PUBLISH = "publish"
EXPOSURE = "exposure"
GOAL = "goal"
CLOSE = "close"
class ContextEventLogger:
@abstractmethod
def handle_event(self, event_type: EventType, data: object):
raise NotImplementedError
```
The data parameter depends on the type of event.
Currently, the SDK logs the following events:
| event | when | data |
|:---: |------------------------------------------------------------|---|
| `Error` | `Context` receives an error | `Throwable` object |
| `Ready` | `Context` turns ready | `ContextData` used to initialize the context |
| `Refresh` | `Context.refresh()` method succeeds | `ContextData` used to refresh the context |
| `Publish` | `Context.publish()` method succeeds | `PublishEvent` sent to the A/B Smartly event collector |
| `Exposure` | `Context.getTreatment()` method succeeds on first exposure | `Exposure` enqueued for publishing |
| `Goal` | `Context.track()` method succeeds | `GoalAchievement` enqueued for publishing |
| `Close` | `Context.close()` method succeeds the first time | `null` |
## Create a New Context Request
**Synchronously**
```python
# define a new context request
context_config = ContextConfig()
context_config.publish_delay = 10
context_config.refresh_interval = 5
context_config = ContextConfig()
ctx = sdk.create_context(context_config)
ctx.wait_until_ready()
```
**Asynchronously**
```python
# define a new context request
context_config = ContextConfig()
context_config.publish_delay = 10
context_config.refresh_interval = 5
context_config = ContextConfig()
ctx = sdk.create_context(context_config)
ctx.wait_until_ready_async()
```
**With Prefetched Data**
```python
# define a new context request
context_config = ContextConfig()
context_config.publish_delay = 10
context_config.refresh_interval = 5
context_config.units = {"session_id": "bf06d8cb5d8137290c4abb64155584fbdb64d8",
"user_id": "12345"}
context_config = ContextConfig()
ctx = sdk.create_context(context_config)
ctx.wait_until_ready_async()
```
**Refreshing the Context with Fresh Experiment Data**
For long-running contexts, the context is usually created once when the application is first started.
However, any experiments being tracked in your production code, but started after the context was created, will not be triggered.
To mitigate this, we can use the `set_refresh_interval()` method on the context config.
```python
default_client_config = DefaultHTTPClientConfig()
default_client_config.refresh_interval = 5
```
Alternatively, the `refresh()` method can be called manually.
The `refresh()` method pulls updated experiment data from the A/B Smartly collector and will trigger recently started experiments when `get_treatment()` is called again.
```python
context.refresh()
```
**Setting Extra Units**
You can add additional units to a context by calling the `set_unit()` or the `set_units()` method.
This method may be used for example, when a user logs in to your application, and you want to use the new unit type to the context.
Please note that **you cannot override an already set unit type** as that would be a change of identity, and will throw an exception. In this case, you must create a new context instead.
The `SetUnit()` and `SetUnits()` methods can be called before the context is ready.
```python
context.set_unit("db_user_id", "1000013")
context.set_units({
"db_user_id": "1000013"
})
```
## Basic Usage
#### Selecting a treatment
```python
res, _ = context.get_treatment("exp_test_experiment")
if res == 0:
# user is in control group (variant 0)
else:
# user is in treatment group
```
### Treatment Variables
```python
res = context.get_variable_value(key, 17)
```
#### Peek at treatment variants
Although generally not recommended, it is sometimes necessary to peek at a treatment or variable without triggering an exposure.
The A/B Smartly SDK provides a `peek_treament()` method for that.
```python
res = context.peek_treament("exp_test_experiment")
if res == 0:
# user is in control group (variant 0)
else:
# user is in treatment group
```
##### Peeking at variables
```python
variable = context.peek_variable("my_variable")
```
#### Overriding treatment variants
During development, for example, it is useful to force a treatment for an experiment. This can be achieved with the `override()` and/or `overrides()` methods.
The `set_override()` and `set_overrides()` methods can be called before the context is ready.
```python
context.set_override("exp_test_experiment", 1) # force variant 1 of treatment
context.set_overrides({
"exp_test_experiment": 1,
"exp_another_experiment": 0
})
```
## Advanced
### Context Attributes
Attributes are used to pass meta-data about the user and/or the request.
They can be used later in the Web Console to create segments or audiences.
The `set_attributes()` and `set_attributes()` methods can be called before the context is ready.
```python
context.set_attributes("user_agent", req.get_header("User-Agent"))
context.set_attributes({
"customer_age": "new_customer"
})
```
### Custom Assignments
Sometimes it may be necessary to override the automatic selection of a
variant. For example, if you wish to have your variant chosen based on
data from an API call. This can be accomplished using the
`set_custom_assignment()` method.
```python
context.set_custom_assignment("exp_test_not_eligible", 3)
```
If you are running multiple experiments and need to choose different
custom assignments for each one, you can do so using the
`set_custom_assignments()` method.
```python
context.set_custom_assignments({"db_user_id2": 1})
```
### Publish
Sometimes it is necessary to ensure all events have been published to the A/B Smartly collector, before proceeding.
You can explicitly call the `publish()` or `publish_async()` methods.
```python
context.publish()
```
### Finalize
The `close()` and `close_async()` methods will ensure all events have been published to the A/B Smartly collector, like `publish()`, and will also "seal" the context, throwing an error if any method that could generate an event is called.
```python
context.close()
```
### Tracking Goals
Goals are created in the A/B Smartly web console.
```python
context.track("payment", {
"item_count": 1,
"total_amount": 1999.99
})
```
## About A/B Smartly
**A/B Smartly** is the leading provider of state-of-the-art, on-premises, full-stack experimentation platforms for engineering and product teams that want to confidently deploy features as fast as they can develop them.
A/B Smartly's real-time analytics helps engineering and product teams ensure that new features will improve the customer experience without breaking or degrading performance and/or business metrics.
### Have a look at our growing list of clients and SDKs:
- [Java SDK](https://www.github.com/absmartly/java-sdk)
- [JavaScript SDK](https://www.github.com/absmartly/javascript-sdk)
- [PHP SDK](https://www.github.com/absmartly/php-sdk)
- [Swift SDK](https://www.github.com/absmartly/swift-sdk)
- [Vue2 SDK](https://www.github.com/absmartly/vue2-sdk)
- [Go SDK](https://www.github.com/absmartly/go-sdk)
- [Ruby SDK](https://www.github.com/absmartly/ruby-sdk)
Raw data
{
"_id": null,
"home_page": null,
"name": "ABSmartly",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ABSmartly, SDK, Testing",
"author": null,
"author_email": "ABSmartly <info@ABSmartly.com>",
"download_url": "https://files.pythonhosted.org/packages/11/c6/e7115367c923218b78468f4fa9b78eb1aafc790d573977da0d716b99d794/absmartly-0.2.3.tar.gz",
"platform": null,
"description": "# A/B Smartly SDK\n\nA/B Smartly - Python SDK\n\n## Compatibility\n\nThe A/B Smartly Python SDK is compatible with Python 3.\nIt provides both a blocking and an asynchronous interfaces.\n\n## Getting Started\n\n### Install the SDK\n ```bash\n pip install absmartly==0.2.3\n ```\n\n### Dependencies\n```\nsetuptools~=60.2.0 \nrequests~=2.28.1 \nurllib3~=1.26.12 \njsons~=1.6.3\n```\n\n\n\n## Import and Initialize the SDK\n\nOnce the SDK is installed, it can be initialized in your project.\n```python\n def main():\n client_config = ClientConfig()\n client_config.endpoint = \"https://sandbox.test.io/v1\"\n client_config.api_key = \"test\"\n client_config.application = \"www\"\n client_config.environment = \"prod\"\n \n default_client_config = DefaultHTTPClientConfig()\n default_client = DefaultHTTPClient(default_client_config)\n sdk_config = ABSmartlyConfig()\n sdk_config.client = Client(client_config, default_client)\n sdk = ABSmartly(sdk_config)\n \n context_config = ContextConfig()\n ctx = sdk.create_context(context_config)\n```\n\n**SDK Options**\n\n| Config | Type | Required? | Default | Description |\n| :---------- |:----------------------------------------------| :-------: |:---------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| endpoint | `string` | ✅ | `undefined` | The URL to your API endpoint. Most commonly `\"your-company.absmartly.io\"` |\n| apiKey | `string` | ✅ | `undefined` | Your API key which can be found on the Web Console. |\n| environment | `\"production\"` or `\"development\"` | ✅ | `undefined` | The environment of the platform where the SDK is installed. Environments are created on the Web Console and should match the available environments in your infrastructure. |\n| application | `string` | ✅ | `undefined` | The name of the application where the SDK is installed. Applications are created on the Web Console and should match the applications where your experiments will be running. |\n| max_retries | `number` | ❌ | `5` | The number of retries before the SDK stops trying to connect. |\n| connection_timeout | `number` | ❌ | `3` | An amount of time, in seconds, before the SDK will stop trying to connect. |\n| context_event_logger | `(self, event_type: EventType, data: object)` | ❌ | See \"Using a Custom Event Logger\" below | A callback function which runs after SDK events. \n\n#### Using a custom Event Logger\nThe A/B Smartly SDK can be instantiated with an event logger used for all contexts.\nIn addition, an event logger can be specified when creating a particular context, in the `ContextConfig`.\n```python\n class EventType(Enum):\n ERROR = \"error\"\n READY = \"ready\"\n REFRESH = \"refresh\"\n PUBLISH = \"publish\"\n EXPOSURE = \"exposure\"\n GOAL = \"goal\"\n CLOSE = \"close\"\n \n \n class ContextEventLogger:\n \n @abstractmethod\n def handle_event(self, event_type: EventType, data: object):\n raise NotImplementedError\n```\nThe data parameter depends on the type of event.\nCurrently, the SDK logs the following events:\n\n| event | when | data |\n|:---: |------------------------------------------------------------|---|\n| `Error` | `Context` receives an error | `Throwable` object |\n| `Ready` | `Context` turns ready | `ContextData` used to initialize the context |\n| `Refresh` | `Context.refresh()` method succeeds | `ContextData` used to refresh the context |\n| `Publish` | `Context.publish()` method succeeds | `PublishEvent` sent to the A/B Smartly event collector |\n| `Exposure` | `Context.getTreatment()` method succeeds on first exposure | `Exposure` enqueued for publishing |\n| `Goal` | `Context.track()` method succeeds | `GoalAchievement` enqueued for publishing |\n| `Close` | `Context.close()` method succeeds the first time | `null` |\n\n\n## Create a New Context Request\n\n**Synchronously**\n```python\n# define a new context request\n context_config = ContextConfig()\n context_config.publish_delay = 10\n context_config.refresh_interval = 5\n\n context_config = ContextConfig()\n ctx = sdk.create_context(context_config)\n ctx.wait_until_ready()\n```\n\n**Asynchronously**\n```python\n# define a new context request\n context_config = ContextConfig()\n context_config.publish_delay = 10\n context_config.refresh_interval = 5\n\n context_config = ContextConfig()\n ctx = sdk.create_context(context_config)\n ctx.wait_until_ready_async()\n```\n\n**With Prefetched Data**\n```python\n# define a new context request\n context_config = ContextConfig()\n context_config.publish_delay = 10\n context_config.refresh_interval = 5\n context_config.units = {\"session_id\": \"bf06d8cb5d8137290c4abb64155584fbdb64d8\",\n \"user_id\": \"12345\"}\n \n context_config = ContextConfig()\n ctx = sdk.create_context(context_config)\n ctx.wait_until_ready_async()\n```\n\n**Refreshing the Context with Fresh Experiment Data**\nFor long-running contexts, the context is usually created once when the application is first started.\nHowever, any experiments being tracked in your production code, but started after the context was created, will not be triggered.\nTo mitigate this, we can use the `set_refresh_interval()` method on the context config.\n\n```python\n default_client_config = DefaultHTTPClientConfig()\n default_client_config.refresh_interval = 5\n```\n\nAlternatively, the `refresh()` method can be called manually.\nThe `refresh()` method pulls updated experiment data from the A/B Smartly collector and will trigger recently started experiments when `get_treatment()` is called again.\n```python\n context.refresh()\n```\n\n**Setting Extra Units**\nYou can add additional units to a context by calling the `set_unit()` or the `set_units()` method.\nThis method may be used for example, when a user logs in to your application, and you want to use the new unit type to the context.\nPlease note that **you cannot override an already set unit type** as that would be a change of identity, and will throw an exception. In this case, you must create a new context instead.\nThe `SetUnit()` and `SetUnits()` methods can be called before the context is ready.\n\n```python\n context.set_unit(\"db_user_id\", \"1000013\")\n \n context.set_units({\n \"db_user_id\": \"1000013\"\n })\n```\n\n## Basic Usage\n\n#### Selecting a treatment\n```python\n res, _ = context.get_treatment(\"exp_test_experiment\")\n if res == 0:\n # user is in control group (variant 0)\n else:\n # user is in treatment group\n```\n\n### Treatment Variables\n\n```python\n res = context.get_variable_value(key, 17)\n```\n\n\n#### Peek at treatment variants\nAlthough generally not recommended, it is sometimes necessary to peek at a treatment or variable without triggering an exposure.\nThe A/B Smartly SDK provides a `peek_treament()` method for that.\n\n```python\n res = context.peek_treament(\"exp_test_experiment\")\n if res == 0:\n # user is in control group (variant 0)\n else:\n # user is in treatment group\n\n```\n##### Peeking at variables\n```python\n variable = context.peek_variable(\"my_variable\")\n```\n\n#### Overriding treatment variants\nDuring development, for example, it is useful to force a treatment for an experiment. This can be achieved with the `override()` and/or `overrides()` methods.\nThe `set_override()` and `set_overrides()` methods can be called before the context is ready.\n```python\n context.set_override(\"exp_test_experiment\", 1) # force variant 1 of treatment\n context.set_overrides({\n \"exp_test_experiment\": 1,\n \"exp_another_experiment\": 0\n })\n```\n\n## Advanced\n\n### Context Attributes\nAttributes are used to pass meta-data about the user and/or the request.\nThey can be used later in the Web Console to create segments or audiences.\nThe `set_attributes()` and `set_attributes()` methods can be called before the context is ready.\n```python\n context.set_attributes(\"user_agent\", req.get_header(\"User-Agent\"))\n \n context.set_attributes({\n \"customer_age\": \"new_customer\"\n })\n```\n\n### Custom Assignments\n\nSometimes it may be necessary to override the automatic selection of a\nvariant. For example, if you wish to have your variant chosen based on\ndata from an API call. This can be accomplished using the\n`set_custom_assignment()` method.\n\n```python\n context.set_custom_assignment(\"exp_test_not_eligible\", 3)\n```\n\nIf you are running multiple experiments and need to choose different\ncustom assignments for each one, you can do so using the\n`set_custom_assignments()` method.\n\n```python\n context.set_custom_assignments({\"db_user_id2\": 1})\n```\n\n### Publish\nSometimes it is necessary to ensure all events have been published to the A/B Smartly collector, before proceeding.\nYou can explicitly call the `publish()` or `publish_async()` methods.\n```python\n context.publish()\n```\n\n### Finalize\nThe `close()` and `close_async()` methods will ensure all events have been published to the A/B Smartly collector, like `publish()`, and will also \"seal\" the context, throwing an error if any method that could generate an event is called.\n```python\n context.close()\n```\n\n### Tracking Goals\nGoals are created in the A/B Smartly web console.\n```python\n context.track(\"payment\", {\n \"item_count\": 1,\n \"total_amount\": 1999.99\n })\n```\n\n## About A/B Smartly\n**A/B Smartly** is the leading provider of state-of-the-art, on-premises, full-stack experimentation platforms for engineering and product teams that want to confidently deploy features as fast as they can develop them.\nA/B Smartly's real-time analytics helps engineering and product teams ensure that new features will improve the customer experience without breaking or degrading performance and/or business metrics.\n\n### Have a look at our growing list of clients and SDKs:\n- [Java SDK](https://www.github.com/absmartly/java-sdk)\n- [JavaScript SDK](https://www.github.com/absmartly/javascript-sdk)\n- [PHP SDK](https://www.github.com/absmartly/php-sdk)\n- [Swift SDK](https://www.github.com/absmartly/swift-sdk)\n- [Vue2 SDK](https://www.github.com/absmartly/vue2-sdk)\n- [Go SDK](https://www.github.com/absmartly/go-sdk)\n- [Ruby SDK](https://www.github.com/absmartly/ruby-sdk)\n",
"bugtrack_url": null,
"license": "The MIT License (MIT) Copyright \u00a9 2022 <copyright holders> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \u201cSoftware\u201d), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \u201cAS IS\u201d, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "ABSmartly Python SDK lib",
"version": "0.2.3",
"project_urls": {
"Homepage": "https://github.com/absmartly/python3-sdk"
},
"split_keywords": [
"absmartly",
" sdk",
" testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "db0004fbeb6414831fbcd08e9e12d5cfc6e1cccd8cf3b625a6e25361eeedd75c",
"md5": "ead1e532ab3c9f255c70bce7e6411380",
"sha256": "9d66cefce646c1ecb1ab56c7f0878b454403b9dd26b595e3497d842f3a6e3a8f"
},
"downloads": -1,
"filename": "ABSmartly-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ead1e532ab3c9f255c70bce7e6411380",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 37366,
"upload_time": "2024-04-18T10:34:00",
"upload_time_iso_8601": "2024-04-18T10:34:00.857461Z",
"url": "https://files.pythonhosted.org/packages/db/00/04fbeb6414831fbcd08e9e12d5cfc6e1cccd8cf3b625a6e25361eeedd75c/ABSmartly-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "11c6e7115367c923218b78468f4fa9b78eb1aafc790d573977da0d716b99d794",
"md5": "9d1e21de8f295f3dfeebc9832bd19b8c",
"sha256": "b25c4dc00f0adcf109e0ac01eb287b28b7fcc0e9d34d2cdf4abf99f450e988dc"
},
"downloads": -1,
"filename": "absmartly-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "9d1e21de8f295f3dfeebc9832bd19b8c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 29829,
"upload_time": "2024-04-18T10:34:02",
"upload_time_iso_8601": "2024-04-18T10:34:02.794464Z",
"url": "https://files.pythonhosted.org/packages/11/c6/e7115367c923218b78468f4fa9b78eb1aafc790d573977da0d716b99d794/absmartly-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-18 10:34:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "absmartly",
"github_project": "python3-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "absmartly"
}
