> ## Documentation Index
> Fetch the complete documentation index at: https://statsig-4b2ff144-devin-1763168466-llm-docs-audit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Python Server SDK
> Statsig's Next-gen Python Server SDK built in our [Server Core](/server-core) framework
Python Core on Github
Migrating from the Legacy Python SDK? See our [Migration Guide](/server-core/migration-guides/python).
## Setup the SDK
This page explains setup the sdk.
## Installation
This page explains installation.
```shell theme={null}
pip install statsig-python-core
```
## Tested Platforms
Docker base images where the Python Core SDK has been tested and verified:
| Docker Base Image | Description |
| ----------------------------------- | ---------------------------------------------------- |
| `python:3.7-alpine` | Python 3.7 on Alpine Linux |
| `python:3.7-buster` | Python 3.7 on Debian Buster |
| `python:3.7-slim` | Python 3.7 slim variant |
| `quay.io/pypa/manylinux2014_x86_64` | Manylinux 2014 x86\_64 for broad Linux compatibility |
| `python:3.10-alpine` | Python 3.10 on Alpine Linux |
| `python:3.10-slim` | Python 3.10 slim variant |
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to create logic branches in code that can be rolled out to different users from the Statsig Console. Gates are always **CLOSED** or **OFF** (think `return false;`) by default.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```python theme={null}
user = StatsigUser("a-user")
if statsig.check_gate(user, "a_gate"):
# Gate is on, enable new feature
else:
# Gate is off
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```python theme={null}
# Get a dynamic config for a specific user
config = statsig.get_dynamic_config(StatsigUser("my_user"), "a_config")
# Access config values with type-safe getters and fallback values
product_name = config.get_string("product_name", "Awesome Product v1") # returns String
price = config.get_float("price", 10.0) # returns float
should_discount = config.get_bool("discount", False) # returns bool
quantity = config.get_integer("quantity", 1) # returns int64
# Advanced Usage:
# You can disable exposure logging for this specific check
options = DynamicConfigEvaluationOptions(disable_exposure_logging=True)
config = statsig.get_dynamic_config(user, "a_config", options)
# The config object also provides metadata about the evaluation
print(config.rule_id) # The ID of the rule that served this config
print(config.id_type) # The type of the evaluation (experiment, config, etc)
```
The `get_dynamic_config()` method returns a DynamicConfig object that allows you to:
* Fetch typed values with fallback defaults using `get_string()`, `get_float()`, `get_boolean()`, and `get_integer()`
* Access evaluation metadata through properties like `rule_id` and `id_type`
* Configure evaluation behavior using `DynamicConfigEvaluationOptions`
By default, Statsig logs exposures automatically when configs are evaluated. You can disable this for specific checks using the evaluation options.
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```Python theme={null}
# Values via get_layer
layer = statsig.get_layer(StatsigUser("my_user"), "user_promo_experiments")
title = layer.get_string("title", "Welcome to Statsig!")
discount = layer.get_float("discount", 0.1)
# Via get_experiment
title_exp = statsig.get_experiment(StatsigUser("my_user"), "new_user_promo_title")
price_exp = statsig.get_experiment(StatsigUser("my_user"), "new_user_promo_price")
title = title_exp.get_string("title", "Welcome to Statsig!")
discount = price_exp.get_float("discount", 0.1)
```
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```python theme={null}
gate = statsig.get_feature_gate(user, "example_gate")
print(gate.rule_id)
print(gate.value)
```
### Parameter Stores
Sometimes you don't know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.
````python theme={null}
# Get a Parameter Store by name
This page explains get a parameter store by name.
param_store = statsig.get_parameter_store(user, "my_parameter_store")
```text
## Retrieving Parameter Values
Parameter Store provides methods for retrieving values of different types with fallback defaults.
```python
# String parameters
string_value = param_store.get_string("string_param", "default_value")
# Boolean parameters
bool_value = param_store.get_bool("bool_param", False)
# Numeric parameters
float_value = param_store.get_float("float_param", 0.0)
integer_value = param_store.get_integer("integer_param", 0)
# Complex parameters
default_array = ["item1", "item2"]
array_value = param_store.get_array("array_param", default_array)
default_map = {"key": "value"}
map_value = param_store.get_map("map_param", default_map)
```text
## Evaluation Options
You can disable exposure logging when retrieving a parameter store:
```python
from statsig_python_core import ParameterStoreEvaluationOptions
options = ParameterStoreEvaluationOptions(disable_exposure_logging=True)
param_store = statsig.get_parameter_store(user, "my_parameter_store", options)
````
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```Python theme={null}
statsig.log_event(
user=StatsigUser("user_id"), # Replace with your user object
event_name="add_to_cart",
value="SKU_12345",
metadata={
"price": "9.99",
"item_name": "diet_coke_48_pack"
}
)
```
### Sending Events to Log Explorer
You can forward logs to Logs Explorer for convenient analysis using the Forward Log Line Event API. This lets you include custom metadata and event values with each log.
```python theme={null}
user = StatsigUser(
user_id="a-user",
custom={
"service": "my-service",
"pod": "my-pod",
"namespace": "my-namespace",
"container": "my-container",
# ...include any service-specific metadata
}
)
# levels: trace, debug, info, log, warn, error
statsig.forward_log_line_event(user, "warn", "script failed to load", {
"custom_metadata": "script_name:my-script"
# ... include any event-specific metadata
})
```
## Using Shared Instance
In some applications, you may want to create a single Statsig instance that can be accessed globally throughout your codebase. The shared instance functionality provides a singleton pattern for this purpose:
```python theme={null}
# Create a shared instance that can be accessed globally
statsig = Statsig.new_shared("secret-key", options)
statsig.initialize().wait()
# Access the shared instance from anywhere in your code
shared_statsig = Statsig.shared()
is_feature_enabled = shared_statsig.check_gate(StatsigUser("user_id"), "feature_name")
# Check if a shared instance exists
if Statsig.has_shared_instance():
# Use the shared instance
pass
# Remove the shared instance when no longer needed
Statsig.remove_shared()
```
The shared instance functionality provides a singleton pattern where a single Statsig instance can be created and accessed globally throughout your application. This is useful for applications that need to access Statsig functionality from multiple parts of the codebase without having to pass around a Statsig instance.
* `Statsig.new_shared(sdk_key, options)`: Creates a new shared instance of Statsig that can be accessed globally
* `Statsig.shared()`: Returns the shared instance
* `Statsig.has_shared_instance()`: Checks if a shared instance exists (useful when you aren't sure if the shared instance is ready yet)
* `Statsig.remove_shared()`: Removes the shared instance (useful when you want to switch to a new shared instance)
`has_shared_instance()` and `remove_shared()` are helpful in specific scenarios but aren't required in most use cases where the shared instance is set up near the top of your application.
Also note that only one shared instance can exist at a time. Attempting to create a second shared instance will result in an error.
## Manual Exposures
By default, the SDK will automatically log an exposure event when you check a gate, get a config, get an experiment, or call get() on a parameter in a layer. However, there are times when you may want to log an exposure event manually. For example, if you're using a gate to control access to a feature, but you don't want to log an exposure until the user actually uses the feature, you can use manual exposures.
All of the main SDK functions (`check_gate`, `get_dynamic_config`, `get_experiment`, `get_layer`) accept an optional `disable_exposure_logging` parameter. When this is set to `True`, the SDK will not automatically log an exposure event. You can then manually log the exposure at a later time using the corresponding manual exposure logging method:
````python theme={null}
result = statsig.check_gate(aUser, 'a_gate_name', FeatureGateEvaluationOptions(disable_exposure_logging=True))
```text
```python
statsig.manually_log_gate_exposure(aUser, 'a_gate_name')
```text
```python
config = statsig.get_dynamic_config(aUser, 'a_dynamic_config_name', DynamicConfigEvaluationOptions(disable_exposure_logging=True))
```text
```python
statsig.manually_log_dynamic_config_exposure(aUser, 'a_dynamic_config_name')
```text
```python
experiment = statsig.get_experiment(aUser, 'an_experiment_name', ExperimentEvaluationOptions(disable_exposure_logging=True))
```text
```python
statsig.manually_log_experiment_exposure(aUser, 'an_experiment_name')
```text
```python
layer = statsig.get_layer(aUser, 'a_layer_name', LayerEvaluationOptions(disable_exposure_logging=True))
paramValue = layer.get('a_param_name', 'fallback_value')
```text
```python
statsig.manually_log_layer_parameter_exposure(aUser, 'a_layer_name', 'a_param_name')
````
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. At least one ID (userID or customID) is required because it's needed to provide a consistent experience for a given user (click here)
Besides userID, we also have email, ip, userAgent, country, locale and appVersion as top-level fields on StatsigUser. In addition, you can pass any key-value pairs in an object/dictionary to the custom field and be able to create targeting based on them.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
```python expandable theme={null}
from statsig_python_core import StatsigUser
user = StatsigUser(
user_id="a-user-id",
email="user@example.com",
ip="192.168.1.1",
user_agent="Mozilla/5.0...",
country="US",
locale="en_US",
app_version="1.0.0",
custom={
# Custom fields
"plan": "premium",
"age": 25
},
custom_ids={
# Custom ID types
"stable_id": "stable-id-123"
},
private_attributes={
# Private attributes not forwarded to integrations
"email": "private@example.com"
}
)
```
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
Custom URL for fetching feature specifications.
How often the SDK updates specifications from Statsig servers (in milliseconds).
Sets the maximum timeout for initialization requests (in milliseconds).
Custom URL for logging events.
When `true`, disables all event logging.
When `true`, disables all network functions: event & exposure logging, spec downloads, and ID List downloads. Formerly called "localMode".
How often events are flushed to Statsig servers (in milliseconds).
Maximum number of events to queue before forcing a flush.
Enable/disable ID list functionality. **Required to be `true` when using segments with more than 1000 IDs.** See [ID List segments](/segments/add-id-list) for more details.
If set to true, the SDK will NOT attempt to parse UserAgents (attached to the user object) into browserName, browserVersion, systemName, systemVersion, and appVersion at evaluation time, when needed for evaluation.
When set to true, the SDK will wait until user agent parsing data is fully loaded during initialization. This may slow down by \~1 second startup but ensures that parsing of the user's userAgent string into fields like browserName, browserVersion, systemName, systemVersion, and appVersion is ready before any evaluations.
If set to true, the SDK will NOT attempt to parse IP addresses (attached to the user object at user.ip) into Country codes at evaluation time, when needed for evaluation.
When set to true, the SDK will wait for country lookup data (e.g., GeoIP or YAML files) to fully load during initialization. This may slow down by \~1 second startup but ensures that IP-to-country parsing is ready at evaluation time.
Custom URL for fetching ID lists.
How often the SDK updates ID lists from Statsig servers (in milliseconds).
Whether to fallback to the Statsig API if custom endpoints fail.
Environment parameter for evaluation.
Controls the verbosity of SDK logs.
Adapter / Interface to use persistent assignment within SDK. [More details](https://docs.statsig.com/server/concepts/persistent_assignment/)
Adapter to listen monitor the health of SDK. See [details](https://docs.statsig.com/sdk_monitoring/)
Custom data store implementation for storing and retrieving configuration data. Used for advanced caching or storage strategies.
Maximum number of batches of events to hold in buffer to retry.
Custom fields to include in all events logged by the SDK.
Compression method for exposure logging. Options: "gzip", "dictionary"
Configuration for connecting through a proxy server. The `ProxyConfig` object has the following properties:
* `proxy_host`: Optional string specifying the proxy server host
* `proxy_port`: Optional number specifying the proxy server port
* `proxy_auth`: Optional string for proxy authentication (format: "username:password")
* `proxy_protocol`: Optional string specifying the protocol (e.g., "http", "https")
Advanced configuration for customizing how the SDK fetches feature specifications. Allows you to configure multiple spec adapters with different priorities and settings.
Each `SpecAdapterConfig` object has the following properties:
* `adapter_type`: String specifying the adapter type (e.g., "http", "grpc")
* `specs_url`: Optional custom URL for fetching specifications
* `init_timeout_ms`: Optional timeout for initialization (in milliseconds)
**Migration Note:** This parameter was previously named `init_resources` in earlier versions. If you're upgrading from an older version, replace `init_resources` with `spec_adapter_configs`.
***
### Example Usage
This page explains example usage.
````python theme={null}
from statsig_python_core import StatsigOptions, SpecAdapterConfig
# Define proxy configuration if needed
proxy_config = {
"proxy_host": "proxy.example.com",
"proxy_port": 8080,
# "proxy_auth": "username:password", # Uncomment if authentication is needed
"proxy_protocol": "http"
}
# Initialize StatsigOptions with custom parameters
options = StatsigOptions()
options.environment = "development"
options.init_timeout_ms = 3000
options.disable_all_logging = False
options.proxy_config = proxy_config
# Pass the options object into statsig.initialize()
statsig = Statsig("secret-key", options)
statsig.initialize().wait()
```text
## Using spec_adapter_configs with Multiple Sources
```python
from statsig_python_core import StatsigOptions, SpecAdapterConfig
# Configure multiple spec adapters with priority order
# First source: Statsig CDN
primary_adapter = SpecAdapterConfig(
adapter_type="http",
specs_url="https://api.statsigcdn.com/v2/download_config_specs",
init_timeout_ms=3000
)
# Second source: Data Store adapter
# The SDK will try this source if the primary source fails
data_store_adapter = SpecAdapterConfig(
adapter_type="data_store",
init_timeout_ms=5000
)
options = StatsigOptions()
options.spec_adapter_configs = [primary_adapter, data_store_adapter]
options.environment = "production"
statsig = Statsig("secret-key", options)
statsig.initialize().wait()
````
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```python theme={null}
statsig.shutdown().wait()
```
## Local Overrides
Local Overrides are a way to override the values of gates, configs, experiments, and layers for testing purposes. This is useful for local development or testing scenarios where you want to force a specific value without having to change the configuration in the Statsig console.
```python theme={null}
# Overrides the given gate to the specified value
statsig.override_gate("a_gate_name", True)
# Overrides the given dynamic config to the provided value
statsig.override_dynamic_config("a_config_name", {"key": "value"})
# Overrides the given experiment to the provided value
statsig.override_experiment("an_experiment_name", {"key": "value"})
# Overrides the given layer to the provided value
statsig.override_layer("a_layer_name", {"key": "value"})
# Overrides the given experiment to a particular groupname, available for experiments only:
statsig.override_experiment_by_group_name("an_experiment_name", "a_group_name")
```
## Client SDK Bootstrapping | SSR
If you are using the Statsig client SDK in a browser or mobile app, you can bootstrap the client SDK with the values from the server SDK to avoid a network request on the client. This is useful for server-side rendering (SSR) or when you want to reduce the number of network requests on the client.
## Persistent Storage
The Persistent Storage interface allows you to implement custom storage for user-specific configurations. This enables you to persist user assignments across sessions, ensuring consistent experiment groups even when the user returns later. This is particularly useful for client-side A/B testing where you want to ensure users always see the same variant.
```python theme={null}
class PersistentStorage(PersistentStorageBaseClass):
def __init__():
# When you initialize, remember to call super.__init__()
super().__init__()
def load(self, key: str) -> Optional[UserPersistedValues]:
"""
Load persisted values for a user from storage
Args:
key: A string key that uniquely identifies a user
Returns:
Dictionary mapping config names to their persisted values
"""
pass
def save(self, key: str, config_name: str, data: StickyValues):
"""
Save a persistent value for a user
Args:
key: A string key that uniquely identifies a user
config_name: The name of the config/experiment
data: The values to persist
"""
pass
def delete(self, key: str, config_name: str):
"""
Delete a persistent value for a user
Args:
key: A string key that uniquely identifies a user
config_name: The name of the config/experiment to delete
"""
pass
```
## Data Store
The Data Store interface allows you to implement custom storage for Statsig configurations. This enables advanced caching strategies and integration with your preferred storage systems.
```python theme={null}
class DataStore(DataStoreBase):
def initialize(self):
"""
Initialize the data store. Called when the Statsig client initializes.
"""
pass
def shutdown(self):
"""
Clean up resources when the Statsig client shuts down.
"""
pass
def get(self, key: str) -> Optional[DataStoreResponse]:
"""
Retrieve value from the data store.
Args:
key: The key to retrieve the value for
Returns:
DataStoreResponse containing the result and time
"""
pass
def set(self, key: str, value: str, time: Optional[int] = None):
"""
Store a value in the data store.
Args:
key: The key to store the value under
value: The value to store
time: Optional timestamp
"""
pass
def support_polling_updates_for(self, key: str) -> bool:
"""
Whether the data store supports polling for updates for the given key.
Args:
key: The key to check
Returns:
True if polling is supported, False otherwise
"""
return False
```
## Custom Output Logger
The Output Logger interface allows you to customize how the SDK logs messages. This enables integration with your own logging system and control over log verbosity.
## Output Logger
The Output Logger Provider interface allows you to customize how the SDK logs internal messages.
```python theme={null}
class OutputLoggerProvider(OutputLoggerProviderBase):
def init(self):
"""
Initialize the logger. Called when the Statsig client initializes.
"""
pass
def debug(self, tag: str, msg: str):
"""
Log a debug message.
Args:
tag: Category/component tag for the message
msg: The message to log
"""
pass
def info(self, tag: str, msg: str):
"""
Log an info message.
Args:
tag: Category/component tag for the message
msg: The message to log
"""
pass
def warn(self, tag: str, msg: str):
"""
Log a warning message.
Args:
tag: Category/component tag for the message
msg: The message to log
"""
pass
def error(self, tag: str, msg: str):
"""
Log an error message.
Args:
tag: Category/component tag for the message
msg: The message to log
"""
pass
def shutdown(self):
"""
Clean up resources when the Statsig client shuts down.
"""
pass
```
## Observability Client
The Observability Client interface allows you to monitor the health of the SDK by integrating with your own observability systems. This enables tracking metrics, errors, and performance data. For more information on the metrics emitted by Statsig SDKs, see the [Monitoring documentation](/sdk_monitoring).
```python theme={null}
class ObservabilityClient(ObservabilityClientBase):
def init(self):
"""
Initialize the observability client. Called when the Statsig client initializes.
"""
pass
def increment(self, metric_name: str, value: float, tags: Optional[Dict[str, str]] = None):
"""
Report a counter metric.
Args:
metric_name: The name of the metric
value: The amount to increment by
tags: Optional tags to associate with the metric
"""
pass
def gauge(self, metric_name: str, value: float, tags: Optional[Dict[str, str]] = None):
"""
Report a gauge metric.
Args:
metric_name: The name of the metric
value: The current value
tags: Optional tags to associate with the metric
"""
pass
def dist(self, metric_name: str, value: float, tags: Optional[Dict[str, str]] = None):
"""
Report a distribution metric.
Args:
metric_name: The name of the metric
value: The value to record
tags: Optional tags to associate with the metric
"""
pass
def error(self, tag: str, error: str):
"""
Report an error.
Args:
tag: Category/component tag for the error
error: The error message
"""
pass
def should_enable_high_cardinality_for_this_tag(self, tag: str) -> bool:
"""
Determine if high cardinality should be enabled for a tag.
Args:
tag: The tag to check
Returns:
True if high cardinality should be enabled, False otherwise
"""
pass
```
## FAQ
See the guide on [device level experiments](/guides/experiment-on-custom-id-types).
## Reference
### API Methods
* `check_gate(user: StatsigUser, gate_name: str, options: Optional[FeatureGateEvaluationOptions] = None) -> bool`
* `get_dynamic_config(user: StatsigUser, config_name: str, options: Optional[DynamicConfigEvaluationOptions] = None) -> DynamicConfig`
* `get_experiment(user: StatsigUser, experiment_name: str, options: Optional[ExperimentEvaluationOptions] = None) -> DynamicConfig`
* `get_layer(user: StatsigUser, layer_name: str, options: Optional[LayerEvaluationOptions] = None) -> Layer`
* `get_feature_gate(user: StatsigUser, gate_name: str, options: Optional[FeatureGateEvaluationOptions] = None) -> FeatureGate`
* `get_parameter_store(user: StatsigUser, parameter_store_name: str, options: Optional[ParameterStoreEvaluationOptions] = None) -> ParameterStore`
* `log_event(user: StatsigUser, event_name: str, value: Optional[Union[str, float]] = None, metadata: Optional[Dict[str, str]] = None) -> None`
* `manually_log_gate_exposure(user: StatsigUser, gate_name: str) -> None`
* `manually_log_dynamic_config_exposure(user: StatsigUser, config_name: str) -> None`
* `manually_log_experiment_exposure(user: StatsigUser, experiment_name: str) -> None`
* `manually_log_layer_parameter_exposure(user: StatsigUser, layer_name: str, parameter_name: str) -> None`
* `get_client_initialize_response(user: StatsigUser, options: Optional[ClientInitializeResponseOptions] = None) -> ClientInitializeResponse`
* `shutdown() -> AsyncResult[None]`
### Fields Needed Methods
The following methods return information about which user fields are needed for evaluation:
* `get_gate_fields_needed(gate_name: str) -> List[str]`
* `get_dynamic_config_fields_needed(config_name: str) -> List[str]`
* `get_experiment_fields_needed(experiment_name: str) -> List[str]`
* `get_layer_fields_needed(layer_name: str) -> List[str]`
These methods return a list of strings representing the user fields that are required to properly evaluate the specified gate, config, experiment, or layer.