feat!: add isolated API instances, remove duped global funcs

[marcozabel]

• introduces support for creating isolated OpenFeature API instances, each with their own providers, hooks, context, and event handling, enabling multi-tenant or side-by-side usage without shared global state

from openfeature.isolated import OpenFeatureAPI, create_api
isolatedApi = create_api()

In order to do this cleanly:

• converts some existing stuff into classes
• removes old duplicated global convenience functions which caused import cycles with these changes (BREAKING)
  • makes OpenFeatureClient direct construction private (use api.get_client()) since we are already doing a breaking change (BREAKING)

---

⚠️ below is the section that will be added to the changelog when this is released (detailing the migration)

Import changes

Several module-level convenience functions moved to openfeature.api. Function signatures are unchanged; update imports only.

• Instead of from openfeature.evaluation_context import get_evaluation_context, use from openfeature.api import get_evaluation_context.
• Instead of from openfeature.hook import add_hooks, use from openfeature.api import add_hooks.
• Instead of from openfeature.transaction_context import set_transaction_context_propagator, use from openfeature.api import set_transaction_context_propagator.
• Instead of from openfeature.transaction_context import NoOpTransactionContextPropagator, use from openfeature.transaction_context.no_op_transaction_context_propagator import NoOpTransactionContextPropagator.

Type imports (EvaluationContext, Hook, HookContext, HookData, HookHints, HookType, ContextVarsTransactionContextPropagator, TransactionContextPropagator) are unchanged.

OpenFeatureClient is no longer publicly constructible

Use api.get_client() (or OpenFeatureAPI.get_client() for isolated instances). Direct construction is no longer supported.

from openfeature import api

client = api.get_client()
client = api.get_client(domain="my-domain")

The OpenFeatureClient type remains importable for type annotations.

Fixes #584

[codecov]

Codecov Report

❌ Patch coverage is 98.42829% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.33%. Comparing base (79bb01b) to head (5b46606).

Files with missing lines	Patch %	Lines
tests/test_isolated_api.py	98.34%	4 Missing ⚠️
openfeature/_api.py	97.14%	2 Missing ⚠️
openfeature/api.py	93.75%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #591      +/-   ##
==========================================
- Coverage   98.34%   98.33%   -0.02%     
==========================================
  Files          45       48       +3     
  Lines        2483     2827     +344     
==========================================
+ Hits         2442     2780     +338     
- Misses         41       47       +6     

Flag	Coverage Δ
unittests	98.33% <98.42%> (-0.02%)	⬇️

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

☔ View full report in Codecov by Harness.
📢 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 isolated OpenFeature API instances, enabling multiple independent configurations within a single application as per specification requirement 1.8. The core logic refactors global state into an OpenFeatureAPI class, with the existing global singleton now delegating to a default instance to maintain backward compatibility. Key changes include the introduction of an EventSupport class, updates to the OpenFeatureClient to reference specific API instances, and the addition of a new openfeature.isolated module. Review feedback recommends improving encapsulation by adding public methods to OpenFeatureAPI for retrieving providers and their status, rather than having the client access protected registry attributes directly.

[toddbaert]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces isolated OpenFeature API instances by creating the OpenFeatureAPI class and the openfeature.isolated module, allowing independent state management for providers, hooks, and contexts as per the specification. The global API has been refactored to delegate to a default instance, and the client, event support, and provider registry have been updated accordingly. The review feedback is highly constructive, pointing out critical improvements such as using weak references for client handlers to prevent memory leaks and reference cycles, handling potential TypeError exceptions when using WeakKeyDictionary with providers that use __slots__, and adding missing helper methods (clear_evaluation_context and clear_transaction_context_propagator) to OpenFeatureAPI to fully satisfy the API contract.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[toddbaert]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces isolated OpenFeature API instances via the new OpenFeatureAPI class and create_api() factory, allowing independent API states with separate providers, hooks, contexts, and event handlers. It refactors global managers into instance-specific classes and implements a weak-reference-based tracking mechanism to prevent a provider from being bound to multiple API instances simultaneously. Feedback from the review highlights a potential race condition in _shutdown_provider where a re-registered provider could be prematurely shut down, and recommends adding a reentrant lock to OpenFeatureAPI to ensure thread-safe operations on hooks.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.