sentry-options 1.2.0__tar.gz → 1.2.2__tar.gz

{sentry_options-1.2.0 → sentry_options-1.2.2}/Cargo.lock

@@ -435,7 +435,7 @@ dependencies = [
 
 [[package]]
 name = "example"
-version = "1.2.0"
+version = "1.2.2"
 dependencies = [
  "anyhow",
  "sentry-options",
@@ -1437,7 +1437,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sentry-options"
-version = "1.2.0"
+version = "1.2.2"
 dependencies = [
  "arc-swap",
  "criterion",
@@ -1451,7 +1451,7 @@ dependencies = [
 
 [[package]]
 name = "sentry-options-cli"
-version = "1.2.0"
+version = "1.2.2"
 dependencies = [
  "chrono",
  "clap",
@@ -1466,7 +1466,7 @@ dependencies = [
 
 [[package]]
 name = "sentry-options-python"
-version = "1.2.0"
+version = "1.2.2"
 dependencies = [
  "pyo3",
  "sentry-options",
@@ -1475,7 +1475,7 @@ dependencies = [
 
 [[package]]
 name = "sentry-options-validation"
-version = "1.2.0"
+version = "1.2.2"
 dependencies = [
  "anyhow",
  "arc-swap",

{sentry_options-1.2.0 → sentry_options-1.2.2}/Cargo.toml

@@ -3,13 +3,13 @@ resolver = "3"
 members = ["sentry-options-validation", "clients/rust", "clients/python"]
 
 [workspace.package]
-version = "1.2.0"
+version = "1.2.2"
 edition = "2024"
 repository = "https://github.com/getsentry/sentry-options"
 license = "Apache-2.0"
 
 [workspace.dependencies]
-sentry-options-validation = { path = "sentry-options-validation", version = "1.2.0" }
+sentry-options-validation = { path = "sentry-options-validation", version = "1.2.2" }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0.145"
 anyhow = "1.0.100"

{sentry_options-1.2.0 → sentry_options-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sentry_options
-Version: 1.2.0
+Version: 1.2.2
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: Implementation :: CPython

{sentry_options-1.2.0 → sentry_options-1.2.2}/clients/python/src/lib.rs

@@ -2,10 +2,11 @@
 
 use std::collections::HashMap;
 use std::sync::OnceLock;
+use std::time::Duration;
 
 use ::sentry_options::{
-    FeatureChecker as RustFeatureChecker, FeatureContext as RustFeatureContext,
-    Options as RustOptions, OptionsError as RustOptionsError,
+    DEFAULT_REFRESH_THRESHOLD, FeatureChecker as RustFeatureChecker,
+    FeatureContext as RustFeatureContext, Options as RustOptions, OptionsError as RustOptionsError,
 };
 use pyo3::exceptions::{PyException, PyRuntimeError, PyValueError};
 use pyo3::prelude::*;
@@ -193,29 +194,62 @@ impl PyFeatureChecker {
 /// Optionally accepts an `on_propagation` callback that fires whenever values
 /// are refreshed with a new `generated_at` timestamp. The callback receives
 /// `(namespace: str, delay_secs: float)`.
+///
+/// `refresh_threshold` is the staleness threshold in seconds for
+/// refresh-on-read (default: 5.0). Pass `None` to disable refresh-on-read
+/// entirely; values then only change via `refresh()`.
 #[pyfunction]
-#[pyo3(signature = (on_propagation=None))]
-fn init(on_propagation: Option<Py<PyAny>>) -> PyResult<()> {
+#[pyo3(signature = (on_propagation=None, refresh_threshold=Some(DEFAULT_REFRESH_THRESHOLD.as_secs_f64())))]
+fn init(on_propagation: Option<Py<PyAny>>, refresh_threshold: Option<f64>) -> PyResult<()> {
     if GLOBAL_OPTIONS.get().is_some() {
         return Ok(());
     }
-    let opts = match on_propagation {
+
+    let refresh_threshold = match refresh_threshold {
+        Some(secs) if !secs.is_finite() || secs < 0.0 => {
+            return Err(PyValueError::new_err(
+                "refresh_threshold must be a non-negative number or None",
+            ));
+        }
+        Some(secs) => Some(Duration::from_secs_f64(secs)),
+        None => None,
+    };
+
+    let mut builder = RustOptions::builder().with_refresh_threshold(refresh_threshold);
+    if let Some(cb) = on_propagation {
         // `Py<PyAny>` is `Send + Sync`; the closure re-acquires the GIL for the
         // call, so the callback can run on whichever thread triggers a refresh.
-        Some(cb) => RustOptions::new_with_propagation_callback(Box::new(move |ns, delay| {
+        builder = builder.with_callback(move |ns, delay| {
             Python::attach(|py| {
                 if let Err(e) = cb.call1(py, (ns, delay)) {
                     e.print(py);
                 }
             });
-        }))
-        .map_err(options_err)?,
-        None => RustOptions::new().map_err(options_err)?,
-    };
+        });
+    }
+    let opts = builder.build().map_err(options_err)?;
     let _ = GLOBAL_OPTIONS.set(opts);
     Ok(())
 }
 
+/// Refresh values from disk, ignoring the staleness threshold.
+///
+/// Returns whether a new snapshot was published, i.e. the files changed on
+/// disk and reloaded successfully. On error the previous snapshot is retained
+/// and served. Calling this more often than the threshold guarantees reads
+/// never refresh inline.
+///
+/// Raises NotInitializedError if init() has not been called.
+#[pyfunction]
+fn refresh(py: Python<'_>) -> PyResult<bool> {
+    let opts = GLOBAL_OPTIONS.get().ok_or_else(|| {
+        NotInitializedError::new_err("Options not initialized - call init() first")
+    })?;
+    // Release the GIL: the reload does file IO, and the propagation callback
+    // re-acquires the GIL itself.
+    py.detach(|| opts.refresh()).map_err(options_err)
+}
+
 /// Get a namespace handle for accessing options.
 ///
 /// Raises RuntimeError if init() has not been called.
@@ -327,6 +361,7 @@ fn _core(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(init, m)?)?;
     m.add_function(wrap_pyfunction!(options, m)?)?;
     m.add_function(wrap_pyfunction!(features, m)?)?;
+    m.add_function(wrap_pyfunction!(refresh, m)?)?;
     // Classes
     m.add_class::<NamespaceOptions>()?;
     m.add_class::<PyFeatureContext>()?;

sentry_options-1.2.2/clients/python/tests/conftest.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from textwrap import dedent
+
+import pytest
+from sentry_options import init
+
+
+@pytest.fixture(scope='session', autouse=True)
+def init_options(tmp_path_factory: pytest.TempPathFactory):
+    """Initialize options once for the test session."""
+    init()
+
+
+def make_options_dir(root: Path, *, generated_at: str | None = None) -> Path:
+    """Create an options directory with a ``test-ns`` schema and values file."""
+    options_dir = root / 'opts'
+    schemas_dir = options_dir / 'schemas' / 'test-ns'
+    values_dir = options_dir / 'values' / 'test-ns'
+    schemas_dir.mkdir(parents=True)
+    values_dir.mkdir(parents=True)
+
+    schemas_dir.joinpath('schema.json').write_text(
+        json.dumps(
+            {
+                'version': '1.0',
+                'type': 'object',
+                'properties': {
+                    'enabled': {
+                        'type': 'boolean',
+                        'default': False,
+                        'description': 'Enabled',
+                    },
+                },
+            },
+        ),
+    )
+
+    values: dict = {'options': {'enabled': True}}
+    if generated_at is not None:
+        values['generated_at'] = generated_at
+    values_dir.joinpath('values.json').write_text(json.dumps(values))
+
+    return options_dir
+
+
+def run_isolated(script: str, options_dir: Path, timeout: int = 30, **env_extra: str) -> None:
+    """Run a Python script in a subprocess with its own ``SENTRY_OPTIONS_DIR``.
+
+    Each subprocess gets a fresh Rust ``OnceLock``, so scripts can call
+    ``init(...)`` with their own settings.
+    """
+    env = os.environ.copy()
+    env['SENTRY_OPTIONS_DIR'] = str(options_dir)
+    env.update(env_extra)
+    result = subprocess.run(
+        [sys.executable, '-c', dedent(script)],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    assert result.returncode == 0, (
+        f"Script failed.\nstdout: {result.stdout}\nstderr: {result.stderr}"
+    )

{sentry_options-1.2.0 → sentry_options-1.2.2}/clients/python/tests/propagation_test.py

@@ -8,65 +8,16 @@ to wait it out.
 """
 from __future__ import annotations
 
-import json
-import os
-import subprocess
-import sys
 from pathlib import Path
-from textwrap import dedent
-
-
-def _make_options_dir(root: Path, *, generated_at: str | None = None) -> Path:
-    options_dir = root / 'opts'
-    schemas_dir = options_dir / 'schemas' / 'test-ns'
-    values_dir = options_dir / 'values' / 'test-ns'
-    schemas_dir.mkdir(parents=True)
-    values_dir.mkdir(parents=True)
-
-    schemas_dir.joinpath('schema.json').write_text(
-        json.dumps(
-            {
-                'version': '1.0',
-                'type': 'object',
-                'properties': {
-                    'enabled': {
-                        'type': 'boolean',
-                        'default': False,
-                        'description': 'Enabled',
-                    },
-                },
-            },
-        ),
-    )
-
-    values: dict = {'options': {'enabled': True}}
-    if generated_at is not None:
-        values['generated_at'] = generated_at
-    values_dir.joinpath('values.json').write_text(json.dumps(values))
-
-    return options_dir
 
-
-def _run(script: str, options_dir: Path, timeout: int = 30, **env_extra: str) -> None:
-    env = os.environ.copy()
-    env['SENTRY_OPTIONS_DIR'] = str(options_dir)
-    env.update(env_extra)
-    result = subprocess.run(
-        [sys.executable, '-c', dedent(script)],
-        env=env,
-        capture_output=True,
-        text=True,
-        timeout=timeout,
-    )
-    assert result.returncode == 0, (
-        f"Script failed.\nstdout: {result.stdout}\nstderr: {result.stderr}"
-    )
+from conftest import make_options_dir
+from conftest import run_isolated
 
 
 def test_propagation_callback_fires_on_generated_at_change(tmp_path: Path) -> None:
-    options_dir = _make_options_dir(tmp_path, generated_at='2024-01-21T18:30:00+00:00')
+    options_dir = make_options_dir(tmp_path, generated_at='2024-01-21T18:30:00+00:00')
     values_file = options_dir / 'values' / 'test-ns' / 'values.json'
-    _run(
+    run_isolated(
         f"""\
         import json
         from sentry_options import init, options
@@ -90,9 +41,9 @@ def test_propagation_callback_fires_on_generated_at_change(tmp_path: Path) -> No
 
 
 def test_get_forced_sees_change_without_waiting(tmp_path: Path) -> None:
-    options_dir = _make_options_dir(tmp_path)
+    options_dir = make_options_dir(tmp_path)
     values_file = options_dir / 'values' / 'test-ns' / 'values.json'
-    _run(
+    run_isolated(
         f"""\
         import json
         from sentry_options import init, options
@@ -114,9 +65,9 @@ def test_get_forced_sees_change_without_waiting(tmp_path: Path) -> None:
 
 
 def test_propagation_callback_not_called_without_generated_at(tmp_path: Path) -> None:
-    options_dir = _make_options_dir(tmp_path)
+    options_dir = make_options_dir(tmp_path)
     values_file = options_dir / 'values' / 'test-ns' / 'values.json'
-    _run(
+    run_isolated(
         f"""\
         import json
         from sentry_options import init, options
@@ -137,9 +88,9 @@ def test_propagation_callback_not_called_without_generated_at(tmp_path: Path) ->
 
 
 def test_propagation_callback_exception_does_not_crash(tmp_path: Path) -> None:
-    options_dir = _make_options_dir(tmp_path, generated_at='2024-01-21T18:30:00+00:00')
+    options_dir = make_options_dir(tmp_path, generated_at='2024-01-21T18:30:00+00:00')
     values_file = options_dir / 'values' / 'test-ns' / 'values.json'
-    _run(
+    run_isolated(
         f"""\
         import json
         from sentry_options import init, options
@@ -161,9 +112,9 @@ def test_propagation_callback_exception_does_not_crash(tmp_path: Path) -> None:
 
 
 def test_propagation_callback_receives_multiple_updates(tmp_path: Path) -> None:
-    options_dir = _make_options_dir(tmp_path, generated_at='2024-01-21T18:00:00+00:00')
+    options_dir = make_options_dir(tmp_path, generated_at='2024-01-21T18:00:00+00:00')
     values_file = options_dir / 'values' / 'test-ns' / 'values.json'
-    _run(
+    run_isolated(
         f"""\
         import json
         from sentry_options import init, options

sentry_options-1.2.2/clients/python/tests/refresh_test.py

@@ -0,0 +1,73 @@
+"""E2E tests for manual refresh and the configurable staleness threshold.
+
+Each test spins up a subprocess with its own ``SENTRY_OPTIONS_DIR`` so the
+Rust ``OnceLock`` starts fresh and ``init(refresh_threshold=...)`` takes
+effect.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from conftest import make_options_dir
+from conftest import run_isolated
+
+
+def test_manual_refresh_with_disabled_threshold(tmp_path: Path) -> None:
+    options_dir = make_options_dir(tmp_path)
+    values_file = options_dir / 'values' / 'test-ns' / 'values.json'
+    run_isolated(
+        f"""\
+        import json
+        from sentry_options import init, options, refresh
+
+        init(refresh_threshold=None)
+        opts = options("test-ns")
+        assert opts.get("enabled") is True
+
+        with open("{values_file}", "w") as f:
+            json.dump({{"options": {{"enabled": False}}}}, f)
+
+        # With refresh-on-read disabled, reads never pick up the change.
+        assert opts.get("enabled") is True
+        # A manual refresh does.
+        assert refresh() is True
+        assert opts.get("enabled") is False
+        # Nothing changed since the last refresh.
+        assert refresh() is False
+        """,
+        options_dir,
+    )
+
+
+def test_refresh_before_init_raises(tmp_path: Path) -> None:
+    options_dir = make_options_dir(tmp_path)
+    run_isolated(
+        """\
+        from sentry_options import NotInitializedError, refresh
+
+        try:
+            refresh()
+        except NotInitializedError:
+            pass
+        else:
+            raise AssertionError("Expected NotInitializedError")
+        """,
+        options_dir,
+    )
+
+
+def test_init_rejects_negative_refresh_threshold(tmp_path: Path) -> None:
+    options_dir = make_options_dir(tmp_path)
+    run_isolated(
+        """\
+        from sentry_options import init
+
+        try:
+            init(refresh_threshold=-1.0)
+        except ValueError:
+            pass
+        else:
+            raise AssertionError("Expected ValueError")
+        """,
+        options_dir,
+    )

{sentry_options-1.2.0 → sentry_options-1.2.2}/clients/python/uv.lock

@@ -126,7 +126,7 @@ wheels = [
 
 [[package]]
 name = "sentry-options"
-version = "1.2.0"
+version = "1.2.2"
 source = { editable = "." }
 
 [package.optional-dependencies]