Statsig Python Server SDK

Warnings

• gotcha The SDK requires a **Server Secret Key** (starts with `sk-`). Using a Client SDK Key (starts with `pk-` or `client-`) will result in initialization failures and prevent the SDK from fetching configurations and evaluating correctly. Server keys should never be exposed in client-side code.
  Fix: Ensure you are using the correct server secret key obtained from your Statsig console. Do not confuse it with client keys.
• breaking Both `statsig.initialize()` and `statsig.shutdown()` are asynchronous operations and **must be awaited**. Failing to `await statsig.initialize()` can lead to the SDK operating with stale or default configurations, and `check_gate`/`get_config` calls may block or return incorrect values. Failing to `await statsig.shutdown()` will result in lost event data as pending events may not be flushed to Statsig servers before your application exits.
  Fix: Always call `await statsig.initialize(secret_key)` at the start of your application and `await statsig.shutdown()` before the application terminates. Ensure your application's entry point uses `asyncio.run()` or similar async executor.
• gotcha The accuracy of feature gate, dynamic config, and experiment evaluations depends entirely on the attributes provided in the `StatsigUser` object. Incomplete or incorrect user attributes can lead to users being evaluated against the wrong segment or receiving default values, resulting in inconsistent experiences.
  Fix: Always provide the most complete and accurate `StatsigUser` object possible. Include `user_id`, and any custom attributes or private attributes that are used in your Statsig rules. Ensure `user_id` is consistent across sessions.

Install

• pip install statsig Install latest version

Imports

• statsig

  import statsig

  While `StatsigServer` exists, the idiomatic way to interact with the SDK is through the top-level `statsig` module functions like `statsig.initialize()`, `statsig.check_gate()`, etc.
• StatsigUser

  from statsig import StatsigUser

• StatsigOptions

  from statsig import StatsigOptions

Quickstart

This quickstart demonstrates how to initialize the Statsig Python SDK, define a user, check a feature gate, retrieve a dynamic config, fetch an experiment, log an event, and properly shut down the SDK. Remember to replace `YOUR_SERVER_SECRET_KEY` with your actual server secret from the Statsig console, or set it via the `STATSIG_SERVER_SECRET` environment variable.

import statsig
import os
import asyncio

async def main():
    # It is crucial to use a server secret key (sk-...) for the server SDK.
    # NEVER expose client keys (pk-..., client-...) in your server-side code.
    secret_key = os.environ.get('STATSIG_SERVER_SECRET', 'YOUR_SERVER_SECRET_KEY')

    if not secret_key or secret_key == 'YOUR_SERVER_SECRET_KEY':
        print("Please set the STATSIG_SERVER_SECRET environment variable or replace 'YOUR_SERVER_SECRET_KEY' in the code.")
        return

    # Initialize the SDK. This is an asynchronous operation.
    print("Initializing Statsig SDK...")
    await statsig.initialize(secret_key)
    print("Statsig SDK initialized.")

    # Define a StatsigUser object with relevant attributes
    user = statsig.StatsigUser(
        user_id="example-user-123",
        email="user@example.com",
        country="US",
        custom={
            "plan": "premium"
        },
        private_attributes={
            "phone_number": "+15551234567"
        }
    )

    # Check a feature gate
    if statsig.check_gate(user, "my_feature_gate"):
        print("Feature 'my_feature_gate' is ON for the user.")
    else:
        print("Feature 'my_feature_gate' is OFF for the user.")

    # Get a dynamic config
    config = statsig.get_config(user, "my_dynamic_config")
    print(f"Value for 'my_dynamic_config': {config.value}")

    # Get an experiment
    experiment = statsig.get_experiment(user, "my_a_b_test")
    print(f"Value for 'my_a_b_test': {experiment.value}")

    # Log an event
    statsig.log_event(user, "product_viewed", value=10.99, metadata={"product_id": "item_xyz"})

    # Shut down the SDK. This is crucial for flushing all pending events.
    print("Shutting down Statsig SDK...")
    await statsig.shutdown()
    print("Statsig SDK shut down.")

if __name__ == "__main__":
    asyncio.run(main())