|
| 1 | +# LaunchDarkly OpenFeature provider for the Server-Side SDK for Python |
| 2 | + |
| 3 | +[](https://github.com/launchdarkly/openfeature-python-server/actions/workflows/ci.yml) |
| 4 | +[](https://packagist.org/packages/launchdarkly/openfeature-server) |
| 5 | +[](https://launchdarkly-openfeature-server.readthedocs.io/en/latest/) |
| 6 | + |
| 7 | +This provider allows for using LaunchDarkly with the OpenFeature SDK for Python. |
| 8 | + |
| 9 | +This provider is designed primarily for use in multi-user systems such as web servers and applications. It follows the server-side LaunchDarkly model for multi-user contexts. It is not intended for use in desktop and embedded systems applications. |
| 10 | + |
| 11 | +This provider is a beta version and should not be considered ready for production use while this message is visible. |
| 12 | + |
| 13 | +# LaunchDarkly overview |
| 14 | + |
| 15 | +[LaunchDarkly](https://www.launchdarkly.com) is a feature management platform that serves trillions of feature flags daily to help teams build better software, faster. [Get started](https://docs.launchdarkly.com/home/getting-started) using LaunchDarkly today! |
| 16 | + |
| 17 | +[](https://twitter.com/intent/follow?screen_name=launchdarkly) |
| 18 | + |
| 19 | +## Supported Python versions |
| 20 | + |
| 21 | +This version of the LaunchDarkly provider works with Python 3.8 and above. |
| 22 | + |
| 23 | +## Getting started |
| 24 | + |
| 25 | +### Requisites |
| 26 | + |
| 27 | +Install the library via pip |
| 28 | + |
| 29 | +```shell |
| 30 | +$ pip install launchdarkly-openfeature-server |
| 31 | +``` |
| 32 | + |
| 33 | +### Usage |
| 34 | + |
| 35 | +```python |
| 36 | +from ldclient import Config, LDClient |
| 37 | +from ld_openfeature import LaunchDarklyProvider |
| 38 | +from openfeature.evaluation_context import EvaluationContext |
| 39 | +from openfeature import api |
| 40 | + |
| 41 | +ld_client = LDClient(config=Config("sdk-key")) |
| 42 | +openfeature_provider = LaunchDarklyProvider(ld_client) |
| 43 | + |
| 44 | +api.set_provider(openfeature_provider) |
| 45 | + |
| 46 | +# Refer to OpenFeature documentation for getting a client and performing evaluations. |
| 47 | +``` |
| 48 | + |
| 49 | +Refer to the [SDK reference guide](https://docs.launchdarkly.com/sdk/server-side/python) for instructions on getting started with using the SDK. |
| 50 | + |
| 51 | +For information on using the OpenFeature client please refer to the [OpenFeature Documentation](https://docs.openfeature.dev/docs/reference/concepts/evaluation-api/). |
| 52 | + |
| 53 | +## OpenFeature Specific Considerations |
| 54 | + |
| 55 | +LaunchDarkly evaluates contexts, and it can either evaluate a single-context, or a multi-context. When using OpenFeature both single and multi-contexts must be encoded into a single `EvaluationContext`. This is accomplished by looking for an attribute named `kind` in the `EvaluationContext`. |
| 56 | + |
| 57 | +There are 4 different scenarios related to the `kind`: |
| 58 | +1. There is no `kind` attribute. In this case the provider will treat the context as a single context containing a "user" kind. |
| 59 | +2. There is a `kind` attribute, and the value of that attribute is "multi". This will indicate to the provider that the context is a multi-context. |
| 60 | +3. There is a `kind` attribute, and the value of that attribute is a string other than "multi". This will indicate to the provider a single context of the kind specified. |
| 61 | +4. There is a `kind` attribute, and the attribute is not a string. In this case the value of the attribute will be discarded, and the context will be treated as a "user". An error message will be logged. |
| 62 | + |
| 63 | +The `kind` attribute should be a string containing only contain ASCII letters, numbers, `.`, `_` or `-`. |
| 64 | + |
| 65 | +The OpenFeature specification allows for an optional targeting key, but LaunchDarkly requires a key for evaluation. A targeting key must be specified for each context being evaluated. It may be specified using either `targetingKey`, as it is in the OpenFeature specification, or `key`, which is the typical LaunchDarkly identifier for the targeting key. If a `targetingKey` and a `key` are specified, then the `targetingKey` will take precedence. |
| 66 | + |
| 67 | +There are several other attributes which have special functionality within a single or multi-context. |
| 68 | +- A key of `privateAttributes`. Must be an array of string values. [Equivalent to the 'private' builder method in the SDK.](https://launchdarkly-python-sdk.readthedocs.io/en/latest/api-main.html#ldclient.ContextBuilder.private) |
| 69 | +- A key of `anonymous`. Must be a boolean value. [Equivalent to the 'anonymous' builder method in the SDK.](https://launchdarkly-python-sdk.readthedocs.io/en/latest/api-main.html#ldclient.ContextBuilder.anonymous) |
| 70 | +- A key of `name`. Must be a string. [Equivalent to the 'name' builder method in the SDK.](https://launchdarkly-python-sdk.readthedocs.io/en/latest/api-main.html#ldclient.ContextBuilder.name) |
| 71 | + |
| 72 | +### Examples |
| 73 | + |
| 74 | +#### A single user context |
| 75 | + |
| 76 | +```python |
| 77 | +context = EvaluationContext("the-key") |
| 78 | +``` |
| 79 | + |
| 80 | +#### A single context of kind "organization" |
| 81 | + |
| 82 | +```python |
| 83 | +context = EvaluationContext("org-key", {"kind": "organization"}); |
| 84 | +``` |
| 85 | + |
| 86 | +#### A multi-context containing a "user" and an "organization" |
| 87 | + |
| 88 | +```python |
| 89 | +attributes = { |
| 90 | + "kind": "multi", |
| 91 | + "organization": { |
| 92 | + "name": "the-org-name", |
| 93 | + "targetingKey", "my-org-key", |
| 94 | + "myCustomAttribute", "myAttributeValue" |
| 95 | + }, |
| 96 | + "user": { |
| 97 | + "key": "my-user-key", |
| 98 | + "anonymous", true |
| 99 | + } |
| 100 | +} |
| 101 | +context = EvaluationContext(null, attributes) |
| 102 | +``` |
| 103 | + |
| 104 | +#### Setting private attributes in a single context |
| 105 | + |
| 106 | +```python |
| 107 | +attributes = { |
| 108 | + "kind": "organization", |
| 109 | + "myCustomAttribute": "myAttributeValue", |
| 110 | + "privateAttributes": ["myCustomAttribute"] |
| 111 | +} |
| 112 | + |
| 113 | +context = EvaluationContext("org-key", attributes) |
| 114 | +``` |
| 115 | + |
| 116 | +#### Setting private attributes in a multi-context |
| 117 | + |
| 118 | +```python |
| 119 | +attributes = { |
| 120 | + "kind": "organization", |
| 121 | + "organization": { |
| 122 | + "name": "the-org-name", |
| 123 | + "targetingKey": "my-org-key", |
| 124 | + # This will ONLY apply to the "organization" attributes. |
| 125 | + "privateAttributes": ["myCustomAttribute"], |
| 126 | + # This attribute will be private. |
| 127 | + "myCustomAttribute": "myAttributeValue", |
| 128 | + }, |
| 129 | + "user": [ |
| 130 | + "key": "my-user-key", |
| 131 | + "anonymous" = > true, |
| 132 | + # This attribute will not be private. |
| 133 | + "myCustomAttribute": "myAttributeValue", |
| 134 | + ] |
| 135 | +} |
| 136 | + |
| 137 | +context = EvaluationContext(null, attributes) |
| 138 | +``` |
| 139 | + |
| 140 | +## Learn more |
| 141 | + |
| 142 | +Check out our [documentation](http://docs.launchdarkly.com) for in-depth instructions on configuring and using LaunchDarkly. You can also head straight to the [complete reference guide for this SDK](https://docs.launchdarkly.com/sdk/server-side/python). |
| 143 | + |
| 144 | +The authoritative description of all properties and methods is in the [python documentation](https://launchdarkly.github.io/python-server-sdk/). |
| 145 | + |
| 146 | +## Contributing |
| 147 | + |
| 148 | +We encourage pull requests and other contributions from the community. Check out our [contributing guidelines](CONTRIBUTING.md) for instructions on how to contribute to this SDK. |
| 149 | + |
| 150 | +## About LaunchDarkly |
| 151 | + |
| 152 | +* LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can: |
| 153 | + * Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases. |
| 154 | + * Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?). |
| 155 | + * Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file. |
| 156 | + * Grant access to certain features based on user attributes, like payment plan (eg: users on the ‘gold’ plan get access to more features than users in the ‘silver’ plan). Disable parts of your application to facilitate maintenance, without taking everything offline. |
| 157 | +* LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Check out [our documentation](https://docs.launchdarkly.com/sdk) for a complete list. |
| 158 | +* Explore LaunchDarkly |
| 159 | + * [launchdarkly.com](https://www.launchdarkly.com/ "LaunchDarkly Main Website") for more information |
| 160 | + * [docs.launchdarkly.com](https://docs.launchdarkly.com/ "LaunchDarkly Documentation") for our documentation and SDK reference guides |
| 161 | + * [apidocs.launchdarkly.com](https://apidocs.launchdarkly.com/ "LaunchDarkly API Documentation") for our API documentation |
| 162 | + * [blog.launchdarkly.com](https://blog.launchdarkly.com/ "LaunchDarkly Blog Documentation") for the latest product updates |
0 commit comments