Python Core SDK Migration Guide
Migrate from the legacy Python Server SDK to the new Python Core SDK
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 are available only in Python Core
- Maintenance: The legacy Python SDK is in maintenance mode and receives only critical bug fixes
Installation
pip install statsig-python-core
StatsigUser
User creation is the same in the new Python Core SDK.
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"
}
)
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() |
Behavioral changes
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
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.
- Keep the old package in place for now. Having both packages running in parallel during local testing can be useful. If needed (depending on the language), you may want to alias the new package.
Update Initialization
- Switch to the new initialization syntax. New SDK keys aren't required. If you update them, ensure they have the same target apps.
- Use the appropriate builder or configuration pattern for setting options. Migrate the StatsigOptions you use, because some were renamed.
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.
Update Method Calls
- Starting with a few calls, switch your config checks from the old SDK to the new SDK, replacing
oldStatsig.getExperiment()withnewStatsig.getExperiment(). - After changing the package usage, test your service locally or with existing test patterns to build confidence in the new SDK's behavior.
- As you migrate additional calls, update method names that changed (notably,
get_config()toget_dynamic_config()). - After you're comfortable with the call-by-call migration, consider using refactoring tools to migrate the remaining calls in bulk.
- Starting with a few calls, switch your config checks from the old SDK to the new SDK, replacing
Test Thoroughly
- Verify that all configs are successfully migrated. Run your test suites end-to-end.
Remove old SDK
- Remove references to the old SDK. Clean up old initialization and import logic.
Additional option: gradual migration using adapter
- Use a migration adapter to wrap the new SDK with the old interface.
- This approach allows incremental migration without updating all call sites at once.
- Python Core Migration Adapter
Need help?
If you encounter issues during migration, contact:
Was this helpful?