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

openfeature/_api.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from openfeature._event_support import EventSupport
+from openfeature.client import OpenFeatureClient
+from openfeature.evaluation_context import EvaluationContext
+from openfeature.event import EventHandler, ProviderEvent
+from openfeature.exception import GeneralError
+from openfeature.hook import Hook
+from openfeature.provider import FeatureProvider, ProviderStatus
+from openfeature.provider._registry import ProviderRegistry
+from openfeature.provider.metadata import Metadata
+from openfeature.transaction_context import TransactionContextPropagator
+from openfeature.transaction_context.no_op_transaction_context_propagator import (
+    NoOpTransactionContextPropagator,
+)
+
+
+class OpenFeatureAPI:
+    """An independent OpenFeature API instance with its own isolated state.
+
+    Each instance maintains its own providers, evaluation context, hooks,
+    event handlers, and transaction context propagator; fully separate from
+    the global singleton and from other instances.
+    """
+
+    def __init__(self) -> None:
+        self._hooks: list[Hook] = []
+        self._evaluation_context = EvaluationContext()
+        self._transaction_context_propagator: TransactionContextPropagator = (
+            NoOpTransactionContextPropagator()
+        )
+        self._event_support = EventSupport()
+        self._provider_registry = ProviderRegistry(
+            event_support=self._event_support,
+            evaluation_context_getter=self.get_evaluation_context,
+        )
+
+    # --- Client creation ---
+
+    def get_client(
+        self, domain: str | None = None, version: str | None = None
+    ) -> OpenFeatureClient:
+        return OpenFeatureClient(domain=domain, version=version, api=self)
+
+    # --- Provider management ---
+
+    def set_provider(
+        self, provider: FeatureProvider, domain: str | None = None
+    ) -> None:
+        if domain is None:
+            self._provider_registry.set_default_provider(provider)
+        else:
+            self._provider_registry.set_provider(domain, provider)
+
+    def set_provider_and_wait(
+        self, provider: FeatureProvider, domain: str | None = None
+    ) -> None:
+        if domain is None:
+            self._provider_registry.set_default_provider(provider, wait_for_init=True)
+        else:
+            self._provider_registry.set_provider(domain, provider, wait_for_init=True)
+
+    def get_provider_metadata(self, domain: str | None = None) -> Metadata:
+        return self._provider_registry.get_provider(domain).get_metadata()
+
+    def get_provider(self, domain: str | None = None) -> FeatureProvider:
+        return self._provider_registry.get_provider(domain)
+
+    def get_provider_status(self, provider: FeatureProvider) -> ProviderStatus:
+        return self._provider_registry.get_provider_status(provider)
+
+    def clear_providers(self) -> None:
+        self._provider_registry.clear_providers()
+        self._event_support.clear()
+
+    def shutdown(self) -> None:
+        # shutdown -> remove providers -> set default provider to NoOp -> remove event handlers
+        self.clear_providers()
+        # remove hooks
+        self.clear_hooks()
+        # set evaluation context to default
+        self._evaluation_context = EvaluationContext()
+        # set propagator to NoOp
+        self._transaction_context_propagator = NoOpTransactionContextPropagator()
+
+    # --- Hooks ---
+
+    def add_hooks(self, hooks: list[Hook]) -> None:
+        self._hooks = self._hooks + hooks
+
+    def clear_hooks(self) -> None:
+        self._hooks = []
+
+    def get_hooks(self) -> list[Hook]:
+        return self._hooks
+
+    # --- Evaluation context ---
+
+    def get_evaluation_context(self) -> EvaluationContext:
+        return self._evaluation_context
+
+    def set_evaluation_context(self, evaluation_context: EvaluationContext) -> None:
+        if evaluation_context is None:
+            raise GeneralError(error_message="No api level evaluation context")
+        self._evaluation_context = evaluation_context
+
+    def clear_evaluation_context(self) -> None:
+        self.set_evaluation_context(EvaluationContext())
+
+    # --- Transaction context ---
+
+    def set_transaction_context_propagator(
+        self, transaction_context_propagator: TransactionContextPropagator
+    ) -> None:
+        self._transaction_context_propagator = transaction_context_propagator
+
+    def clear_transaction_context_propagator(self) -> None:
+        self.set_transaction_context_propagator(NoOpTransactionContextPropagator())
+
+    def get_transaction_context(self) -> EvaluationContext:
+        return self._transaction_context_propagator.get_transaction_context()
+
+    def set_transaction_context(self, evaluation_context: EvaluationContext) -> None:
+        self._transaction_context_propagator.set_transaction_context(evaluation_context)
+
+    # --- Event handlers ---
+
+    def add_handler(self, event: ProviderEvent, handler: EventHandler) -> None:
+        self._event_support.add_global_handler(event, handler, self.get_client)
+
+    def remove_handler(self, event: ProviderEvent, handler: EventHandler) -> None:
+        self._event_support.remove_global_handler(event, handler)
+
+
+_default_api = OpenFeatureAPI()

openfeature/_event_support.py

@@ -4,6 +4,7 @@
 import threading
 import typing
 from collections import defaultdict
+from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor
 from logging import getLogger
 
@@ -23,103 +24,6 @@
 _event_executor = ThreadPoolExecutor(thread_name_prefix="openfeature-event-handler")
 atexit.register(_event_executor.shutdown, wait=True)
 
-_global_lock = threading.RLock()
-_global_handlers: dict[ProviderEvent, list[EventHandler]] = defaultdict(list)
-
-_client_lock = threading.RLock()
-_client_handlers: dict[OpenFeatureClient, dict[ProviderEvent, list[EventHandler]]] = (
-    defaultdict(lambda: defaultdict(list))
-)
-
-
-def run_client_handlers(
-    client: OpenFeatureClient, event: ProviderEvent, details: EventDetails
-) -> None:
-    with _client_lock:
-        handlers_by_event = _client_handlers.get(client)
-        if handlers_by_event is None:
-            return
-
-        handlers = tuple(handlers_by_event.get(event, ()))
-
-    for handler in handlers:
-        _submit_handler(handler, details)
-
-
-def run_global_handlers(event: ProviderEvent, details: EventDetails) -> None:
-    with _global_lock:
-        handlers = tuple(_global_handlers.get(event, ()))
-
-    for handler in handlers:
-        _submit_handler(handler, details)
-
-
-def add_client_handler(
-    client: OpenFeatureClient, event: ProviderEvent, handler: EventHandler
-) -> None:
-    with _client_lock:
-        handlers = _client_handlers[client][event]
-        handlers.append(handler)
-
-    _run_immediate_handler(client, event, handler)
-
-
-def remove_client_handler(
-    client: OpenFeatureClient, event: ProviderEvent, handler: EventHandler
-) -> None:
-    with _client_lock:
-        handlers = _client_handlers[client][event]
-        handlers.remove(handler)
-
-
-def add_global_handler(event: ProviderEvent, handler: EventHandler) -> None:
-    with _global_lock:
-        _global_handlers[event].append(handler)
-
-    from openfeature.api import get_client  # noqa: PLC0415
-
-    _run_immediate_handler(get_client(), event, handler)
-
-
-def remove_global_handler(event: ProviderEvent, handler: EventHandler) -> None:
-    with _global_lock:
-        _global_handlers[event].remove(handler)
-
-
-def run_handlers_for_provider(
-    provider: FeatureProvider,
-    event: ProviderEvent,
-    provider_details: ProviderEventDetails,
-) -> None:
-    details = EventDetails.from_provider_event_details(
-        provider.get_metadata().name, provider_details
-    )
-    # run the global handlers
-    run_global_handlers(event, details)
-    # run the handlers for clients associated to this provider
-    with _client_lock:
-        clients = tuple(
-            client for client in _client_handlers if client.provider == provider
-        )
-
-    for client in clients:
-        run_client_handlers(client, event, details)
-
-
-def _run_immediate_handler(
-    client: OpenFeatureClient, event: ProviderEvent, handler: EventHandler
-) -> None:
-    status_to_event = {
-        ProviderStatus.READY: ProviderEvent.PROVIDER_READY,
-        ProviderStatus.ERROR: ProviderEvent.PROVIDER_ERROR,
-        ProviderStatus.FATAL: ProviderEvent.PROVIDER_ERROR,
-        ProviderStatus.STALE: ProviderEvent.PROVIDER_STALE,
-    }
-    if event == status_to_event.get(client.get_provider_status()):
-        _submit_handler(
-            handler, EventDetails(provider_name=client.provider.get_metadata().name)
-        )
-
 
 def _submit_handler(handler: EventHandler, details: EventDetails) -> None:
     _event_executor.submit(_run_handler, handler, details)
@@ -132,8 +36,112 @@ def _run_handler(handler: EventHandler, details: EventDetails) -> None:
         logger.exception("Unhandled exception in OpenFeature event handler")
 
 
-def clear() -> None:
-    with _global_lock:
-        _global_handlers.clear()
-    with _client_lock:
-        _client_handlers.clear()
+class EventSupport:
+    """Per-API-instance event handler storage and dispatch."""
+
+    def __init__(self) -> None:
+        self._global_lock = threading.RLock()
+        self._global_handlers: dict[ProviderEvent, list[EventHandler]] = defaultdict(
+            list
+        )
+
+        self._client_lock = threading.RLock()
+        self._client_handlers: dict[
+            OpenFeatureClient, dict[ProviderEvent, list[EventHandler]]
+        ] = defaultdict(lambda: defaultdict(list))
+
+    def run_client_handlers(
+        self, client: OpenFeatureClient, event: ProviderEvent, details: EventDetails
+    ) -> None:
+        with self._client_lock:
+            handlers_by_event = self._client_handlers.get(client)
+            if handlers_by_event is None:
+                return
+
+            handlers = tuple(handlers_by_event.get(event, ()))
+
+        for handler in handlers:
+            _submit_handler(handler, details)
+
+    def run_global_handlers(self, event: ProviderEvent, details: EventDetails) -> None:
+        with self._global_lock:
+            handlers = tuple(self._global_handlers.get(event, ()))
+
+        for handler in handlers:
+            _submit_handler(handler, details)
+
+    def add_client_handler(
+        self, client: OpenFeatureClient, event: ProviderEvent, handler: EventHandler
+    ) -> None:
+        with self._client_lock:
+            handlers = self._client_handlers[client][event]
+            handlers.append(handler)
+
+        self._run_immediate_handler(client, event, handler)
+
+    def remove_client_handler(
+        self, client: OpenFeatureClient, event: ProviderEvent, handler: EventHandler
+    ) -> None:
+        with self._client_lock:
+            handlers = self._client_handlers[client][event]
+            handlers.remove(handler)
+
+    def add_global_handler(
+        self,
+        event: ProviderEvent,
+        handler: EventHandler,
+        get_client: Callable[[], OpenFeatureClient],
+    ) -> None:
+        with self._global_lock:
+            self._global_handlers[event].append(handler)
+
+        self._run_immediate_handler(get_client(), event, handler)
+
+    def remove_global_handler(
+        self, event: ProviderEvent, handler: EventHandler
+    ) -> None:
+        with self._global_lock:
+            self._global_handlers[event].remove(handler)
+
+    def run_handlers_for_provider(
+        self,
+        provider: FeatureProvider,
+        event: ProviderEvent,
+        provider_details: ProviderEventDetails,
+    ) -> None:
+        details = EventDetails.from_provider_event_details(
+            provider.get_metadata().name, provider_details
+        )
+        # run the global handlers
+        self.run_global_handlers(event, details)
+        # run the handlers for clients associated to this provider
+        with self._client_lock:
+            clients = tuple(
+                client
+                for client in self._client_handlers
+                if client.provider == provider
+            )
+
+        for client in clients:
+            self.run_client_handlers(client, event, details)
+
+    def _run_immediate_handler(
+        self, client: OpenFeatureClient, event: ProviderEvent, handler: EventHandler
+    ) -> None:
+        status_to_event = {
+            ProviderStatus.READY: ProviderEvent.PROVIDER_READY,
+            ProviderStatus.ERROR: ProviderEvent.PROVIDER_ERROR,
+            ProviderStatus.FATAL: ProviderEvent.PROVIDER_ERROR,
+            ProviderStatus.STALE: ProviderEvent.PROVIDER_STALE,
+        }
+        if event == status_to_event.get(client.get_provider_status()):
+            _submit_handler(
+                handler,
+                EventDetails(provider_name=client.provider.get_metadata().name),
+            )
+
+    def clear(self) -> None:
+        with self._global_lock:
+            self._global_handlers.clear()
+        with self._client_lock:
+            self._client_handlers.clear()