statsig-python-core 0.22.0__tar.gz → 0.22.0rc2609012332__tar.gz

{statsig_python_core-0.22.0 → statsig_python_core-0.22.0rc2609012332}/Cargo.lock

@@ -2987,7 +2987,7 @@ dependencies = [
 
 [[package]]
 name = "sigstat-grpc"
-version = "0.22.0"
+version = "0.22.0-rc.2609012332"
 dependencies = [
  "async-trait",
  "chrono",
@@ -3079,7 +3079,7 @@ checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
 
 [[package]]
 name = "statsig-node"
-version = "0.22.0"
+version = "0.22.0-rc.2609012332"
 dependencies = [
  "async-trait",
  "napi",
@@ -3094,7 +3094,7 @@ dependencies = [
 
 [[package]]
 name = "statsig-pyo3"
-version = "0.22.0"
+version = "0.22.0-rc.2609012332"
 dependencies = [
  "async-trait",
  "lazy_static",
@@ -3109,7 +3109,7 @@ dependencies = [
 
 [[package]]
 name = "statsig-rust"
-version = "0.22.0"
+version = "0.22.0-rc.2609012332"
 dependencies = [
  "ahash",
  "arc-swap",
@@ -3163,7 +3163,7 @@ dependencies = [
 
 [[package]]
 name = "statsig_elixir"
-version = "0.22.0"
+version = "0.22.0-rc.2609012332"
 dependencies = [
  "async-trait",
  "parking_lot",
@@ -3176,7 +3176,7 @@ dependencies = [
 
 [[package]]
 name = "statsig_ffi"
-version = "0.22.0"
+version = "0.22.0-rc.2609012332"
 dependencies = [
  "async-trait",
  "cbindgen",

{statsig_python_core-0.22.0 → statsig_python_core-0.22.0rc2609012332}/Cargo.toml

@@ -19,7 +19,7 @@ exclude = [
 [workspace.package]
 edition = "2021"
 license = "ISC"
-version = "0.22.0"
+version = "0.22.0-rc.2609012332"
 homepage = "https://statsig.com/"
 authors = ["Statsig"]
 readme = "README.md"

{statsig_python_core-0.22.0 → statsig_python_core-0.22.0rc2609012332}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statsig_python_core
-Version: 0.22.0
+Version: 0.22.0rc2609012332
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

{statsig_python_core-0.22.0 → statsig_python_core-0.22.0rc2609012332}/py_src/statsig_python_core/statsig.py

@@ -1,3 +1,4 @@
+import json
 import os
 from statsig_python_core import (
     DynamicConfigEvaluationOptions,
@@ -10,7 +11,7 @@ from statsig_python_core import (
     notify_python_fork,
     notify_python_shutdown,
 )
-from typing import Optional
+from typing import Any, Callable, Literal, Optional
 from .error_boundary import ErrorBoundary
 from .statsig_types import (
     DynamicConfig,
@@ -21,6 +22,15 @@ from .statsig_types import (
 )
 import atexit
 
+SdkEventName = Literal[
+    "*",
+    "gate_evaluated",
+    "dynamic_config_evaluated",
+    "experiment_evaluated",
+    "layer_evaluated",
+    "specs_updated",
+]
+
 
 def handle_atexit():
     notify_python_shutdown()
@@ -83,6 +93,24 @@ class Statsig(StatsigBasePy):
             and cls._statsig_shared_instance is not None
         )
 
+    # ------------------------------------------------------------ [ SDK Events ]
+
+    def subscribe(
+        self, event_name: SdkEventName, callback: Callable[[Any], None]
+    ) -> str:
+        """Subscribes to an SDK event, returning a subscription id.
+
+        The callback is invoked on an SDK background thread with the event as a
+        dict: `{"event_name": ..., "data": {...}}`. Pass `"*"` to receive every
+        event. Remove the subscription with `unsubscribe_by_id`, `unsubscribe`
+        or `unsubscribe_all`.
+        """
+
+        def on_event(raw: str) -> None:
+            ErrorBoundary._capture("subscribe", lambda: callback(json.loads(raw)))
+
+        return super()._INTERNAL_subscribe(event_name, on_event)
+
     # ------------------------------------------------------------ [ Core APIs ]
 
     def get_feature_gate(

{statsig_python_core-0.22.0 → statsig_python_core-0.22.0rc2609012332}/py_src/statsig_python_core/statsig_python_core.pyi

@@ -293,7 +293,27 @@ class StatsigBasePy:
     def get_experiment_list(self) -> builtins.list[builtins.str]: ...
     def get_autotune_list(self) -> builtins.list[builtins.str]: ...
     def get_parameter_store_list(self) -> builtins.list[builtins.str]: ...
+    def get_layer_list(self) -> builtins.list[builtins.str]: ...
     def identify(self, user: StatsigUser) -> None: ...
+    def _INTERNAL_subscribe(self, event_name: typing.Literal['*', 'gate_evaluated', 'dynamic_config_evaluated', 'experiment_evaluated', 'layer_evaluated', 'specs_updated'], callback: typing.Callable[[builtins.str], None]) -> builtins.str:
+        r"""
+        Subscribes to an SDK event, returning a subscription id.
+        
+        The callback receives the event as a raw JSON string. Prefer
+        `Statsig.subscribe`, which parses it into a dict first.
+        """
+    def unsubscribe(self, event_name: typing.Literal['*', 'gate_evaluated', 'dynamic_config_evaluated', 'experiment_evaluated', 'layer_evaluated', 'specs_updated']) -> None:
+        r"""
+        Removes every subscription for the given event.
+        """
+    def unsubscribe_by_id(self, subscription_id: builtins.str) -> None:
+        r"""
+        Removes the single subscription created by `subscribe`.
+        """
+    def unsubscribe_all(self) -> None:
+        r"""
+        Removes every subscription across all events.
+        """
 
 @typing.final
 class StatsigOptions:

{statsig_python_core-0.22.0 → statsig_python_core-0.22.0rc2609012332}/statsig-grpc/src/statsig_grpc_client.rs

@@ -61,7 +61,7 @@ impl StatsigGrpcClient {
         client
             .get_config_spec(request)
             .await
-            .map_err(StatsigGrpcErr::ErrorGrpcStatus)
+            .map_err(|e| StatsigGrpcErr::ErrorGrpcStatus(Box::new(e)))
             .map(|r| r.into_inner())
     }
 
@@ -75,7 +75,7 @@ impl StatsigGrpcClient {
         client
             .stream_config_spec(request)
             .await
-            .map_err(StatsigGrpcErr::ErrorGrpcStatus)
+            .map_err(|e| StatsigGrpcErr::ErrorGrpcStatus(Box::new(e)))
             .map(|s| s.into_inner())
     }
 

{statsig_python_core-0.22.0 → statsig_python_core-0.22.0rc2609012332}/statsig-grpc/src/statsig_grpc_err.rs

@@ -7,7 +7,7 @@ pub enum StatsigGrpcErr {
     FailedToGetLock,
     Authentication(String),
     FailedToConnect(String),
-    ErrorGrpcStatus(Status),
+    ErrorGrpcStatus(Box<Status>),
     CustomErr(String),
 }
 

{statsig_python_core-0.22.0 → statsig_python_core-0.22.0rc2609012332}/statsig-pyo3/src/statsig_base_py.rs

@@ -26,7 +26,9 @@ use pyo3::{
 use pyo3_stub_gen::derive::*;
 use serde_json::Value;
 use statsig_rust::{
-    log_e, ClientInitResponseOptions, DynamicConfigEvaluationOptions, ExperimentEvaluationOptions,
+    log_e,
+    sdk_event_emitter::{SdkEventEmitter, SubscriptionID},
+    ClientInitResponseOptions, DynamicConfigEvaluationOptions, ExperimentEvaluationOptions,
     FeatureGateEvaluationOptions, HashAlgorithm, LayerEvaluationOptions, ObservabilityClient,
     ParameterStoreEvaluationOptions, Statsig, UserPersistedValues,
 };
@@ -595,11 +597,98 @@ impl StatsigBasePy {
         self.inner.get_parameter_store_list()
     }
 
+    #[pyo3(name = "get_layer_list")]
+    pub fn get_layer_list(&self) -> Vec<String> {
+        self.inner.get_layer_list()
+    }
+
     #[pyo3(signature = (user))]
     pub fn identify(&self, user: &StatsigUserPy) -> PyResult<()> {
         self.inner.identify(&user.inner);
         Ok(())
     }
+
+    /// Subscribes to an SDK event, returning a subscription id.
+    ///
+    /// The callback receives the event as a raw JSON string. Prefer
+    /// `Statsig.subscribe`, which parses it into a dict first.
+    #[pyo3(name = "_INTERNAL_subscribe")]
+    pub fn _internal_subscribe(
+        &self,
+        py: Python,
+        #[gen_stub(override_type(
+            type_repr = "typing.Literal['*', 'gate_evaluated', 'dynamic_config_evaluated', 'experiment_evaluated', 'layer_evaluated', 'specs_updated']"
+        ))]
+        event_name: String,
+        #[gen_stub(override_type(type_repr = "typing.Callable[[builtins.str], None]"))]
+        callback: Py<PyAny>,
+    ) -> String {
+        self.detach_for_emitter(py, |emitter| {
+            emitter
+                .subscribe(&event_name, move |event| {
+                    let raw = match event.to_raw_json_string() {
+                        Some(raw) => raw,
+                        None => return,
+                    };
+
+                    SafeGil::run(|py| {
+                        let py = match py {
+                            Some(py) => py,
+                            None => return,
+                        };
+
+                        if let Err(e) = callback.call1(py, (raw,)) {
+                            log_e!(TAG, "Failed to call SDK event subscriber: {:?}", e);
+                        }
+                    });
+                })
+                .encode()
+        })
+    }
+
+    /// Removes every subscription for the given event.
+    pub fn unsubscribe(
+        &self,
+        py: Python,
+        #[gen_stub(override_type(
+            type_repr = "typing.Literal['*', 'gate_evaluated', 'dynamic_config_evaluated', 'experiment_evaluated', 'layer_evaluated', 'specs_updated']"
+        ))]
+        event_name: String,
+    ) {
+        self.detach_for_emitter(py, |emitter| emitter.unsubscribe(&event_name));
+    }
+
+    /// Removes the single subscription created by `subscribe`.
+    pub fn unsubscribe_by_id(&self, py: Python, subscription_id: String) {
+        let sub_id = match SubscriptionID::decode(&subscription_id) {
+            Some(sub_id) => sub_id,
+            None => {
+                log_e!(TAG, "Invalid subscription ID: {}", subscription_id);
+                return;
+            }
+        };
+
+        self.detach_for_emitter(py, |emitter| emitter.unsubscribe_by_id(&sub_id));
+    }
+
+    /// Removes every subscription across all events.
+    pub fn unsubscribe_all(&self, py: Python) {
+        self.detach_for_emitter(py, |emitter| emitter.unsubscribe_all());
+    }
+}
+
+impl StatsigBasePy {
+    /// Subscription bookkeeping takes an emitter lock that an in-flight emit may
+    /// still hold while it blocks waiting on the GIL. Release the GIL so that
+    /// emit can complete and drop the lock, rather than deadlocking against us.
+    fn detach_for_emitter<F, R>(&self, py: Python, f: F) -> R
+    where
+        F: Send + FnOnce(&SdkEventEmitter) -> R,
+        R: Send,
+    {
+        let emitter = self.inner.event_emitter.clone();
+        py.detach(move || f(&emitter))
+    }
 }
 
 fn get_completion_event(py: Python) -> PyResult<(Py<PyAny>, Py<PyAny>)> {

statsig_python_core-0.22.0rc2609012332/statsig-pyo3/tests/test_get_layer_list.py

@@ -0,0 +1,42 @@
+"""
+Tests focused on the get_layer_list API.
+Verifies the configured layer names are returned.
+"""
+
+import json
+import pytest
+from statsig_python_core import Statsig, StatsigOptions
+from pytest_httpserver import HTTPServer
+from utils import get_test_data_resource
+
+
+@pytest.fixture
+def statsig_setup(httpserver: HTTPServer):
+    dcs_content = get_test_data_resource("eval_proj_dcs.json")
+    json_data = json.loads(dcs_content)
+
+    httpserver.expect_request(
+        "/v2/download_config_specs/secret-key.json"
+    ).respond_with_json(json_data)
+
+    httpserver.expect_request("/v1/log_event").respond_with_json({"success": True})
+
+    options = StatsigOptions(
+        specs_url=httpserver.url_for("/v2/download_config_specs"),
+        log_event_url=httpserver.url_for("/v1/log_event"),
+    )
+    statsig = Statsig("secret-key", options)
+
+    statsig.initialize().wait()
+
+    yield statsig
+
+    statsig.shutdown().wait()
+
+
+def test_get_layer_list_returns_configured_layers(statsig_setup):
+    statsig = statsig_setup
+    layer_list = statsig.get_layer_list()
+
+    assert isinstance(layer_list, list)
+    assert "test_layer" in layer_list

statsig_python_core-0.22.0rc2609012332/statsig-pyo3/tests/test_sdk_event_emitter.py

@@ -0,0 +1,187 @@
+import json
+import threading
+import time
+from typing import Any, Callable, List
+
+import pytest
+from pytest_httpserver import HTTPServer
+from werkzeug import Request, Response
+
+from statsig_python_core import Statsig, StatsigOptions
+from utils import get_test_data_resource
+
+# The SDK clamps anything below 1000ms back to the default, so this is as fast
+# as the background update thread can be driven.
+SPECS_SYNC_INTERVAL_MS = 1000
+WAIT_TIMEOUT_S = 15.0
+
+
+class SpecsFeed:
+    """Serves the DCS fixture with a newer lcut on every request, so each poll is
+    a real spec update and `specs_updated` keeps firing for as long as we poll."""
+
+    def __init__(self, httpserver: HTTPServer):
+        self._specs = json.loads(get_test_data_resource("eval_proj_dcs.json"))
+        del self._specs["checksum"]
+        self._lock = threading.Lock()
+        self._request_count = 0
+
+        httpserver.expect_request(
+            "/v2/download_config_specs/secret-key.json"
+        ).respond_with_handler(self._respond)
+        httpserver.expect_request("/v1/log_event").respond_with_json({"success": True})
+
+    @property
+    def request_count(self) -> int:
+        with self._lock:
+            return self._request_count
+
+    def _respond(self, _request: Request) -> Response:
+        with self._lock:
+            self._request_count += 1
+            self._specs["time"] += 1
+            body = json.dumps(self._specs)
+
+        return Response(body, content_type="application/json")
+
+
+class EventRecorder:
+    """Subscriber that collects the events the SDK emits on its update thread."""
+
+    def __init__(self) -> None:
+        self.events: List[Any] = []
+
+    def __call__(self, event: Any) -> None:
+        self.events.append(event)
+
+    @property
+    def count(self) -> int:
+        return len(self.events)
+
+
+def wait_until(predicate: Callable[[], bool], timeout_s: float = WAIT_TIMEOUT_S) -> bool:
+    deadline = time.monotonic() + timeout_s
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(0.01)
+    return predicate()
+
+
+@pytest.fixture
+def specs_feed(httpserver: HTTPServer) -> SpecsFeed:
+    return SpecsFeed(httpserver)
+
+
+@pytest.fixture
+def statsig(httpserver: HTTPServer, specs_feed: SpecsFeed):
+    options = StatsigOptions()
+    options.specs_url = httpserver.url_for("/v2/download_config_specs")
+    options.log_event_url = httpserver.url_for("/v1/log_event")
+    options.specs_sync_interval_ms = SPECS_SYNC_INTERVAL_MS
+    options.output_log_level = "error"
+
+    statsig = Statsig("secret-key", options)
+    yield statsig
+    statsig.shutdown().wait()
+
+
+def test_specs_updated_fires_with_payload(statsig):
+    recorder = EventRecorder()
+    statsig.subscribe("specs_updated", recorder)
+
+    statsig.initialize().wait()
+
+    assert wait_until(lambda: recorder.count > 0), "specs_updated never fired"
+
+    event = recorder.events[0]
+    assert event["event_name"] == "specs_updated"
+
+    data = event["data"]
+    assert data["source"] == "Network"
+    assert data["source_api"].startswith("http://")
+    assert isinstance(data["values"]["time"], int)
+    assert "test_public" in data["values"]["feature_gates"]
+
+
+def test_wildcard_subscription_receives_specs_updated(statsig):
+    recorder = EventRecorder()
+    statsig.subscribe("*", recorder)
+
+    statsig.initialize().wait()
+
+    assert wait_until(
+        lambda: any(e["event_name"] == "specs_updated" for e in recorder.events)
+    ), "'*' subscription never received specs_updated"
+
+
+def test_unsubscribe_by_id_stops_only_that_subscription(statsig):
+    kept, dropped = EventRecorder(), EventRecorder()
+    statsig.subscribe("specs_updated", kept)
+    dropped_id = statsig.subscribe("specs_updated", dropped)
+    assert isinstance(dropped_id, str) and dropped_id
+
+    statsig.initialize().wait()
+    assert wait_until(lambda: dropped.count > 0), "specs_updated never fired"
+
+    statsig.unsubscribe_by_id(dropped_id)
+    dropped_at, kept_at = dropped.count, kept.count
+
+    assert wait_until(lambda: kept.count >= kept_at + 2), "specs stopped updating"
+    assert dropped.count == dropped_at
+
+
+def test_unsubscribe_removes_every_subscription_for_the_event(statsig):
+    first, second, wildcard = EventRecorder(), EventRecorder(), EventRecorder()
+    statsig.subscribe("specs_updated", first)
+    statsig.subscribe("specs_updated", second)
+    statsig.subscribe("*", wildcard)
+
+    statsig.initialize().wait()
+    assert wait_until(
+        lambda: first.count > 0 and second.count > 0
+    ), "specs_updated never fired"
+
+    statsig.unsubscribe("specs_updated")
+    first_at, second_at, wildcard_at = first.count, second.count, wildcard.count
+
+    assert wait_until(
+        lambda: wildcard.count >= wildcard_at + 2
+    ), "specs stopped updating"
+    assert first.count == first_at
+    assert second.count == second_at
+
+
+def test_unsubscribe_all_stops_every_subscription(statsig, specs_feed):
+    specs_updated, wildcard = EventRecorder(), EventRecorder()
+    statsig.subscribe("specs_updated", specs_updated)
+    statsig.subscribe("*", wildcard)
+
+    statsig.initialize().wait()
+    assert wait_until(
+        lambda: specs_updated.count > 0 and wildcard.count > 0
+    ), "specs_updated never fired"
+
+    statsig.unsubscribe_all()
+    specs_updated_at, wildcard_at = specs_updated.count, wildcard.count
+    requests_at = specs_feed.request_count
+
+    assert wait_until(
+        lambda: specs_feed.request_count >= requests_at + 2
+    ), "specs stopped updating"
+    assert specs_updated.count == specs_updated_at
+    assert wildcard.count == wildcard_at
+
+
+def test_subscriber_exception_does_not_break_other_subscribers(statsig):
+    healthy = EventRecorder()
+
+    def raises(_event: Any) -> None:
+        raise RuntimeError("subscriber blew up")
+
+    statsig.subscribe("specs_updated", raises)
+    statsig.subscribe("specs_updated", healthy)
+
+    statsig.initialize().wait()
+
+    assert wait_until(lambda: healthy.count >= 2), "throwing subscriber halted emission"

{statsig_python_core-0.22.0 → statsig_python_core-0.22.0rc2609012332}/statsig-rust/Cargo.toml

@@ -44,7 +44,7 @@ serde_json = { version = "1.0.143", features = [
 ] }
 serde_with = "3.4.0"
 sha2 = "0.10.8"
-sigstat-grpc = { path = "../statsig-grpc", version = "0.22.0", optional = true }
+sigstat-grpc = { path = "../statsig-grpc", version = "0.22.0-rc.2609012332", optional = true }
 simple_logger = { version = "5.0.0" }
 tempfile = "3.8.1"
 tokio = { version = "1.39.1", features = ["full"] }

{statsig_python_core-0.22.0 → statsig_python_core-0.22.0rc2609012332}/statsig-rust/src/statsig_metadata.rs

@@ -10,7 +10,7 @@ lazy_static! {
     static ref STATSIG_METADATA: RwLock<StatsigMetadata> = RwLock::new(StatsigMetadata::new());
 }
 
-pub const SDK_VERSION: &str = "0.22.0";
+pub const SDK_VERSION: &str = "0.22.0-rc.2609012332";
 
 const TAG: &str = stringify!(StatsigMetadata);