fix: address multi-provider review issues

- Fix ContextVar propagation to ThreadPoolExecutor workers (Python <3.12)
- Fix _refresh_aggregate_status dropping events during partial init failure
- Add shouldEvaluateThisProvider check to skip NOT_READY/FATAL providers
- Fix ComparisonStrategy to return first provider result on no-mismatch
- Add InternalHookProvider protocol replacing fragile duck-typing
- Scope get_status override in registry to InternalHookProvider only
- Rename camelCase instance variables to snake_case

Signed-off-by: Jonathan Norris <jonathan.norris@dynatrace.com>

Author: jonathannorris

openfeature/client.py

@@ -30,7 +30,7 @@
     before_hooks,
     error_hooks,
 )
-from openfeature.provider import FeatureProvider, ProviderStatus
+from openfeature.provider import FeatureProvider, InternalHookProvider, ProviderStatus
 from openfeature.provider._registry import provider_registry
 from openfeature.transaction_context import get_transaction_context
 
@@ -471,21 +471,22 @@ def _establish_hooks_and_provider(
         )
 
     def _provider_uses_internal_hooks(self, provider: FeatureProvider) -> bool:
-        uses_internal_hooks = getattr(provider, "uses_internal_provider_hooks", None)
-        return bool(callable(uses_internal_hooks) and uses_internal_hooks())
+        return (
+            isinstance(provider, InternalHookProvider)
+            and provider.uses_internal_provider_hooks()
+        )
 
     def _set_internal_provider_hook_runtime(
         self,
         provider: FeatureProvider,
         flag_type: FlagType,
         hook_hints: HookHints,
     ) -> object | None:
-        if not self._provider_uses_internal_hooks(provider):
+        if not isinstance(provider, InternalHookProvider):
             return None
-        set_hook_runtime = getattr(provider, "set_internal_provider_hook_runtime", None)
-        if not callable(set_hook_runtime):
+        if not provider.uses_internal_provider_hooks():
             return None
-        return set_hook_runtime(
+        return provider.set_internal_provider_hook_runtime(
             flag_type=flag_type,
             client_metadata=self.get_metadata(),
             hook_hints=hook_hints,
@@ -496,9 +497,8 @@ def _reset_internal_provider_hook_runtime(
     ) -> None:
         if runtime_token is None:
             return
-        reset_hook_runtime = getattr(provider, "reset_internal_provider_hook_runtime", None)
-        if callable(reset_hook_runtime):
-            reset_hook_runtime(runtime_token)
+        if isinstance(provider, InternalHookProvider):
+            provider.reset_internal_provider_hook_runtime(runtime_token)
 
     def _assert_provider_status(
         self,

openfeature/provider/__init__.py

@@ -22,6 +22,7 @@
     "FeatureProvider",
     "FirstMatchStrategy",
     "FirstSuccessfulStrategy",
+    "InternalHookProvider",
     "Metadata",
     "MultiProvider",
     "ProviderEntry",
@@ -128,6 +129,32 @@ async def resolve_object_details_async(
     ]: ...
 
 
+@typing.runtime_checkable
+class InternalHookProvider(typing.Protocol):
+    """Protocol for providers that manage their own provider hook execution.
+
+    Providers implementing this protocol (e.g. MultiProvider) handle provider
+    hook lifecycle internally. The client will skip its own provider hook
+    invocations and instead delegate to the provider via the set/reset methods.
+
+    The registry will also use get_status() from this protocol instead of its
+    own internal status tracking for providers that implement it.
+    """
+
+    def uses_internal_provider_hooks(self) -> bool: ...
+
+    def set_internal_provider_hook_runtime(
+        self,
+        flag_type: typing.Any,
+        client_metadata: typing.Any,
+        hook_hints: typing.Any,
+    ) -> typing.Any: ...
+
+    def reset_internal_provider_hook_runtime(self, token: typing.Any) -> None: ...
+
+    def get_status(self) -> ProviderStatus: ...
+
+
 class AbstractProvider(FeatureProvider):
     def __init__(self, *args: typing.Any, **kwargs: typing.Any) -> None:
         # this makes sure to invoke the parent of `FeatureProvider` -> `object`

openfeature/provider/_registry.py

@@ -5,7 +5,7 @@
     ProviderEventDetails,
 )
 from openfeature.exception import ErrorCode, GeneralError, OpenFeatureError
-from openfeature.provider import FeatureProvider, ProviderStatus
+from openfeature.provider import FeatureProvider, InternalHookProvider, ProviderStatus
 from openfeature.provider.no_op_provider import NoOpProvider
 
 
@@ -80,6 +80,9 @@ def _initialize_provider(self, provider: FeatureProvider) -> None:
         try:
             if hasattr(provider, "initialize"):
                 provider.initialize(self._get_evaluation_context())
+            # InternalHookProvider (e.g. MultiProvider) emits its own events
+            # during initialize(), so only dispatch PROVIDER_READY if the
+            # provider hasn't already transitioned away from NOT_READY.
             if self.get_provider_status(provider) == ProviderStatus.NOT_READY:
                 self.dispatch_event(
                     provider, ProviderEvent.PROVIDER_READY, ProviderEventDetails()
@@ -90,6 +93,8 @@ def _initialize_provider(self, provider: FeatureProvider) -> None:
                 if isinstance(err, OpenFeatureError)
                 else ErrorCode.GENERAL
             )
+            # Same guard: skip if the provider already emitted its own error
+            # event and transitioned out of NOT_READY.
             if self.get_provider_status(provider) == ProviderStatus.NOT_READY:
                 self.dispatch_event(
                     provider,
@@ -117,11 +122,10 @@ def _shutdown_provider(self, provider: FeatureProvider) -> None:
         provider.detach()
 
     def get_provider_status(self, provider: FeatureProvider) -> ProviderStatus:
-        provider_status_getter = getattr(provider, "get_status", None)
-        if callable(provider_status_getter):
-            status = provider_status_getter()
-            if isinstance(status, ProviderStatus):
-                return status
+        # Only InternalHookProvider implementations (e.g. MultiProvider) manage
+        # their own status. For all other providers, use the registry's tracking.
+        if isinstance(provider, InternalHookProvider):
+            return provider.get_status()
         return self._provider_status.get(provider, ProviderStatus.NOT_READY)
 
     def dispatch_event(