feat: add set_provider_and_wait() for blocking initialization

Adds set_provider_and_wait() and set_provider_and_wait(domain) to the
public API, implementing spec requirement 1.1.2.4: "The API SHOULD
provide functions to set a provider and wait for the initialize function
to return or abnormally terminate."

This aligns the Python SDK with Java, Go, and Node.js SDKs which all
offer both blocking and non-blocking provider registration.

Behavior changes:
- set_provider_and_wait(): calls initialize() synchronously on the
  caller's thread. If initialize() raises, the exception propagates
  to the caller and PROVIDER_ERROR is dispatched.
- set_provider(): now runs initialize() in a background daemon thread.
  Errors are caught and dispatched as PROVIDER_ERROR events without
  propagating to the caller.

This is a behavioral change to set_provider(): previously it ran
initialize() synchronously. Now it runs asynchronously. Callers who
need synchronous initialization should switch to set_provider_and_wait().

Author: leoromanovsky

openfeature/api.py

@@ -31,6 +31,7 @@
     "remove_handler",
     "set_evaluation_context",
     "set_provider",
+    "set_provider_and_wait",
     "set_transaction_context",
     "set_transaction_context_propagator",
     "shutdown",
@@ -44,12 +45,40 @@ def get_client(
 
 
 def set_provider(provider: FeatureProvider, domain: str | None = None) -> None:
+    """Set the provider and return immediately.
+
+    Initialization happens in a background thread. The provider starts in
+    NOT_READY status and transitions to READY (or ERROR) once initialization
+    completes. Use add_handler(ProviderEvent.PROVIDER_READY, ...) to be
+    notified when the provider is ready for flag evaluation.
+
+    Spec reference: Requirement 1.1.2.2
+    """
     if domain is None:
         provider_registry.set_default_provider(provider)
     else:
         provider_registry.set_provider(domain, provider)
 
 
+def set_provider_and_wait(
+    provider: FeatureProvider, domain: str | None = None
+) -> None:
+    """Set the provider and wait for initialization to complete.
+
+    Blocks the calling thread until the provider's initialize() method
+    returns successfully or raises an exception. If initialization fails,
+    the exception is re-raised to the caller.
+
+    Spec reference: Requirement 1.1.2.4 - "The API SHOULD provide functions
+    to set a provider and wait for the initialize function to return or
+    abnormally terminate."
+    """
+    if domain is None:
+        provider_registry.set_default_provider_and_wait(provider)
+    else:
+        provider_registry.set_provider_and_wait(domain, provider)
+
+
 def clear_providers() -> None:
     provider_registry.clear_providers()
     _event_support.clear()

openfeature/provider/_registry.py

@@ -1,3 +1,5 @@
+import threading
+
 from openfeature._event_support import run_handlers_for_provider
 from openfeature.evaluation_context import EvaluationContext, get_evaluation_context
 from openfeature.event import (
@@ -22,6 +24,16 @@ def __init__(self) -> None:
         }
 
     def set_provider(self, domain: str, provider: FeatureProvider) -> None:
+        self._set_provider_internal(domain, provider, wait=False)
+
+    def set_provider_and_wait(
+        self, domain: str, provider: FeatureProvider
+    ) -> None:
+        self._set_provider_internal(domain, provider, wait=True)
+
+    def _set_provider_internal(
+        self, domain: str, provider: FeatureProvider, *, wait: bool
+    ) -> None:
         if provider is None:
             raise GeneralError(error_message="No provider")
         if domain is None:
@@ -36,7 +48,10 @@ def set_provider(self, domain: str, provider: FeatureProvider) -> None:
             ):
                 self._shutdown_provider(old_provider)
         if provider != self._default_provider and provider not in providers.values():
-            self._initialize_provider(provider)
+            if wait:
+                self._initialize_provider(provider)
+            else:
+                self._initialize_provider_async(provider)
         providers[domain] = provider
 
     def get_provider(self, domain: str | None) -> FeatureProvider:
@@ -45,6 +60,14 @@ def get_provider(self, domain: str | None) -> FeatureProvider:
         return self._providers.get(domain, self._default_provider)
 
     def set_default_provider(self, provider: FeatureProvider) -> None:
+        self._set_default_provider_internal(provider, wait=False)
+
+    def set_default_provider_and_wait(self, provider: FeatureProvider) -> None:
+        self._set_default_provider_internal(provider, wait=True)
+
+    def _set_default_provider_internal(
+        self, provider: FeatureProvider, *, wait: bool
+    ) -> None:
         if provider is None:
             raise GeneralError(error_message="No provider")
         if (
@@ -55,7 +78,10 @@ def set_default_provider(self, provider: FeatureProvider) -> None:
         self._default_provider = provider
 
         if self._default_provider not in self._providers.values():
-            self._initialize_provider(provider)
+            if wait:
+                self._initialize_provider(provider)
+            else:
+                self._initialize_provider_async(provider)
 
     def get_default_provider(self) -> FeatureProvider:
         return self._default_provider
@@ -76,6 +102,7 @@ def _get_evaluation_context(self) -> EvaluationContext:
         return get_evaluation_context()
 
     def _initialize_provider(self, provider: FeatureProvider) -> None:
+        """Initialize the provider synchronously, re-raising on failure."""
         provider.attach(self.dispatch_event)
         try:
             if hasattr(provider, "initialize"):
@@ -97,6 +124,36 @@ def _initialize_provider(self, provider: FeatureProvider) -> None:
                     error_code=error_code,
                 ),
             )
+            raise
+
+    def _initialize_provider_async(self, provider: FeatureProvider) -> None:
+        """Initialize the provider in a background thread, swallowing exceptions."""
+        provider.attach(self.dispatch_event)
+
+        def _run() -> None:
+            try:
+                if hasattr(provider, "initialize"):
+                    provider.initialize(self._get_evaluation_context())
+                self.dispatch_event(
+                    provider, ProviderEvent.PROVIDER_READY, ProviderEventDetails()
+                )
+            except Exception as err:
+                error_code = (
+                    err.error_code
+                    if isinstance(err, OpenFeatureError)
+                    else ErrorCode.GENERAL
+                )
+                self.dispatch_event(
+                    provider,
+                    ProviderEvent.PROVIDER_ERROR,
+                    ProviderEventDetails(
+                        message=f"Provider initialization failed: {err}",
+                        error_code=error_code,
+                    ),
+                )
+
+        thread = threading.Thread(target=_run, daemon=True)
+        thread.start()
 
     def _shutdown_provider(self, provider: FeatureProvider) -> None:
         try:

tests/test_api.py

@@ -14,6 +14,7 @@
     remove_handler,
     set_evaluation_context,
     set_provider,
+    set_provider_and_wait,
     shutdown,
 )
 from openfeature.evaluation_context import EvaluationContext
@@ -330,6 +331,86 @@ def test_provider_error_handlers_run_if_provider_initialize_function_terminates_
     spy.provider_error.assert_called_once()
 
 
+def test_set_provider_and_wait_blocks_until_initialize_completes():
+    # Given
+    evaluation_context = EvaluationContext("targeting_key", {"attr1": "val1"})
+    provider = MagicMock(spec=FeatureProvider)
+
+    # When
+    set_evaluation_context(evaluation_context)
+    set_provider_and_wait(provider)
+
+    # Then - initialize should have been called synchronously
+    provider.initialize.assert_called_with(evaluation_context)
+    # Provider should be READY after set_provider_and_wait returns
+    client = get_client()
+    assert client.get_provider_status() == ProviderStatus.READY
+
+
+def test_set_provider_and_wait_raises_on_initialization_failure():
+    # Given
+    provider = MagicMock(spec=FeatureProvider)
+    provider.initialize.side_effect = ProviderFatalError()
+
+    spy = MagicMock()
+    add_handler(ProviderEvent.PROVIDER_ERROR, spy.provider_error)
+
+    # When / Then - should propagate the exception to the caller
+    with pytest.raises(ProviderFatalError):
+        set_provider_and_wait(provider)
+
+    # Error handler should still have been called
+    spy.provider_error.assert_called_once()
+
+
+def test_set_provider_and_wait_with_domain():
+    # Given
+    provider = MagicMock(spec=FeatureProvider)
+
+    # When
+    set_provider_and_wait(provider, domain="test")
+
+    # Then
+    provider.initialize.assert_called_once()
+    test_client = get_client("test")
+    assert test_client.provider == provider
+
+
+def test_set_provider_runs_init_in_background():
+    """set_provider() should not raise even if initialize() fails."""
+    # Given
+    provider = MagicMock(spec=FeatureProvider)
+    provider.initialize.side_effect = Exception("init failed")
+
+    # When - should NOT raise (error is handled in background thread)
+    set_provider(provider)
+
+    # Give the background thread a moment to complete
+    import time
+    time.sleep(0.1)
+
+    # Then - provider should be in ERROR state (not READY)
+    client = get_client()
+    assert client.get_provider_status() == ProviderStatus.ERROR
+
+
+def test_set_provider_async_eventually_becomes_ready():
+    """set_provider() runs init in background, provider transitions to READY."""
+    # Given
+    provider = MagicMock(spec=FeatureProvider)
+
+    # When
+    set_provider(provider)
+
+    # Give the background thread a moment to complete
+    import time
+    time.sleep(0.1)
+
+    # Then - provider should be READY
+    client = get_client()
+    assert client.get_provider_status() == ProviderStatus.READY
+
+
 def test_provider_status_is_updated_after_provider_emits_event():
     # Given
     provider = NoOpProvider()