Python Core SDK Migration Guide

This guide will help you migrate from the legacy Python Server SDK to the new Python Core SDK. The Python Core SDK offers significant performance improvements and new features, as it's built on a shared Rust core library.

Why Migrate?

• Performance: Python Core evaluates faster than the legacy SDK
• New Features: Access to Parameter Stores, CMAB (Contextual Multi-Armed Bandits), observabilityClient, and more
• Future Support: All new features and improvements will only be available in Python Core
• Maintenance: The legacy Python SDK is in maintenance mode and will only receive critical bug fixes

Installation

New Installation

pip install statsig-python-core

Legacy Installation

pip install statsig

StatsigUser

New User Creation

from statsig_python_core import *

user = StatsigUser(
    user_id="user_123",
    email="user@example.com",
    ip="192.168.0.1",
    user_agent="Mozilla/5.0",
    country="US",
    custom={
        "subscription_level": "premium"
    }
)

Legacy User Creation

from statsig import StatsigUser

user = StatsigUser(
    user_id="user_123",
    email="user@example.com",
    ip="192.168.0.1",
    user_agent="Mozilla/5.0",
    country="US",
    custom={
        "subscription_level": "premium"
    }
)

API Changes

Key Package and Class Changes

Feature	Python Core SDK	Legacy Python SDK	Status
Package	statsig_python_core	statsig	⚠️ Renamed
Import	from statsig_python_core import *	from statsig import Statsig	⚠️ Change
Options	StatsigOptions	StatsigOptions	✓ Same
User	StatsigUser	StatsigUser	✓ Same
Initialize	statsig.initialize().wait()	statsig.initialize()	⚠️ Added .wait()
Check Gate	statsig.check_gate()	statsig.check_gate()	✓ Same
Get Config	statsig.get_dynamic_config()	statsig.get_config()	⚠️ Renamed
Get Experiment	statsig.get_experiment()	statsig.get_experiment()	✓ Same
Get Layer	statsig.get_layer()	statsig.get_layer()	✓ Same
Log Event	statsig.log_event()	statsig.log_event()	✓ Same
Shutdown	statsig.shutdown().wait()	statsig.shutdown()	⚠️ Added .wait()

For more details on the new API, see Python Core SDK documentation.

Behavioral Changes

User-Agent Parsing

• The SDK now uses a lightweight YAML-based User-Agent parser based on a reduced version of the ua-parser regex definitions.
• This parser supports the following commonly used browsers:
  • Chrome
  • Firefox / Firefox Mobile
  • Safari / Mobile Safari
  • Chrome Mobile
  • Android
  • Edge / Edge Mobile
  • IE Mobile
  • Opera Mobile
• If your use case requires identifying less common browsers, you should parse the User-Agent externally before sending it to Statsig.

Lazy Initialization: User-Agent Parser & Country Lookup

• User-Agent parsing and country lookup are now lazy-loaded by default to improve SDK initialization performance.
• If your application relies on these features being ready immediately after initialize(), you can opt in by setting:
  • wait_for_user_agent_init
  • wait_for_country_lookup_init
• ⚠️ Enabling these options will increase total initialization time.
• To disable these features entirely, use the following StatsigOptions flags:
  • disable_user_agent_parsing
  • disable_country_lookup

ID List Feature

• The ID List functionality is disabled by default.
• To enable it, set the following in your StatsigOptions:
  • enable_id_lists

Endpoint Changes (v1 → v2)

• The core SDK now fetches configuration specs from a new endpoint:
  • Old: v1/download_config_specs
  • New: v2/download_config_specs
• If you are hosting your own pass-through proxy, ensure it supports and correctly routes the v2 endpoint.
• If you are using the Statsig Forward Proxy (SFP), this endpoint migration is handled automatically.

StatsigOptions Changes

The table below shows the mapping between legacy SDK options and Server Core SDK options:

Old Option	New / Notes
api	Deprecated
idlists_thread_limit, logging_interval, enable_debug_logs, events_flushed_callback	Deprecated
timeout	Deprecated (was only for network)
api_for_download_config_specs	specs_url – must complete with endpoint
api_for_get_id_lists	id_lists_url – must complete with endpoint
api_for_log_event	log_event_url – must complete with endpoint
tier	environment
init_timeout	init_timeout_ms – applies to overall initialization (suggest adding +1000 ms if enabling UA)
rulesets_sync_interval	specs_sync_interval_ms (unit: milliseconds)
idlists_sync_interval	id_lists_sync_interval_ms (unit: milliseconds)
local_mode	disable_network
event_queue_size	event_logging_max_queue_size
data_store	Still supported but interface changed
fallback_to_statsig_api	Still supported
output_logger_level	Now output_log_level
overall_init_timeout	Replaced by init_timeout_ms
observability_client, sdk_error_callback	Now within observability_client interface
custom_logger	Now OutputLoggerProvider interface
bootstrap_values, evaluation_callback, proxy_configs, out_of_sync_threshold_in_s, rules_updated_callback	Not yet supported

Recommended Migration Path

1. Add the new Dependencies

• Add the new SDK package/module and any required platform-specific dependencies for your environment.
• Update import or require statements to reference the new SDK namespace or module.
• For now - keep the old package in-place, it can be helpful to have both running in parallel momentarily during local testing for your upgrade. If needed (language dependent), you may want to alias the new package.

3. Update Initialization

• Switch to the new initialization syntax. New SDK keys aren't needed - if you choose to update them, ensure they have the same target apps.
• If needed, use the appropriate builder or configuration pattern for setting options, and ensure you migrate the StatsigOptions you use, as some were renamed.

4. Update User Creation

• Migrate to the new format for creating user objects.
• If needed, use the builder pattern or updated constructor to set user properties.

5. Update Method Calls

• Starting with a few calls, switch your config checks from the new to old SDK, replacing oldStatsig.getExperiment() with newStatsig.getExperiment()
• As you change the package usage, conduct some testing of your service locally or with existing test patterns, to build confidence in the new SDK's operation.
• As you migrate additional calls, update method names if they've changed (notably, get_config() to get_dynamic_config)
• Once comfortable with the operation of the new SDK from call-by-call migration, consider the use of refactoring tools to migrate the bulk of your remaining calls.

6. Test Thoroughly

• Verify that all of your configs are successfully migrated - run your test suites end-to-end.

7. Remove old SDK

• Remove references to the old SDK, and clean up old initialization and import logic.

7. Optional: Gradual Migration Using Adapter

• Use a migration adapter to wrap the new SDK with the old interface.
• This allows for incremental migration without updating all call sites at once.
• https://github.com/statsig-io/statsig-server-core-migration-adapters/blob/main/python_core_migration_adapter.py

Need Help?

If you encounter any issues during migration, please reach out to us:

• Statsig Slack Community
• GitHub Issues