GrowthBook Python SDK
Powerful Feature flagging and A/B testing for Python apps.
![Build Status](https://github.com/growthbook/growthbook-python/workflows/Build/badge.svg)
- Lightweight and fast
- Local evaluation, no network requests required
- Python 3.6+
- 100% test coverage
- Flexible targeting
- Use your existing event tracking (GA, Segment, Mixpanel, custom)
- Remote configuration to change feature flags without deploying new code
Installation
pip install growthbook
(recommended) or copy growthbook.py
into your project
Quick Usage
from growthbook import GrowthBook
attributes = {
"id": "123",
"customUserAttribute": "foo"
}
def on_experiment_viewed(experiment, result):
analytics.track(attributes["id"], "Experiment Viewed", {
'experimentId': experiment.key,
'variationId': result.variationId
})
gb = GrowthBook(
attributes = attributes,
on_experiment_viewed = on_experiment_viewed,
api_host = "https://cdn.growthbook.io",
client_key = "sdk-abc123"
)
gb.load_features()
if gb.is_on("my-feature"):
print("My feature is on!")
color = gb.get_feature_value("button-color-feature", "blue")
Web Frameworks (Django, Flask, etc.)
For web frameworks, you should create a new GrowthBook
instance for every incoming request and call destroy()
at the end of the request to clean up resources.
In Django, for example, this is best done with a simple middleware:
from growthbook import GrowthBook
def growthbook_middleware(get_response):
def middleware(request):
request.gb = GrowthBook(
)
request.gb.load_features()
response = get_response(request)
request.gb.destroy()
return response
return middleware
Then, you can easily use GrowthBook in any of your views:
def index(request):
feature_enabled = request.gb.is_on("my-feature")
Loading Features
There are two ways to load feature flags into the GrowthBook SDK. You can either use the built-in fetching/caching logic or implement your own custom solution.
Built-in Fetching and Caching
To use the built-in fetching and caching logic, in the GrowthBook
constructor, pass in your GrowthBook api_host
and client_key
. If you have encryption enabled for your GrowthBook endpoint, you also need to pass the decryption_key
into the constructor.
Then, call the load_features()
method to initiate the HTTP request with a cache layer.
Here's a full example:
gb = GrowthBook(
api_host = "https://cdn.growthbook.io",
client_key = "sdk-abc123",
cache_ttl = 60,
)
gb.load_features()
Caching
GrowthBook comes with a custom in-memory cache. If you run Python in a multi-process mode, the different processes cannot share memory, so you likely want to switch to a distributed cache system like Redis instead.
Here is an example of using Redis:
from redis import Redis
import json
from growthbook import GrowthBook, AbstractFeatureCache, feature_repo
class RedisFeatureCache(AbstractFeatureCache):
def __init__(self):
self.r = Redis(host='localhost', port=6379)
self.prefix = "gb:"
def get(self, key: str):
data = self.r.get(self.prefix + key)
return None if data is None else json.loads(data)
def set(self, key: str, value: dict, ttl: int) -> None:
self.r.set(self.prefix + key, json.dumps(value))
self.r.expire(self.prefix + key, ttl)
feature_repo.set_cache(RedisFeatureCache())
Custom Implementation
If you prefer to handle the entire fetching/caching logic yourself, you can just pass in a dict
of features from the GrowthBook API directly into the constructor:
features = {'my-feature':{'defaultValue':False}}
gb = GrowthBook(
features = features
)
Note: When doing this, you do not need to specify your api_host
or client_key
and you don't need to call gb.load_features()
.
GrowthBook class
The GrowthBook constructor has the following parameters:
- enabled (
bool
) - Flag to globally disable all experiments. Default true. - attributes (
dict
) - Dictionary of user attributes that are used for targeting and to assign variations - url (
str
) - The URL of the current request (if applicable) - qa_mode (
boolean
) - If true, random assignment is disabled and only explicitly forced variations are used. - on_experiment_viewed (
callable
) - A function that takes experiment
and result
as arguments. - api_host (
str
) - The GrowthBook API host to fetch feature flags from. Defaults to https://cdn.growthbook.io
- client_key (
str
) - The client key that will be passed to the API Host to fetch feature flags - decryption_key (
str
) - If the GrowthBook API endpoint has encryption enabled, specify the decryption key here - cache_ttl (
int
) - How long to cache features in-memory from the GrowthBook API (seconds, default 60
) - features (
dict
) - Feature definitions from the GrowthBook API (only required if client_key
is not specified) - forced_variations (
dict
) - Dictionary of forced experiment variations (used for QA)
There are also getter and setter methods for features and attributes if you need to update them later in the request:
gb.set_features(gb.get_features())
gb.set_attributes(gb.get_attributes())
Attributes
You can specify attributes about the current user and request. These are used for two things:
- Feature targeting (e.g. paid users get one value, free users get another)
- Assigning persistent variations in A/B tests (e.g. user id "123" always gets variation B)
Attributes can be any JSON data type - boolean, integer, float, string, list, or dict.
attributes = {
'id': "123",
'loggedIn': True,
'age': 21.5,
'tags': ["tag1", "tag2"],
'account': {
'age': 90
}
}
gb = GrowthBook(attributes = attributes)
gb.set_attributes(attributes)
Tracking Experiments
Any time an experiment is run to determine the value of a feature, you want to track that event in your analytics system.
You can use the on_experiment_viewed
option to do this:
from growthbook import GrowthBook, Experiment, Result
def on_experiment_viewed(experiment: Experiment, result: Result):
analytics.track(attributes["id"], "Experiment Viewed", {
'experimentId': experiment.key,
'variationId': result.variationId
})
gb = GrowthBook(
on_experiment_viewed = on_experiment_viewed
)
Using Features
There are 3 main methods for interacting with features.
gb.is_on("feature-key")
returns true if the feature is ongb.is_off("feature-key")
returns false if the feature is ongb.get_feature_value("feature-key", "default")
returns the value of the feature with a fallback
In addition, you can use gb.evalFeature("feature-key")
to get back a FeatureResult
object with the following properties:
- value - The JSON-decoded value of the feature (or
None
if not defined) - on and off - The JSON-decoded value cast to booleans
- source - Why the value was assigned to the user. One of
unknownFeature
, defaultValue
, force
, or experiment
- experiment - Information about the experiment (if any) which was used to assign the value to the user
- experimentResult - The result of the experiment (if any) which was used to assign the value to the user
Sticky Bucketing
By default GrowthBook does not persist assigned experiment variations for a user. We rely on deterministic hashing to ensure that the same user attributes always map to the same experiment variation. However, there are cases where this isn't good enough. For example, if you change targeting conditions in the middle of an experiment, users may stop being shown a variation even if they were previously bucketed into it.
Sticky Bucketing is a solution to these issues. You can provide a Sticky Bucket Service to the GrowthBook instance to persist previously seen variations and ensure that the user experience remains consistent for your users.
A sample InMemoryStickyBucketService
implementation is provided for reference, but in production you will definitely want to implement your own version using a database, cookies, or similar for persistence.
Sticky Bucket documents contain three fields
attributeName
- The name of the attribute used to identify the user (e.g. id
, cookie_id
, etc.)attributeValue
- The value of the attribute (e.g. 123
)assignments
- A dictionary of persisted experiment assignments. For example: {"exp1__0":"control"}
The attributeName/attributeValue combo is the primary key.
Here's an example implementation using a theoretical db
object:
from growthbook import AbstractStickyBucketService, GrowthBook
class MyStickyBucketService(AbstractStickyBucketService):
def get_assignments(self, attributeName: str, attributeValue: str) -> Optional[Dict]:
return db.find({
"attributeName": attributeName,
"attributeValue": attributeValue
})
def save_assignments(self, doc: Dict) -> None:
db.upsert({
"attributeName": doc["attributeName"],
"attributeValue": doc["attributeValue"]
}, {
"$set": {
"assignments": doc["assignments"]
}
})
gb = GrowthBook(
sticky_bucket_service = MyStickyBucketService()
)
Inline Experiments
Instead of declaring all features up-front and referencing them by ids in your code, you can also just run an experiment directly. This is done with the run
method:
from growthbook import Experiment
exp = Experiment(
key = "my-experiment",
variations = ["red", "blue", "green"]
)
print(gb.run(exp).value)
As you can see, there are 2 required parameters for experiments, a string key, and an array of variations. Variations can be any data type, not just strings.
There are a number of additional settings to control the experiment behavior:
- key (
str
) - The globally unique tracking key for the experiment - variations (
any[]
) - The different variations to choose between - seed (
str
) - Added to the user id when hashing to determine a variation. Defaults to the experiment key
- weights (
float[]
) - How to weight traffic between variations. Must add to 1. - coverage (
float
) - What percent of users should be included in the experiment (between 0 and 1, inclusive) - condition (
dict
) - Targeting conditions - force (
int
) - All users included in the experiment will be forced into the specified variation index - hashAttribute (
string
) - What user attribute should be used to assign variations (defaults to "id") - hashVersion (
int
) - What version of our hashing algorithm to use. We recommend using the latest version 2
. - namespace (
tuple[str,float,float]
) - Used to run mutually exclusive experiments.
Here's an example that uses all of them:
exp = Experiment(
key="my-test",
variations=[0, 1],
seed="abcdef123456",
weights=[0.4, 0.6],
coverage=0.2,
condition={
'country': 'US',
'browser': {
'$in': ['chrome', 'firefox']
}
},
hashAttribute="sessionId",
hashVersion=2,
namespace=("pricing", 0, 0.5),
)
Inline Experiment Return Value
A call to run
returns a Result
object with a few useful properties:
result = gb.run(exp)
print(result.inExperiment)
print(result.variationId)
print(result.value)
print(result.hashUsed)
print(result.hashAttribute)
print(result.hashValue)
The inExperiment
flag will be false if the user was excluded from being part of the experiment for any reason (e.g. failed targeting conditions).
The hashUsed
flag will only be true if the user was randomly assigned a variation. If the user was forced into a specific variation instead, this flag will be false.
Example Experiments
3-way experiment with uneven variation weights:
gb.run(Experiment(
key = "3-way-uneven",
variations = ["A","B","C"],
weights = [0.5, 0.25, 0.25]
))
Slow rollout (10% of users who match the targeting condition):
gb = GrowthBook(
attributes = {
"id": "123",
"beta": True,
"qa": True,
},
)
gb.run(Experiment(
key = "slow-rollout",
variations = ["A", "B"],
coverage = 0.1,
condition = {
'beta': True
}
))
Complex variations
result = gb.run(Experiment(
key = "complex-variations",
variations = [
("blue", "large"),
("green", "small")
],
))
print(result.value[0] + "," + result.value[1])
Assign variations based on something other than user id
gb = GrowthBook(
attributes = {
"id": "123",
"company": "growthbook"
}
)
gb.run(Experiment(
key = "by-company-id",
variations = ["A", "B"],
hashAttribute = "company"
))
Logging
The GrowthBook SDK uses a Python logger with the name growthbook
and includes helpful info for debugging as well as warnings/errors if something is misconfigured.
Here's an example of logging to the console
import logging
logger = logging.getLogger('growthbook')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler()
formatter = logging.Formatter('%(asctime)s %(name)s %(levelname)s %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)