feat!: make set_provider non-blocking, add set_provider_and_wait

[jonathannorris]

Summary

• set_provider() now returns immediately; provider initialization runs in a background thread (daemon)
• Adds set_provider_and_wait() that blocks until initialization completes or re-raises on failure
• Updates existing tests to use set_provider_and_wait where init completion is required; adds 8 new tests covering non-blocking semantics explicitly

Motivation

Closes#594. Spec Requirement 1.1.2.4 implies set_provider() should be non-blocking, with a separate variant for callers who need to wait. Python was the only SDK where set_provider() blocked by default. The gunicorn DoS scenario in the issue is real — a provider that hangs during init causes gunicorn to kill the worker with a cryptic WORKER TIMEOUT.

All other SDKs (Go, Java, JS/TS, Ruby) have the same split: a fire-and-forget default and a *AndWait variant. This implementation follows Ruby's approach since it's also synchronous — a wait_for_init flag in the registry routes to either Thread(daemon=True).start() or an inline call.

Behavior change

set_provider() — non-blocking (default):

• Returns before initialize() completes
• Flag evaluations during the init window return the default value with PROVIDER_NOT_READY
• Initialization errors fire a PROVIDER_ERROR event; they are not propagated to the caller

set_provider_and_wait() — blocking:

• Blocks until initialize() completes or raises
• Provider is READY (or in error state) before the call returns
• Re-raises the original exception on failure

Notes

This is a breaking behavioral change for callers who relied on set_provider() blocking until ready. Tagging as feat! so release-please bumps the minor version (pre-1.0, so 0.9.x → 0.10.0 per bump-minor-pre-major). Getting this in before 1.0 is the right call to avoid carrying it as a breaking change post-stable.

Relates to: #96
Fixes: #594

[codecov]

Codecov Report

❌ Patch coverage is 98.82353% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.28%. Comparing base (760d808) to head (2084adf).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
openfeature/provider/_registry.py	96.15%	3 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #595 +/- ##
==========================================
- Coverage 98.35% 98.28% -0.07% 
==========================================
Files 45 45 Lines 2183 2386 +203 ==========================================
+ Hits 2147 2345 +198 - Misses 36 41 +5 

Flag	Coverage Δ
unittests	98.28% <98.82%> (-0.07%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gemini-code-assist]

Code Review

This pull request introduces asynchronous provider initialization to the OpenFeature Python SDK. The set_provider method is now non-blocking by default, delegating initialization to a background thread, while a new set_provider_and_wait method has been added for cases requiring blocking behavior. The documentation and existing tests have been updated to reflect these changes. Feedback from the review highlights critical thread-safety concerns, specifically a race condition in the provider registry that could lead to redundant initializations and the need for synchronization when updating shared state from background threads.

[Copilot]

Pull request overview

This PR updates the provider registration API to make set_provider() non-blocking by default (initialization runs asynchronously), and introduces set_provider_and_wait() for callers/tests that need to block until provider initialization completes or fails. This aligns the Python SDK behavior with the OpenFeature spec guidance and other SDKs.

Changes:

• Make provider initialization asynchronous by default via a background daemon thread.
• Add set_provider_and_wait() (blocking) and update tests/BDD steps to use it where readiness is required.
• Update README examples to document the new semantics and correct a few API usage examples.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
openfeature/provider/_registry.py	Adds async initialization path (wait_for_init flag) and refactors initialization into _run_initialize.
openfeature/api.py	Exposes set_provider_and_wait() and adds it to __all__.
tests/test_api.py	Updates existing tests to block where needed; adds new tests for non-blocking semantics.
tests/provider/test_registry.py	Updates registry tests for the new wait_for_init behavior; adds new async-init tests.
tests/conftest.py	Switches fixture initialization to set_provider_and_wait to ensure readiness.
tests/features/steps/steps.py	Updates behave steps to use set_provider_and_wait.
tests/features/steps/metadata_steps.py	Updates behave steps to use set_provider_and_wait.
README.md	Documents non-blocking set_provider() and adds example for set_provider_and_wait(); adjusts several snippets for API correctness.

Comments suppressed due to low confidence (2)

openfeature/provider/_registry.py:130

• With async initialization, _shutdown_provider can run before _run_initialize has ever set an entry in _provider_status. del self._provider_status[provider] will then raise KeyError, which is caught and reported as a shutdown failure (and also leaves status cleanup inconsistent). Consider using pop(..., None) and/or inserting an initial NOT_READY status when initialization starts so shutdown/clear is safe while init is in-flight.

 def _shutdown_provider(self, provider: FeatureProvider) -> None:
try:
if hasattr(provider, "shutdown"):
provider.shutdown()
del self._provider_status[provider]
except Exception as err:

openfeature/provider/_registry.py:108

• _initialize_provider now spawns a background thread which always calls self.dispatch_event(...PROVIDER_READY/ERROR...) after initialize() finishes. If the provider is replaced/cleared/shutdown while init is still running, this thread can still update _provider_status and run global/client handlers after the provider has been detached, causing late/incorrect events and state resurrection. Consider tracking init threads/futures and canceling/ignoring completion for providers no longer registered (e.g., generation token or per-provider state guarded by a lock).

 def _initialize_provider(
self, provider: FeatureProvider, wait_for_init: bool = False
) -> None:
provider.attach(self.dispatch_event)
if wait_for_init:
self._run_initialize(provider, raise_on_error=True)
else:
thread = threading.Thread(
target=self._run_initialize,
args=(provider,),
kwargs={"raise_on_error": False},
daemon=True,
)
thread.start()
def _run_initialize(
self, provider: FeatureProvider, raise_on_error: bool = False
) -> None:
try:
if hasattr(provider, "initialize"):
provider.initialize(self._get_evaluation_context())
self.dispatch_event(
provider, ProviderEvent.PROVIDER_READY, ProviderEventDetails()
)
except Exception as err:

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jonathannorris]

There's a related PR (#567) worth flagging. It takes a purely additive approach — set_provider() stays blocking, and set_provider_and_wait() is added as a second blocking method. That doesn't fix the DoS scenario from #594; a hanging provider still blocks the caller.

This PR makes set_provider() actually non-blocking (background thread), matching Go, Java, JS/TS, and Ruby. It's a breaking behavioral change, which is exactly why the 1.0-release label matters.

[toddbaert]

Pulled locally and added a few fixes:

• closed the race where concurrent set_provider calls with the same instance could double-initialize
• prevented a late PROVIDER_READY/PROVIDER_ERROR from a background init from clobbering the status of a provider that was already replaced or shut down_
• eliminated a KeyError in shutdownby using pop not del
• made old-provider shutdown async so a hanging shutdown() can't block set_provider (otherwise the DoS this PR fixes is only half-closed).

I added tests that seemed reasonable for these. Python is not my strong-suit so please take a look @jonathannorris .

commit is here.

I think this resolves all the review feedback by bots and @dd-oleksii .

[toddbaert]

Leaving this open for a bit because it's a pretty fundamental change, but I will get it merged this week. Please weigh in if you have objections.

[jonathannorris]

We found an issue with the stale check @toddbaert added in _run_initialize. It checks provider not in self._provider_status, but replaced providers stay in _provider_status until _shutdown_provider pops them — and since shutdown runs asynchronously via _shutdown_if_unused, there's a window where a stale provider's initialize() can complete, pass the check, and dispatch PROVIDER_READY even though it's no longer bound to any domain.

The fix is to check active registration instead:

# current (insufficient)ifprovidernotinself._provider_status:
return# correctifproviderisnotself._default_providerandprovidernotinself._providers.values():
return

Will push a fix.

[leohoare]

It looks like there is a race condition on shutdown.

Now that old-provider shutdown runs in the background, re-registering the same provider instance while its previous shutdown is still finishing lets the stale shutdown wipe out the fresh registration's event wiring and status.

Proposed Fix (or something like):

• Add a per-registration generation token (a counter bumped each time a provider is registered).
• Have each background shutdown capture the token it was started for.
• Before the shutdown does its final detach() and status pop, re-check that the provider's current token still matches.
• If the provider has been re-registered since (newer token), skip the cleanup instead of clobbering the new setup.

[toddbaert]

It looks like there is a race condition on shutdown.

Now that old-provider shutdown runs in the background, re-registering the same provider instance while its previous shutdown is still finishing lets the stale shutdown wipe out the fresh registration's event wiring and status.

Proposed Fix (or something like):

• Add a per-registration generation token (a counter bumped each time a provider is registered).
• Have each background shutdown capture the token it was started for.
• Before the shutdown does its final detach() and status pop, re-check that the provider's current token still matches.
• If the provider has been re-registered since (newer token), skip the cleanup instead of clobbering the new setup.

Good call. This race is valid; repro added as test_stale_shutdown_does_not_clobber_re_registered_provider.
My simpler fix: pass a flag from _shutdown_if_unused so _shutdown_provider re-checks under the lock afterprovider.shutdown() returns; skip pop/detach if re-registered. Sync shutdown() path unaffected. This makes the test pass and fixes the bug, I think... see: commit.